13. S3 Gateway

VDURA’s S3 gateway exposes tenant volumes over the S3 protocol. Configuration is split across five areas: per-tenant gateway config, realm-wide S3 administration (Platform Admin only), buckets, credential lookup, and the gateway instances themselves.

13.1 Tenant S3 Configuration

Endpoint Summary

GET /api/v1/tenants/{tenant_id}/s3

Get S3 config

Returns the S3 gateway configuration for the specified tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, GetS3ConfigResponse)

Example

{
   "s3_config" : {
      "default_dir_mode" : "755",
      "default_group" : "gid:65534",
      "default_obj_mode" : "644",
      "default_owner" : "uid:65534",
      "default_prefix" : "/vol1/t1",
      "enabled" : true,
      "tls" : {}
   }
}

PUT /api/v1/tenants/{tenant_id}/s3

Create S3 config

Creates the S3 gateway configuration for the specified tenant. 409 if a config already exists; callers needing replace semantics must DELETE first.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: S3ConfigCreateRequest

Request payload for creating a tenant’s S3 configuration.

Every field carries a default, so PUT /s3 {} is a complete request: it creates the disabled config with the empty prefix and the POSIX defaults a tenant starts with. Those defaults live here rather than in a factory beside the service, because this is the only place that can publish them - an operator reading the API document sees what an omitted field will be, and there is no second copy to drift from it.

access_key, secret_key and control_plane have no field here at all; :mod:app.use_cases.create_s3_config mints all three.

Example

{
   "aggregator" : {
      "enabled" : false
   },
   "default_dir_mode" : "755",
   "default_group" : "gid:65534",
   "default_obj_mode" : "644",
   "default_owner" : "uid:65534",
   "default_prefix" : "/vol1/t1",
   "enabled" : true,
   "tls" : {}
}

Responses

PATCH /api/v1/tenants/{tenant_id}/s3

Update S3 config

Partially updates the S3 gateway configuration for the specified tenant. The response names the fields of this request that already-running gateway instances will not pick up until they are restarted - empty when every change is in effect now, which includes a tenant with no started instance.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: S3ConfigPatchRequest

Request payload for partially updating a tenant’s S3 configuration.

At least one field must be provided. Null values are not allowed - omit fields that should not change.

Example

{
   "default_prefix" : "/vol1/t1",
   "enabled" : false
}

Responses

Response Body (200, S3ConfigUpdateResponse)

Example

{
   "restart_required" : [
      "access_log",
      "debug_log"
   ]
}

DELETE /api/v1/tenants/{tenant_id}/s3

Delete S3 config

Deletes the S3 gateway configuration for the specified tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

POST /api/v1/tenants/{tenant_id}/s3/tls/renew

Renew the realm-generated S3 edge cert

Forces a fresh mint of the tenant S3 edge certificate and stores it with the tenant’s S3 configuration. Manual operator action: renewal is not automated, so an operator runs this before the stored cert lapses. Valid only when tls.mode = realm-generated (the realm owns that cert); a tenant-provided cert is renewed by uploading a new one via PATCH /s3 and this returns 409. The minted SANs follow the tenant’s current aggregator.enabled state. Renewal disrupts nothing: a running gateway re-reads the cert and key without restarting. Authorization: gated on s3-config:update, like every other write to the tenant S3 config; the tenant admin and platform-admin both hold it.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

13.2 Realm-Wide S3 Administration

Endpoint Summary

GET /api/v1/s3/enabled

Get realm-wide S3 enable flag

Returns the realm-wide S3 enable flag. Distinct from the per-tenant s3 enabled toggle on /api/v1/tenants/{id}/s3/; this flag gates provisioning of any new tenant-level S3 state. A fresh realm reports enabled=false until the operator opts in via PUT.

Authentication: required (PasswordLogin or BearerJWT).

Responses

Response Body (200, S3EnabledResponse)

Example

{
   "enabled" : false,
   "tenants_with_s3_enabled" : [
      "tn1"
   ],
   "warning" : "1 tenant(s) still have S3 enabled at the tenant level"
}

PUT /api/v1/s3/enabled

Set realm-wide S3 enable flag

Sets the realm-wide S3 enable flag. A successful write takes effect on every node: turning S3 off stops every running S3 gateway instance; turning it back on re-applies per-tenant intent and brings the gateways back up. Per-tenant enabled records are preserved across both transitions. Disabling while at least one tenant has tenant-level S3 enabled is permitted but surfaces a warning listing the still-enabled tenants in the response.

Authentication: required (PasswordLogin or BearerJWT).

Request Body (application/json, required)

Schema: S3EnabledRequest

Request body for PUT /s3/enabled.

Example

{
   "enabled" : true
}

Responses

Response Body (200, S3EnabledResponse)

Example

{
   "enabled" : false,
   "tenants_with_s3_enabled" : [
      "tn1"
   ],
   "warning" : "1 tenant(s) still have S3 enabled at the tenant level"
}

GET /api/v1/s3/prefix

Get realm-wide S3 prefix path

Returns the realm-wide S3 prefix path that anchors per-tenant prefixes under a common root. Distinct from the per-tenant default_prefix carried on /api/v1/tenants/{id}/s3/. A fresh realm reports the empty string until the operator sets a value.

Authentication: required (PasswordLogin or BearerJWT).

Responses

Response Body (200, S3PrefixResponse)

Example

{
   "prefix" : "/realm-root"
}

PUT /api/v1/s3/prefix

Set realm-wide S3 prefix path

Sets the realm-wide S3 prefix path. Non-empty values MUST begin with “/” and MUST NOT carry trailing whitespace. An empty string clears the prefix.

Authentication: required (PasswordLogin or BearerJWT).

Request Body (application/json, required)

Schema: S3PrefixRequest

Request body for PUT /s3/prefix.

Example

{
   "prefix" : "/realm-root"
}

Responses

Response Body (200, S3PrefixResponse)

Example

{
   "prefix" : "/realm-root"
}

13.3 S3 Buckets

Endpoint Summary

GET /api/v1/tenants/{tenant_id}/s3/buckets

List S3 buckets

List the tenant’s S3 buckets, as a running gateway reports them.

The gateway is the only bucket catalogue, so a tenant with no running instance cannot be listed: that is a 503, never an empty list.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, ListS3BucketsResponse)

POST /api/v1/tenants/{tenant_id}/s3/buckets

Create S3 bucket

Create an S3 bucket on a running gateway, owned by the PanFS user the request names.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: S3BucketCreateRequest

Request payload for creating an S3 bucket.

Example

{
   "name" : "my-bucket",
   "owner" : "alice"
}

Responses

DELETE /api/v1/tenants/{tenant_id}/s3/buckets/{name}

Delete S3 bucket

Delete an S3 bucket from a running gateway.

A non-empty bucket returns 409 and stays listed. A bucket the gateway does not hold is a 404, unless an earlier attempt of this same request may have deleted it.

Authorization is the s3-buckets:delete verb plus caller-tenant scoping, like every other operation on this surface. Deletion is NOT conditioned on the caller having created the bucket.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

13.4 S3 Credentials

Endpoint Summary

POST /api/v1/tenants/{tenant_id}/s3-credentials/{access_key}/reveal

Resolve an S3 access key to the identity behind it

Return the credential behind an access key, with the profile and POSIX ids that go with it - everything an auth.Account needs, because the access key is the only handle the data plane holds and a second lookup would cost a round trip per IAM cache miss. Called by the S3 gateway on that miss, through POST /s3/gateway/s3-credentials/{access_key}/reveal, and gated on fs-users:read-s3-secret. A disabled user answers 404, which the gateway maps to its no-such-user error.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, S3CredentialsRevealResponse)

Example

{
   "access_key" : "alice",
   "gid" : 65534,
   "profile" : "user",
   "secret_key" : "7f9a3d2e8c1b4a6f0d5e2c8b9f1a3d7e",
   "uid" : 65534
}

13.5 S3 Gateway Instances

Endpoint Summary

GET /api/v1/tenants/{tenant_id}/s3/instances

List a tenant’s S3 gateway instances

Return every instance of the tenant with its observed/health merged in.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, S3InstanceListResponse)

POST /api/v1/tenants/{tenant_id}/s3/instances

Create an S3 gateway instance

Writes the desired-state record for a new S3 gateway instance placed on the specified node. The instance starts in desired=created; use the start endpoint to bring it online. At most one instance per tenant per node, and the tenant must have a subnet: the gateway binds inside the tenant network namespace, which a tenant with no subnet does not have.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: S3InstanceCreateRequest

Create a new S3 gateway instance for a tenant on a specific node.

Example

{
   "dataserial" : "08823f71a1eecc",
   "instance_id" : "abc12"
}

Responses

Response Body (201, S3InstanceCreateResponse)

POST /api/v1/tenants/{tenant_id}/s3/instances/delete-all

Delete every instance of the tenant and wait for teardown

Fan out desired=deleting to every (iid, data_serial) owned by the tenant and block until the owning node has removed each instance record, which is the terminal state, or until timeout seconds elapse. Intended as the companion to the DELETE /api/v1/tenants/{id} guard: an operator runs delete-all first, waits for it to succeed, then deletes the tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, S3InstanceFanoutResponse)

POST /api/v1/tenants/{tenant_id}/s3/instances/start-all

Start every instance of the tenant

Records the new desired state of every instance of the tenant and returns without waiting for them to reach it. Poll GET /tenants/{tenant_id}/s3/instances for the observed state.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (202, S3InstanceFanoutResponse)

POST /api/v1/tenants/{tenant_id}/s3/instances/stop-all

Stop every instance of the tenant

Records the new desired state of every instance of the tenant and returns without waiting for them to reach it. Poll GET /tenants/{tenant_id}/s3/instances for the observed state.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (202, S3InstanceFanoutResponse)

GET /api/v1/tenants/{tenant_id}/s3/instances/{iid}

Show an S3 gateway instance (bare-iid fan-out or specific node)

Return one or many matching rows as a per-node result set.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, S3InstanceFanoutResponse)

DELETE /api/v1/tenants/{tenant_id}/s3/instances/{iid}

Delete an S3 gateway instance (fan-out if node omitted; requires confirm)

If dataserial is omitted and more than one node hosts a matching iid, confirm=true is required; otherwise the API returns 409 and a preview body listing the matches, so the caller can decide whether to proceed.

Records the delete and returns without waiting for the instance to be removed. Poll GET /tenants/{tenant_id}/s3/instances/{iid} until it answers 404: the instance is gone. If the delete named a dataserial, poll with the same dataserial: without it the GET still answers for the placements on other nodes.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (202, S3InstanceFanoutResponse)

POST /api/v1/tenants/{tenant_id}/s3/instances/{iid}/start

Start an S3 gateway instance (fan-out if node omitted)

Records the new desired state and returns without waiting for the instance to reach it. Poll GET /tenants/{tenant_id}/s3/instances/{iid} for the observed state.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (202, S3InstanceFanoutResponse)

POST /api/v1/tenants/{tenant_id}/s3/instances/{iid}/stop

Stop an S3 gateway instance (fan-out if node omitted)

Records the new desired state and returns without waiting for the instance to reach it. Poll GET /tenants/{tenant_id}/s3/instances/{iid} for the observed state.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (202, S3InstanceFanoutResponse)