Garage
@thomas/garagev2026.10.11.1
01README
Control-plane administration of a Garage (S3-compatible object store) cluster through its Admin API v2 (bearer token). Reads cluster health, buckets, access keys, and the full key×bucket permission matrix. Creates, updates and deletes buckets; manages aliases; creates, imports, updates, rotates and deletes access keys; and grants or revokes read/write/owner permissions. Never touches S3 object data; delete and revoke methods verify the target by id first.
02Behaviors
@thomas/garagev2026.10.11.1garage.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| endpoint | string | Base URL of the Garage Admin API, e.g. http://garage-host:3903 or an HTTPS |
| adminToken | string | Garage [admin] admin_token (Bearer). Supply via vault: |
| s3Region? | string | S3 region label this cluster advertises (informational; echoed in output) |
fn cluster_health()
Fetch cluster health (status, node + partition counts). Read-only.
fn bucket_list()
List buckets, enriched with usage/quotas/per-key permissions (factory: one
fn bucket_get(id?: string, globalAlias?: string, search?: string)
Get one bucket by exactly one of id, globalAlias or search (full detail). Read-only.
| Argument | Type | Description |
|---|---|---|
| id? | string | Bucket id (exact) |
| globalAlias? | string | Global alias to look up |
| search? | string | Partial id/alias to search |
fn key_list()
List access keys (id/name/expiry; factory: one `key` per key). Read-only.
fn key_get(id?: string, search?: string, showSecretKey?: boolean)
Get one access key by exactly one of id or search, with the buckets it can reach.
| Argument | Type | Description |
|---|---|---|
| id? | string | Access key id (exact) |
| search? | string | Partial id/name to search |
| showSecretKey? | boolean | Include the secret access key in output (sensitive: stored in a vault, the data keeps a reference) |
fn permissions_audit()
Build the full key×bucket permission matrix and risk flags (orphan keys,
fn bucket_create(globalAlias?: string, localAlias?: string, localAliasAccessKeyId?: string, localAliasRead?: boolean, localAliasWrite?: boolean, localAliasOwner?: boolean)
Create a bucket with a global (or local) alias. Idempotent on globalAlias:
| Argument | Type | Description |
|---|---|---|
| globalAlias? | string | Global alias for the new bucket (the usual case) |
| localAlias? | string | Local alias name (requires localAliasAccessKeyId) |
| localAliasAccessKeyId? | string | Access key the local alias belongs to |
| localAliasRead? | boolean | Grant the local alias's key read on the new bucket |
| localAliasWrite? | boolean | Grant the local alias's key write on the new bucket |
| localAliasOwner? | boolean | Grant the local alias's key owner on the new bucket |
fn bucket_update(id: string, websiteEnabled?: boolean, indexDocument?: string, errorDocument?: string)
Update a bucket's quotas and/or static-website config (UpdateBucket).
| Argument | Type | Description |
|---|---|---|
| id | string | Bucket id to update |
| websiteEnabled? | boolean | Enable/disable static website serving |
| indexDocument? | string | Website index document key |
| errorDocument? | string | Website error document key |
fn bucket_delete(id: string, allowNonEmpty?: boolean)
Delete a bucket BY ID (verified to exist first; refuses a non-empty bucket
| Argument | Type | Description |
|---|---|---|
| id | string | Bucket id to delete (verified to exist first) |
| allowNonEmpty? | boolean | Attempt deletion even if the bucket reports objects (Garage will still refuse a non-empty bucket) |
fn bucket_alias_add(bucketId: string, globalAlias?: string, localAlias?: string, accessKeyId?: string)
Add a global or local alias to a bucket (AddBucketAlias). An alias
| Argument | Type | Description |
|---|---|---|
| bucketId | string | Bucket id |
| globalAlias? | string | Global alias to add/remove |
| localAlias? | string | Local alias to add/remove |
| accessKeyId? | string | Access key the local alias belongs to (required for localAlias) |
fn bucket_alias_remove(bucketId: string, globalAlias?: string, localAlias?: string, accessKeyId?: string)
Remove a global or local alias from a bucket (RemoveBucketAlias).
| Argument | Type | Description |
|---|---|---|
| bucketId | string | Bucket id |
| globalAlias? | string | Global alias to add/remove |
| localAlias? | string | Local alias to add/remove |
| accessKeyId? | string | Access key the local alias belongs to (required for localAlias) |
fn key_create(name?: string, allowCreateBucket?: boolean, expiration?: string, neverExpires?: boolean)
Create a new access key. The secret is returned on `key-result`
| Argument | Type | Description |
|---|---|---|
| name? | string | Human-readable key name |
| allowCreateBucket? | boolean | Permit this key to create buckets |
| expiration? | string | RFC 3339 expiry timestamp (omit + neverExpires=true for no expiry) |
| neverExpires? | boolean | Key never expires. false needs expiration: a new key has no expiry otherwise. |
fn key_import(accessKeyId: string, secretAccessKey: string, name?: string)
Import a pre-existing access key pair (ImportKey) — e.g. to recreate a key
| Argument | Type | Description |
|---|---|---|
| accessKeyId | string | Existing access key id to import |
| secretAccessKey | string | Matching secret access key |
| name? | string | Human-readable key name |
fn key_update(id: string, name?: string, allowCreateBucket?: boolean, expiration?: string, neverExpires?: boolean)
Update a key's name, create-bucket permission, and/or expiry (UpdateKey).
| Argument | Type | Description |
|---|---|---|
| id | string | Access key id to update |
| name? | string | New name |
| allowCreateBucket? | boolean | Set/clear the create-bucket permission |
| expiration? | string | New RFC 3339 expiry |
| neverExpires? | boolean | true clears the expiry. false does nothing; set expiration instead. |
fn key_rotate(id: string, name?: string)
Rotate a key: create a NEW key, copy the OLD key's bucket grants and
| Argument | Type | Description |
|---|---|---|
| id | string | Access key id to rotate (the OLD key) |
| name? | string | Name for the new key; defaults to the old key's name + ' (rotated)' |
fn key_delete(id: string)
Delete an access key BY ID (verified to exist first). A key that is
| Argument | Type | Description |
|---|---|---|
| id | string | Access key id to delete (verified to exist first) |
fn key_allow(bucketId: string, accessKeyId: string, read?: boolean, write?: boolean, owner?: boolean)
Grant read/write/owner on a bucket to a key (AllowBucketKey). Idempotent.
| Argument | Type | Description |
|---|---|---|
| bucketId | string | Bucket id |
| accessKeyId | string | Access key id |
| read? | boolean | Read permission |
| write? | boolean | Write permission |
| owner? | boolean | Owner permission (manage aliases, quotas, website) |
fn key_deny(bucketId: string, accessKeyId: string, read?: boolean, write?: boolean, owner?: boolean)
Revoke read/write/owner on a bucket from a key (DenyBucketKey). Each flag
| Argument | Type | Description |
|---|---|---|
| bucketId | string | Bucket id |
| accessKeyId | string | Access key id |
| read? | boolean | Read permission |
| write? | boolean | Write permission |
| owner? | boolean | Owner permission (manage aliases, quotas, website) |
fn cluster_status()
Cluster status: this node's id, Garage version, layout version, and every
fn layout_get()
Get the current cluster layout — assigned roles plus any staged changes. Read-only.
fn layout_assign(nodeId: string, zone?: string, tags?: array, zoneRedundancy?: string)
STAGE a role for a node (zone, storage capacity in bytes or null for gateway,
| Argument | Type | Description |
|---|---|---|
| nodeId | string | Node id to assign a role to (from cluster_status) |
| zone? | string | Zone/datacenter label for the node. Omit to keep the node's current zone |
| tags? | array | Node tags. Omit to keep the node's current tags (none for a node with no role yet). |
| zoneRedundancy? | string | Cluster zone redundancy: "maximum" or a positive integer (atLeast N). Omit to leave unchanged. |
fn layout_apply()
Commit staged layout changes (ApplyClusterLayout). Defaults to the current
fn layout_revert()
Discard all staged (un-applied) layout changes (RevertClusterLayout).
fn cluster_init(nodeId?: string, zone?: string, tags?: array, zoneRedundancy?: string, force?: boolean)
First-boot convenience: assign a storage role to the node (defaults to the
| Argument | Type | Description |
|---|---|---|
| nodeId? | string | Node to configure; defaults to the responding node (correct for a single-node cluster) |
| zone? | string | Zone/datacenter label |
| tags? | array | Optional node tags |
| zoneRedundancy? | string | "maximum" or a positive integer (atLeast N); omit for the cluster default |
| force? | boolean | Re-initialise even if the layout already has assigned roles |
Resources
cluster-health(1h)— Cluster health snapshot (status, node + partition counts)
bucket(infinite)— A bucket (aliases, usage, quotas, and per-key permissions)
key(infinite)— An access key (attributes + the buckets it can reach)
permission-audit(infinite)— Full key×bucket permission matrix plus risk flags
bucket-result(infinite)— Result of a bucket create/update/delete/alias operation
key-result(infinite)— Result of a key create/import/update/rotate/delete (may carry the secret, vaulted)
permission-result(infinite)— Result of a key allow/deny on a bucket
cluster-status(1h)— Cluster status (this node id, version, and all nodes/roles)
cluster-layout(1h)— Current cluster layout (assigned roles + staged changes)
layout-result(infinite)— Result of a layout stage/apply/revert or cluster_init
03Previous Versions
2026.06.24.1
04Stats
A
93 / 100
Downloads
32
Archive size
35.9 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License1/2partial
no SPDX license declared
- Verified public repository2/2earned
05Platforms
06Labels