Upgrade surface dispositions

This table belongs to the upgrade checklist. After you record the starting state, assign every surface a disposition and plan its required operator action before you apply the release.

Surface	Disposition	Upgrade behavior	Required operator action
Controller, worker, and Console assets	Replace	The controller image owns all three.	Roll out API and worker together. Verify the embedded source commit and both observed image digests or IDs.
PostgreSQL schema and migration-owned data	Auto-migrate and preserve	The canonical migrator applies supported pending migrations before API and worker startup. An image rollback does not reverse them.	Run migration preflight, inspect pending migrations, retain the receipt, and stop all old writers. The image helper stops only the API and worker. Prefer a reviewed forward fix after commit.
Installation YAML	Reconcile manually	API and worker read it independently at startup. Updating a protected file alone does not reload either process.	Reconcile every Driver, Backend, image, network, storage, logging, and Preset-file setting. Update the mounted Secret or file and restart API and worker.
IAM, Backends, and control-plane records	Preserve and reconcile	Namespaces, Roles, AccessBindings, service accounts, Backends, deployment work, and audit records persist in PostgreSQL; external identity providers and sinks do not.	Compare counts and stable IDs, retain service-principal ownership, finish or resolve active work, and verify audit and observability delivery.
Helm chart and cluster prerequisites	Reconcile manually	Helm reconciles chart-owned resources. CRDs, node assets, storage classes, cluster overlays, and external controllers may have separate owners.	Diff the rendered candidate against live resources. Preserve reviewed RBAC, selectors, NetworkPolicies, sidecars, probes, Gateway and HTTP routes, certificates, DNS rewrites, CSI and local-path settings, proxy rules, and seccomp profiles. Apply prerequisites before workloads need them.
Bundled Collector configuration	Reconcile manually	The Collector reads the operator-created Secret named by `logging.collector.configSecretName`. Helm never updates it, so the previous release's log filtering remains.	Refresh `collector.yaml` and `kubernetes.yaml` from the release source, merge reviewed local changes, and restart the Collector.
Default and file-backed Presets	Create missing; refresh untouched; reconcile edited	Startup creates missing names in each eligible Namespace. With `includeDefaults` enabled, it also refreshes copies still equal to an earlier shipped bundled default, keeping their IDs. Copies matching no shipped version, and `presets.files` copies, are preserved.	Per Namespace, save `occ preset get ID -o json` per default copy before and after: a refreshed copy keeps its ID with the new template; refusals log `presets.default-refresh-skipped`. Its `installation-defaults-refresh` audit event (`version`, `previousVersion`) is database-only. For edited copies and file-backed Presets, compare persisted templates with candidate files and `PATCH` intended same-name Presets in place so IDs, IAM grants, and bookmarks remain stable. Remove obsolete copies only after checking exact-resource references.
Agent draft and Configuration metadata	Preserve	PostgreSQL stores Agent drafts, Configuration metadata, references, and version relationships. A deployment snapshots the current draft rather than replaying the selected version.	Review drafts before a runtime release. Preserve IDs and do not assume a bundled default rewrites saved Configuration JSON.
Configuration values	Preserve in the selected ConfigurationDriver	The current Kubernetes Driver stores values in ConfigMaps; the filesystem development Driver uses `occ_configuration_data`. Switching Drivers does not migrate values.	Inventory and back up the active Driver's storage. Keep the Driver identity stable, or run a separately reviewed data migration before changing it.
Runtime image selection	Reconcile manually	Installation configuration selects images for future deployments. Reloading the controller requests no deployments, but the next maintenance pass of an Agent with repository credentials applies the current images to its selected version.	Set immutable gateway and Agent runtime digests and restart API and worker. The production helper deploys every recorded running Agent. Leave stopped and deleting Agents untouched.
Agent revisions and Kubernetes workloads	Preserve or redeploy deliberately	Controller-only releases do not request deployments, but the new worker can restart existing Agent Pods once, and a broker restart can fail repository-bound versions and queue retirement. Runtime releases save replacement versions through the ordinary deployment path. Projected runtime Secrets and Pods are recreated.	Record the fleet first, allow replacement capacity and downtime, wait for durable deployment success, and verify the selected version and Pod digest. Never replay an unknown deployment response until version history shows whether OCC accepted it.
Secret metadata, values, and generated credentials	Preserve across both stores	PostgreSQL stores Secret metadata and references; the selected SecretDriver owns values. External tokens, Slack apps, and provider accounts can change outside OCE.	Back up the owning Secret store, preserve canonical Kubernetes Secrets, verify references and access metadata, and prove delivery with a real operation. Never copy credential bytes into Compose, YAML, logs, or upgrade evidence.
Repository access and broker state	Reconcile durable inputs; recreate sessions	Repository metadata, broker image, service name, CA, runtime policy, volumes, and external GitHub App grants must remain compatible. Broker sessions are ephemeral and image rollout does not expand external installations.	Preserve the exact Service name, hostname, certificate, and CA until old sessions drain, along with repository volumes and grants. A lost session can fail its version; inspect cleanup and explicitly deploy a new authorized version when needed. Verify clone and the required read or write operation.
Plugin integrations	Reconcile manually	Catalogs, policy, credentials, and external authorization are independent of an image replacement.	Reconcile catalog availability, reviewer policy, NetworkPolicies, Secret bindings, and external grants. Verify a representative tool call.
Authentication, TLS, and routing	Preserve and reconcile	Auth secrets, hostnames, cookie scope, certificates, Gateway routes, and trusted-proxy CIDRs are operator-owned. Auth sessions may be invalidated when these change.	Preserve stable secrets when sessions should survive. Reconcile origins and routes with the live hostname, and verify human login, service-key access, workspace routing, and native admin access.
PostgreSQL, bootstrap, workspace, gateway, and repository volumes	Preserve	These survive only while their external database, PVCs, k3d volumes, or Compose volumes remain. Images do not recreate them.	Keep the existing resources and reclaim policies. Do not delete these to force an upgrade through.
Native-admin pod-local edits and broker sessions	Recreate or discard	Pod-local changes and in-memory sessions disappear when the owning Pod restarts. Managed Configurations and PVC data persist.	Move intended configuration into a managed resource before rollout. Worker maintenance replaces a broker session that the service recorded as disposed, which recreates the dedicated Codex Pod; inspect other lost sessions and retained cleanup obligations.
Long-lived local profile state	Preserve and reconcile manually	Compose files, bind mounts, kubeconfig, cluster name, image tags, private state files, and named volumes sit outside the release image.	Update every image consumer, retain PostgreSQL and k3d volumes, add new mounted files explicitly, and verify rendered Compose and Helm configuration before recreating only affected services. A custom retained topology needs its own procedure.