Deployment configuration¶
Use Admin to manage an installation interactively. To manage endpoints or selected feature switches from Compose, Helm, or CI, apply a versioned deployment manifest. All runtimes sharing the installation database use the applied values and locks.
Local runtime surfaces¶
DEPLOYMENT_PROFILE selects the local profile. Its default surfaces are:
| Profile | Surfaces |
|---|---|
full |
admin, ceph_admin, storage_ops, manager, portal, browser |
admin |
admin, ceph_admin, storage_ops |
user |
manager, portal, browser |
Set RUNTIME_SURFACES to a JSON array, or set the Helm value runtimeSurfaces
to a YAML list. The full profile accepts any subset. The admin profile can
omit ceph_admin. The user profile has a fixed set of surfaces. Portal requires
both a runtime exposing portal and the shared portal_enabled setting.
Apply a revision¶
Save the manifest as JSON. For example:
{
"schema_version": 1,
"revision": 1,
"features": {"portal_enabled": true},
"storage_endpoints": [
{
"key": "primary-rgw",
"name": "Primary RGW",
"endpoint_url": "https://s3.example.com",
"provider": "ceph",
"service_identity_mode": "managed",
"is_default": true,
"features": {"admin": {"enabled": true}},
"credentials": {
"admin": {
"access_key_file": "/deployment/credentials/admin-access-key",
"secret_key_file": "/deployment/credentials/admin-secret-key"
}
}
}
]
}
Use a positive, increasing revision for the installation. Omit a section or
feature key to retain its existing management policy. A Boolean value sets and
locks a feature. Use null to make a feature or the inventory editable while
preserving its current values. The supported switches are manager_enabled,
managed_rgw_accounts_enabled, managed_rgw_users_enabled,
shared_s3_connections_enabled, private_s3_connections_enabled,
openstack_enabled, ceph_admin_enabled, storage_ops_enabled,
browser_enabled, portal_enabled, cost_enabled, and endpoint_status_enabled.
On a fresh installation, direct RGW Account management is enabled. Standalone RGW Users, shared Admin-managed S3 connections, private user-owned S3 connections, and OpenStack Clouds are disabled until explicitly enabled.
A storage_endpoints list must cover every registered endpoint. An empty list
locks an empty inventory. Give each entry a stable key containing 1–64 lowercase
letters, digits, underscores or hyphens, starting with a letter or digit.
An existing endpoint without a key is adopted by its current URL. Later
revisions identify it by key and can change its URL without changing its ID.
The first entry becomes the default when the list declares none explicitly.
Keep secret values in files readable by the provisioning process. Configure the
admin, runtime, supervision, and ceph_admin pairs under credentials
as required by the Ceph endpoint configuration.
Each pair references an absolute access_key_file and secret_key_file. Apply a
new revision when replacing credentials, including when file paths stay the same.
Use the same database and credential key ring as the application:
Omit --file to read inline JSON from DEPLOYMENT_CONFIG. The command prepares
the database schema and reports the applied revision. Exit status 2 means the
revision is applied and one or more endpoint identities still need attention.
Correct RGW connectivity or permissions and rerun the same revision to resume.
Invalid or stale revisions exit with status 1. To restore earlier values, submit
them as a newer revision.
To remove an endpoint or change its provider or identity mode, apply
"storage_endpoints": null, complete the operation in Admin, then apply a
new manifest covering the resulting inventory. Existing associations remain
subject to the Admin deletion safeguards.
Compose and Helm¶
With Compose, set DEPLOYMENT_CREDENTIALS_DIR to a host directory containing
the referenced credential files. The one-shot service mounts it read-only at
/deployment/credentials. Use the same Compose project and env file as the
installation. In a split, run it from the Admin project only. The manifest can
be supplied inline with DEPLOYMENT_CONFIG:
DEPLOYMENT_CONFIG="$(cat deployment-config/manifest.json)" \
docker compose --profile provision run --rm configure-deployment
Alternatively, mount a directory containing both the manifest and its
credentials/ subdirectory and pass --file explicitly:
docker compose --profile provision run --rm \
--volume "$PWD/deployment-config:/deployment:ro" \
configure-deployment --file /deployment/manifest.json
For Helm, supply an existing, preferably immutable, ConfigMap containing
manifest.json and, when needed, an existing Secret with the referenced files:
deploymentConfiguration:
enabled: true
revision: "1"
manifestConfigMap: bucketreef-config-1
credentialSecret: bucketreef-rgw-1
The Job mounts the Secret at /deployment/credentials and runs from the Admin
or full release. Make PostgreSQL, the ConfigMap, Secrets and network access
available before creating the Job. The Job applies migrations before the
manifest. On first installation or a coordinated cutover, render and apply
templates/deployment-configuration-job.yaml in a pipeline stage, wait for Job
completion, then deploy the app releases with Job creation disabled. With GitOps
you can order these stages explicitly. For existing compatible backends, Helm can
also manage the Job as part of an upgrade. Use a new revision and ConfigMap for
each configuration change. A Helm rollback affects the workloads. Restoring the
database configuration requires a new manifest revision.
Migrate from environment overrides¶
- Record the effective features that you want to keep, the existing endpoint IDs, and the environment of each runtime. Back up the database and preserve the credential key ring together. Test the upgrade against an isolated copy.
- Remove
FEATURE_*_ENABLEDandENV_STORAGE_ENDPOINTSfrom your deployment files. For a split, keep the existing profile selectors and useRUNTIME_SURFACESonly for explicit local exceptions. For a full deployment, translate any deliberately restricted surface set intoRUNTIME_SURFACES. The oldFEATURE_ADMIN_ENABLEDmaps to local surface exposure only. - Put any required global values in
features. For example, use"features": {"portal_enabled": true}if the User backend served Portal. Use each feature's persisted field name in the manifest. Values forced by the old environment could differ from those stored in the database. - Convert the old endpoint array to
storage_endpoints. The migration gives previously locked rows the keyendpoint-<id>. Use that exact key for each of those rows. Give the remaining rows new keys and use their current URLs for adoption. Convert inline credential pairs to secret file references. Keep every existing endpoint in the first managed manifest. - Stop all old backends sharing the database. Apply revision 1 with the new
image before starting the new Admin and User backends. If you want to take
ownership through Admin, apply an explicit
"storage_endpoints": nullinstead. The migration preserves the prior inventory lock even when the new runtime starts without any provisioning environment variables. - Verify the endpoint IDs, default endpoint, locks, and Portal access from both profiles. For rollback to binaries from before this change, use the verified pre-upgrade database and credential key ring.