215 lines
6.2 KiB
Markdown
215 lines
6.2 KiB
Markdown
# Garage Admin SDK
|
|
|
|
Operate your Garage cluster programatically
|
|
|
|
## ⚠️ DISCLAIMER
|
|
|
|
**THESE SDK ARE TECHNICAL PREVIEWS**. The following limitations apply:
|
|
- The API is not complete, some actions are possible only through the `garage` binary
|
|
- The underlying admin API is not yet stable nor complete, it can breaks at any time
|
|
- The generator configuration is currently tweaked, the library might break at any time due to a generator change
|
|
- Because the API and the library are not stable, none of them are published in a package manager (npm, pypi, etc.)
|
|
- This code has not been extensively tested, some things might not work (please report!)
|
|
|
|
To have the best experience possible, please consider:
|
|
- Make sure that the version of the library you are using is pinned (`go.sum`, `package-lock.json`, `requirements.txt`).
|
|
- Before upgrading your Garage cluster, make sure that you can find a version of this SDK that works with your targeted version and that you are able to update your own code to work with this new version of the library.
|
|
- Join our Matrix channel at `#garage:deuxfleurs.fr`, say that you are interested by this SDK, and report any friction.
|
|
- If stability is critical, mirror this repository on your own infrastructure, regenerate the SDKs and upgrade them at your own pace.
|
|
|
|
## For SDK users
|
|
|
|
The following languages are supported:
|
|
- [Python](#python)
|
|
- [Javascript](#javascript)
|
|
- [Golang](#golang)
|
|
|
|
### Python
|
|
|
|
You need at least Python 3.6, pip, and setuptools.
|
|
Because the python package is in a subfolder, the command is a bit more complicated than usual:
|
|
|
|
```bash
|
|
pip3 install --user 'git+https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-python'
|
|
```
|
|
|
|
Now, let imagine you have a fresh Garage instance running on localhost, with the admin API configured on port 3903 with the bearer `s3cr3t`:
|
|
|
|
```python
|
|
import garage_admin_sdk
|
|
from garage_admin_sdk.apis import *
|
|
from garage_admin_sdk.models import *
|
|
|
|
configuration = garage_admin_sdk.Configuration(
|
|
host = "http://localhost:3903/v0",
|
|
access_token = "s3cr3t"
|
|
)
|
|
|
|
# Init APIs
|
|
api = garage_admin_sdk.ApiClient(configuration)
|
|
nodes, layout, keys, buckets = NodesApi(api), LayoutApi(api), KeyApi(api), BucketApi(api)
|
|
|
|
# Display some info on the node
|
|
status = nodes.get_nodes()
|
|
print(f"running garage {status.garage_version}, node_id {status.node}")
|
|
|
|
# Change layout of this node
|
|
current = layout.get_layout()
|
|
layout.add_layout({
|
|
status.node: NodeClusterInfo(
|
|
zone = "dc1",
|
|
capacity = 1,
|
|
tags = [ "dev" ],
|
|
)
|
|
})
|
|
layout.apply_layout(LayoutVersion(
|
|
version = current.version + 1
|
|
))
|
|
|
|
# Create key, allow it to create buckets
|
|
kinfo = keys.add_key(AddKeyRequest(name="openapi"))
|
|
|
|
allow_create = UpdateKeyRequestAllow(create_bucket=True)
|
|
keys.update_key(kinfo.access_key_id, UpdateKeyRequest(allow=allow_create))
|
|
|
|
# Create a bucket, allow key, set quotas
|
|
binfo = buckets.create_bucket(CreateBucketRequest(global_alias="documentation"))
|
|
binfo = buckets.allow_bucket_key(AllowBucketKeyRequest(
|
|
bucket_id=binfo.id,
|
|
access_key_id=kinfo.access_key_id,
|
|
permissions=AllowBucketKeyRequestPermissions(read=True, write=True, owner=True),
|
|
))
|
|
binfo = buckets.update_bucket(binfo.id, UpdateBucketRequest(
|
|
quotas=UpdateBucketRequestQuotas(max_size=19029801,max_objects=1500)))
|
|
|
|
# Display key
|
|
print(f"""
|
|
cluster ready
|
|
key id is {kinfo.access_key_id}
|
|
secret key is {kinfo.secret_access_key}
|
|
bucket {binfo.global_aliases[0]} contains {binfo.objects}/{binfo.quotas.max_objects} objects
|
|
""")
|
|
```
|
|
|
|
*This example is named `short.py` in the example folder. Other python examples are also available.*
|
|
|
|
See also:
|
|
- [examples](./example/python)
|
|
- [generated doc](./garage-admin-sdk-python)
|
|
|
|
### Javascript
|
|
|
|
Install the SDK with:
|
|
|
|
```bash
|
|
npm install --save git+https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-js.git
|
|
```
|
|
|
|
A short example:
|
|
|
|
```javascript
|
|
const garage = require('garage_administration_api_v0garage_v0_8_0');
|
|
|
|
const api = new garage.ApiClient("http://127.0.0.1:3903/v0");
|
|
api.authentications['bearerAuth'].accessToken = "s3cr3t";
|
|
|
|
const [node, layout, key, bucket] = [
|
|
new garage.NodesApi(api),
|
|
new garage.LayoutApi(api),
|
|
new garage.KeyApi(api),
|
|
new garage.BucketApi(api),
|
|
];
|
|
|
|
node.getNodes().then((data) => {
|
|
console.log(`nodes: ${Object.values(data.knownNodes).map(n => n.hostname)}`)
|
|
}, (error) => {
|
|
console.error(error);
|
|
});
|
|
```
|
|
|
|
See also:
|
|
- [examples](./example/javascript)
|
|
- [generated doc](./garage-admin-sdk-js)
|
|
|
|
### Golang
|
|
|
|
Install the SDK with:
|
|
|
|
```bash
|
|
go get git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-golang
|
|
```
|
|
|
|
A short example:
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
"os"
|
|
garage "git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-golang"
|
|
)
|
|
|
|
func main() {
|
|
// Set Host and other parameters
|
|
configuration := garage.NewConfiguration()
|
|
configuration.Host = "127.0.0.1:3903"
|
|
|
|
|
|
// We can now generate a client
|
|
client := garage.NewAPIClient(configuration)
|
|
|
|
// Authentication is handled through the context pattern
|
|
ctx := context.WithValue(context.Background(), garage.ContextAccessToken, "s3cr3t")
|
|
|
|
// Send a request
|
|
resp, r, err := client.NodesApi.GetNodes(ctx).Execute()
|
|
if err != nil {
|
|
fmt.Fprintf(os.Stderr, "Error when calling `NodesApi.GetNodes``: %v\n", err)
|
|
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
|
|
}
|
|
|
|
// Process the response
|
|
fmt.Fprintf(os.Stdout, "Target hostname: %v\n", resp.KnownNodes[resp.Node].Hostname)
|
|
}
|
|
```
|
|
|
|
See also:
|
|
- [examples](./example/golang)
|
|
- [generated doc](./garage-admin-sdk-golang)
|
|
|
|
## For SDK developpers
|
|
|
|
PR are accepted for other languages as soon as good examples are provided.
|
|
Especially, we want them to be meaningful, manually written, and covering
|
|
a large range of the API. Thanks in advance :-)
|
|
|
|
### Clone this repo
|
|
|
|
```bash
|
|
git clone ...
|
|
git submodule update --init
|
|
```
|
|
|
|
### (Re)generate libraries
|
|
|
|
```bash
|
|
# Check the OpenAPI spec file
|
|
gradle validate
|
|
|
|
# (re)build the python client
|
|
gradle buildPythonClient
|
|
|
|
# (re)build the Go client
|
|
gradle buildGoClient
|
|
|
|
# (re)build the javascrit cient
|
|
gradle buildJavascriptClient
|
|
```
|
|
|
|
## Support a new language
|
|
|
|
Read the doc: https://openapi-generator.tech/docs/installation
|
|
We use the Gradle plugins: https://openapi-generator.tech/docs/plugins
|
|
Many generators exist: https://openapi-generator.tech/docs/generators
|