Skip to content

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.

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.

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.

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:

python -m app.scripts.check_production_readiness

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}/precheck queues preparation and returns 202. { "active_checks": false } (the default) is read-only; true explicitly 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/migrations accepts only draft configuration fields. The update-only configuration_revision field is rejected on creation. PUT draft updates require configuration_revision; they increment it and invalidate the report. POST /start requires the checked revision and, for immediate mode, confirm_write_interruption: true. Reports expire after 15 minutes.
  • POST /continue requires { "confirmed": true } for cutover.
  • POST /restore-access, /cleanup-target and /cleanup-source require explicit confirmation and return 202. Their status is independent of the transfer result.
  • Source cleanup is available only through the explicit /cleanup-source operation. Migration configuration no longer has a delete_source field. 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:

cd backend
python -m app.scripts.preflight_outbound_targets

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:

  1. Stop the frontend, backend replicas, schedulers, and CronJobs.
  2. Create and verify a restorable database backup. Keep the old credential encryption key with it.
  3. 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.
  4. Generate strong, mutually distinct UI_JWT_KEYS, API_JWT_KEYS, and CREDENTIAL_KEYS, plus a strong scheduler token. Configure TLS, exact origins and hosts, WebAuthn, trusted proxy CIDRs, and registered S3 endpoints.
  5. Set BUCKETREEF_DB_BACKUP_VERIFIED=true only for the verified migration run. Deploy backend, frontend, migrations, and configuration together.
  6. 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.
  7. 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.

  1. Stop old application instances and every background worker.
  2. Create and verify a restorable database backup. For SQLite, include the database, -wal, and -shm files as one consistent set. For PostgreSQL, validate the dump by restoring it to a separate database.
  3. If the migration reports associations without useful rights, set BUCKETREEF_DB_BACKUP_VERIFIED=true only after that restore verification. Empty databases and databases without such associations do not require this override.
  4. Run Alembic through revision 0069 while the old processes remain stopped.
  5. Deploy the new backend and frontend together, then start new workers.
  6. Run python -m app.scripts.reconcile_portal_iam first in its default dry-run mode. Review the per-account summary and then rerun with --apply.
  7. 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, and account_administrator were the only stored association role values.
  • 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.

  1. Back up the application database and record the spaces that must be recreated.
  2. 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.
  3. Apply the database migration. Any remaining Portal database metadata is purged transactionally; unrelated public links are preserved.
  4. 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.

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/traffic resources.
  • POST /api/admin/users/{user_id}/assign-account: replace account links atomically through PATCH /api/admin/users/{user_id} with account_links.
  • GET /api/connections/{connection_id}/capabilities: consume the capabilities field returned by the connection list and write resources.
  • GET /api/portal/eligibility: load /api/portal/state, which enforces the same eligibility check and returns 403 when Portal is unavailable.

Requests to the removed paths return 404. Deploy the backend and frontend together.

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:

  1. Back up the database and verify a restore.
  2. Set BUCKETREEF_DB_BACKUP_VERIFIED=true for the migration process.
  3. 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) with 400.
  • Frontend context persistence uses the independent selectedManagerExecutionContextId and selectedBrowserExecutionContextId preferences, with ctx as the authoritative URL parameter in each tab.
  • Legacy shared local storage keys (selectedExecutionContextId, selectedS3AccountId, and selectedBrowserContextId) are ignored.
  • Removed runtime env flags COST_ENABLED and HEALTHCHECK_ENABLED are no longer accepted; use the explicit FEATURE_COST_ENABLED and FEATURE_ENDPOINT_STATUS_ENABLED force-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.

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.