Migrating a stateless application is not a data problem, and treating it as one is why first attempts take a full day instead of forty minutes. There is nothing to copy except a few megabytes of YAML. Every hour you will lose goes to three things: objects you should never have carried across, an admission controller that rejects images which ran unquestioned on TKGI for years, and a hostname that resolves to the wrong load balancer. Velero and OADP, which stands for OpenShift API for Data Protection and is simply Velero packaged as an Operator, are the easy part of this Part.

My reference migration uses wave1-web: three Deployments, eleven pods, no persistent volume claims, an NSX-T backed LoadBalancer Service, and one Ingress serving a public hostname. It is deliberately the second namespace I moved, not the first, because wave1-api from Part 17 had no ingress path and taught me almost nothing about cutover.

Preflight and What Counts as Stateless

Stateless in a migration context is narrower than most teams assume. No PersistentVolumeClaim is necessary but not sufficient. A Deployment that writes to an emptyDir cache and rebuilds it on start is stateless. A Deployment that writes session data to local disk and expects it back is not, and it will pass every check below and then fail in production when a user gets bounced to a different replica. Ask the application owner one question before you touch anything: if I delete every pod right now, what is lost.

Pin your versions before the first command, because Velero only tests one minor version of skew and OADP moves on its own cadence.

That last command is worth more than the rest of the preflight combined. Two of my three Deployments carry a hardcoded UID, one of them root. On TKGI, with pod admission effectively switched off, nobody ever noticed. On OpenShift both will be rejected, and knowing that before you start converts a mysterious outage into a planned ten minute edit. Part 7 covers why the restricted-v2 Security Context Constraint behaves this way, so I will not repeat it here.

Part 7, Security Context Constraints and Pod Admission is the prerequisite reading for everything in step 3 below.

Step 1, Backing Up wave1-web on TKGI

Almost every tutorial you will find reaches for –include-namespaces and stops there. On a TKGI source that is the wrong default, and it is the single thing in this Part that contradicts the common advice most directly. A whole namespace backup drags across ServiceAccounts bound to UAA identities that do not exist on OpenShift, image pull Secrets for a registry you are about to re-point, Services carrying an allocated ClusterIP from a Service CIDR OpenShift does not use, NSX-T annotations that OVN-Kubernetes will ignore, and an Ingress whose host names a load balancer you plan to switch off. You then spend an afternoon deleting objects you deliberately created.

Restore what the application owns. Rebuild what the platform owns. That distinction is the reference artifact of this Part, and it is the table I still paste into every migration ticket.

With that decided, the backup command writes itself.

Forty one seconds and thirty one objects. An unfiltered backup of the same namespace produced two hundred and nine objects, most of them endpoint slices and token Secrets that would have been noise at best and actively harmful at worst. Note –snapshot-volumes=false: there is nothing to snapshot, and leaving the default on wastes a CSI round trip against vSphere that can hang for minutes if the source storage provider is unhappy.

Step 2, Preparing an OpenShift Project That Will Accept the Pods

Create the project before the restore, not during it. If Velero creates the namespace it will do so without the annotations OpenShift relies on to allocate a UID range, and you will chase a much stranger class of failure. A project made by oc new-project gets its range immediately.

Read that UID range and write it down: 1001120000/10000. Any pod in this project that asks for a specific user outside 1001120000 through 1001129999 will be rejected, and my web Deployment asks for 1001. Two of these values are now on a collision course, and neither Velero nor OADP will warn you.

Step 3, Restoring with OADP, Then Fixing Admission

I use a Restore custom resource rather than the Velero CLI on the OpenShift side, for one practical reason: the file goes into git, and the next twenty five namespaces are a copy with one name changed. I also prefer oc over kubectl throughout the OpenShift half of this series, because oc understands Routes, Projects, SCC and oc adm policy, and dropping to kubectl for those means hand writing RBAC that one subcommand does correctly.

Phase Completed. Zero errors, zero warnings, zero running pods. This is the moment that catches people, and it is not a bug in either tool. Velero restored eleven object definitions faithfully; OpenShift admission then declined to create the pods those definitions asked for. Both statements are true simultaneously.

Here is what that learning curve looked like in wall clock across my first four namespaces. Note that it got worse before it got better, because namespace two was the one with a hardcoded UID and a registry certificate problem stacked on top of each other.

Step 4, Ingress to Route and DNS Cutover

OpenShift automatically creates a managed Route object whenever an Ingress object is created, and deletes it again when the Ingress goes away. That behaviour is convenient in normal operation and dangerous during a migration, because the generated Route copies the host field verbatim. My restored Ingress named shop.example.com, a hostname that still resolves to an NSX-T virtual server carrying live production traffic. OpenShift now claims it too, and whichever answer DNS gives is the one your users get.

flowchart TD
  A[Ingress restored into project] --> B[OpenShift generates a managed Route]
  B --> C[Generated Route claims the live production hostname]
  C --> D[Create a second Route on a test hostname]
  D --> E[Validate through the OpenShift ingress controller]
  E --> F[Switch the DNS record to the OpenShift VIP]
  F --> G[Delete the restored Ingress and its managed Route]
  E --> H[Fallback, leave DNS pointing at NSX and investigate]

That Harbor certificate patch deserves its own warning. It is one line, it looks harmless, and it triggers a Machine Config rollout that drains and restarts every node in the cluster one at a time. On my six node cluster that took roughly forty minutes, during which the other pilot namespace I was mid way through migrating kept getting evicted. Do the registry trust configuration once, on day zero, before any workload arrives. Part 15 covers registry setup properly, and I should have finished it before starting this.

Rollback deserves a sentence of its own too, because it is genuinely easy here and it will not be in Part 19, where persistent volumes arrive. Until DNS moves, TKGI is still serving every request. Deleting the OpenShift project costs you nothing except the twenty minutes you spent on it. Take advantage of that while it lasts.

Verification, Rollback and Common Failures

Green means four things, and replica counts are only the first. Every Deployment reports its full replica count Ready. Every pod has restarted zero times after the first sixty seconds, which rules out a crash loop that replica count alone will hide for a while. Your test Route returns the same status code and a comparable response time as the production hostname. And oc get events in the project is empty of Warning entries. If any one of those four is off, do not touch DNS.

Six failures cover nearly everything I hit moving nine stateless workloads. Keep this next to the runbook.

One more verification step earns its keep, and it is embarrassingly low tech. Before DNS moves, grep every restored ConfigMap for three strings: your old pod CIDR, your old cluster DNS domain, and your old registry hostname. A loop over oc -n wave1-web get cm -o yaml piped through grep takes eleven seconds and needs no tooling. It has found something in four of the nine namespaces I have moved, and in three of those four the application would have started, passed every probe, and misbehaved only under real traffic.

Four questions come up on every wave, so here are my answers rather than a link to a mailing list thread.

Field Note from a Deployment That Restored Clean and Never Started

My worst day on this was not the SCC rejection, which is loud and self explaining once you have read it once. It was a Deployment that restored, started, passed its readiness probe, served my curl, and then broke for real users about ninety minutes later.

What I had missed was a ConfigMap key holding a comma separated allowlist of source CIDRs. On TKGI those CIDRs described the NSX-T pod network, 172.16.0.0/16. On OpenShift the OVN-Kubernetes cluster network is a different range entirely, and every internal call from web-bff to web was arriving from an address the application considered untrusted. It did not reject those calls. It downgraded them to an anonymous session, silently, exactly as it had been written to do six years earlier. My health check hit a path that did not care, so everything looked green.

Three hours to find, four minutes to fix, and the reason I now run a blunt grep across every restored ConfigMap for the old pod CIDR, the old cluster domain and the old registry hostname before I let anyone near DNS. That grep takes eleven seconds and it has caught something in four of the nine namespaces I have moved. Restore verification that only looks at pod status is verification of the platform, not of the application.

Migrate Every Namespace Twice Before You Cut DNS

My recommendation from nine of these is simple and slightly unpopular with project managers. Run the full backup and restore loop, find your admission and configuration problems, then delete the project and run it again from the same backup with your fixes folded into the restore. Second pass on wave1-web took four minutes and produced a namespace with no accumulated manual patching in it, which means the runbook you hand to the next engineer actually works as written. A namespace you fixed by hand is a namespace nobody else can reproduce.

On Monday, take your smallest customer facing stateless namespace and run only the preflight from step 1: list its Deployments and print runAsUser for each. That one command tells you how much of this Part applies to your estate, and it costs nothing and changes nothing. Part 19 adds persistent volumes, where rollback stops being free.

References

About The Author

Dr. Pranay Jha

Dr. Pranay Jha is a Cloud and AI Consultant with 18+ years of experience in hybrid cloud, virtualization, and enterprise infrastructure transformation. He specializes in VMware technologies, multi-cloud strategy, and Generative AI solutions. He holds a PhD in Computer Applications with research focused on Cloud and AI, has published multiple research papers, and has been a VMware vExpert since 2016 and a VMUG Community Leader.

See author's posts