Operations: Upgrade and Compatibility Notes¶
Shared deployment configuration¶
This release changes the deployment contract for FEATURE_*_ENABLED and
ENV_STORAGE_ENDPOINTS. Convert local surfaces and shared configuration before
restarting upgraded runtimes. Follow the migration procedure.
Existing endpoint records and associations are preserved by the database migration.
2026-11 managed resource feature switches¶
Migration 0272_resource_feature_switches adds independent global switches for
direct RGW Account management, standalone RGW Users, shared Admin-managed S3
connections, and private user-owned S3 connections. Existing installations
materialize all four switches as enabled so their current capabilities remain
available after upgrade. Explicit values already present in application settings
are preserved.
Fresh installations use the model defaults. RGW Accounts are enabled, while RGW
Users, shared S3 connections, and private S3 connections are disabled. The
existing openstack_enabled value is not changed by this migration.
2026-11 canonical Portal server access-log filter rules¶
Portal server access-log advanced filters now validate each rule's value shape
at the API boundary. in and not_in require list values, scalar operators
reject list values, and null checks reject a supplied value.
The access-log matcher now relies on that validated contract directly instead of keeping silent fallback branches for impossible fields or operators.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical Ceph Admin identity filter rules¶
Ceph Admin account and RGW user advanced filters now validate each field's
supported operators and value shape at the API boundary. Text, boolean, and
numeric fields accept only their matching operator families; in and not_in
require list values, scalar operators reject list values, and null checks reject
a supplied value.
Identity listing enrichment now derives its required profile, quota, status, limits, stats, and usage sources only from fields that the validated filter contract can actually contain.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical advanced bucket filter rules¶
Shared Ceph Admin and Storage Ops advanced bucket filters now validate field
operators and value shapes at the API boundary. Text, boolean, numeric, and tag
fields accept only their supported operators; in and not_in require list
values, scalar operators reject list values, and null checks reject a supplied
value. Feature-parameter rules likewise reject list values when the parameter
requires one scalar value.
The matching backend now consumes these validated rules directly instead of carrying fallback behavior for missing fields, operators, feature parameters, or unsupported combinations. The bundled frontend builds the same typed rule contract.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical bucket listing sort contract¶
The shared Ceph Admin and Storage Ops bucket listing contract now validates
sort_by against name, tenant, owner, used_bytes, and object_count.
It also validates ui_tag_match as any or all. Unknown values are rejected
at request validation instead of silently falling back to name sorting or
any tag matching.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical Ceph Admin identity sorting¶
Ceph Admin account and user listings now validate sort_by against the fields
offered by their bundled frontend tables. Unknown sort fields are rejected at
request validation instead of silently falling back to the account ID or user
UID. The retired account name alias is removed; use account_name.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical Admin MFA reset response¶
POST /api/admin/users/{user_id}/mfa/reset now returns 204 No Content after
the reset succeeds. The bundled frontend already treats the operation as a
command and does not consume a response payload.
Passkey-enrollment requirements and removed passkey, recovery-code, and challenge counts remain recorded in the security audit. The operator recovery CLI retains the same detailed reset result for its audit entry.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical Storage Endpoint credential replacement¶
Storage Endpoint editing and onboarding now use one credential-pair contract for Admin, Runtime, Supervision, and Ceph Admin identities. Leaving both fields blank reuses a complete stored pair when the endpoint target is unchanged. Supplying replacement credentials requires both the access key and secret key.
Admin access keys are no longer pre-populated in edit forms or echoed by onboarding validation. Feature detection no longer accepts the historical access-key-only payload that matched a submitted Admin access key to the stored secret.
Deploy the backend and bundled frontend together. No database migration is required because persisted Storage Endpoint credentials are unchanged.
2026-11 canonical Portal Storage Space provenance¶
Migration 0262_canonical_portal_storage_space_origin converts any historical
portal_storage_space_metadata.origin value outside portal_generic,
portal_named, and imported to imported, preserving the runtime behavior
previously provided by a compatibility fallback. It then adds a database check
constraint so future rows cannot reintroduce non-canonical provenance values.
The runtime now consumes the persisted canonical value directly. No operator repair is required for legacy or otherwise unsupported values.
2026-11 canonical Portal Storage Space summaries¶
Portal Storage Space summary responses no longer expose the persisted origin
provenance field. The bundled frontend does not consume that provenance and uses
the explicit name_editable capability for rename behavior. Provenance remains
stored internally for lifecycle and deletion audit data.
The same summary contract now omits owner_user_id and the per-space
quota_max_objects value. Both remain available to backend catalogue workflows
that need them for audit metadata and usage aggregation, while the bundled
frontend no longer receives unused internal projections.
Deploy the backend and bundled frontend together. No database migration is required because persisted Storage Space metadata is unchanged.
2026-11 canonical Portal collaboration metadata¶
Portal Storage Space share responses no longer expose the synthetic
activity_label value, which was always generated as an activity-state label
and was not consumed by the bundled frontend. Portal request messages likewise
no longer expose author_user_id or author_role; the UI identifies message
authors by email and does not consume either projection.
Portal request responses also omit the internal execution result and
decided_by_user_id. The bundled frontend does not consume either value and
continues to use decided_by_email plus the decision timestamp for display.
Portal collaborator trend responses now expose only the baseline label and
collaborator count used by the dashboard. The computed window and
period_start projections were not consumed by the bundled frontend.
Portal Storage Space share responses no longer expose the synthetic
direction projection. Visibility already determines whether a caller sees all
shares or only its own grant, and the bundled frontend never consumed that
field. They now identify each explicit grant directly by its required
user_id, email, and role; the route already identifies the Storage Space, so
the duplicated share ID and Storage Space ID/name projections are removed.
The private-space owner embedded in the access summary is now limited to the
email and optional display name used by the bundled frontend; redundant user,
role, access-source, and avatar projections are removed.
Share-candidate responses now omit the constant Portal role and unused avatar.
The candidate routes already return only Portal users, so the frontend derives
that fixed role while retaining the dynamic access source and invitation state.
Storage Space share creation requests now require the candidate user_id and
role. The legacy email selector has been removed because the bundled frontend
creates shares from the candidate catalogue, which already provides the
canonical user identifier.
Public-link responses now expose only the link identifier, Storage Space
identity, object display name, URL, expiration, and computed status. Exact
object_key, label, creator email, creation timestamp, and revocation timestamp
remain persisted and continue to drive object matching, lifecycle, and audit
behavior internally.
The request-message author ID and role, decision user ID, and execution result remain persisted for internal audit, provenance, and workflow diagnostics. Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical quota size units¶
Internal account, RGW user, bucket, and Portal quota write APIs now accept only
the canonical MiB, GiB, and TiB size units. The bundled frontend uses the
same shared contract for Admin, Manager, Portal, and bulk bucket operations.
Inputs such as lowercase gib, GB, or raw bytes are rejected during request
validation instead of reaching the later quota conversion step.
Ceph Admin quota forms remain a separate RGW administration contract and still
support raw bytes (B). Deploy the backend and bundled frontend together. No
database migration is required because persisted quota values are unchanged.
2026-11 canonical onboarding progress resources¶
Migration 0261_canonical_onboarding_resources closes the internal onboarding
checkpoint schema and removes metadata that becomes redundant once its canonical
resource identifier exists. endpoint_name is discarded after a newly created
endpoint is recorded in draft.endpoint_id, while rgw_account_id and
account_name are discarded after the local account_id checkpoint exists.
Retry metadata is retained while the corresponding resource has not yet been
created.
Onboarding checkpoint resources are now backend-internal state and are no longer returned by the Admin onboarding API. The bundled frontend did not consume that state. Deploy the backend and frontend from the same release.
2026-11 canonical onboarding endpoint checkpoints¶
Migration 0260_onboarding_endpoint_checkpoint removes the duplicated endpoint
identifier from onboarding journey resources. The selected or newly created
endpoint is now identified only by draft.endpoint_id. A partial apply that
created an endpoint keeps the boolean resources.endpoint_created checkpoint so
the backend still requires reconciliation before the draft can be edited.
The Admin onboarding API and bundled frontend use this canonical shape together. Deploy the backend and frontend from the same release.
2026-11 canonical execution-context payloads¶
The internal execution-context catalogue now treats
destination_switching_allowed, execution_destinations,
storage_endpoint_capabilities, and capabilities as complete response
contracts. Backend producers populate these fields explicitly and the bundled
frontend consumes them directly instead of tolerating partial legacy payloads.
Deploy the backend and bundled frontend together. No database migration is required because persisted execution-context data is unchanged.
2026-11 canonical Portal Storage Space listing filters¶
GET /api/portal/storage-spaces now accepts only the canonical Portal roles,
Storage Space statuses (Active, Attention, Archived), and documented sort
keys. Invalid role, status, or sort values return 422 instead of being
silently ignored or falling back to name sorting. The bundled frontend uses the
same typed values. Deploy the backend and frontend together. No database
migration is required.
2026-11 canonical static application settings¶
Migration 0258_canonical_static_app_settings materializes every static default
in the canonical app_settings row while preserving explicit persisted values.
The runtime now requires those fields instead of reconstructing them through
Pydantic defaults on each database read.
Four bootstrap values remain environment-derived and are intentionally outside
this migration: portal.bucket_defaults.cors_allowed_origins plus
manager.bucket_migration_parallelism_default,
manager.bucket_migration_parallelism_max, and
manager.bucket_migration_max_active_per_endpoint. Missing values for those
four fields still resolve from deployment configuration. Other app_settings
keys are not modified.
2026-11 obsolete global onboarding setting removal¶
Migration 0257_remove_obsolete_onboarding_setting removes the retired
onboarding object from the canonical app_settings payload. Migration 0125
already transferred the historical global dismissal state to each administrator
present at that upgrade, and current onboarding state is stored per user in
onboarding_preferences and onboarding_journeys.
The Admin settings API and bundled frontend no longer carry
onboarding.dismissed. Dismissing or resuming Getting started continues to use
the dedicated onboarding API and does not mutate application settings.
2026-11 canonical application security settings¶
Migration 0256_canonical_app_settings_security materializes the current
security-policy defaults in the persisted app_settings row for
require_passkey_for_admins, require_passkey_for_users,
allow_user_profile_name_edit, allow_user_external_identity_link, and
allow_user_external_identity_unlink. Explicit persisted values are preserved.
After the migration, the runtime requires these fields in the canonical
database payload instead of silently supplying Pydantic defaults. Fresh
settings construction and the initial APP_SETTINGS_PATH bootstrap input keep
their normal defaults. Other app_settings keys, including the endpoint
service-identity installation identifier, are outside this migration.
2026-11 canonical bucket migration runtime limits¶
Bucket migration planning and worker scheduling now use the persisted Manager settings as their single runtime source for parallelism and per-endpoint concurrency limits. A failure to load those settings is surfaced to the caller instead of silently switching to the environment-derived bootstrap defaults.
BUCKET_MIGRATION_PARALLELISM_MAX and
BUCKET_MIGRATION_MAX_ACTIVE_PER_ENDPOINT still define the initial defaults
used when application settings are first bootstrapped. After bootstrap, change
the corresponding Manager settings through the application settings contract.
2026-11 canonical onboarding completion¶
Migration 0255_canonical_onboarding_completion removes the historical
onboarding_preferences.initial_setup_completed_at compatibility marker. For
an administrator who still has that marker and no current onboarding journey,
the migration materializes an immutable configured version-2 journey with the
same completion timestamp before dropping the column. Administrators who
already have a current journey keep that journey as the sole completion source,
matching the existing runtime precedence.
After the migration, onboarding completion is derived only from canonical
onboarding_journeys state. Downgrade restores the compatibility marker for
the synthetic completion journeys and removes those synthetic rows.
2026-11 cost storage snapshot cleanup¶
Migration 0250_remove_cost_by_bucket removes the unused
cost_storage_daily.by_bucket column. BucketReef never reads this per-bucket
breakdown for cost calculation, reporting, or display, so cost collection now
persists only the aggregate byte and object totals that the Cost Explorer
actually consumes.
The unused COST_STORE_BY_BUCKET runtime setting is removed with the column.
Downgrade recreates the nullable JSON column, but discarded historical
per-bucket breakdowns cannot be reconstructed.
2026-11 canonical external identity browser settings¶
External identity browser state now uses the provider-neutral runtime settings
EXTERNAL_IDENTITY_LINK_ATTEMPT_TTL_SECONDS and
EXTERNAL_IDENTITY_BROWSER_COOKIE_NAME. The retired
OIDC_LINK_ATTEMPT_TTL_SECONDS and OIDC_BROWSER_COOKIE_NAME names are not
runtime aliases.
Before upgrading a deployment that overrides either old setting, move its value
to the corresponding canonical setting. The default browser-binding cookie name
changes from oidc_browser_binding to external_identity_browser_binding.
OIDC or LDAP authentication/linking transactions already in progress across the
deployment restart must be started again.
2026-11 access audit response cleanup¶
The Admin effective-access API now returns each right as its canonical code
plus provenance sources. The redundant English label field was removed from
the application response because the bundled frontend localizes the closed right
code set itself. CSV export keeps the existing human-readable labels. Deploy the
backend and frontend from the same release.
2026-11 quota-monitor result cleanup¶
The internal quota-monitor and usage-history collection responses no longer
echo quota_alerts_enabled, quota_alerts_configured,
usage_history_enabled, usage_history_collection_enabled, or
threshold_percent. Those values are configuration inputs to the workflows,
while the operational responses now contain only execution outcomes. The quota
monitor endpoint exposes alert, notification, and email counters; the usage
history endpoint exposes hourly and daily snapshot counters. Shared subject,
error, retention, and skipped-status fields remain on both responses.
2026-11 Admin usage-history collection response cleanup¶
POST /api/admin/usage-history/collect now returns only the collection outcome
used by the Admin UI: processed-subject and snapshot counters, collection
errors and warnings, plus the optional skipped status and reason. Internal
quota configuration, alert-delivery counters, retention details, and run
timestamps remain available to the operational quota-monitoring service and
its internal endpoints instead of being duplicated in the Admin response.
Deploy matching backend and frontend versions together.
2026-11 first-admin bootstrap provenance cleanup¶
Migration 0234_remove_first_admin_created_user_id removes the unused
first_admin_bootstrap.created_user_id foreign key. The bootstrap singleton
continues to retain consumed_at so an installation cannot reopen first-admin
bootstrap after the initial account has been created.
The created administrator is already identified durably by the security audit entry emitted by both web and CLI bootstrap flows, so the bootstrap row no longer duplicates that provenance. Downgrade recreates the nullable foreign key without inventing a historical user reference.
2026-11 OIDC link session metadata cleanup¶
Migration 0233_remove_unused_oidc_link_session_metadata removes three
persisted fields that were carried through secure external-identity linking but
never consumed by the runtime: external_identity_link_attempts.initiating_auth_session_id
and oidc_login_states.target_user_id / auth_session_id.
Link attempts remain bound to the browser secret and explicit
link_attempt_id. The target user is resolved from the link attempt itself,
and profile-link MFA freshness is captured in mfa_verified_at when the
attempt is created. Downgrade recreates the removed nullable columns without
inventing historical values.
2026-11 OIDC issuer pin timestamp cleanup¶
Migration 0232_remove_oidc_issuer_pin_timestamps removes the unused
created_at and last_verified_at columns from oidc_provider_issuer_pins.
The durable security contract remains the provider ID and its pinned issuer;
neither timestamp was consumed for expiry, authorization, audit, or display.
An already-pinned provider whose discovered issuer still matches now follows a read-only database path instead of writing a verification timestamp on every OIDC authentication. First-time issuer pinning still persists the provider and issuer before authentication continues. Downgrade recreates both historical timestamp columns using the downgrade time because their previous values are not part of the current contract and cannot be reconstructed.
2026-11 durable S3 account import¶
Migration 0231_s3_account_import_intents adds the
s3_account_import_intents saga table. Before BucketReef creates a missing
RGW Account root user or root access key, it persists the target identity and
the exact credential pair that the remote mutation must use. Secrets use the
normal encrypted credential type.
Retries resume the same intent through prepared, creating, and
remote_created. Existing complete root credentials are snapshotted and
reused; missing credentials use a deterministic persisted pair. A retry after
an ambiguous RGW or database failure verifies the exact access-key/secret pair
before continuing, so it does not silently accept an access-key collision or
generate another credential. For batch imports, all remote intents are
completed before local S3 Account rows are staged, preserving local batch
atomicity.
Complete pending S3 Account imports before downgrading. Migration 0231
refuses to drop the intent table while it contains rows.
2026-11 durable S3 user import¶
Migration 0230_s3_user_import_intents adds the s3_user_import_intents
saga table. Before BucketReef creates the managed access key used to import an
existing RGW User, it now persists the target identity plus a generated access
key ID and encrypted secret. The RGW key is then created with that exact pair
and checkpointed before the local s3_users row is committed.
Retries resume the same intent. If RGW created the key but the checkpoint or final local commit failed, BucketReef verifies the deterministic access-key ID and reuses the encrypted secret instead of creating another key. For batch imports, all remote credentials are checkpointed before any local S3 User row is staged, preserving local batch atomicity.
Complete pending S3 User imports before downgrading. Migration 0230 refuses
to drop the intent table while it contains rows.
2026-11 durable S3 account deletion¶
Migration 0229_s3_account_deletion_state adds the s3_account_deletions
saga table. BucketReef now checkpoints Portal IAM cleanup, RGW root-user
deletion, and RGW Account deletion before removing the local Account row.
Retries resume from the last durable checkpoint. If the root user or RGW Account was already deleted when a database commit failed, BucketReef verifies that absence and continues without replaying the destructive remote operation. Account metadata, quota, association, and feature updates are rejected while remote deletion is pending.
Complete pending S3 Account deletions before downgrading. Migration 0229
refuses to drop the saga table while it contains rows.
2026-11 durable S3 user deletion¶
Migration 0228_s3_user_deletion_state adds the s3_user_deletions saga
table. BucketReef now persists the requested RGW cleanup action before deleting
the managed interface access key or the complete RGW user, then checkpoints
remote completion before purging the local S3 User row.
This makes deletion retryable across database commit failures. In particular, if the interface access key was removed from RGW but the completion checkpoint did not commit, the next retry verifies that the key is already absent and continues without replaying the remote delete. S3 User metadata, quota, and key mutations are rejected while a deletion is pending so the persisted identity snapshot cannot drift during recovery.
Complete pending S3 User deletions before downgrading. Migration 0228
refuses to drop the saga table while it contains rows. Apply the normal Alembic
upgrade path when deploying this backend version.
2026-11 durable Portal IAM user revocation¶
Migration 0227_portal_iam_revocation_state adds the
portal_iam_revocations cleanup queue. Portal role removal, UI-user
deactivation, collaborator removal, and UI-user deletion now disable active
Portal IAM access keys before committing the local access change, then persist
the remote cleanup intent before deleting the IAM user. If the local database
commit fails, BucketReef restores the previous key status and rolls back the
queue entry.
After the local access removal commits, a remote IAM cleanup failure no longer
reverts or obscures the local result. The queue remains durable and the
disabled IAM identity is retried by the normal Portal IAM reconciliation
workflow. Queue rows deliberately do not reference users with a foreign key,
so pending cleanup survives complete deletion of the BucketReef UI user.
reconcile_portal_iam can therefore finish orphaned cleanup entries after the
user row is gone.
Complete pending Portal IAM revocations before downgrading. Migration 0227
refuses to drop the queue while it contains rows. Apply the normal Alembic
upgrade path when deploying this backend version.
2026-11 durable Portal external tool revocation¶
Migration 0226_portal_external_credential_revocation extends
portal_external_access_credentials.status with RevocationPending. External
tool credential deletion now disables the IAM access key, persists the pending
state and removes that credential from the Storage Space policy projection
before the remote access key, inline policy, and IAM user are removed.
revoked_at is set only after remote cleanup succeeds.
If remote cleanup or final persistence fails, the bundled Portal shows the
credential as Revocation pending, prevents reactivation, and lets the user
retry deletion. The remote cleanup operations are idempotent, so a retry can
complete a partially finished revocation. Complete pending revocations before
downgrading; migration 0226 refuses to downgrade while any pending row
exists. Deploy the backend and bundled frontend together and apply the normal
Alembic upgrade path.
2026-11 canonical user avatar preferences¶
Migration 0225_canonical_user_avatar_preference normalizes every persisted
users.avatar_preference value to one of auto, uploaded, gravatar, or
initials. Matching values are trimmed and lowercased; unsupported values are
reset to the safe auto preference. The migration then installs a database
check constraint so later writes cannot reintroduce another value.
The backend ORM carries the same constraint and the application API validates the same preference set. Downgrade removes only the database constraint; the canonicalized values are preserved.
2026-11 canonical external identity provider invariants¶
Migration 0224_external_identity_provider_invariants canonicalizes provider
metadata in external identities, link requests, and link attempts, then
enforces the same rules with database check constraints. Provider types are
limited to oidc and ldap; provider IDs are trimmed, lowercased, non-empty,
and limited to the supported identifier syntax. OIDC rows require a trimmed
issuer without a trailing slash, while LDAP rows require issuer=NULL.
For durable identities and pending link requests, the migration validates the
canonical identity key before writing. It stops the upgrade if normalization
would collapse two rows onto the same OIDC (issuer, subject) or LDAP
(provider_id, subject) identity instead of silently choosing one. Repair the
reported rows and retry the migration. Downgrade removes the new check
constraints but keeps the canonicalized provider metadata.
The authentication and Admin identity response schemas expose provider_type
with the same closed oidc / ldap contract, and the bundled frontend relies
on that canonical value. Deploy the backend and frontend from the same release.
2026-11 Manager bucket tenant metadata¶
Manager bucket summary and listing responses now expose the resolved RGW tenant
through the optional tenant field. The Bucket Overview shows that value in
Bucket details only when the execution context is tenanted; non-tenanted
buckets keep the previous layout without an empty tenant row.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 explicit IAM role trust policy¶
Manager role creation now requires assume_role_policy_document explicitly.
The backend no longer injects a wildcard Principal when the field is omitted,
and the bundled frontend starts new role trust policies empty so an
administrator must choose the trusted principal deliberately.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 paginated Admin association catalogs¶
The internal unpaginated Admin summary routes
GET /api/admin/users/minimal, GET /api/admin/groups/minimal,
GET /api/admin/accounts/minimal, GET /api/admin/s3-users/minimal, and
GET /api/admin/s3-connections/minimal have been removed.
The bundled frontend now uses the paginated, searchable
/api/admin/users/options and /api/admin/groups/options catalogs for UI
principals, and the canonical paginated /api/admin/accounts,
/api/admin/s3-users, and /api/admin/s3-connections listings for storage
association candidates. Deploy the backend and bundled frontend together. No
database migration is required.
2026-11 atomic UI user creation associations¶
The internal POST /api/admin/users contract now accepts the complete initial
association set: RGW account links, S3 user links, shared S3 connection IDs,
UI group IDs, and OpenStack cloud IDs. The bundled frontend sends these links
with the create request instead of creating the user first and applying a
follow-up PATCH.
Deploy the backend and bundled frontend together. This removes the partial creation state where a UI user could be persisted successfully before a later association update failed. Initial associations are validated in the same database transaction. Portal IAM identities remain lazily provisioned on first use, so initial role links do not trigger external IAM synchronization during user creation. No database migration is required.
2026-10 LDAP Admin import search filter¶
Migration 0223_ldap_import_search_filter adds the optional
ldap_providers.import_search_filter field used by Admin directory search when
pre-provisioning an LDAP-backed UI user. Existing UI-managed LDAP providers get
NULL, which preserves the previous behavior: BucketReef derives the import
filter from user_filter by replacing {username} with *{query}*.
When configured, the custom filter must contain {query}. BucketReef escapes
the administrator-entered search text before substitution. Environment-managed
providers expose the same capability through
LDAP_PROVIDERS__<key>__IMPORT_SEARCH_FILTER and do not depend on this database
column.
2026-10 external identity link attempts for LDAP and OIDC¶
Migration 0222_external_identity_link_attempts generalizes the short-lived
OIDC account-link attempt table to external_identity_link_attempts. Existing
OIDC attempts are preserved with provider_type=oidc; the issuer becomes
nullable so LDAP attempts can use the same browser-bound transaction model.
The migration also adds ldap_providers.linking_policy, defaulting existing
UI-managed LDAP providers to manual.
Deploy the backend and bundled frontend together so both use the generalized external-identity linking workflow. A downgrade removes LDAP link attempts, because the previous OIDC-only schema cannot represent them. These rows are ephemeral account-link transactions; persisted LDAP identities and BucketReef users are unaffected by that downgrade cleanup.
2026-10 external identity link request review context¶
Migration 0221_identity_link_request_context adds email_verified and
request_source to external_identity_link_requests. Existing requests are
backfilled with email_verified=false and request_source=NULL; new requests
persist the review context that administrators use when deciding whether an
external identity should be linked to an existing BucketReef user.
2026-10 explicit Browser Object Lock capability state¶
Browser object Legal Hold and Retention responses now include the explicit
object_lock_enabled boolean. S3 reads that report no usable Object Lock
configuration, including RGW InvalidRequest responses for these two reads,
are normalized by the backend to object_lock_enabled=false instead of forcing
the frontend to infer bucket capability from human-readable error text.
Deploy the backend and bundled frontend together. This changes only the internal application API response shape and does not require a database migration.
2026-10 structured global Cost-disabled errors¶
Admin, Manager, and Portal Cost endpoints now return the canonical structured
403 detail {"code":"cost_disabled","message":"Cost is disabled"} when the
global Cost feature is disabled. The bundled Admin frontend checks the stable
cost_disabled code instead of parsing the human-readable message.
Deploy the backend and bundled frontend together. Internal callers that used
the previous plain "Cost is disabled" detail must switch to the structured
code. Per-project and per-resource Cost policy denials keep their distinct
messages. No database migration is required.
2026-10 secure OIDC account linking and issuer binding¶
Migration 0220_oidc_secure_account_linking binds OIDC identities to their
discovered issuer and introduces short-lived browser-bound account-linking
transactions. OIDC identity uniqueness is now (issuer, subject), while LDAP
keeps (provider_id, subject) uniqueness. Provider IDs remain configuration
and provenance for OIDC rather than part of the immutable external identity.
Existing active OIDC identities do not have a trustworthy persisted issuer. The migration removes those OIDC identity mappings and OIDC link requests, increments the affected users' authentication version, revokes their active UI sessions, refresh tokens, and API tokens, removes associated OpenStack session credentials, and deletes pre-upgrade OIDC login states that lack issuer/browser binding. The BucketReef user account itself is preserved. The issuer is established only by a fresh OIDC authentication; it is never inferred from the current provider configuration.
After the upgrade, a user's next OIDC login follows the normal secure
account-link collision workflow and recreates the identity only after the
existing account has been proved or an administrator has approved the link.
LDAP identities are preserved. New UI-managed providers default to the
reauthenticate linking policy. Environment-managed providers retain the
manual default unless configured otherwise.
2026-10 structured S3 capability state¶
Migration 0219_structure_s3_capabilities replaces the text JSON capability
snapshots in s3_connections.capabilities_json and s3_sessions.capabilities
with structured JSON. The connection column is renamed to
s3_connections.capabilities so its storage name matches the application
model. Existing connection profiles must contain a boolean can_manage_iam;
session snapshots must match the canonical session capability shape established
by earlier migrations. Malformed JSON or invalid shapes stop the upgrade.
Connection probes and S3 session creation now read and write dictionaries directly without serializing or parsing JSON text at runtime. The downgrade restores canonical compact JSON text and the legacy connection column name.
2026-10 structured Cost measurement breakdowns¶
Migration 0218_structure_cost_measurement_breakdowns replaced the text JSON
representations in cost_usage_daily.ops_breakdown and the then-existing
cost_storage_daily.by_bucket with structured JSON columns. Existing non-null
operation breakdowns must map operation names to integer counts. Existing
per-bucket breakdowns must map bucket names to objects containing integer
used_bytes and object_count values. Malformed JSON or values with another
shape stop the upgrade explicitly.
At that revision, cost collection stored both breakdowns directly as structured
values and cost aggregation stopped reparsing persisted JSON text. Migration
0250_remove_cost_by_bucket later removes the unused per-bucket snapshot
column. The 0218 downgrade still recreates canonical JSON text from the
structured objects when traversing that historical schema.
2026-10 structured account Portal settings overrides¶
Migration 0217_structure_portal_settings_override replaces the
s3_accounts.portal_settings_override text representation with a structured
JSON column. Existing non-null values must decode to JSON objects; malformed
JSON, null, or values with another shape stop the upgrade explicitly.
Portal settings services now read and write override objects directly and keep
SQL NULL as the canonical representation when no account override exists.
The downgrade recreates canonical JSON text from the structured object.
2026-10 structured webhook delivery payloads¶
Migration 0216_structure_webhook_delivery_payloads replaces
webhook_deliveries.payload_json text with structured JSON stored in the
payload column. Existing values must decode to JSON objects; malformed JSON,
null, or values with another shape stop the upgrade explicitly.
Webhook event producers now persist the structured envelope directly. Delivery still serializes that object with the existing canonical JSON format before signing and sending it, so the documented raw-body HMAC contract and wire bytes remain stable for payloads created by prior BucketReef versions. The downgrade recreates canonical JSON text from the structured objects.
2026-10 structured audit metadata¶
Migration 0215_structure_audit_metadata replaces audit_logs.metadata_json
text with structured JSON stored in the metadata column. Existing non-null
values must decode to JSON objects; malformed JSON or values with another shape
stop the upgrade explicitly.
Audit producers now persist sanitized metadata objects directly. Metadata size limits and secret redaction remain unchanged, and free-text audit search casts the structured JSON to text only for matching. The downgrade recreates the former text column from the structured objects.
2026-10 structured WebAuthn credential transports¶
Migration 0214_structure_webauthn_transports replaces
webauthn_credentials.transports_json text with the structured JSON
transports list. Existing values must decode to JSON arrays containing only
strings; malformed JSON or values with another shape stop the upgrade
explicitly.
WebAuthn registration now stores transport hints directly as structured values. The downgrade recreates the former text column from the structured list.
2026-11 canonical bucket migration rollback status¶
Migration 0239_canonical_migration_rollback_status normalizes the retired
bucket migration and item status rolled_back to the current terminal status
canceled. It also recomputes the persisted migration counters for records that
contained a retired item status. Historical item steps such as rolled_back
and migration events remain unchanged so the completed rollback operation stays
visible in the record history.
The backend and bundled frontend no longer accept rolled_back as a current
migration or item status. Deploy them together after applying the Alembic
upgrade.
2026-11 canonical bucket migration cancellation counters¶
Migration 0240_retire_migration_skipped_status normalizes the retired item
status skipped to canceled and replaces the persisted skipped_items
counter with canceled_items. The new counter is recomputed from item rows so
it includes both historical skipped items and ordinary canceled items.
Historical item steps such as skipped remain unchanged, preserving why an
old item was not copied. The current backend and bundled frontend expose only
the canonical canceled item status and canceled_items counter, so deploy
them together after applying the Alembic upgrade.
2026-11 endpoint health latest-state cleanup¶
Migration 0241_remove_latest_availability removes the unused
endpoint_health_latest.availability_24h column. Endpoint availability shown
by the application is derived from health rollups for the requested time
window, so the removed value duplicated historical health data without serving
a runtime or API consumer.
The migration does not remove raw health checks or rollups. Current endpoint
status and latency summaries continue to use endpoint_health_latest, while
availability percentages continue to be calculated from rollup samples.
Migration 0242_remove_latest_sample_count also removes the write-only
endpoint_health_latest.latency_sample_count column. Sample counters remain on
health status segments and rollups, where they are used to maintain and weight
latency aggregates.
2026-11 OpenStack context service-name cleanup¶
Migration 0243_remove_context_service_name removes the unused
openstack_project_contexts.service_name column. OpenStack target discovery
continues to expose the current Keystone catalog service name directly, while
durable project contexts retain the endpoint name, service type, region,
interface, and endpoint URL required for execution and revalidation.
Downgrade recreates the nullable column without reconstructing its historical value because the persisted service name had no runtime consumer.
2026-11 bucket migration precheck-state cleanup¶
Migration 0244_remove_migration_precheck_status removes the duplicated
bucket_migrations.precheck_status column and its index. The canonical
preparation state, checked configuration revision, and check timestamp already
govern whether a migration can start, while the structured precheck report
retains the diagnostic result shown by the Manager UI.
Downgrade reconstructs precheck_status from preparation_status, mapping
ready to passed, blocked to failed, and other preparation states to
pending.
2026-11 bucket migration target-snapshot cleanup¶
Migration 0245_remove_migration_target_snapshot removes the unused
bucket_migration_items.target_snapshot column. Active migration execution
retains the source snapshot because it drives source-versioning and replay
behavior. Target state is evaluated during checks and was not consumed after
the check completed.
Downgrade recreates target_snapshot as a nullable JSON column without
reconstructing historical values because no runtime workflow consumed them.
2026-11 bucket migration checked-revision cleanup¶
Migration 0246_remove_migration_checked_revision removes the duplicated
bucket_migrations.checked_revision column. Preparation checkpoints already
reject a configuration revision change while checks are running, draft updates
mark preparation as stale, and start requests compare the submitted
configuration_revision with the current draft.
Downgrade recreates checked_revision and sets it to the current
configuration_revision only for migrations whose preparation state is
ready; all other rows remain NULL.
2026-11 bucket migration heartbeat-state cleanup¶
Migration 0247_remove_migration_last_heartbeat removes the unused
bucket_migrations.last_heartbeat_at column. Worker ownership and expiry are
already tracked by worker_lease_owner and worker_lease_until; execution
progress continues to refresh the canonical updated_at timestamps on the
migration and active item.
Downgrade recreates last_heartbeat_at as a nullable UTC timestamp without
reconstructing historical values because no runtime decision or API response
consumed the column.
2026-11 bucket migration runtime-timestamp cleanup¶
Migration 0248_remove_migration_runtime_timestamps removes the unused
top-level bucket_migrations.started_at and bucket_migrations.finished_at
columns. Neither timestamp is consumed by workflow decisions or the Manager
API; updated_at remains the canonical migration activity timestamp, while
per-bucket started_at and finished_at are retained on migration items.
Downgrade recreates both top-level timestamps as nullable UTC values without reconstructing historical data.
2026-11 canonical Browser favorites¶
Migration 0249_canonical_browser_favorites removes the retired surface and
workspace dimensions from personal Browser favorites. Favorites are exposed
only by the standalone /browser workspace, so current writes and reads now
persist only the path identity: name, execution context, bucket, and prefix.
Existing favorites whose historical surface is browser are retained. Rows
for embedded Manager, Portal, or Ceph Admin surfaces are discarded because those
surfaces no longer expose favorites. A retained favorite that carried another
historical workspace is revalidated through the canonical Browser execution
policy when it is opened. Downgrade reconstructs both removed fields as
browser; it cannot restore discarded embedded-surface rows or historical
workspace values.
2026-10 structured bucket migration workflow state¶
Migration 0213_structure_bucket_migration_json replaces the bucket migration
workflow's persisted JSON text columns with structured JSON columns, including
precheck reports, preparation and cleanup recovery state, object-diff samples,
source and target snapshots, replication state, policy backups, and event
metadata. Existing non-null values must decode to JSON objects; malformed JSON
or values with another shape stop the upgrade explicitly instead of being
discarded.
Bucket migration services now read and write native structured values directly while preserving the existing workflow, recovery checkpoints, and transaction boundaries. The downgrade recreates the former text columns from the structured objects.
2026-10 structured user UI preferences¶
Migration 0212_structure_user_ui_preferences replaces
users.ui_preferences_json text with the structured JSON ui_preferences
object. Existing values must decode to JSON objects; malformed JSON or values
with another shape stop the upgrade explicitly.
Profile updates and user responses now persist and validate the preferences object directly instead of serializing JSON text at runtime. The downgrade recreates the former text column from the structured object.
2026-10 structured backend operation lease context¶
Migration 0211_structure_operation_lease_context replaces
backend_operation_leases.metadata_json text with the structured JSON
lease_context object. Existing non-null values must decode to JSON objects;
malformed JSON or values with another shape stop the upgrade explicitly.
Operation lease acquisition and renewal now persist the context object directly instead of serializing JSON text at runtime. The downgrade recreates the former text column from the structured object.
2026-10 structured managed private access IAM state¶
Migration 0210_structure_managed_access_iam_lists replaces the
managed_private_accesses.iam_groups_json, iam_managed_policies_json, and
iam_inline_policy_names_json text columns with structured JSON
iam_groups, iam_managed_policies, and iam_inline_policy_names lists.
Existing values must decode to arrays containing only non-empty strings;
malformed JSON or values with the wrong shape stop the upgrade explicitly.
Managed private access provisioning, retry detection, and compensation now use the structured lists directly instead of serializing and parsing JSON text at runtime. The downgrade recreates the former text JSON columns from the structured lists.
2026-10 structured Portal request payloads¶
Migration 0208_structure_portal_request_payloads replaces
portal_admin_requests.payload_json and result_json text with structured JSON
payload and result objects. Existing payloads must decode to JSON objects;
results may be null, but any present result must also be an object. Malformed
JSON or values with the wrong shape stop the upgrade explicitly.
Portal request creation, execution, and response serialization now use the structured objects directly. Admin free-text search keeps matching request payload content by casting the JSON object to text only for the search query. The downgrade recreates the former text JSON columns from the structured objects.
2026-10 structured bucket usage statistics payloads¶
Migration 0207_structure_bucket_usage_stats_payloads replaces the five
bucket_usage_stats_snapshots.*_distribution_json text columns with non-null
structured JSON distribution lists and replaces warnings_json with the
nullable structured JSON warnings list. Existing distribution values must
decode to JSON arrays of objects, and warnings must decode to an array of
strings when present. Malformed JSON or values with the wrong shape stop the
upgrade explicitly.
Bucket usage collection and reads now store and consume the structured values directly instead of serializing and parsing JSON text at runtime. The downgrade recreates the former text JSON columns from the structured values.
2026-10 structured onboarding journey state¶
Migration 0206_structure_onboarding_journey_payloads replaces
onboarding_journeys.draft_json and resources_json text with non-null
structured JSON draft and resources objects. Every existing value must
decode to a JSON object; malformed, null, array, or scalar values stop the
upgrade explicitly.
Guided onboarding now reads and writes both objects directly. Resource checkpoints replace the JSON object on each update so SQLAlchemy persists nested changes reliably. The downgrade recreates the former text columns from the structured objects.
2026-10 structured application settings payloads¶
Migration 0205_structure_app_settings_payloads replaces
app_settings.payload_json text with a non-null structured JSON payload
column. Existing values may contain any valid JSON type because the table stores
both the application settings object and internal scalar settings; malformed
JSON stops the upgrade explicitly.
Application settings and the endpoint service-identity installation ID now use
structured values directly. The settings optimistic concurrency check uses the
row updated_at value instead of comparing serialized JSON text. The downgrade
recreates the former text column from the structured payloads.
2026-10 structured authentication challenge payloads¶
Migration 0204_structure_auth_challenge_payloads replaces
auth_challenges.payload_json text with a non-null structured JSON payload
column. Every existing value must decode to a JSON object; malformed, null,
array, or scalar payloads stop the upgrade explicitly.
WebAuthn challenge creation and consumption now use the structured object directly while retaining the existing challenge integrity check. The downgrade recreates the former text column from the structured payloads.
2026-10 structured OIDC provider lists¶
Migration 0203_structure_oidc_provider_lists replaces the UI-managed OIDC
scopes_json and trusted_email_domains_json text columns with structured
JSON scopes and trusted_email_domains lists. Existing scopes must be a
non-empty array of non-empty strings, and trusted domains must be an array of
strings; invalid persisted values stop the upgrade explicitly.
OIDC provider configuration now reads and writes both lists directly. Runtime validation still rejects structurally corrupted persisted values. The downgrade recreates the former text columns from the structured lists.
2026-10 structured API token scopes¶
Migration 0202_structure_api_token_scopes replaces
api_tokens.scopes_json text with a non-null structured JSON scopes
column. Existing values must decode to a JSON array containing only strings;
malformed JSON, non-array values, and arrays containing non-string values stop
the upgrade explicitly.
API token creation, listing, and authentication now use the structured list directly. Authentication still fails closed if the persisted structure is corrupted after migration. The downgrade recreates the former text column from the structured list.
2026-10 structured user notification payloads¶
Migration 0201_structure_user_notification_payloads replaces
user_notifications.payload_json text with a non-null structured JSON
payload column. Every existing value must decode to a JSON object; malformed,
null, array, or scalar payloads stop the upgrade explicitly instead of being
accepted through a runtime compatibility parser.
Notification producers and API serialization now use the structured object directly. The downgrade recreates the former text column from the structured payloads.
2026-10 structured Storage Endpoint features¶
Migration 0200_structure_storage_endpoint_features replaces the persisted
storage_endpoints.features_config YAML text with a non-null structured JSON
features column. Existing feature documents are validated and normalized
during the migration; invalid persisted values stop the upgrade explicitly
instead of being carried forward through a runtime compatibility path.
The bundled backend API and frontend now exchange the structured features
object directly. Deploy them together. Text parsing remains only at explicit
configuration boundaries: SEED_S3_ENDPOINT_FEATURES accepts the documented
YAML/JSON document, and ENV_STORAGE_ENDPOINTS[].features accepts its documented
JSON mapping. The configuration-facing health-check URL key remains
healthcheck_url; the persisted/API field is url.
The undocumented ENV_STORAGE_ENDPOINTS[].features_config compatibility field
has been removed. The downgrade recreates the former YAML column from the
structured values.
2026-10 normalized S3 connection custom endpoints¶
Migration 0199_normalize_s3_connection_custom_endpoints replaces the
s3_connections.custom_endpoint_config text JSON blob with dedicated
custom_endpoint_url, custom_region, custom_force_path_style,
custom_verify_tls, and custom_provider columns. Connections bound to a
registered Storage Endpoint keep those custom columns empty. Manual connections
must contain a usable endpoint URL plus boolean path-style and TLS flags;
malformed persisted custom endpoint data stops the upgrade explicitly.
Runtime connection services now read and write those structured columns
directly. The application API continues to expose the endpoint as
endpoint_url, region, force_path_style, verify_tls, and
provider_hint; for a manual endpoint, provider_hint is backed by the
custom_provider column. The downgrade recreates the canonical text JSON blob
from the structured columns.
OpenStack project connections¶
Migration 0194_openstack_connect adds optional clouds and session-bound
credentials, plus the initiating-session reference on migrations. Deploy backend
and frontend together for the new context types. No cloud or additional access
is enabled automatically. Configure outbound policy and explicit grants before
use; see OpenStack connections.
Migration 0195_openstack_catalog_targets moves OpenStack S3 execution targets
from manually associated BucketReef Storage Endpoints to the scoped Keystone
service catalog. Migration 0195 initially retained the former endpoint-bound
project contexts as non-executable legacy markers, while removing the obsolete
openstack_cloud_endpoints association. Migration
0198_remove_openstack_legacy_contexts subsequently deletes those legacy
contexts and credentials and removes their endpoint_id column. After applying
the current migration chain, no endpoint-bound legacy project context remains;
projects must be activated from a current Keystone catalog target. Deploy backend
and frontend together because project activation exchanges a Keystone target_id,
and the selected region/URL are part of the session-bound execution context. The
migration also adds openstack_clouds.managed_endpoints_only, defaulting to
false. Catalog targets whose canonical S3 URL matches a current Storage Endpoint
are associated dynamically; enabling the policy restricts activation to those
managed matches while keeping other Keystone regions visible as disabled choices.
Migration 0196_openstack_all_users_group moves OpenStack cloud admission into
the standard UI User/UI Group association model. The previous per-cloud global
all_users flag is represented by a built-in All users UI group whose
membership is implicit for every active UI user, including users created later.
Existing direct user and group cloud links are preserved. If an existing custom
group already uses the reserved All users name, the migration preserves it
under a deterministic All users (custom) name before creating the system
group. Deploy backend and frontend together because cloud create/update payloads
no longer carry user, group, or global-access fields.
2026-10 RGW multisite execution destinations¶
Migration 0197_rgw_multisite_execution_destinations adds optional realm_id,
zonegroup_id, and zone_id metadata to Storage Endpoints plus the
allow_multisite_endpoint_switching UI User/UI Group permission. Existing
records remain disabled and unassociated by default.
For Ceph endpoints, Realm ID and Zonegroup ID must be configured together.
Manager and standalone Browser expose alternate destinations only to effectively
authorized users and only between Ceph endpoints whose declared Realm ID and
Zonegroup ID both match. Manager supports RGW Account, RGW User, and
endpoint-backed S3 Connection contexts; standalone Browser supports its
endpoint-backed private S3 Connections. Custom-URL and temporary-credential
connections remain pinned. The selected logical context and its credentials stay
unchanged while the destination endpoint and its capabilities change. Deploy
backend and frontend together because execution-context responses, Browser
transfer policies, and requests now carry the destination metadata and optional
execution_endpoint_id parameter.
This topology is administrator-declared metadata. It does not use RGW multisite
system keys or add zone=read/metadata=read to the Runtime identity.
Migration 0209_rgw_multisite_resource_switching adds nullable
allow_multisite_endpoint_switching overrides to RGW Accounts and RGW Users.
The shared manager.feature_policies.rgw_multisite_endpoint_switching policy
defaults to targeted, so existing resources do not gain endpoint-switching
rights automatically. An Account or RGW User can opt in explicitly, while an
existing UI User/UI Group grant remains an independent additive grant. Setting
the shared platform policy to disabled blocks only the Account/User resource
grant; it does not revoke an effective UI User/UI Group grant. S3 Connections
continue to use only the UI User/UI Group permission.
2026-10 Ceph Admin multisite diagnostics¶
Multisite topology and diagnostic endpoint selection are discovered live from the configured Ceph Admin endpoints. The diagnostic topology remains live and is not persisted as a Ceph Admin association. The optional Storage Endpoint Realm/Zonegroup/Zone metadata used by RGW execution switching is a separate declarative configuration and is not used as a substitute for Ceph Admin diagnostic discovery. The diagnostics feature itself requires no database migration. Deploy the bundled backend and frontend together for the new diagnostic DTOs and routes. See Multisite diagnostics.
2026-10 access-key metadata updates use PATCH¶
Manager access-key metadata updates now use PATCH for both RGW-user keys and
IAM-user keys. Metadata payloads intentionally preserve omitted fields and only
apply values present in the request, so the former PUT routes have been
removed instead of retained as compatibility aliases. Access-key status
updates remain PUT because the status payload is a complete boolean state.
The bundled frontend has been updated with the API cutover. No database migration is required.
2026-10 Manager IAM identity updates use PATCH¶
Manager IAM user, group, and role updates now use PATCH on their existing
identity resource URLs. Their update payloads are intentionally sparse and
apply only supplied fields, so the former top-level PUT routes have been
removed instead of retained as compatibility aliases. PUT remains in use for
complete IAM sub-resources such as inline policies and role tags.
The bundled frontend has been updated with the API cutover. No database migration is required.
2026-11 Manager IAM group and role creation is backend-orchestrated¶
Manager IAM group and role create payloads now carry selected managed-policy ARNs together with inline policies. The backend applies the complete create-time configuration and compensates a failed policy step by removing the requested policies before deleting the newly created group or role. The bundled frontend no longer fans out separate policy-attachment requests after creation.
Manager IAM user creation now also requires an explicit non-null create_key
boolean. The bundled frontend already sends that choice for every create
request, so the backend no longer treats omission as false.
Deploy the bundled frontend and backend together. No database migration is required.
2026-10 Ceph Admin account and user config updates use PATCH¶
Ceph Admin account and user configuration updates now use
PATCH /ceph-admin/endpoints/{endpoint_id}/accounts/{account_id}/config and
PATCH /ceph-admin/endpoints/{endpoint_id}/users/{user_id}/config. Both
contracts are intentionally sparse and apply only supplied fields, so the
former PUT routes have been removed instead of retained as compatibility
aliases.
The bundled frontend has been updated with the API cutover. No database migration is required.
2026-10 Portal project settings partial updates use PATCH¶
Delegated Portal project settings now use PATCH /portal/settings. Project
overrides are intentionally sparse and apply only supplied fields, so the
former PUT route has been removed instead of retained as a compatibility
alias.
The bundled frontend has been updated with the API cutover. No database migration is required.
2026-10 current-user profile partial updates use PATCH¶
Authenticated profile updates now use PATCH /users/me. The profile payload is
intentionally sparse and applies only supplied fields, so the former PUT
route has been removed instead of retained as a compatibility alias. Avatar
replacement remains PUT /users/me/avatar.
The bundled frontend has been updated with the API cutover. No database migration is required.
2026-10 private S3 connection partial updates use PATCH¶
User-owned S3 connection updates now use PATCH /connections/{connection_id}.
The payload is intentionally sparse and applies only supplied fields, including
credential and endpoint changes, so the former PUT route has been removed
instead of retained as a compatibility alias.
The bundled frontend has been updated with the API cutover. No database migration is required.
2026-11 private connection workspace access is explicit¶
Private S3 connection creation and OpenStack project imports now require
non-null access_manager and access_browser booleans. The bundled frontend
already sends both workspace choices for every create request, so the backend
no longer invents Manager/Browser access when either field is omitted.
Deploy the bundled frontend and backend together. No database migration is required.
2026-11 principal Browser access is explicit¶
Account and RGW User association payloads now require a non-null
allow_manager_browser_data_access boolean for every principal link. The
bundled frontend already sends that choice for user, group, account, and RGW
User association edits, so the backend no longer treats omission as false.
Deploy the bundled frontend and backend together. No database migration is required.
2026-11 RGW create tenant selection is explicit¶
RGW Account and RGW User creation payloads now require a non-null
rgw_tenant string. Use an empty string to select the default RGW tenant; the
bundled frontend now sends that value explicitly when managed tenant creation
is disabled or no named tenant is selected.
Deploy the bundled frontend and backend together. Internal onboarding and demo seed paths have also been updated. No database migration is required.
2026-10 RGW User partial updates use PATCH¶
Admin RGW User updates now use PATCH /admin/s3-users/{user_id}. The update
payload is intentionally sparse and applies only supplied fields, so the former
PUT route has been removed instead of retained as a compatibility alias.
The bundled frontend has been updated with the API cutover. No database migration is required.
2026-10 RGW Account partial updates use PATCH¶
Admin RGW Account updates now use PATCH /admin/accounts/{account_id}. Account
Portal overrides now use PATCH /admin/accounts/{account_id}/portal-settings.
Both payloads intentionally apply only supplied fields, so their former PUT
routes have been removed instead of retained as compatibility aliases.
The bundled frontend has been updated with the API cutover. No database migration is required.
2026-10 shared S3 connection partial updates use PATCH¶
The admin shared-S3-connection update now uses
PATCH /admin/s3-connections/{connection_id} because
S3ConnectionAdminUpdate intentionally applies only supplied fields. The
former PUT route has been removed instead of retained as a compatibility
alias.
The bundled frontend has been updated with the API cutover. No database migration is required.
2026-10 storage endpoint partial updates use PATCH¶
The admin storage-endpoint configuration update now uses
PATCH /admin/storage-endpoints/{endpoint_id} because
StorageEndpointUpdate intentionally applies only supplied fields. The
former PUT route has been removed instead of retained as a compatibility
alias.
The dedicated tags/default operations keep their existing PUT routes. The
bundled frontend has been updated with the API cutover. No database migration
is required.
2026-11 explicit storage endpoint credential removal¶
Storage endpoint PATCH requests now distinguish omitted write-only credential
pairs from explicit removal. Omitted Runtime, Supervision, or Ceph Admin credential
fields preserve the stored pair. Sending both fields of a pair as null clears it
when the resulting endpoint configuration does not require those credentials.
The bundled frontend already omits stored write-only pairs during ordinary edits, so no frontend migration or database migration is required.
2026-10 UI user partial updates use PATCH¶
The admin UI-user update endpoint now uses PATCH /admin/users/{user_id}
because UserUpdate intentionally applies only supplied fields. The former
PUT route has been removed instead of retained as a compatibility alias.
Avatar replacement and administrator password replacement keep their existing
PUT endpoints. The bundled frontend has been updated with the API cutover.
No database migration is required.
2026-10 UI group partial updates use PATCH¶
The admin UI-group update endpoint now uses PATCH /admin/groups/{group_id}
because its payload is intentionally partial. The former PUT route has been
removed instead of retained as a compatibility alias.
The bundled frontend has been updated with the API cutover. No database migration is required.
2026-10 explicit identity-provider configuration payloads¶
OIDC and LDAP provider create/update requests now require the complete
non-secret configuration. Nullable configuration fields must be sent
explicitly as null when unset.
Secret controls remain optional so an update can preserve an existing OIDC client secret or LDAP bind password. The bundled frontend already sends the complete provider configuration. No database migration is required.
2026-10 explicit webhook endpoint payloads¶
Webhook endpoint create and update requests now require both enabled and
event_types. Requests no longer inject false and ["*"] when those
fields are omitted, preventing incomplete PUT payloads from silently resetting
the endpoint state.
The bundled frontend already sends both fields. No database migration is required.
2026-10 canonical static website payloads¶
Bucket static-website reads and updates now use separate contracts and require
the complete four-field shape: index_document, error_document,
redirect_all_requests_to, and routing_rules. Nullable values remain
nullable, but callers must send them explicitly instead of relying on omission
defaults.
The bundled frontend already sends the complete update payload. No database migration is required.
2026-10 canonical Object Lock payloads¶
Bucket Object Lock reads and updates now require the complete four-field shape:
enabled, mode, days, and years. Each value remains nullable, but callers
must state the intended value instead of relying on omission defaults.
The bundled frontend already sends the complete payload. No database migration is required.
2026-10 canonical public access block updates¶
Bucket public-access-block reads now return all four nullable state fields,
while update requests require all four boolean values explicitly. Omitted or
null write fields are no longer interpreted as false.
The bundled frontend already normalizes and sends the complete write payload. No database migration is required.
2026-10 explicit Ceph Admin user caps updates¶
Ceph Admin RGW user-capability updates now require an explicit values array.
An omitted array no longer means an empty replacement set; callers that intend
to clear all caps must send values: [] explicitly.
The bundled frontend already sends the canonical payload. No database migration is required.
2026-10 explicit tag update payloads¶
Bucket and storage-endpoint tag updates now require the tags field instead of
silently treating an omitted field as an empty list. The bundled frontend
already sends the intended tag list for every update; bucket tags can also be
cleared through the dedicated delete route.
Deploy the backend and bundled frontend together. No database migration is required.
2026-10 canonical storage endpoint responses¶
Admin storage-endpoint responses now require the complete normalized endpoint state, including nullable metadata, service-identity status, capabilities, permissions, tags, and feature configuration. The nested Admin Ops permission object likewise requires all eight read/write flags. The backend already materialized these fields; the bundled frontend no longer carries omission fallbacks.
Deploy the backend and bundled frontend together. No database migration is required.
2026-10 canonical Browser object protection payloads¶
Browser ACL, legal-hold, and retention writes now use dedicated update payloads. Legal-hold status plus retention mode and retain-until are required on writes. Read responses always include their nullable state and version fields, and retention responses no longer expose the write-only governance-bypass option.
Deploy the backend and bundled frontend together. No database migration is required.
2026-10 canonical Browser object-tag payloads¶
Browser object-tag updates now require an explicit tags collection. Object-tag
responses always include tags and nullable version_id.
Deploy the backend and bundled frontend together. Direct callers must send the canonical update object. No database migration is required.
2026-10 canonical SNS policy and configuration payloads¶
Manager SNS topic policy responses and updates now require policy, and topic
configuration responses and updates require configuration. Empty state is an
explicit empty object instead of an omitted field or model default.
Deploy the backend and bundled frontend together. Direct callers must send the canonical objects for update requests. No database migration is required.
2026-10 canonical bucket scalar configuration responses¶
Bucket versioning responses now always include nullable status plus boolean
enabled. Bucket policy responses always include nullable policy, and access
logging responses always include enabled, target_bucket, and
target_prefix; disabled logging uses explicit null targets.
Deploy the backend and bundled frontend together. Direct callers should no longer rely on omitted fields for these successful reads. No database migration is required.
2026-10 canonical bucket detail collections¶
Bucket property responses now always include lifecycle_rules, ACL responses
always include grants, and static website responses always include
routing_rules. Empty state is represented by an empty array instead of an
omitted field or a model default.
Deploy the backend and bundled frontend together. Direct callers should expect these collections on successful reads. No database migration is required.
2026-10 canonical encryption, notification, and replication payloads¶
Bucket encryption responses and updates now require a rules array. Bucket
notification and replication responses and updates likewise require their
configuration objects. The backend already materialized these fields for
successful reads, and the bundled frontend already models them as required.
Deploy the backend and bundled frontend together. Direct callers must send the canonical fields instead of relying on empty defaults. No database migration is required.
2026-10 canonical lifecycle and CORS rule collections¶
Bucket lifecycle and CORS application responses now always require their
rules arrays. The backend already materialized these collections for every
successful read and update, and the bundled frontend already treats them as
required fields; omission fallbacks have been removed from shared bucket
operations.
Deploy the backend and bundled frontend together. Direct callers must include
rules when updating lifecycle configuration and must expect rules on
successful lifecycle and CORS responses. No database migration is required.
2026-11 canonical Manager bucket creation versioning¶
Manager POST /manager/buckets now requires a non-null versioning boolean.
The bundled frontend already sends the explicit value for every bucket create
request, so the backend no longer accepts omission or null and silently
normalizes them to false.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical Browser bucket creation versioning¶
Browser POST /browser/buckets now also requires a non-null versioning
boolean. The Browser create dialog already tracks this choice explicitly, and
the bundled frontend now requires callers of its Browser bucket API helper to
provide that value instead of defaulting omission to false.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical onboarding service identity mode¶
Admin onboarding apply requests now require an explicit service_identity_mode
(managed or external). The onboarding form already selects and sends this
mode for every apply operation; the bundled frontend type now reflects that
required contract instead of allowing callers to rely on the backend default.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical Admin RGW resource PATCH nullability¶
Admin RGW Account and RGW User PATCH payloads now distinguish omission from an
explicit null. email: null clears the stored optional email, while omitting
email preserves it. Non-nullable update fields such as name, association
lists, tags, and the Account storage endpoint reject explicit null; use an
empty list to clear associations or tags. Nullable quota values and feature
overrides keep their existing clear/inherit semantics.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical Manager IAM PATCH contracts¶
Manager IAM user and group PATCH payloads now reject explicit null for
identity names and IAM paths. IAM role PATCH payloads reject explicit null
for trust-policy and max-session-duration updates.
The unused IAM role path PATCH field has been removed because RGW IAM does
not support changing a role path and the BucketReef frontend never submitted
that field. Omit fields to preserve their current value.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical Storage Endpoint PATCH nullability¶
Storage Endpoint PATCH payloads now reject explicit null for concrete
configuration fields: name, endpoint_url, path-style and TLS booleans,
provider, service_identity_mode, ceph_admin_allowed, and
features. Omit those fields to preserve their current value.
Intentional clear semantics remain nullable for region, Ceph multisite IDs, coordinates, and credential fields. Credential pair validation and write-only secret preservation continue to apply.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical UI principal PATCH nullability¶
Admin UI User and UI Group PATCH payloads now reject explicit null for
concrete mutations such as identity/access fields, Manager tool access, and
association lists. Omit those fields to preserve their current value and use an
empty list to clear associations. UI User creation likewise rejects
openstack_cloud_ids: null; omit it or send an array.
Nullable reset semantics remain explicit: UI Users accept full_name: null and
ui_language: null; UI Groups accept description: null and
avatar_icon: null.
The current-user profile PATCH follows the same contract. It accepts null
only for full_name and ui_language. Avatar preference, quota toggles,
ui_preferences, and password fields reject explicit null; use
avatar_preference: "auto" or ui_preferences: {} for those resets. Audit
metadata now preserves explicit nullable resets instead of dropping them.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical S3 and RGW create payloads¶
Create payloads for RGW Accounts, RGW Users, private S3 Connections, and Admin
S3 Connections now reject explicit tags: null; omit tags to use an empty
default or send an array to define tags. Private S3 Connection creation no
longer exposes the unsupported is_active field in the bundled frontend, and
custom-endpoint force_path_style / verify_tls values must be booleans when
present. Preset endpoint creation continues to omit those endpoint booleans so
the configured endpoint supplies them.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical S3 Connection PATCH nullability¶
Private and Admin S3 Connection PATCH payloads now reject explicit null for
fields that represent concrete mutations such as names, status/access flags,
custom endpoint URL and booleans, tags, association lists, and credential
rotation. Omit those fields to preserve the current value and use an empty list
to clear tags or Admin UI associations. The bundled frontend also omits the
Admin credentials field when no rotation is requested.
null remains intentional for fields with clear/detach/inherit semantics:
storage_endpoint_id, provider_hint, region, RGW identity fields, and the
Admin allow_activity_history override.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 explicit Admin principal access on create¶
Admin creation of local UI users, LDAP-imported UI users, and UI groups now requires explicit role and access choices. The bundled Admin forms already materialize these values, so backend models no longer supply authorization defaults when a create caller omits them.
Association collections keep their existing create defaults, including the intentional OpenStack association omission semantics, and PATCH/update payloads remain optional field-by-field. Deploy the backend and bundled frontend together. No database migration is required.
2026-11 explicit Ceph Admin RGW user mutation choices¶
Ceph Admin RGW user creation now requires an explicit generate_key choice,
and RGW capability updates require an explicit mode (replace, add, or
remove). The bundled create and edit forms already materialize these choices,
so the backend no longer selects a mutating default when either field is
omitted.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical Admin Portal settings PATCH payload¶
Admin account Portal settings updates now separate the replacement override
from delegation controls. Send the complete override under override; an
explicit empty object ("override": {}) clears account-specific Portal
overrides, while omitting override preserves the current override for a
delegation-only update.
The three delegation booleans and the override field reject explicit null.
Omit one of those control fields to leave it unchanged. Nullable values inside
override retain their existing inheritance/reset semantics.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical bucket quota write contract¶
Manager and Ceph Admin bucket quota updates now replace the quota subresource
with PUT instead of exposing replacement semantics through PATCH. The
payload requires an explicit enabled boolean: true requires at least one
quota limit, while false clears the quota and must not carry limits.
max_size_unit is required whenever max_size_gb is set and must be
omitted otherwise.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical bucket migration draft replacement¶
Manager bucket migration draft updates now use PUT instead of PATCH.
The update request already carries the complete draft definition plus its
configuration_revision, and saving a draft replaces that configuration
atomically before invalidating any previous precheck state.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 canonical Ceph Admin RGW PATCH nullability¶
Ceph Admin RGW account and user configuration PATCH payloads now reject
explicit null for boolean mutations and for the RGW user caps mutation.
Omit one of those fields to leave it unchanged and send an explicit boolean or
capability update to change it. This removes ambiguous cases where null
either behaved as a no-op or implicitly enabled a quota.
Intentional clear operations remain nullable: account and user text fields,
profile limits, and quota size/object limits still use null to request the
corresponding RGW clear/reset value.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 explicit Portal access-key target¶
Portal POST /portal/access-keys now requires a request body with an explicit
target_type (self or external). The bundled Portal UI already sends this
choice for personal and external access-key creation, so the backend no longer
treats an omitted body or target as an implicit personal-key request.
Deploy the backend and bundled frontend together. No database migration is required.
2026-11 explicit Portal Storage Space creation access¶
Portal Storage Space create and import requests now require the access choices
that the bundled UI already materializes. Creation requires an explicit naming
mode plus visibility, share_scope, nullable account_member_role, and
initial_shares; import requires the same access fields except the naming mode.
Sharing combinations are validated as canonical state instead of being silently
normalized. A PATCH that explicitly sets share_scope to account must also
send account_member_role as Viewer or Editor; the backend no longer
supplies an implicit Editor role. PATCH requests that do not change sharing
continue to omit those fields normally. visibility is creation-only and is no
longer accepted by the update payload. Explicit null clears nullable update
metadata such as description, project_key, and dataset_label, while
omitting a field leaves its current value unchanged.
Deploy the backend and bundled frontend together. No database migration is required.
2026-10 canonical OIDC provider collection payloads¶
Admin OIDC provider create and update requests now require JSON arrays for
scopes and trusted_email_domains. The application API no longer accepts
comma-separated strings or explicit null for those fields. The bundled
frontend already sends canonical arrays.
Environment OIDC configuration keeps its existing string parsing because environment variables are text. No database migration is required.
2026-10 canonical bucket Object Lock properties¶
Bucket property responses now expose Object Lock state only through the
object_lock object. The redundant top-level object_lock_enabled field has
been removed because it duplicated object_lock.enabled from the same storage
read and could drift from the detailed configuration.
Deploy the backend and bundled frontend together. Internal callers of bucket
property routes must read object_lock.enabled. No database migration is
required.
2026-10 API prefix configuration rename¶
The backend runtime setting formerly named API_V1_PREFIX has been renamed to
API_PREFIX. The configured route prefix remains /api by default; this change
removes the misleading version suffix from the configuration contract because
the application API is not mounted below a /v1 path.
Update custom environment files, deployment manifests, and secret/configuration
management to use API_PREFIX. The removed API_V1_PREFIX variable is no
longer read by the backend and has no compatibility alias. The bundled Helm
values now use API_PREFIX.
2026-10 canonical bucket migration diagnostic metadata¶
Migration 0182_canonical_bucket_migration_diagnostics makes nullable
diagnostic metadata explicit in persisted bucket migration precheck reports.
Existing checks gain null values for missing impact, remediation,
permission, context_id, bucket, and details fields instead of relying on
field omission.
Deploy the migration, backend, and frontend together. New diagnostics always
emit the complete canonical shape. Downgrade removes nullable fields whose value
is null for compatibility with the previous application version.
2026-10 bucket migration source-cleanup contract¶
Migration 0183_remove_bucket_migration_delete_source removes the obsolete
bucket_migrations.delete_source column and delete_source_safe precheck fields.
Source deletion is already an explicit, separately confirmed maintenance operation
through /cleanup-source; current migrations never schedule source deletion as a
transfer step.
Deploy the migration, backend, and frontend together. Creation and update payloads,
responses, precheck reports, and migration webhook payloads no longer expose the
retired setting. Downgrade recreates delete_source=false and restores the retired
precheck field as true, which matches the non-destructive transfer contract.
2026-10 bucket migration precheck safety cleanup¶
Migration 0184_remove_bucket_migration_report_safety removes the redundant
rollback_safe and same_endpoint_copy_safe booleans from persisted precheck
reports. Blocking safety is already represented by typed diagnostics with explicit
codes, severity and blocking state, and no runtime or frontend logic consumes the
aggregate booleans.
Deploy the migration, backend, and frontend together. Downgrade reconstructs the retired booleans from the persisted diagnostics so older downgrade steps can still rebuild their historical execution-plan shape.
2026-10 explicit bucket migration targets¶
Migration 0185_remove_bucket_migration_mapping_prefix removes the unused
bucket_migrations.mapping_prefix column. Each bucket mapping now requires its
final target_bucket explicitly; the Manager wizard already sends this canonical
shape after applying its prefix, suffix and per-bucket overrides.
Deploy the migration, backend, and frontend together. Existing migrations keep
their final destination names on bucket_migration_items, so no target data is
lost. Downgrade recreates the retired nullable prefix column without attempting to
infer a prefix from explicit target names.
2026-10 bucket migration target-state cleanup¶
Migration 0186_remove_bucket_migration_target_exists removes the unused
bucket_migration_items.target_bucket_exists column and the matching internal API
field. The value was never set to true or used by migration execution or the
Manager UI; target creation ownership is tracked separately by
target_created_by_migration.
Deploy the migration, backend, and frontend together. Downgrade recreates the
retired column with its historical false default.
2026-10 bucket migration cleanup-state simplification¶
Migration 0187_remove_bucket_migration_cleanup_status removes the unused
per-item cleanup_status column and matching internal API field. Maintenance
progress is tracked by the migration-level maintenance_status, while per-item
failures remain available through cleanup_error.
Deploy the migration, backend, and frontend together. Downgrade recreates the
retired per-item status with its historical idle default.
2026-10 bucket migration request-state simplification¶
Migration 0188_remove_bucket_migration_request_flags removes the redundant
pause_requested and cancel_requested boolean columns. The migration status
already carries the same request states atomically as pause_requested and
cancel_requested, and worker control now reads that status as the single source
of truth.
Deploy the migration and backend together. Downgrade recreates both booleans and derives their values from the matching status so older code sees the historical mirrored representation.
2026-11 typed bucket migration maintenance state¶
Manager bucket-migration responses now expose the existing maintenance state as
closed values. maintenance_operation is limited to restore_access,
cleanup_source, or cleanup_target, while maintenance_status is limited to
idle, queued, running, failed, or completed.
The preparation state is likewise exposed as the closed set unverified,
checking, blocked, ready, or stale.
Deploy the backend and bundled frontend together. Existing database rows do not require migration because these are the only values produced by the maintenance workflow since the fields were introduced.
2026-11 typed key-rotation result targets¶
Admin key-rotation results now expose target_type as the closed set endpoint,
account, or s3_user, matching the only target categories emitted by the
rotation service. Result status and durable rotation phase use the same canonical
closed types internally.
Deploy the backend and bundled frontend together. No database migration is required because this change only tightens the internal response contract around values already produced by the service.
2026-11 canonical bucket migration retry step¶
Migration 0237_canonical_bucket_migration_retry_step rewrites the retired
rollback_failed item step to sync for failed workflow-v2 bucket migrations.
That step was produced by the removed rollback workflow and only survived as a
special case in failed-item retry handling.
Historical workflow-v1 rows are left unchanged because they cannot be replayed.
The runtime no longer carries a rollback_failed compatibility branch. Downgrade
keeps the canonical sync value because the previous application already accepts
it and a reverse conversion would be ambiguous.
The current workflow also no longer treats the retired skip_existing strategy
as executable. Workflow-v2 planning has produced only current_only or
version_aware since workflow-v2 was introduced. Historical reports may still
display skip_existing, but those records are not replayable by the current
worker.
Current prechecks no longer emit the retired rollback_not_safe diagnostic.
Explicit rollback operations were removed in favor of restore_access and
cleanup_target, while Object Lock remains blocked by the specific
object_lock_governance_not_supported diagnostic. Historical reports and old
Alembic reconstruction logic may still contain rollback_not_safe.
Migration 0238_remove_retired_migration_webhooks removes persisted webhook
subscriptions for the three retired rollback audit events. These event types
can no longer be emitted because their Manager routes were removed. Other
subscriptions, wildcard subscriptions, historical audit records, and historical
webhook deliveries are preserved. Downgrade does not recreate deleted
subscriptions because their endpoint ownership cannot be reconstructed safely.
2026-10 onboarding journey state cleanup¶
Migration 0189_remove_onboarding_journey_dead_state removes the unused
evidence_json, readiness_json, and validated_at columns from
onboarding_journeys. The current guided onboarding flow stores its canonical
draft, created resources, pending step, and configured timestamp; the retired
columns were no longer populated or consumed.
Deploy the migration and backend together. Downgrade recreates the removed JSON columns as empty objects and restores the nullable validation timestamp.
2026-10 operation lease timestamp cleanup¶
Migration 0190_remove_operation_lease_acquired_at removes the unused
backend_operation_leases.acquired_at column. Lease ownership is determined by
lease_owner and lease_until, while updated_at already records acquisition,
renewal, and release writes; no runtime path consumed a separate acquisition
timestamp.
Deploy the migration and backend together. Downgrade recreates acquired_at
from the row's current updated_at value.
2026-10 first-admin bootstrap timestamp cleanup¶
Migration 0191_remove_first_admin_bootstrap_issued_at removes the unused
first_admin_bootstrap.issued_at column. Bootstrap availability and token
expiry are determined by token_digest, expires_at, and consumed_at;
no runtime path consumed a separate issuance timestamp.
Deploy the migration and backend together. Downgrade recreates issued_at as
a nullable column without reconstructing historical issuance timestamps.
2026-10 API token create response cleanup¶
The POST /api/auth/api-tokens response no longer includes the constant
token_type field. The frontend only consumes the one-time access_token
and the persisted api_token metadata.
Deploy matching backend and frontend versions together.
2026-10 onboarding response cleanup¶
Admin onboarding responses no longer expose the unused actor_id status field
or the internal journey pending_step. The backend continues to persist and
use pending_step to resume interrupted onboarding work; it is no longer part
of the frontend contract.
Deploy matching backend and frontend versions together.
2026-10 healthcheck response cleanup¶
Admin healthcheck read responses no longer expose the unused
resolution_seconds, baseline_latency_ms, or sample_count projection
fields. Rollup resolution, latency baselines, and sample counts remain internal
inputs to health evaluation and aggregation.
Deploy matching backend and frontend versions together.
2026-10 admin stats response cleanup¶
Admin statistics responses no longer expose the unused unassigned_accounts,
unassigned_s3_users, or accounts_with_usage counters. Assignment totals
and storage usage aggregates that are displayed by the frontend remain
unchanged.
Deploy matching backend and frontend versions together.
2026-10 bucket overview response cleanup¶
Admin and Manager storage statistics no longer expose the unused
largest_bucket and most_objects_bucket overview fields. Bucket-level
usage remains available in bucket_usage, while the overview keeps the
counts and averages displayed by the frontend.
Deploy matching backend and frontend versions together.
2026-10 quota test-email response cleanup¶
The quota notification SMTP test endpoint now returns only the recipient
address used for the successful test. The constant status and redundant
sent_at response fields were unused by the frontend; the message body still
records the send timestamp.
Deploy matching backend and frontend versions together.
2026-10 cost analytics response cleanup¶
Cost analytics concentration responses no longer expose
subject_total_cost. The value remains an internal intermediate used to
derive other_cost and top_five_ratio, which are the values displayed by
the frontend.
Deploy matching backend and frontend versions together.
2026-10 authentication response cleanup¶
Authentication responses no longer expose the unused S3-session
session_id and user_uid descriptor fields or the external-identity
link_request_id. Session and RGW user identifiers remain internal to
authentication and audit workflows, and external-identity link requests remain
traceable through audit records.
Deploy matching backend and frontend versions together.
2026-10 bucket comparison action response cleanup¶
Manager bucket-comparison action responses now return only
succeeded_count, failed_count, and the user-facing message. Request
identity fields, the planned count, and failed-key samples remain available to
the backend for orchestration and audit metadata instead of being duplicated in
the frontend response.
Deploy matching backend and frontend versions together.
2026-10 admin dashboard scope response cleanup¶
The Admin dashboard scope response now returns only each supervised endpoint's
endpoint_id and name. Internal Admin Ops URLs and per-feature enablement
flags remain backend inputs for collection, while collection failures continue
to expose their sanitized endpoint URL through coverage.issues where the
frontend actually displays it.
Deploy matching backend and frontend versions together.
2026-10 webhook delivery response cleanup¶
Admin webhook delivery read models no longer expose the unused
delivery_id, event_id, endpoint_id, next_attempt_at, or
created_at fields. Delivery scheduling and external webhook identifiers
remain persisted and continue to drive the worker and outbound webhook
protocol. The test-delivery action still returns its queued delivery_id.
Deploy matching backend and frontend versions together.
2026-10 bucket migration precheck response cleanup¶
Manager migration responses now expose an explicit precheck read model instead of returning the persisted precheck JSON verbatim. The response keeps the blocking/warning counts, diagnostics, and reviewed per-bucket plan used by the frontend. Internal context snapshots, source/target bucket profiles, target object counts, capability summaries, and duplicated status/revision metadata remain persisted for workflow execution but are no longer projected through the application API.
Deploy matching backend and frontend versions together.
2026-10 endpoint health status segment cleanup¶
Migration 0192_remove_endpoint_health_checks_count removes the unused
endpoint_health_status_segments.checks_count column. Health status segments
continue to retain their time range and latency aggregates; latency aggregation
uses the separate latency_sample_count state.
2026-10 quota alert state cleanup¶
Migration 0193_remove_unused_quota_alert_state removes four write-only
quota-alert history fields: last_ratio_pct, last_checked_at,
last_notified_level, and last_notified_at. Alert transition and
deduplication behavior continues to use the persisted last_level.
2026-10 Portal deleted-folder restore progress cleanup¶
Portal deleted-folder restore progress events no longer include the unused
current_key field. The frontend derives progress from the aggregate scan and
restore counters, so per-file keys are no longer serialized on every restore
completion event.
Deploy matching backend and frontend versions together.
2026-10 bucket migration list response cleanup¶
The Manager migration list endpoint now returns a dedicated summary read model instead of the full migration detail projection. List rows keep context IDs, workflow/preparation state, progress counters, maintenance state, and update time. Detailed configuration, actions, errors, and precheck reports remain on the single-migration endpoint and stream, avoiding unnecessary persisted-report parsing during list refreshes.
Deploy matching backend and frontend versions together.
2026-10 bucket migration read-model cleanup¶
Bucket migration list/detail responses no longer expose runtime fields that the Manager frontend never consumed. The trimmed fields include internal worker and revision state, unused timestamps and counters, plus the persisted strong-integrity setting. Recent migration events expose only the identifier, message and creation time used by the Manager UI; item linkage, severity and metadata remain persisted internally. Execution state remains stored and used by the backend exactly as before.
Deploy the backend and frontend together. This cleanup changes only the internal application API response shape and does not require a database migration.
2026-10 bucket migration execution strategy column¶
Migration 0179_bucket_migration_execution_strategy replaces the generic
execution_plan_json blob with a nullable execution_strategy column on
bucket migration items. Earlier cleanup reduced the plan to one runtime value;
precheck pass/fail state and blocking diagnostics already live in the migration
precheck report.
Deploy the migration and backend together. Draft items keep a null strategy until precheck assigns one, and runnable items require an explicit supported strategy. Downgrade reconstructs the former JSON payload from the strategy and the persisted precheck report.
2026-10 canonical bucket migration execution strategy¶
Migration 0178_canonical_bucket_migration_plan_strategy makes the execution
strategy explicit in current workflow-v2 item plans. Missing or blank strategy
values that previously meant current_only at runtime are rewritten once in
the database; surrounding whitespace is removed. Historical workflow-v1 rows
remain untouched because they cannot be replayed.
Deploy the migration and backend together. The worker no longer supplies a default strategy for persisted plans and rejects malformed plans instead. Downgrade keeps the explicit strategy because it is already accepted by the previous application version.
2026-10 bucket migration execution-plan safety cleanup¶
Migration 0177_remove_bucket_migration_plan_safety removes
delete_source_safe, rollback_safe, and same_endpoint_copy_safe from
persisted per-bucket execution plans. These values already live in the
precheck report and the worker never reads the execution-plan copies.
Deploy the migration and backend together. New execution plans contain only the fields needed to execute or reject an item. Downgrade reconstructs the retired safety fields from the canonical per-item precheck report when those values are available.
2026-10 bucket migration execution-plan cleanup¶
Migration 0176_remove_bucket_migration_plan_blocked removes the redundant
blocked flag from persisted per-bucket execution plans. The worker already
uses the canonical supported field to decide whether an item may run, so
persisting both booleans allowed contradictory state without adding behavior.
Deploy the migration and backend together. New execution plans omit blocked.
Downgrade reconstructs it as the inverse of supported for the previous
application version.
2026-10 bucket migration report version cleanup¶
Migration 0175_remove_bucket_migration_report_version removes the unused
report_version metadata from persisted bucket migration precheck reports and
per-bucket execution plans. Runtime code never selected behavior from this value,
so retaining it only implied a compatibility contract that did not exist.
Deploy the migration, backend, and frontend together. New reports and execution
plans omit report_version. Downgrade restores version 3 on valid persisted
objects for the previous application version.
2026-10 canonical bucket migration item identities¶
Migration 0174_remove_bucket_migration_item_identities removes duplicated
source_identity and target_identity fields from persisted per-bucket
precheck items. The execution contexts already belong to the migration record
and report context block, so keeping a copy on every item created redundant
state that could drift.
Deploy the migration, backend, and frontend together. New precheck reports no longer emit the per-item identity copies. Downgrade reconstructs them from the canonical migration source and target context IDs for the previous application version.
2026-10 canonical bucket migration diagnostic severity¶
Migration 0173_canonical_bucket_migration_severity rewrites persisted bucket
migration diagnostics to use only severity. Historical diagnostics that have
only the retired level alias are promoted to severity; when both fields
exist, severity remains authoritative and level is removed.
Deploy the migration, backend, and frontend together. New precheck diagnostics
no longer duplicate severity under level, and runtime readers no longer carry
the fallback. Migration event records still use their distinct level field.
Downgrade recreates diagnostic level from canonical severity.
2026-10 canonical bucket migration precheck diagnostics¶
Migration 0172_canonical_bucket_migration_checks rewrites persisted bucket
migration precheck reports so item diagnostics use only the canonical checks
field. Historical reports that contain only the retired messages alias are
migrated into checks; when both fields exist, checks remains authoritative
and messages is removed.
Deploy the migration, backend, and frontend together. New reports no longer
emit duplicate messages data, and the frontend reads only checks. Downgrade
recreates messages from canonical checks for the previous application version.
2026-10 context-bound direct transfer workers¶
Deploy the backend and frontend together. Direct transfers now obtain their
authorized endpoint policy through /api/browser/direct-transfer-policy and
load an HTTP worker below /api/browser/direct-transfer-worker/. Route that
worker prefix to the frontend Nginx, preserving its query string and the
existing /api session cookie. The bundled Helm ingress includes the exception
to its general backend API route. Outer proxies must preserve the worker's
single dynamic CSP and disable caching. No database migration is required.
Failed direct writes are no longer automatically replayed through the proxy; check the destination before retrying an uncertain write.
2026-10 Ceph Admin access-key read contract¶
Ceph Admin user access-key list and user-detail responses no longer include
secret_key. Existing RGW keys remain unchanged; this only tightens the
application API so ordinary reads cannot disclose stored or upstream-returned
secret material. Newly created access keys still return their secret once from
the dedicated creation response.
Deploy the backend and bundled frontend together. Direct callers must stop
expecting secret_key on existing-key reads. No database migration is required.
2026-10 surface-specific bucket operation requests¶
Bucket integrity checks, purge operations, and targeted usage-statistics scans
now expose separate request schemas for their execution surface. Manager routes
accept buckets; Storage Ops routes accept targets with an explicit execution
context; Ceph Admin routes accept RGW targets carrying the tenant and bucket
name. A request can no longer include, omit, or switch to another surface's
target shape and rely on router-side compatibility validation.
Deploy the backend and bundled frontend together. The canonical frontend JSON
payloads are unchanged, but direct callers using the wrong collection now fail
request validation with HTTP 422. No database migration is required for this
API cutover.
2026-11 canonical bucket operation targets¶
Manager bucket-integrity and bucket-purge requests now use targets, matching
the canonical collection name used by Storage Ops and Ceph Admin. The target
value remains surface-specific: Manager sends bucket-name strings, Storage Ops
sends execution-context targets, and Ceph Admin sends RGW tenant-aware bucket
references. The retired Manager buckets field is rejected with HTTP 422.
Bucket usage-statistics streams keep their current surface-specific target
contract. Storage Ops sends execution-context targets, Ceph Admin targeted
scans send RGW targets, and Manager aggregate or single-bucket scans derive
their bucket set from the selected context or path. Single-bucket stream routes
do not require a request body.
Deploy the matching backend and bundled frontend together for the Manager integrity and purge request cutover. No database migration is required.
2026-10 Ceph Admin tenant-aware bucket identity¶
Ceph Admin bucket operations now treat the physical bucket identity as the endpoint, RGW tenant, and unqualified bucket name. Targeted integrity, purge, usage-statistics, configuration backup, comparison, and bulk UI requests carry the tenant explicitly so two tenants may contain buckets with the same name without collapsing into one selection or persisted statistics row. The bundled frontend and backend must be deployed together because these internal request payloads changed without compatibility aliases.
Migration 0180_bucket_usage_stats_tenant_identity adds bucket_tenant to
persisted bucket usage snapshots and includes it in their uniqueness key.
Existing rows are assigned the default RGW tenant (''). Apply the Alembic
migration with the matching application release before resuming bucket usage
statistics collection.
2026-10 Manager and Browser execution-context selector¶
Manager and Browser routes that select an S3 execution identity now use the
context_id query parameter. The former account_id parameter is removed from
those routes because the selector may represent an account, S3 connection,
S3 user, or authorized Ceph Admin context. Portal routes continue to use
account_id because Portal selects a real BucketReef account.
There is no runtime alias from account_id to context_id. Deploy the matching
backend and frontend together, and update local scripts or functional clients
that call /manager or /browser directly.
2026-10 canonical production-readiness CLI¶
The deployment-check CLI now uses the same production_readiness terminology
as the Admin surface and service contract:
The former app.scripts.check_production_hardening module was only a naming
compatibility holdover and has been removed rather than retained as an alias.
Update local operational commands when deploying this backend version.
2026-10 canonical audit execution context¶
Migration 0155_canonical_audit_context completes the audit execution-context
cutover introduced by migration 0150. It backfills account-scoped audit rows
created while the compatibility columns still existed, converts historical
Portal account rows to context_kind=portal_account, and then removes
audit_logs.account_id, audit_logs.account_name, their foreign key, and their
account lookup index.
At that cutover, the Admin Audit and Manager Activity APIs exposed only
context_kind, context_id, and context_name; deploy the backend and frontend
together. The webhook event payload keeps its existing optional account object
so external webhook consumers are unaffected by the database/API cleanup.
2026-11 Manager activity response cleanup¶
GET /manager/activity no longer returns context_kind or context_id. The
request already selects one execution context and the backend filters audit rows
to that exact context, so those response fields duplicated request scope and had
no frontend consumer. context_name remains available for historical display
when an activity row has no more specific target identifier. Deploy the backend
and frontend together.
2026-10 canonical Portal collaborator requests¶
Migration 0156_canonical_portal_user_access_requests completes the Portal
collaborator request cutover. Historical portal_user_access additions that
predate explicit collaborator intents and roles are rewritten with
intent=add and portal_role=portal_user. Current role-change requests and
explicit portal_manager additions are preserved.
After this migration, the runtime no longer supplies missing intent or role defaults when executing a persisted collaborator request. A malformed row is failed instead of being interpreted as a Portal User addition. Persisted intent, role, and role-change identifiers are consumed with their canonical JSON types and values; the runtime does not trim or coerce malformed values. Apply the database migration before starting the matching backend version.
2026-10 canonical audit statuses¶
Migration 0157_canonical_audit_status reduces persisted audit outcomes to the
canonical values success, failure, and partial. Historical failed and
error rows are rewritten to failure, including differences in case or
surrounding whitespace. The migration stops if another unknown status exists so
operators can repair it explicitly instead of silently changing its meaning.
After the migration, the database enforces the canonical status set. Manager
Activity therefore filters and renders failure directly and no longer carries
aliases for historical values. Apply the database migration before starting the
matching backend version.
RGW tenant identity¶
Migration 0152_rgw_principal_tenants adds non-null rgw_tenant fields to
s3_accounts and s3_users, with the empty string as the canonical
representation of the default RGW tenant. Existing pre-tenant BucketReef
identities are migrated directly to that default tenant instead of retaining an
unknown runtime state.
Migration 0153_rgw_tenant_default_compat repairs development databases that
may already have executed an earlier, nullable draft of 0152. It converts
remaining NULL tenant values to '', restores the non-null/default schema,
and removes the obsolete expression index used by that draft. Current
installations still run the revision in sequence, but normal runtime code does
not keep a nullable-tenant compatibility path.
S3 user uniqueness covers endpoint, tenant and UID. Downgrade is refused if UIDs would violate the former global uniqueness constraint. Back up the database before upgrading, as for other schema changes.
Bucket migration workflow v2¶
Migration 0135_bucket_migration_workflow adds persisted preparation, revision-bound
reports, recovery journals, destination provenance and independent cleanup state.
Deploy backend, worker, and frontend together.
Before upgrading, stop admitting new migration commands. Finish or explicitly stop all queued, running, paused and awaiting-cutover operations using the old version. Verify restoration of destination protections and of source protections for failed or canceled operations. Back up the database and configuration, then stop the old application/workers before applying Alembic. The schema upgrade refuses to proceed while active operations or unresolved protections are recorded. This check does not contact S3: operators must also verify the actual storage policies.
Historical final operations remain visible as workflow v1 and cannot be replayed. Their records are not queued again. Old draft reports and item plans are invalidated; source deletion is disabled on these drafts and checks must be repeated. Successfully retained read-only sources can be restored explicitly after upgrading.
API compatibility changes:
POST /manager/migrations/{id}/precheckqueues preparation and returns 202.{ "active_checks": false }(the default) is read-only;trueexplicitly acknowledges active tests after the UI has displayed their effects.GET /manager/migrations/{id}and its existing SSE stream publish progress, preparation state, typed diagnostics and backend-authorized actions.POST /manager/migrationsaccepts only draft configuration fields. The update-onlyconfiguration_revisionfield is rejected on creation.PUTdraft updates requireconfiguration_revision; they increment it and invalidate the report.POST /startrequires the checked revision and, for immediate mode,confirm_write_interruption: true. Reports expire after 15 minutes.POST /continuerequires{ "confirmed": true }for cutover.POST /restore-access,/cleanup-targetand/cleanup-sourcerequire explicit confirmation and return 202. Their status is independent of the transfer result.- Source cleanup is available only through the explicit
/cleanup-sourceoperation. Migration configuration no longer has adelete_sourcefield. The combined rollback endpoints reject execution and direct clients to the separate recovery operations.
Preparation has its own worker loop, separate from long copies. Both loops renew leases during blocking storage requests. Mutation intents and original policies are saved before active probes; expired leases allow recovery by another worker. Incomplete restoration blocks preparation. Diagnostics/events exclude secrets and policy backups; only operator commands are added to the audit log.
Do not downgrade while any operation or protection is active: downgrade refuses that state. For rollback, use the verified database backup and matching previous application only after stopping writers and verifying storage protection restoration. Never allow old and new workers to process the same migration database concurrently.
2026-09 canonical onboarding journeys¶
Migration 0131_canonical_onboarding_journeys removes pre-v2 onboarding
journey rows. A configured historical journey is reduced to the per-admin
initial_setup_completed_at marker so the setup assistant stays completed
until that administrator starts a new current journey. Historical incomplete
journeys were already hidden by the current UI and are discarded.
After the migration, runtime onboarding code accepts only version-2 journey payloads and no longer parses older journey formats. Downgrade removes the completion marker and cannot reconstruct deleted historical drafts.
2026-09 canonical S3 identity whitespace¶
Migration 0127_canonical_s3_identity_whitespace trims surrounding whitespace
from persisted s3_accounts.rgw_account_id, s3_accounts.rgw_user_uid, and
s3_users.rgw_user_uid, then requires those database values to remain already
trimmed and non-empty. Case and all non-surrounding characters are preserved.
The migration stops before changing data if trimming would make two unique
identities collide (s3_accounts.rgw_account_id or s3_users.rgw_user_uid).
Repair those conflicting rows before upgrading. After the migration, runtime
code consuming persisted account and S3-user identities trusts the database
invariant instead of retaining whitespace cleanup compatibility paths.
Downgrade restores the previous non-empty constraints but cannot restore whitespace removed by the upgrade.
2026-09 canonical S3 user identities¶
Migration 0126_canonical_s3_user_identities makes the existing S3-user RGW
identity contract explicit in the database: s3_users.rgw_user_uid must contain
at least one non-whitespace character. Creation and import normalize explicit UID
input before persistence. Current creation treats whitespace-only optional UID
input the same as an omitted UID and generates a namespaced
bkr-s3u-<uuid> identifier.
The migration stops with an explicit error if an existing row contains a blank UID because BucketReef cannot safely invent the corresponding remote RGW identity. Repair those rows before upgrading. After the migration, the runtime does not retain a blank-UID compatibility path. The downgrade removes the check constraint but does not recreate invalid values.
2026-09 canonical Manager usage snapshot scopes¶
Migration 0124_canonical_manager_usage_scopes replaces accepted alternative
spellings of Manager context IDs in bucket usage snapshots, such as 0001,
conn-0008, and s3u-0003, with the resolved identifiers 1, conn-8, and
s3u-3. Account, connection, and S3-user scopes stay separate. Direct-session
IDs, unrecognized scopes, other workspaces, and historical audit rows are
unchanged.
When several snapshots map to the same context and bucket, the migration keeps
the newest calculated_at, breaking ties by updated_at and then the highest
row ID. It preserves that row's statistics, warnings, and timestamps and
removes only its superseded duplicate snapshots. Back up the database first;
downgrade leaves canonical snapshots intact and cannot restore discarded
duplicates or their original selector spellings.
Stop old backend instances and ongoing usage scans before applying the migration, then deploy the matching backend so subsequent scans use the resolved context ID. No runtime alias lookup is retained. Native storage permissions and the accepted request selectors are unchanged.
2026-09 least-privilege containers and strict network policy¶
The application images now run with fixed non-root identities and a read-only
root filesystem. nginx moved from container port 80 to 8080; Compose host
port 8080 and the Helm frontend Service port 80 are unchanged. Replace the
old runtime-installing Compose scheduler with the matching dedicated scheduler
image. Preserve the backend /data volume and provide a writable /tmp only;
do not make the image root writable to work around startup failures.
Before the first rootless Compose start, stop the old backend and inspect the
existing named volume ownership. If its files were created by root, perform a
single controlled ownership migration to UID/GID 10001:10001 using the exact
volume name from docker volume ls; back up the volume first. Do not recreate
or replace it, because it contains the SQLite database and historical encrypted
credentials.
Helm enables the strict NetworkPolicy profile by default and intentionally
refuses incomplete values. Before upgrading, inventory the namespace/pod labels
of the ingress controller and DNS service, the exact proxy pod CIDRs, every
external database CIDR, and all private storage or webhook target CIDRs and
ports. Configure networkPolicy.ingressController, networkPolicy.dns,
networkPolicy.publicHttpsEgress, and any required
networkPolicy.privateEgress entries. Public HTTPS ranges must explicitly
exclude private, loopback, link-local, metadata, multicast, and reserved
networks. Render and review the resulting policies before applying them.
This is a breaking deployment boundary: old Helm values that lack selectors or egress rules no longer render in the strict profile. Disabling the profile is reserved for an isolated migration validation; production operators must complete the inventory rather than leave it disabled.
2026-09 trusted proxy boundary¶
The application now reports an empty TRUSTED_PROXY_CIDRS as a Warning: with
no trusted peers it safely ignores forwarded client addresses. Trusting the
entire IPv4 or IPv6 address space is a startup security blocker in production.
The Helm chart intentionally keeps a stricter deployment contract and requires
the structured backend.trustedProxyCidrs value; it rejects a raw
backend.env.TRUSTED_PROXY_CIDRS override. Before upgrading, identify the
actual direct peers that connect to the backend and configure their narrow
CIDRs. Requests from any other peer ignore X-Forwarded-For; trusted chains
continue to be evaluated from right to left so an injected left-most value
cannot select a new rate-limit identity.
For Docker Compose with a fixed proxy address, a /32 entry is preferred. For
Kubernetes, use the verified ingress-controller pod subnet or addresses rather
than the entire cluster or private address space. The chart intentionally fails
to render until this boundary is supplied.
2026-09 outbound target allowlists¶
Production now fails closed for user-controlled outbound destinations. Populate
USER_SUPPLIED_S3_ENDPOINT_ALLOWED_HOSTS for user-created S3 connections and
WEBHOOK_ALLOWED_HOSTS for webhook endpoints before the
upgrade. A plain entry authorizes only that exact hostname; subdomains require
an explicit *.example.com entry, which does not authorize the apex.
Run the preflight against the existing database before deploying:
The command prints only uncovered hostnames. Existing user-created manual connections outside the allowlist remain stored but cannot be used until the operator updates the allowlist. Admin-registered storage endpoints remain available. Existing webhook URLs outside the webhook allowlist cannot be saved or delivered. Production webhooks use HTTPS unless the private-target option and an explicit host allowlist entry are both configured.
Migration 0132_webhook_endpoints replaces the former per-migration
bucket_migrations.webhook_url field with global Admin-managed webhook
endpoints and a durable delivery queue. Distinct legacy migration callback URLs
are imported once as disabled endpoints subscribed to
manager.bucket_migration.event; they intentionally have no signing secret and
must be reviewed, assigned a new secret, and enabled by a super-administrator.
The temporary BUCKET_MIGRATION_WEBHOOK_* configuration aliases have been
removed. Before upgrading, migrate any remaining webhook settings to the
canonical WEBHOOK_* variables. The durable database queue has no queue-size
environment setting.
2026-09 Manager and Portal account-role split¶
Migration 0122_split_account_access_roles replaces the single association
role with independent manager_role and portal_role columns on direct user
and UI-group links. It also removes the obsolete BucketReef users.is_root and
user_s3_accounts.is_root columns. Ceph account-root identities, RGW account
credentials, and the corresponding technical sessions are unchanged.
The migration maps account_administrator and former root links to Manager
administrator only; portal_user and portal_manager map to the matching
Portal role only. It adds database constraints requiring at least one role and
allowing Manager Browser data access only with a Manager administrator role.
Backend, frontend, and migration must be deployed together because the old
role contract is rejected.
Alembic does not contact RGW, delete AccountIAMUser rows, reconcile Portal IAM,
or install a post-migration cleanup hook. Historical IAM identities are left
untouched. This project is treated as not yet deployed in production; if an
existing development environment is inconsistent, recreate its database and
RGW test resources instead of adding migration compatibility machinery.
Normal runtime synchronization remains active for explicit Portal-role grants and revocations after the migration. Downgrade is refused when any association contains both a Manager and Portal role because the former schema cannot represent that state without losing access information.
2026-08 first-administrator bootstrap cutover¶
Migration 0119_first_admin_bootstrap adds the one-time bootstrap singleton.
The former SEED_ + SUPER_ADMIN_{EMAIL,PASSWORD,FULL_NAME,MODE} environment
family and automatic startup creation have been removed without aliases or
runtime warnings.
Before upgrading a deployment that depended on those variables, use the old
release to confirm the administrator exists. If the database is empty, deploy
the migration/backend, then immediately either issue a temporary URL with
python -m app.scripts.issue_first_admin_bootstrap or create the administrator
with python -m app.scripts.create_first_admin; only then remove the former
variables from Compose, Helm values and secret management. Existing user
databases do not reopen bootstrap. Existing-administrator recovery remains a
separate command and never creates a new first user.
Deploy migration, backend and frontend together. The Admin onboarding response
uses complete and the journey list as its setup-state contract; obsolete
endpoint/storage readiness summary fields are no longer returned.
2026-08 authentication cutover¶
Migrations 0107 through 0110 replace legacy browser Bearers and refresh
rows with revocable database sessions, single-use refresh families, separate
external identities, WebAuthn, recovery codes, persistent rate limits, and
scoped API tokens. The cutover revokes every existing UI session and API token,
deletes every S3 session and its credential material, and purges OIDC states.
This is a backend/frontend/configuration big-bang boundary; there is no legacy Bearer compatibility. Apply the cutover as one maintenance operation:
- Stop the frontend, backend replicas, schedulers, and CronJobs.
- Create and verify a restorable database backup. Keep the old credential encryption key with it.
- Before changing
CREDENTIAL_KEYS, use the existing Admin key-rotation workflow to re-encrypt every persisted credential with a strong new primary key. Validate reads while the old key remains second in the ring, then retire it. - Generate strong, mutually distinct
UI_JWT_KEYS,API_JWT_KEYS, andCREDENTIAL_KEYS, plus a strong scheduler token. Configure TLS, exact origins and hosts, WebAuthn, trusted proxy CIDRs, and registered S3 endpoints. - Set
BUCKETREEF_DB_BACKUP_VERIFIED=trueonly for the verified migration run. Deploy backend, frontend, migrations, and configuration together. - Create the first superadmin interactively if the database has no users. Otherwise notify every user that reauthentication is required and every automation owner that API tokens must be recreated with explicit scopes.
- Verify passkey enrollment and login, refresh rotation, session inventory and revocation, API scopes, OIDC reauthenticated linking and administrator fallback, LDAP linking, S3 expiry, security headers, schedulers, and audit redaction.
Migration 0109 erases S3 session secrets and has no data-restoring downgrade.
If rollback is required after 0109, stop all writers and restore the
pre-deployment database and matching credential keys. Do not run Alembic
downgrade through the cutover.
2026-08 strict API object contracts¶
All backend application request and response objects now reject unknown
properties. Canonical frontend requests are unchanged, but an API request that
still sends a removed field now receives 422 instead of silently discarding
it. Deploy the backend and frontend together, and remove obsolete properties
from any local scripts before upgrading.
2026-08 canonical object data plane¶
The unused Manager object upload, folder creation, deletion, and presigned
download routes under /api/manager/buckets/{bucket_name}/objects/* have been
removed. The Manager bucket detail keeps its read-only object listing endpoint.
Use the Browser object endpoints for data-plane operations; there is no Manager
compatibility alias. Deploy the backend and frontend together, and migrate any
local functional tooling to the Browser routes before upgrading.
2026-08 strict environment-managed provider configuration¶
Entries nested under OIDC_PROVIDERS, LDAP_PROVIDERS, and
ENV_STORAGE_ENDPOINTS now reject unknown fields instead of silently ignoring
them. Before deploying, remove obsolete fields and correct misspelled names in
those environment values. Valid configurations and the top-level handling of
unrelated process environment variables are unchanged.
2026-08 canonical Storage Endpoint feature configuration¶
Migration 0115_canonical_storage_endpoint_features rewrites every persisted
Storage Endpoint feature document under the single features root inside the
then-current YAML features_config column. It converts the former health-check
url and endpoint aliases to healthcheck_url, normalizes configured URLs
and modes, and removes unknown feature names or fields that the runtime
previously ignored. Invalid active values with the wrong type stop the migration
explicitly. The downgrade keeps the canonical YAML because discarded inert
keys and aliases cannot be reconstructed.
That YAML contract was an intermediate migration state. Migration
0200_structure_storage_endpoint_features later replaces the persisted
features_config column with structured features. Current API and
ENV_STORAGE_ENDPOINTS payloads use that structured field directly; only
SEED_S3_ENDPOINT_FEATURES keeps the documented YAML/JSON text boundary. See
structured Storage Endpoint features.
2026-08 canonical Storage Endpoint providers¶
Migration 0116_canonical_storage_endpoint_providers trims and lowercases the
persisted provider values ceph, aws, and other, converts every missing or
unsupported historical value to the previously effective ceph default, and
adds a database constraint. New invalid values now fail validation instead of
being interpreted silently as Ceph. The downgrade removes the constraint but
keeps the canonicalized values.
2026-08 canonical Storage Endpoint admin endpoint¶
Migration 0117_remove_storage_endpoint_admin_endpoint removes the redundant
storage_endpoints.admin_endpoint column. At that migration boundary, the
configured override already lived in features_config at
features.admin.endpoint. Migration 0200_structure_storage_endpoint_features
subsequently moves that document into the structured features column, which
is the current persisted source. The downgrade recreates an empty nullable
column but cannot reconstruct its former duplicate values.
Storage Endpoint create and update requests now reject the removed
admin_endpoint property. Put the override in the canonical features object
instead. Storage Endpoint responses expose it through
features.admin.endpoint; the separate feature-detection request keeps its
transient admin_endpoint probe input. Deploy migration, backend, and frontend
together.
2026-08 canonical Storage Endpoint URLs¶
Migration 0118_canonical_storage_endpoint_urls trims persisted Storage
Endpoint URLs, removes trailing slashes, and adds a database constraint that
keeps new values canonical. The migration stops before changing the schema if
an URL becomes empty or if two endpoints would become duplicates after
normalization; repair or delete the reported rows and retry the upgrade.
Runtime Ceph Admin consumers now trust this database contract instead of repairing endpoint URLs or supplying missing provider, region, and TLS values. The downgrade removes the constraint but keeps the normalized URLs.
2026-08 Clipboard API requirement¶
Frontend copy actions now rely exclusively on the browser Clipboard API. The
deprecated document.execCommand("copy") fallback has been removed. Serve the
application from a context where navigator.clipboard.writeText is available;
otherwise copy actions report that the clipboard is unavailable.
2026-08 minimal Topic contract¶
Manager Topic responses no longer expose the unused owner and is_ceph
properties. Provider-specific listing remains an internal backend concern;
clients receive only the canonical topic name, ARN, and configurable
attributes. Deploy the backend and frontend together.
2026-08 minimal Portal state contract¶
GET /api/portal/state now returns only effective Portal role, permissions,
and feature flags. The duplicated project ID, IAM identity, access-key list,
provisioning marker, endpoint, usage, quota, and creation marker fields have
been removed. Use the selected /api/portal/accounts entry for project
identity, /api/portal/access-keys for IAM identity and keys, and
/api/portal/usage for usage and quotas. Deploy the backend and frontend
together.
2026-08 removal of temporary S3 connections¶
Migration 0106_remove_temporary_s3_connections removes the retired
is_temporary, temp_user_uid, and temp_access_key_id columns. The internal
temporary-connection cleanup route and the hidden execution-context contract
are removed with them. Expiring STS credentials remain supported through
session_token and expires_at.
The migration stops before changing the schema if a temporary connection still exists. While the previous release is running, revoke every remote RGW access key recorded by those rows and then delete the corresponding temporary connections. Verify a restorable database backup before retrying the upgrade. Deploy the migration, backend, and frontend together. Downgrade recreates empty compatibility columns but cannot restore the removed subsystem or remote keys.
2026-08 canonical execution-context catalogue¶
The unused GET /api/manager/accounts endpoint has been removed. The frontend
already uses GET /api/me/execution-contexts?workspace=manager, whose explicit
context kinds and capabilities replace the heterogeneous account-shaped
response. Requests to the removed endpoint now return 404. Canonical account
responses now always include a non-null Storage Endpoint ID, name, URL, and
capability map, plus an explicit default-endpoint flag. Execution-context
responses likewise always include endpoint name, URL, default flag, and
capabilities; only the endpoint ID remains nullable for custom connections.
The catalogue no longer returns quota_max_size_gb, quota_max_objects,
max_buckets, max_users, max_roles, or max_groups: these fields were
always null after dynamic RGW limit lookups moved to the dedicated Manager
context endpoint. Deploy the backend and frontend together.
2026-08 removal of the dead Portal key setting¶
Migration 0093_remove_dead_portal_key_setting removes allow_portal_key
from global application settings and account-level Portal overrides. The flag
was persisted and exposed by the API but never affected Portal behavior.
Deploy the migration, backend, and frontend together. Portal settings payloads containing the removed field are rejected, including custom bootstrap JSON files. Invalid bootstrap files now fail explicitly instead of silently loading defaults. Downgrade does not recreate this no-op value.
2026-08 canonical Portal access-key bucket field¶
Portal access-key responses now expose the selected S3 bucket only as
bucket_name. The duplicate response field storage_space_id has been
removed; it remains the request field used when creating an external key.
Deploy the backend and frontend together.
2026-08 canonical UI user roles¶
Migration 0092_canonical_user_roles converts users.role to exactly one of
ui_superadmin, ui_admin, ui_user, or ui_none, installs a database check
constraint, and sets the database default to ui_user. Known historical names
are mapped to their canonical role; unknown or empty values become ui_none so
the migration never widens access.
Deploy the migration, backend, and frontend together. Admin user APIs reject
removed role names with 422, and the frontend no longer repairs roles from
API responses or persisted sessions. Downgrade drops
the constraint but does not recreate historical role spellings.
2026-08 control-plane audit boundary¶
Migration 0091_purge_data_plane_audit_logs irreversibly removes historical
object data-plane actions and non-audit operational noise from audit_logs.
Take a verified application database backup immediately before applying it;
downgrade is intentionally unsupported and recovery requires restoring that
backup. Deploy the migration, backend, and frontend together.
The application audit now contains only control-plane, security,
configuration, and global workflow-control events. Object evidence moves to
Server Access Logging or the provider's equivalent. Portal clients must use
/api/portal/access-logs/page and /api/portal/access-logs/raw; the
removed non-paginated /api/portal/access-logs route,
/api/portal/transfers, and
/api/portal/transfers/server-access-logs* routes return 404. The
remaining access log routes do not accept mode and expose all S3 categories
with action, space, path, identity, and result filters.
2026-08 canonical bucket migration JSON state¶
Migration 0090_canonical_bucket_migration_json rewrites persisted bucket
migration reports, snapshots, plans, replication state, policy backups, diff
samples, and event metadata to JSON objects or SQL NULL. Invalid operational
state becomes NULL, forcing safe recomputation or a new precheck. Historical
diff and event values remain available under value or unparsed envelopes.
The absence of an original bucket policy is now stored directly as SQL NULL
instead of the JSON scalar null.
Deploy the migration and backend together. Worker and API readers now reject
malformed or non-object persisted JSON rather than silently treating it as
missing state. The cleanup is not reversed on downgrade.
Migration 0213_structure_bucket_migration_json later replaces these canonical
text JSON values with structured JSON columns.
2026-08 canonical custom S3 connection endpoints¶
Migration 0089_canonical_s3_connection_endpoints rewrites every manual S3
connection endpoint with the then-current JSON fields, maps the retired
provider_hint key inside that blob to provider, supplies the migration's
boolean defaults, and clears custom JSON from connections bound to a registered
Storage Endpoint. The
migration stops with the affected connection ID if a manual connection has no
usable endpoint URL; repair or delete that invalid row before retrying.
Deploy the migration and backend together. Runtime readers now reject malformed,
partial, or unknown custom endpoint data instead of repairing it or consulting
removed model attributes. Registered endpoints also propagate their configured
TLS verification flag to connections. The cleanup is not reversed on downgrade.
Migration 0199_normalize_s3_connection_custom_endpoints later removes that
intermediate text blob and stores the custom endpoint fields in dedicated
columns. See
normalized S3 connection custom endpoints.
2026-08 canonical account Portal settings overrides¶
Migration 0088_canonical_portal_settings_override replaces the historical
{"admin": {...}} envelope with the direct PortalSettingsOverride object.
It removes obsolete portal_manager data and unknown or invalid fields while
retaining every valid current override. Empty, malformed, and non-object values
become NULL, the canonical representation of no account override.
Deploy the migration and backend together. The backend no longer unwraps old
payloads or hides invalid persisted values, and the API rejects unknown override
fields. The data cleanup is not reversed on downgrade.
Migration 0217_structure_portal_settings_override later changes this canonical
text representation to structured JSON.
2026-08 canonical audit metadata¶
Migration 0087_canonical_audit_metadata rewrites every non-null audit metadata
payload as a JSON object. Existing objects retain their fields, other valid JSON
values move under value, and malformed historical text moves under unparsed
so old audit evidence is not discarded. New oversized metadata uses a bounded,
valid JSON envelope with a preview and the original serialized length.
Deploy the migration and backend together. Audit and Portal readers now share a
strict object contract instead of hiding malformed storage independently. The
data cleanup is not reversed on downgrade.
Migration 0215_structure_audit_metadata later replaces the canonical text
metadata representation with structured JSON.
2026-08 canonical cost operation breakdowns¶
Migration 0086_canonical_billing_ops_breakdown rewrites each available daily
operation breakdown as a JSON object mapping operation names to integer counts.
Malformed, non-object, and empty payloads become NULL, which remains the
canonical representation when detailed operation data was not collected.
Deploy the migration and backend together. Cost aggregation now rejects any
remaining non-canonical breakdown instead of skipping it or coercing values at
runtime. The data cleanup is not reversed on downgrade.
Migration 0218_structure_cost_measurement_breakdowns later changes the
canonical text breakdowns to structured JSON.
2026-08 canonical bucket usage statistics JSON¶
Migration 0085_canonical_bucket_usage_stats_json rewrites every persisted
bucket distribution as a JSON list of objects and every non-null warning set as
a JSON list of strings. Malformed containers and entries are removed once; at
this migration boundary, warnings_json = NULL is the canonical representation
of no warnings.
Deploy the migration and backend together. Snapshot loading now validates every
distribution entry and warning instead of returning empty data for malformed
storage. The data cleanup is not reversed on downgrade.
Migration 0207_structure_bucket_usage_stats_payloads later replaces the text
distribution and warning columns with structured JSON lists.
2026-08 canonical managed-access IAM state¶
Migration 0084_canonical_managed_access_iam_lists rewrites the tracked IAM
groups, managed policies, and inline policy names for every managed private
access as ordered, deduplicated JSON lists of non-empty strings. Malformed or
non-list values become empty lists.
Deploy the migration and backend together. Saga replay and cleanup now reject
any remaining malformed or non-string IAM state instead of coercing or dropping
values at runtime. The data cleanup is not reversed on downgrade.
Migration 0210_structure_managed_access_iam_lists later replaces these
canonical text lists with structured JSON lists.
2026-08 legacy Portal application settings¶
Migration 0099_migrate_legacy_portal_app_settings updates every database-backed
application settings payload that still uses the former Portal contract. It
renames allow_portal_user_bucket_create to
allow_private_storage_space_create without overwriting an existing current
value, and removes the obsolete bucket_access_policy,
iam_group_manager_policy, and iam_group_user_policy fields. Deployments that
already applied the equivalent manual repair are left unchanged.
The migration validates all rows before writing any update. It stops explicitly
when a payload or its portal section is not a JSON object, or when the legacy
create setting is not a boolean. Restore or correct that source value before
retrying the upgrade. The optional APP_SETTINGS_PATH bootstrap file is outside
Alembic's database scope and must already use the current field names. Removed
policy values and renamed settings are not reconstructed on downgrade.
2026-08 canonical UI-managed OIDC scopes¶
Migration 0083_canonical_oidc_provider_scopes rewrites every UI-managed OIDC
scope set as a non-empty JSON list of trimmed strings. Empty, malformed, or
non-list values receive the current openid, email, and profile defaults.
Deploy the migration and backend together. OIDC provider loading now rejects
any remaining malformed, empty, or non-string scope set instead of repairing it
at runtime. The ORM and database defaults are also aligned. Data cleanup is not
reversed on downgrade.
Migration 0203_structure_oidc_provider_lists later replaces this canonical
text representation with structured JSON.
2026-08 canonical persisted application settings¶
Migration 0082_canonical_app_settings_payload rewrites every database-backed
application settings payload as a JSON object and replaces malformed or
non-object values with {}. Valid object fields remain unchanged.
Deploy the migration and backend together. Once settings have been imported to
the database, loading now uses the strict AppSettings contract and exposes
invalid values instead of reverting silently to defaults. The optional disk
bootstrap uses defaults only when the configured bootstrap file is absent; an
invalid file fails validation and must already use the current schema. Data
cleanup is not reversed on downgrade.
Migration 0205_structure_app_settings_payloads later replaces the canonical
text payload with the structured JSON payload column.
2026-08 canonical Portal request JSON¶
Migration 0081_canonical_portal_request_json rewrites every Portal request
payload and non-null result as a JSON object. Malformed and non-object values
become {} while an absent result remains NULL for undecided requests.
Deploy the migration and backend together. Portal request execution and API
serialization now reject any remaining malformed or non-object JSON instead of
repairing it at runtime. The data cleanup is not reversed on downgrade.
Migration 0208_structure_portal_request_payloads later replaces the canonical
text payload and result columns with structured JSON objects.
2026-08 canonical user notification payloads¶
Migration 0080_canonical_user_notification_payloads rewrites notification
payloads as JSON objects, replaces null or malformed values with {}, and makes
user_notifications.payload_json non-nullable with the same database default.
Deploy the migration and backend together. Notification serialization now
rejects non-object or malformed payloads instead of silently returning an empty
object. Downgrade makes the column nullable again but keeps canonicalized data.
Migration 0201_structure_user_notification_payloads later replaces this text
column with the structured JSON payload column.
2026-08 canonical user UI preferences¶
Migration 0079_canonical_user_ui_preferences rewrites every persisted user UI
preference payload to the current theme and selected_portal_account_id
contract. Malformed or invalid payloads become empty preferences, removed fields
are discarded, and account identifiers are trimmed.
Deploy the migration and backend together. The backend now treats any remaining
non-canonical payload as data corruption instead of repairing it during profile
serialization. The data cleanup is intentionally not reversed on downgrade.
Migration 0212_structure_user_ui_preferences later replaces the canonical text
preferences with the structured JSON ui_preferences column.
2026-08 normalized tags only¶
Migration 0078_remove_legacy_tags_json removes the tags_json mirrors from
storage endpoints, S3 accounts, S3 users, and S3 connections. Normalized tag
definitions and ordered link tables have been the only read source since their
introduction; the backend now writes only that canonical model.
Deploy the migration and backend together because older instances still write the removed columns. Downgrade recreates each JSON mirror from the normalized links in stored order, but the current backend never reads or maintains it.
2026-08 canonical S3 connection capabilities¶
Migration 0077_canonical_s3_connection_capabilities rewrites every cached S3
connection capability profile to a JSON object containing the required boolean
can_manage_iam. Malformed profiles and the removed iam_capable key resolve
to the safe value false; unrelated current extension fields are retained. The
database default is changed to the same canonical profile.
Deploy the migration and backend together. The backend now treats missing,
malformed, or non-canonical profiles as data corruption instead of repairing
them at runtime. Downgrade restores the old empty-object default but cannot
recreate discarded malformed or legacy values.
Migration 0219_structure_s3_capabilities later replaces the canonical text
profile with the structured JSON s3_connections.capabilities column.
2026-08 schema index reconciliation¶
Migration 0076_remove_redundant_provider_indexes removes the non-unique LDAP
and OIDC provider_id indexes that duplicated the existing unique constraints.
It does not rewrite provider data or weaken uniqueness. The SQLAlchemy metadata
now also reflects the indexes already installed by earlier migrations, and the
full Alembic head is checked against that metadata in the backend test suite.
2026-08 canonical S3 session capabilities¶
Migration 0075_canonical_s3_session_capabilities materializes a complete
capability snapshot for every existing direct S3 session, replaces missing or
malformed snapshots with the current safe defaults, and makes
s3_sessions.capabilities non-nullable. The backend no longer repairs invalid
session capability data at runtime.
Stop backend instances while applying the migration so no session is created
during the table alteration. Existing direct S3 sessions remain usable with
their canonicalized snapshot. Downgrade makes the column nullable again but
does not recreate missing or malformed values; deploy matching code if a
downgrade is unavoidable.
Migration 0219_structure_s3_capabilities later changes the session capability
snapshot from text JSON to structured JSON while retaining the column name.
2026-08 timezone-aware UTC migration¶
Migration 0074_timezone_aware_utc_timestamps converts every persisted
PostgreSQL timestamp to TIMESTAMP WITH TIME ZONE. Existing values are
interpreted explicitly as UTC during the conversion; no server or session
timezone is consulted. The application now rejects timezone-naive datetime
writes and serializes persisted values with an explicit UTC offset.
Stop all backend instances and workers before applying the migration, because
old code still writes and compares naive values. Back up the database, run
Alembic through revision 0074, then deploy the backend and frontend together.
On large PostgreSQL tables, plan a maintenance window: each altered table is
locked while PostgreSQL rewrites or validates its timestamp columns.
SQLite has no timezone-bearing timestamp storage, so the migration does not
rewrite its columns. The SQLAlchemy adapter still rejects naive application
writes, stores the normalized UTC wall-clock representation, and restores an
aware UTC value on every read. Back up the database, -wal, and -shm files as
one consistent set before upgrading.
Downgrade converts PostgreSQL values back to timezone-naive UTC. It does not restore the old application contract; deploy compatible code at the same time if a downgrade is unavoidable.
2026-08 managed private access migration¶
Migration 0070_managed_private_access is DB-only. It adds
s3_connections.server_managed with a false default and creates the durable
managed_private_accesses saga table. Existing connections and remote RGW/IAM
resources are not modified, adopted, or contacted during Alembic.
Deploy backend and frontend together so Manager does not expose a provisioning
action before the specialized endpoints and immutable-credential rules are
available. After upgrade, smoke-test both Create my personal access branches,
Profile deletion, and Retry cleanup. A cleanup_pending row is operational
state, not disposable bookkeeping: retain it until the idempotent remote
cleanup succeeds.
Downgrade removes only the new table and marker column. It cannot clean up remote identities or keys already created by the application; delete every server-managed private connection through the running orchestrator before downgrading.
2026-08 canonical access model migration¶
Historical migration boundary
This section describes the intermediate schema and API at revision 0069.
The later Manager and Portal account-role split
replaces that single role with two independent axes. Current payloads use
manager_role and portal_role, not role; see the
current access contract.
Migration 0069_canonical_account_access_roles was a breaking, DB-only
migration. It replaced the previous account-association dimensions with one ordered
role, removed the legacy columns in the same release, and made shared S3
connections Manager-only.
At that release, the backend API accepted and returned only the canonical
role; backend and frontend had to be deployed together across that boundary.
Required deployment sequence¶
Rolling upgrade is prohibited because old backend instances and workers still expect the removed columns.
- Stop old application instances and every background worker.
- Create and verify a restorable database backup. For SQLite, include the
database,
-wal, and-shmfiles as one consistent set. For PostgreSQL, validate the dump by restoring it to a separate database. - If the migration reports associations without useful rights, set
BUCKETREEF_DB_BACKUP_VERIFIED=trueonly after that restore verification. Empty databases and databases without such associations do not require this override. - Run Alembic through revision
0069while the old processes remain stopped. - Deploy the new backend and frontend together, then start new workers.
- Run
python -m app.scripts.reconcile_portal_iamfirst in its default dry-run mode. Review the per-account summary and then rerun with--apply. - Smoke-test Admin associations, shared-connection remediation, empty/private Browser, Manager Browser, Portal, direct S3 sessions, and Ceph Admin Browser.
Alembic never contacts RGW. Portal IAM reconciliation is intentionally a separate, resumable command; a partial IAM failure must not alter the canonical database role.
Data transformation¶
- At revision
0069,portal_user,portal_manager, andaccount_administratorwere the only stored associationrolevalues. - Root account links always become
account_administrator. - A legacy admin flag outranks a legacy Portal role.
- Associations that previously granted no useful right are deleted, not
retained with
role = NULL. No tombstone or compatibility row is written. - Shared connections have Browser access disabled. Those with Manager access
stay ready; the others receive the stable remediation reason
shared_connection_manager_access_disabled. - Private connection owners, credentials, activity flags, and access flags are unchanged.
The downgrade reconstructs the legacy schema and fields for surviving rows. It cannot recreate deleted no-right associations; restoring the verified backup is the only recovery path for that explicitly non-reversible data.
2026-07 Portal Storage Space access migration¶
Migration 0066_portal_storage_space_access_model clears the database state of
existing Portal Storage Spaces before installing the strict private/team access
model. It removes their grants, external-credential records, and public links.
It does not contact RGW or delete storage-side resources.
- Back up the application database and record the spaces that must be recreated.
- Before upgrading, remove the old Storage Spaces and revoke their external IAM credentials through the application workflow. This must happen before Alembic because a database migration cannot revoke RGW-side credentials.
- Apply the database migration. Any remaining Portal database metadata is purged transactionally; unrelated public links are preserved.
- Recreate private spaces or re-import team spaces so bucket policies, IAM identities, and fixed Portal groups are provisioned with the strict model.
There is no runtime conversion or compatibility path for old Owner grants, shared-space owners, or editable Portal IAM policies.
2026-08 S3 connection credential owner types¶
Migration 0073_canonical_connection_owner_types makes connection identity
metadata strict. It converts rgw_user to the canonical s3_user, trims and
normalizes the supported values, clears unsupported owner types, and installs a
database constraint. The only stored values are now iam_user, account_user,
s3_user, or NULL.
The downgrade removes the constraint but does not recreate noncanonical values. Back up the application database before the migration if those values must be inspected or exported.
2026-08 canonical S3 user endpoints¶
Migration 0094_canonical_s3_user_endpoints assigns every detached S3 user to
the current default Ceph endpoint, then makes s3_users.storage_endpoint_id
non-nullable. Before upgrading, verify that a Ceph endpoint is marked as the
default. The migration stops with an explicit error when detached users exist
without such an endpoint; it does not guess another backend or retain a runtime
fallback.
After this boundary, S3 user creation and import APIs require
storage_endpoint_id. Existing S3 users cannot change endpoint. Deploy the
backend and frontend together because the request and response contracts are
both strict.
2026-08 canonical S3 account endpoints¶
Migration 0095_canonical_s3_account_endpoints assigns every detached S3
account to the current default Ceph endpoint, then makes
s3_accounts.storage_endpoint_id non-nullable. Before upgrading, verify that a
Ceph endpoint is marked as the default. The migration stops with an explicit
error when detached accounts exist without such an endpoint; it does not retain
a runtime fallback.
After this boundary, S3 account creation and import APIs require
storage_endpoint_id, and update requests reject an explicit null endpoint.
Account-specific RGW operations always use the persisted endpoint. Deploy the
backend and frontend together because the request and response contracts are
both strict.
2026-08 canonical secret keyrings¶
The backend accepts only the keyring settings UI_JWT_KEYS, API_JWT_KEYS, and
CREDENTIAL_KEYS. JWT_KEYS, FERNET_KEY, and CREDENTIAL_KEY are ignored.
Before upgrading from a deployment that still uses a shared JWT_KEYS ring,
copy its complete ordered key list to both UI_JWT_KEYS and API_JWT_KEYS so
active JWTs remain valid through the cutover. The rings can then be rotated to
distinct values after the old tokens have expired. Replace a singular
CREDENTIAL_KEY with a one-item CREDENTIAL_KEYS list and keep every
historical credential key required to decrypt stored values, with the key used
for new values first.
Empty keyrings are rejected at startup. Removed environment variables no longer provide runtime compatibility.
2026-08 strict credential encryption¶
Migration 0098_encrypt_plaintext_secrets encrypts any remaining plaintext
credentials in storage endpoints, S3 accounts, IAM users, S3 users, S3
connections, authentication providers, and S3 sessions. After this boundary,
the ORM rejects plaintext or otherwise unreadable values instead of returning
them as usable secrets.
Before upgrading, configure CREDENTIAL_KEYS with the current key followed by
every historical credential key still needed by the database. The migration
stops when a stored Fernet token cannot be decrypted, rather than encrypting an
unreadable token a second time. Its downgrade keeps credentials encrypted.
2026-08 Manager Browser active context¶
Migration 0103_manager_browser_data_access adds the non-null
allow_manager_browser_data_access flag to UI-user and UI-group associations
with S3 Accounts and RGW users. The secure default is false; no existing
association is enabled automatically.
Deploy the backend and frontend together. The embedded /manager/browser now
uses the active Manager ctx and sends X-S3-Workspace: manager-browser on all
Browser API calls. An older frontend will not send that explicit surface, while
an older backend cannot enforce the new per-association permission. After
deployment, verify Account, RGW-user, owned private-connection, shared-
connection, and immediate-revocation scenarios. Standalone /browser, Portal,
and Ceph Admin Browser execution policies are unchanged.
2026-08 canonical S3 user execution context¶
The execution-context API now reports managed RGW users with
kind="s3_user". The obsolete legacy_user value is rejected throughout the
backend and frontend; no runtime alias is retained. Context identifiers remain
s3u-<id>, so persisted bucket migrations and workspace selections do not
require a database migration. Deploy the backend and frontend together.
2026-08 canonical S3 user association payloads¶
Admin user and group writes now accept only structured s3_user_links entries.
The obsolete s3_user_ids request field is rejected with 422; every link
must state its s3_user_id and may explicitly enable
allow_manager_browser_data_access. Responses continue to expose the
association details needed by the frontend. The duplicate accounts,
s3_users, and s3_connections identifier arrays are no longer returned by
Admin user or group responses; consume account_links, s3_user_links, and
s3_connection_details instead. The nested effective_access projection also
stops duplicating canonical links and details through accounts, s3_users,
s3_connections, and manager_browser_s3_users. Admin user responses expose
group membership only through group_details, and group responses expose
members only through user_details; the duplicate group_ids and user_ids
response fields are removed. Deploy the backend and frontend together.
2026-08 canonical RGW user principal links¶
Admin RGW user responses now expose UI-user and UI-group associations only
through user_links and group_links. The duplicate user_ids, user_details,
group_ids, and group_details response fields are removed. Updates also accept
only the structured link fields; sending user_ids or group_ids returns 422.
Deploy the backend and frontend together.
2026-08 canonical S3 connection principal details¶
Admin S3 connection responses no longer duplicate user_details and
group_details through user_ids and group_ids. The structured details are
the only response representation. The group_ids update field remains the
canonical write contract for replacing group links. Deploy the backend and
frontend together.
2026-08 redundant API route removal¶
Four backend routes that had no frontend consumer are removed without runtime aliases:
GET /api/admin/stats/overview: use the canonical/api/admin/stats/summary,/api/admin/stats/storage, and/api/admin/stats/trafficresources.POST /api/admin/users/{user_id}/assign-account: replace account links atomically throughPATCH /api/admin/users/{user_id}withaccount_links.GET /api/connections/{connection_id}/capabilities: consume thecapabilitiesfield returned by the connection list and write resources.GET /api/portal/eligibility: load/api/portal/state, which enforces the same eligibility check and returns403when Portal is unavailable.
Requests to the removed paths return 404. Deploy the backend and frontend
together.
2026-08 canonical RGW account principal links¶
Admin RGW account responses and minimal summaries now expose UI-user and
UI-group associations only through user_links and group_links. The duplicate
user_ids and group_ids response fields are removed. Updates also accept only
the structured link fields, which require an explicit role for every principal;
sending user_ids, group_ids, or a null link list returns 422. Send an empty
list to clear an association set. The obsolete is_s3_user discriminator is
also removed because these endpoints return RGW accounts exclusively. Consumers
that operate on mixed execution contexts must use the canonical kind field.
The unused root_user_email and root_user_id projections are no longer
returned, eliminating per-account root-link lookups. Account response models now
reject unknown fields internally so obsolete projections cannot be silently
reintroduced. Deploy the backend and frontend together.
2026-08 schema drift reconciliation¶
Migration 0105_reconcile_schema_drift converges databases created by two
historical schema variants. It converts legacy text-backed
storage_endpoints.latitude and storage_endpoints.longitude columns to
floating-point columns, while leaving already-canonical databases unchanged.
Blank coordinate strings become NULL. Non-numeric, non-finite, or out-of-range
coordinates stop the migration with the affected endpoint ID and name; repair
those values before retrying.
Some older databases also contain the orphan
can_access_manager_bucket_usage_stats column on users or ui_groups. No
application model, permission check, or API consumes that flag. The migration
drops the column only when it exists and requires a tested restorable backup:
- Back up the database and verify a restore.
- Set
BUCKETREEF_DB_BACKUP_VERIFIED=truefor the migration process. - Run the Alembic upgrade.
Fresh databases without the orphan columns do not require the backup flag. A
downgrade recreates both legacy columns with false; it cannot restore discarded
orphan values.
2026-08 canonical RGW account identities¶
Migration 0104_canonical_s3_account_identities requires every persisted RGW
account to have non-empty rgw_account_id and rgw_user_uid values. The
migration intentionally stops with the affected database IDs and names when an
incomplete row exists; repair those identities from the authoritative Ceph RGW
configuration before retrying the upgrade.
Admin RGW account responses now use the database identifier as the numeric id
and expose the external RGW identifier through the required rgw_account_id
field. The duplicate db_id field and the unused root rgw_user_uid projection
are removed. Deploy the backend and frontend together.
Portal account responses use the same numeric database id; URL parameters and
browser preferences may still serialize that value as text. Linked account
details returned with UI groups now require rgw_account_id. Backend services
that operate on persisted accounts consume the stored rgw_user_uid directly
instead of deriving an -admin identity from the account ID.
2026-03 compatibility cleanup¶
Current behavior after cleanup:
- API context selectors reject legacy account inputs (
-1,null, negative ids) with400. - Frontend context persistence uses the independent
selectedManagerExecutionContextIdandselectedBrowserExecutionContextIdpreferences, withctxas the authoritative URL parameter in each tab. - Legacy shared local storage keys (
selectedExecutionContextId,selectedS3AccountId, andselectedBrowserContextId) are ignored. - Removed runtime env flags
COST_ENABLEDandHEALTHCHECK_ENABLEDare no longer accepted; use the explicitFEATURE_COST_ENABLEDandFEATURE_ENDPOINT_STATUS_ENABLEDforce-locks.
Manager and Ceph Admin bucket-configuration routes now normalize explicit S3
NotImplemented/XNotImplemented responses to HTTP 501 with
detail.code = "feature_not_implemented". Deploy the backend and bundled
frontend together so unsupported bucket features are classified from this
structured contract instead of RGW error-message text.
Operator guidance¶
- Remove scripts relying on legacy selector values.
- Validate UI context persistence after upgrades.
- Use explicit
FEATURE_*controls for forced feature state. - Back up the application database before migrations.
- Confirm the credential encryption key is unchanged after restore or redeploy.
- Validate the Admin, Manager, Portal, and Browser entry routes with the intended roles after upgrade.
Related pages¶
Durable endpoint identity and rotation boundary¶
Every Ceph entry in ENV_STORAGE_ENDPOINTS must now explicitly declare
service_identity_mode (managed or external). Add this field to deployment
inventories before upgrading, including inventories shared with user instances.
The whole inventory is validated before endpoint writes; missing mode or incomplete
external credentials prevents synchronization/startup. Generated managed secrets
stay encrypted in the database and are preserved across unchanged ENV reloads.
Runtime is required for Admin/Accounts; Supervision is required for Metrics, Usage
or signed S3 healthchecks. Ceph Admin alone requires neither service identity.
On upgrade from 0.2.13, migration creates the previously absent Runtime identity for
each existing Ceph endpoint using the endpoint's migrated external mode and a
missing status. Configure Runtime Read Ops with exactly
accounts=read;user-info-without-keys=read;buckets=read and no admin/system flag
before Manager/Portal live account, user and bucket enrichment resumes. There is no
Admin Ops fallback for these reads.
Existing Supervision credentials migrate as external without changing their RGW
users. They must validate with exactly usage=read;buckets=read and no admin/system
flag; adjust or replace credentials whose RGW user carries broader or different
capabilities. External mode requires complete pairs for enabled features; unused
pairs can remain empty, while partial pairs prevent startup. Managed mode
provisions the required identities at save/apply or during recovery; disabling
features keeps configured identities intact. Unused empty placeholders are skipped.
Existing managed endpoints needing Supervision require Admin Ops users=write
once to provision it. Usage availability is determined by Supervision and no longer
requires Admin Ops usage=read. Ready managed identities survive removal of
users=write; creating, converting or rotating them requires restoring that
permission.
Migration 0141_durable_key_rotation replaces previous_access_key with an encrypted
rotation journal, including existing pending retirements. Preserve the database and
credential encryption ring together. Resume pending operations through
Key Rotation; finish them before downgrading.
Administration and dedicated Ceph Admin instances reconcile persisted endpoints on
startup. User instances never perform those remote mutations.
Ceph Admin external credential cutover¶
Migration 0143_external_ceph_admin_credentials moves Ceph Admin identities
back to operator-owned external credentials while preserving complete stored
access-key and secret-key pairs from 0.2.13. It removes pending Ceph Admin
managed-rotation intents and managed-only UID, provenance, and validation
state. The preserved pair is revalidated after upgrade. Supply credentials
again only when the stored pair is incomplete or invalid.
Migration 0138_endpoint_service_identities, which introduces the explicit
per-endpoint ceph_admin_allowed flag earlier in the same migration chain,
initializes that authorization to disabled. Explicitly re-enable Ceph Admin
after the preserved credentials validate. Existing RGW users and their data are
left untouched. Inspect obsolete users and keys manually and remove only those
that are no longer required.
Downgrade cannot preserve the operator-owned Ceph Admin credential contract. It resets Ceph Admin identities to managed mode and clears their stored credential pair, so preserve a restorable database backup and the matching credential encryption ring before crossing this boundary.