Migration 1.2.0 to 1.3.0
For feature and product changes in the target release, see OLIVE Version 1.3.0.
Do not run helm upgrade from 1.2.0 to 1.3.0, and do not point an existing Argo CD application at the 1.3 chart version.
The migration path is: export everything from 1.2 → remove the old deployment and wait until it is gone → deploy 1.3 fresh → import.
The reason is the scope of the change. 1.3 alters the service-account and Vault role model, the namespace layout, the network policy set and the set of services published on the ingress, and it removes the common assets tenant. An in-place upgrade would leave the old identities, policies and tenant in place alongside the new ones, in a state that is neither the old deployment nor the new one.
Overview of the procedure
- Export all content from the 1.2 deployment.
- Verify the exports.
- Remove the 1.2 deployment and wait until it is fully removed.
- Prepare the 1.3 values files.
- Deploy 1.3.
- Import the required configuration bundle, then your exported content.
- Validate.
- Enable the security controls, in order.
1. Export from 1.2
Export all repository content from every tenant, using the export function of the repository editor or the import/export API.
Do this per tenant, including the common-assets tenant if you have one — its content has to land somewhere in 1.3, and that place is an ordinary tenant.
Record, before you tear anything down:
- The list of tenants and their namespaces.
- Each tenant's Keycloak realm, clients and role assignments.
- Which secrets live in Vault under each tenant's paths.
- Any egress destinations your connectivity depends on, since 1.3's network policies block private destinations outside the cluster by default.
- Any services you had published on the ingress, because 1.3 does not publish internal services unless asked.
2. Verify the exports
Open each export and confirm it contains what you expect before removing anything. Once the deployment is gone, the storage goes with it.
Keep the exports somewhere outside the cluster.
3. Remove the 1.2 deployment
Remove the deployments and wait until they are actually gone — including namespaces, PersistentVolumeClaims and the underlying volumes. A partially deleted namespace stuck in Terminating will block the new deployment, and a leftover PVC will be re-bound by the new release with old content in it.
kubectl get ns
kubectl get pvc -A
kubectl get pv
Only proceed when the old namespaces no longer exist and no PersistentVolume from the old deployment is left bound.
Uninstall and Teardown lists what a deployment removes and what it leaves behind, including the Vault policies and auth roles named after each tenant.
Vault and Keycloak are cluster-level dependencies and are not removed with the OLIVE deployment. Tenant-specific Vault roles, policies and auth mounts from 1.2 should be cleaned up before onboarding the same tenant name into 1.3, so that the 1.3 role set is created cleanly rather than merged with the old one.
4. Prepare the 1.3 values
Start from the examples in the Chart Values Reference rather than editing your 1.2 files.
What changes:
| 1.2 | 1.3 |
|---|---|
commonLibraryName: common-assets | Removed. Do not set it |
A common-assets tenant deployment | Removed. Its content goes into an ordinary tenant |
oliveCore: true on the common assets tenant | Removed. Keep oliveCore: false everywhere |
services.stateful.opensearch: true | OpenSearch is gone. The key is inert in 1.3 and can be removed; the 1.2 volume and its Vault credentials are left behind by the teardown |
| "Stateless layer" deployment | The shared runtime pool (multi-shared), same role, clearer name |
| Services published on the ingress by default | mapToAPI: true per service, only where needed |
| — | global.networkPolicy, global.serviceMesh, global.serviceAccounts, global.vault, global.keycloakIpBlocks, global.nonRoutableCidrs |
| — | tenant-setup.imageVerification.mode, tenant-setup.imageRegistry.mode |
| — | couchdb.credentials.rotationId, seaweedfs.credentials.rotationId |
| — | global.express.releaseVersion, global.keycloakBaseURL, global.keycloakVaultPath, global.urlScheme |
global.namespace had to equal global.tenant | The two are independent. Keep the tenant name as it was — it builds the DNS subdomain and names the Vault and Temporal accounts — and give the namespace a prefix if you want more structure, for example oli-<tenant> |
Set the security controls to the posture you actually want — this is a fresh deployment, so there is no reason to deploy in one shape and then change it. Start both admission modes in a reporting mode, because that costs nothing and tells you what enforce would have blocked:
tenant-setup:
imageVerification:
mode: audit
imageRegistry:
mode: audit
Where they should end up differs. imageRegistry.mode and podPrivileges.mode belong at enforce; imageVerification.mode is recommended to stay at audit, because enforcing it makes pod creation depend on Fulcio and Rekor being reachable. See The recommended posture.
Set global.serviceMesh.mode to what is actually installed on the cluster — none if no mesh is installed, ambient if one is. Guessing produces policies for the wrong traffic shape, and the symptom is a timeout rather than an error.
See Security Configuration for what each control does.
5. Deploy 1.3
Deploy the shared runtime pool first, then each tenant. See Implementation Phase.
Wait for the shared pool to be healthy before deploying tenants — the tenant deployments reference its namespace through global.express.sharedNamespace.
6. Import
- Import the foundational OLIVE Connectivity Bundle for 1.3 first, from
03 Foundational Configuration Packagein the development package. The start page does not automatically detect missing configuration packages during a migration, so import it manually through the repository editor's import dialog. One import covers it — the handbooks are packaged inside the bundle in 1.3, where 1.2.0 needed them as two separate imports. See Import Required Foundational OLIVE Connectivity Bundle. - Import your exported content, per tenant.
If you previously had a common-assets tenant, decide where its content belongs. The usual pattern is to nominate one ordinary tenant as the library tenant and import the shared templates and microfrontend components there, then distribute them to other tenants by export/import.
7. Validate
Confirm the deployment itself is sound:
- Every tenant's Editor and repository are reachable.
- Login works, and the
user,editorandadminroles behave as expected. Note that in 1.3 these are genuinely different permissions — an account that relied on an editor role to perform an administrative action in 1.2 will now be refused. - Whoever imports content, edits
core-tagged entries or deploys pilets holds the admin role. All three were available to an editor in 1.2 and are admin operations in 1.3, so a person who did this work before may no longer be able to. - Datapoints and connectors execute, including ones that call external systems.
- Scheduled jobs fire.
- Files upload and download.
- Microfrontend components still render and still work. In 1.3 a pilet may only call the local paths
/data-orchestrator/and/repository/get, plus the publicfile-storage-serviceAPI with GET, so a component that called another service, or uploaded directly, needs reworking by whoever wrote it. The connectivity handbook documents the new rules. - Any service you rely on from outside the cluster is reachable; if not, it needs
mapToAPI: true.
1.3's egress guard rejects calls to internal address ranges, Kubernetes-internal service names and link-local metadata addresses, and logs OLIFETCH1. If a datapoint in your 1.2 content pointed at an in-cluster service or an internal host, it will stop working. This is intended. Public destinations are unaffected, so the usual fix is to reach the system through an endpoint exposed outside the cluster. If that is genuinely impossible, see Security Configuration → Network Policies for how to raise the case.
Placeholders in HTTP datapoint definitions are restricted by a character allow list that depends on where they appear — URL host, port, method, query key or value, header value, form body. Header names are no longer substitutable. A definition that relied on a placeholder producing a header name, or on characters outside the allow list, needs to be reworked.
8. Confirm the security controls are actually in effect
The controls were set in step 4 and deployed in step 5, so there is nothing to switch on here — only to verify, because several of them fail silently when a prerequisite is missing:
- Network policies exist and are enforced:
kubectl -n <ns> get networkpolicy, and confirm with your cluster operator that the CNI enforces them. A CNI that ignores NetworkPolicy accepts the objects and restricts nothing. - Admission policies are evaluating the namespace:
kubectl get policyreport -n <ns>. An empty report in a namespace set toauditmeans the Kyverno policies are not deployed or are selecting a different label. - Service mesh, if you set
ambient: the namespace carries the enrolment label, probes still pass, and traffic is tunnelled. - Keycloak MFA is enforced for administrative roles — a realm setting, not a chart value.
If something is wrong, Security Configuration has a sequence for narrowing down which control is responsible.
Rollback
Because this is a redeploy rather than an upgrade, rollback means redeploying 1.2 from your recorded values and re-importing the exports from step 1. This is the reason step 2 exists: keep the exports until 1.3 has been running to your satisfaction.