Migrating from OpenShift 3 to OpenShift 4: a step-by-step method

Moving from OpenShift 3.11 to OpenShift 4 is not a simple upgrade. It is a migration to a new platform. I have supported this kind of transition in an enterprise context with strict compliance requirements: here is the method I use to limit risk and downtime.

Why you don't "upgrade" from OpenShift 3 to 4

OpenShift 4 was redesigned from the ground up. The cluster is driven by Operators, nodes run Red Hat Enterprise Linux CoreOS, and the platform updates itself through the Cluster Version Operator. Installation, authentication configuration, monitoring and logging no longer work the way they did in 3.x.

As a result, there is no in-place upgrade path. You build a new OpenShift 4 cluster and move your applications to it.

Step 1 — Inventory what you have

A successful migration starts with an accurate map:

• namespaces, their owners and their criticality;
• stateless and stateful workloads, with their persistent volumes and storage classes;
• the DeploymentConfigs, BuildConfigs, ImageStreams and templates in use;
• external dependencies: databases, DNS, certificates, firewalls, integrations;
• quotas, RBAC and any custom Security Context Constraints.

This inventory is used to group applications into migration waves, from the least critical to the most sensitive.

Step 2 — Build the target cluster as code

The new cluster must be reproducible from day one. I describe the infrastructure with Terraform, the configuration with Ansible, and the cluster configuration (LDAP authentication, RBAC, quotas, NetworkPolicies, monitoring) with OpenShift GitOps (Argo CD). If the cluster ever needs to be rebuilt, everything is in Git.

Decisions to make at this stage: sizing, storage through CSI drivers, networking (OVN-Kubernetes is the default plugin in recent versions) and the exposure strategy (Routes, Ingress Controllers, certificates).

Step 3 — Prepare the applications

Migration is the right moment to modernize:

• progressively replace DeploymentConfigs with standard Kubernetes Deployments;
• remove deprecated APIs from manifests;
• externalize configuration into ConfigMaps and Secrets;
• replace the isolation of OpenShift SDN's "multitenant" mode with explicit NetworkPolicies.

Step 4 — Redeploy rather than copy, when you can

For stateless applications whose manifests live in Git, the cleanest option is often to redeploy them on the new cluster through CI/CD or Argo CD, rather than copying legacy objects. You start again from a clean, versioned baseline.

For stateful applications, Red Hat provides the Migration Toolkit for Containers (MTC). It migrates a namespace's resources and persistent volume data from a source cluster to a target cluster through an object-storage replication repository.

Step 5 — Migrate in waves, starting with a pilot

I always start with a non-critical pilot namespace to validate the whole chain: permissions, networking, storage, DNS, certificates and monitoring. Then every wave follows the same flow:

1. Stage migration: copy data while the application still runs on the source, to shorten the cutover;
2. Cutover window: stop the source application, run a final sync, start on the target;
3. DNS switch to the new routes;
4. Functional validation with the application teams.

Step 6 — Validate, observe, keep a rollback plan

After each cutover, I watch the Golden Signals (latency, traffic, errors, saturation) in Prometheus and Grafana. The old cluster stays available until the wave is validated: if something goes wrong, rolling back often just means switching DNS back.

Step 7 — Decommission cleanly

Once every wave is validated: archive configurations, revoke access and certificates on the old cluster, update documentation and runbooks, then shut down the 3.x platform.

Summary

• OpenShift 4 is a new platform: you migrate, you don't upgrade.
• Inventory and migration waves first, tools second.
• Target cluster built as code with Terraform, Ansible and Argo CD.
• GitOps redeployment for stateless apps, MTC for stateful ones.
• Pilot, stage migration, short cutover, observability and a rollback plan.

Planning an OpenShift migration? See how I can help or email me.