Skip to content

secretmanager.md

Latest commit

 

History

History
213 lines (145 loc) · 4.72 KB

secretmanager.md

File metadata and controls

213 lines (145 loc) · 4.72 KB
Raw

Secret Manager

Cloudbox emulates the Secret Manager REST API (v1). The google-cloud-secret-manager Python SDK works against it without modification.

Connection

Port: 8090 (override with CLOUDBOX_SECRET_MANAGER_PORT)

from google.api_core.client_options import ClientOptions
from google.auth.credentials import AnonymousCredentials
from google.cloud import secretmanager

client = secretmanager.SecretManagerServiceClient(
    credentials=AnonymousCredentials(),
    client_options=ClientOptions(api_endpoint="http://localhost:8090"),
)

Secrets

Create secret

POST /v1/projects/{project}/secrets?secretId={id}

{
  "replication": { "automatic": {} },
  "labels": { "env": "local" }
}

The secretId must be provided as a query parameter or in the body. Returns the secret resource. 409 if the secret already exists.

Get secret

GET /v1/projects/{project}/secrets/{secret_id}

Returns the secret metadata. 404 if not found.

List secrets

GET /v1/projects/{project}/secrets?pageSize=25&pageToken=

Returns { "secrets": [...], "nextPageToken": "...", "totalSize": N }.

Update secret (patch labels)

PATCH /v1/projects/{project}/secrets/{secret_id}

{ "labels": { "updated": "true" } }

Currently only labels can be updated. Returns the updated secret resource.

Delete secret

DELETE /v1/projects/{project}/secrets/{secret_id}

Deletes the secret and all its versions. Returns {}.

Secret versions

Secret values are stored as versions. Each addVersion call creates a new numbered version. The latest version is always accessible via the special alias "latest".

Add version

POST /v1/projects/{project}/secrets/{secret_id}:addVersion

{
  "payload": {
    "data": "bXktc2VjcmV0LXZhbHVl"
  }
}

payload.data must be base64-encoded. Returns the newly created version resource with state: ENABLED.

Version numbers are sequential integers starting at 1.

Access (read) version payload

POST /v1/projects/{project}/secrets/{secret_id}/versions/{version_id}:access

version_id may be a version number ("1", "2") or the alias "latest".

Returns:

{
  "name": "projects/local-project/secrets/my-secret/versions/1",
  "payload": { "data": "bXktc2VjcmV0LXZhbHVl" }
}

403 if the version is disabled or destroyed.

Get version metadata

GET /v1/projects/{project}/secrets/{secret_id}/versions/{version_id}

Returns version metadata without the payload. Supports "latest" alias.

List versions

GET /v1/projects/{project}/secrets/{secret_id}/versions?pageSize=25&pageToken=&filter=

Optional filter parameter accepts state=ENABLED, state=DISABLED, or state=DESTROYED to narrow results.

Returns { "versions": [...], "nextPageToken": "...", "totalSize": N }.

Disable version

POST /v1/projects/{project}/secrets/{secret_id}/versions/{version_id}:disable

Sets the version state to DISABLED. Disabled versions cannot be accessed. Returns the updated version resource.

Enable version

POST /v1/projects/{project}/secrets/{secret_id}/versions/{version_id}:enable

Sets the version state back to ENABLED. Returns the updated version resource.

Destroy version

POST /v1/projects/{project}/secrets/{secret_id}/versions/{version_id}:destroy

Sets the version state to DESTROYED and wipes the payload permanently. Returns the updated version resource.

Version states

State Description
ENABLED Active — payload can be accessed
DISABLED Suspended — access returns 403
DESTROYED Permanently deleted — payload is gone

Secret resource fields

Field Type Description
name string Full resource name: projects/{project}/secrets/{id}
replication object Replication policy (stored but not enforced)
labels object User-defined key-value labels
createTime string RFC 3339 creation timestamp

Version resource fields

Field Type Description
name string Full resource name including version number
createTime string RFC 3339 creation timestamp
state string ENABLED, DISABLED, or DESTROYED

Known limitations

Feature Notes
CMEK (customer-managed encryption) Payloads are stored as plaintext; kmsKeyName field accepted but not enforced
Rotation notifications Pub/Sub rotation notifications not published on addVersion
IAM (getIamPolicy / setIamPolicy) Not implemented
Replication policies replication field is accepted and stored but not enforced

Examples

uv run python examples/secretmanager/basic.py