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
8 months ago
example Update the rest of the repo to the new URL 11 months ago
garage@30f1636a00 include int64 patch 8 months ago
garage-admin-sdk-golang@c965fe7f7d include int64 patch 8 months ago
garage-admin-sdk-js@635d3c1517 Update the rest of the repo to the new URL 11 months ago
garage-admin-sdk-python@f48df53ba2 Update the rest of the repo to the new URL 11 months ago
.gitignore Improve code generation 1 year ago
.gitmodules Update submodules address 11 months ago Update README with new values 11 months ago
build.gradle Update the rest of the repo to the new URL 11 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: