garage-admin-sdk-generator/README.md

175 lines
5 KiB
Markdown
Raw Normal View History

2022-09-13 14:00:03 +00:00
# Garage Admin SDK
2022-09-12 15:02:35 +00:00
2022-11-13 13:37:55 +00:00
Operate your Garage cluster programatically
2022-11-13 13:52:24 +00:00
## ⚠️ 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`).
- Join our Matrix channel at `#garage:deuxfleurs.fr`, say that you are interested by this SDK, and report any friction.
2022-11-13 13:55:01 +00:00
- If stability is critical, mirror this repository on your own infrastructure, regenerate the SDKs and upgrade them at your own pace.
2022-11-13 13:52:24 +00:00
2022-09-13 15:54:05 +00:00
## For SDK users
2022-11-13 13:37:55 +00:00
The following languages are supported:
- [Python](#python)
- [Javascript](#javascript)
2022-11-13 13:52:24 +00:00
- [Golang](#golang)
2022-09-13 15:54:05 +00:00
### 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
2022-11-13 13:24:06 +00:00
pip3 install --user 'git+https://git.deuxfleurs.fr/quentin/garage-admin-sdk-python'
2022-09-13 15:54:05 +00:00
```
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
2022-11-12 21:48:50 +00:00
from garage_admin_sdk.apis import *
from garage_admin_sdk.models import *
2022-09-13 15:54:05 +00:00
configuration = garage_admin_sdk.Configuration(
host = "http://localhost:3903/v0",
access_token = "s3cr3t"
2022-09-13 15:54:05 +00:00
)
# 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({
2022-09-28 18:26:01 +00:00
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
2022-11-12 22:16:11 +00:00
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),
))
2022-11-12 22:16:11 +00:00
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}
2022-11-12 22:16:11 +00:00
bucket {binfo.global_aliases[0]} contains {binfo.objects}/{binfo.quotas.max_objects} objects
""")
2022-09-13 15:54:05 +00:00
```
*This example is named `short.py` in the example folder. Other python examples are also available.*
See also:
2022-11-13 13:37:55 +00:00
- [examples](./example/python)
- [generated doc](./garage-admin-sdk-python)
### Javascript
Install the SDK with:
```bash
npm install --save git+https://git.deuxfleurs.fr/quentin/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)
2022-09-13 15:54:05 +00:00
2022-11-13 13:52:24 +00:00
### Golang
See also:
- [examples](./example/golang)
- [generated doc](./garage-admin-sdk-golang)
2022-09-13 15:54:05 +00:00
## For SDK developpers
2022-11-13 13:55:01 +00:00
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 :-)
2022-09-13 15:54:05 +00:00
### Clone this repo
2022-09-12 15:02:35 +00:00
2022-09-13 14:00:03 +00:00
```bash
git clone ...
2022-09-14 13:45:21 +00:00
git submodule update --init
2022-09-12 15:02:35 +00:00
```
2022-09-13 14:00:03 +00:00
2022-09-13 15:54:05 +00:00
### (Re)generate libraries
2022-09-13 14:00:03 +00:00
```bash
# Check the OpenAPI spec file
gradle validate
# (re)build the python client
gradle buildPythonClient
2022-11-13 13:52:24 +00:00
# (re)build the Go client
gradle buildGoClient
# (re)build the javascrit cient
gradle buildJavascriptClient
2022-09-12 15:02:35 +00:00
```
2022-09-13 15:54:05 +00:00
## 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