Skip to content

Migration sequence

Linux/bash is the default. This page aligns with docs/runbooks/00-secuencia-y-matriz.md in the repository.

Complete Prerequisites before step 1.

Order of operations

Migration sequence

Namespace 3scale-db states

  1. Install 3scale 2.15 on a test cluster — 3scale operator + APIManager with embedded databases (Install 3scale 2.15 (lab)).
  2. Confirm the matrix: OpenShift version supported by both 2.15 and 2.16; latest CSV on channel threescale-2.15.
  3. Snapshot / backup PVCs and secrets (system-database, system-redis, backend-redis).
  4. Open a maintenance window: scale the 3scale operator and components to 0 except the database you are dumping.
  5. Externalize PostgreSQL 10 → 15 in-cluster (Externalize PostgreSQL).
  6. Externalize Redis 6 → 7 in-cluster (Externalize Redis).
  7. Set spec.externalComponents on the APIManager (the PostgreSQL and Redis runbooks do this).
  8. Restore replicas. Validate Admin Portal, Developer Portal, and APIcast.
  9. Upgrade the 3scale operator to channel threescale-2.16 (Upgrade operator to 2.16).
  10. Upgrade OpenShift afterwards, if needed, per Supported Configurations.
  11. Operate day 2 in 3scale-db: persist Redis, backups, pinned digests (Day 2 operations).

If a step fails before system-app-pre succeeds on 2.16, see Rollback.

Do not combine upgrades

Do not run the 3scale upgrade and the OpenShift upgrade in the same maintenance window.

Lab vs production overlays

Overlay StorageClass Use
lab / lab-persist gp3-csi (example) Test clusters
prod / prod-persist Cluster default Production-like

The 3scale procedure is the same. Only storage defaults differ.

Deployment options

# Phase 1: 3scale operator 2.15 + APIManager
oc apply -k gitops/
oc apply -k gitops/rhacm/              # managed cluster via ACM hub

# Phase 2: in-cluster databases (create system-database secret in 3scale-db first)
oc apply -k gitops/external-db
oc apply -k gitops/rhacm/external-db

oc apply -k kustomize/overlays/lab-operator
oc apply -k kustomize/overlays/lab-efs
oc apply -k kustomize/overlays/lab-apimanager
# after dump/restore:
oc apply -k kustomize/overlays/lab

See GitOps and RHACM for wave ordering and RHACM placement.