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
Javascript
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:

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:

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/v1",
  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([
  NodeRoleChange(
    id = status.node,
    zone = "dc1",
    capacity = 1000000000,
    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.

Javascript

Install the SDK with:

npm install --save git+https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-js.git

A short example:

const garage = require('garage_administration_api_v1garage_v0_9_0');

const api = new garage.ApiClient("http://127.0.0.1:3903/v1");
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);
});

Golang

Install the SDK with:

go get git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-golang

A short example:

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)
}

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

git clone ...
git submodule update --init

(Re)generate libraries

# 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

6.2 KiB Raw Blame History