You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Quentin 4b0dc1c25b
include int64 patch
2 months ago
example Update the rest of the repo to the new URL 4 months ago
garage@30f1636a00 include int64 patch 2 months ago
garage-admin-sdk-golang@c965fe7f7d include int64 patch 2 months ago
garage-admin-sdk-js@635d3c1517 Update the rest of the repo to the new URL 4 months ago
garage-admin-sdk-python@f48df53ba2 Update the rest of the repo to the new URL 4 months ago
.gitignore Improve code generation 6 months ago
.gitmodules Update submodules address 4 months ago Update README with new values 4 months ago
build.gradle Update the rest of the repo to the new URL 4 months ago

Garage Admin SDK

Operate your Garage cluster programatically


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


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+'

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/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()
  status.node: NodeClusterInfo(
    zone = "dc1",
    capacity = 1,
    tags = [ "dev" ],
  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(,
  permissions=AllowBucketKeyRequestPermissions(read=True, write=True, owner=True),
binfo = buckets.update_bucket(, UpdateBucketRequest(

# Display key
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 in the example folder. Other python examples are also available.

See also:


Install the SDK with:

npm install --save git+

A short example:

const garage = require('garage_administration_api_v0garage_v0_8_0');

const api = new garage.ApiClient("");
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) => {

See also:


Install the SDK with:

go get

A short example:

package main

import (
    garage ""

func main() {
    // Set Host and other parameters
    configuration := garage.NewConfiguration()
    configuration.Host = ""

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

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:
We use the Gradle plugins:
Many generators exist: