OpenShift to vSphere Kubernetes Service: What’s Different from a Rancher Migration

Why the opinionated OpenShift platform demands a fundamentally different migration strategy — and where the Rancher playbook still applies.

Migrating OpenShift workloads to vSphere Kubernetes Service (VKS) on VMware Cloud Foundation requires more than infrastructure migration—it requires application and platform decoupling.

📖  This is Part 2 of Capstone-S’s VKS Migration Series. Part 1 — “Migrating Applications from Rancher to vSphere Kubernetes Service on VMware Cloud Foundation” — is available at capstone-s.com/insights/ and covers the foundational migration framework: pre-migration assessment, cluster provisioning, Velero-based PVC migration, progressive traffic cutover, and post-migration hardening. This article assumes familiarity with that framework and focuses exclusively on the deltas introduced by OpenShift’s opinionated platform model. Read Part 1 first if you have not already done so.

Executive Summary

On the surface, both Rancher and OpenShift are Kubernetes management platforms, and a migration from either to vSphere Kubernetes Service (VKS) on VMware Cloud Foundation (VCF) follows the same high-level arc: assess, provision, migrate workloads, cut over, harden. But the similarities end there.

Red Hat OpenShift is a full Platform-as-a-Service (PaaS) built on Kubernetes. It ships its own container runtime (CRI-O), its own ingress controller (HAProxy-based Router), its own image registry (Quay / integrated registry), its own CI/CD system (OpenShift Pipelines / Tekton), its own service mesh (OpenShift Service Mesh / Istio), its own build system (Source-to-Image, BuildConfigs), and a strict Security Context Constraints (SCC) model that is fundamentally different from Kubernetes-native PodSecurity standards.

Every one of those proprietary layers must be mapped to a VKS equivalent, replaced with an upstream alternative, or — in some cases — refactored out of the application entirely before migration can succeed. This article documents each of those gaps and the recommended resolution path, building directly on the five-phase framework from Part 1.

The Core Difference: Vanilla Kubernetes vs. an Opinionated PaaS

Rancher is a management layer over standard Kubernetes clusters. Its downstream clusters run unmodified upstream Kubernetes — RKE, RKE2, or k3s. Workloads running on Rancher-managed clusters are generally portable to any conformant Kubernetes distribution with minimal changes.

OpenShift is fundamentally different. It ships a hardened, opinionated Kubernetes distribution (OKD upstream) with Red Hat-specific extensions baked into the control plane. Applications built for OpenShift frequently depend on OpenShift-specific APIs and behaviors that do not exist in upstream Kubernetes — including VKS.

⚠️  The single most important pre-migration question for OpenShift workloads is: “Does this application use OpenShift-specific APIs?” If the answer is yes — and it often is — those dependencies must be resolved before the migration can proceed. This assessment step is significantly more involved than the equivalent step in a Rancher migration.

Phase 1: Assessment — The Additional Dimensions for OpenShift

The Part 1 assessment framework (cluster inventory, dependency mapping, feature gap analysis) applies here, but OpenShift introduces several additional dimensions that must be evaluated explicitly.

1.1  Security Context Constraints (SCC) Audit

OpenShift’s SCC model predates Kubernetes PodSecurity Standards (PSS) and is more granular. Many OpenShift workloads run under SCCs such as anyuid, privileged, or nonroot — policies that either do not exist in vanilla Kubernetes or map imperfectly to PSS restricted/baseline profiles.

For each workload, document:

• The SCC assigned via oc get pod <name> -o yaml | grep openshift.io/scc
• Whether the workload requires root UID (0) — a significant portability red flag.
• Use of OpenShift-specific volume types: emptyDir with medium: Memory is fine; hostPath mounts may indicate tight node coupling.
• RunAsUser / FSGroup / SELinux label settings hardcoded in pod specs.

Map each SCC to the closest Kubernetes PSS equivalent and flag workloads that require refactoring to drop root privileges or remove hostPath dependencies. This is often the most labor-intensive part of an OpenShift migration — and there is no shortcut.

1.2  BuildConfig and Source-to-Image (S2I) Usage

OpenShift BuildConfigs and S2I are OpenShift-native resources (build.openshift.io/v1). They do not exist in VKS. Every BuildConfig in your environment must be replaced with an equivalent CI/CD pipeline before migration.

Enumerate all BuildConfigs with:

oc get buildconfigs -A -o custom-columns=NS:.metadata.namespace,NAME:.metadata.name,STRATEGY:.spec.strategy.type,SOURCE:.spec.source.type

The replacement strategy depends on the build type: Docker strategy maps cleanly to a GitHub Actions or Tekton pipeline running docker build / buildah bud. S2I strategy requires more work — either replicate the S2I assemble script logic in a Dockerfile, or adopt a cloud-native buildpack (CNB) approach using Paketo or the Tanzu Build Service (now Buildpacks for VMware Tanzu).

1.3  ImageStream and Integrated Registry Dependencies

OpenShift ImageStreams (image.openshift.io/v1) are a proprietary abstraction over container image references that enables automatic pod re-deployment when an image tag is updated. They do not exist in VKS. Workloads that reference images via ImageStream tags (e.g., image: myapp:latest resolved through an ImageStream) must be updated to reference a standard OCI registry directly.

Assessment steps:

• Run oc get imagestreams -A to enumerate all ImageStreams.
• Identify Deployments/DeploymentConfigs that use ImageChange triggers — these will silently stop working on VKS if not converted.
• Plan image promotion to an external registry: Azure Container Registry, Harbor, or Quay (self-hosted) are all viable targets on VKS.

1.4  DeploymentConfig vs. Deployment

OpenShift’s DeploymentConfig (apps.openshift.io/v1) is a superset of Kubernetes Deployment with additional trigger and lifecycle hook capabilities. While Red Hat deprecated DeploymentConfig in OpenShift 4.x in favour of standard Deployments, many enterprise OpenShift environments — especially those migrated from OpenShift 3.x — still run DeploymentConfigs.

Every DeploymentConfig must be converted to a standard Kubernetes Deployment before migrating to VKS. The oc convert plugin or manual YAML translation handles most cases, but lifecycle hooks (pre/mid/post) that invoke oc exec or oc rsh will need to be rewritten as Kubernetes init containers or Jobs.

1.5  Route vs. Ingress

OpenShift Routes (route.openshift.io/v1) are the OpenShift-native equivalent of Kubernetes Ingress resources. They are not compatible with standard Kubernetes Ingress controllers, including the NGINX, Contour, or Istio Gateways you will use on VKS.

For each Route in your environment:

• Run oc get routes -A -o wide to enumerate all routes, their hostnames, TLS termination mode (edge, passthrough, re-encrypt), and backend services.
• Edge TLS routes map directly to standard Ingress with TLS termination — the lowest-effort conversion.
• Passthrough routes (SNI-based) require an Ingress controller with TCP passthrough support (e.g., NGINX with ssl-passthrough annotation) or an Istio Gateway with TLS mode: PASSTHROUGH.
• Re-encrypt routes (TLS end-to-end) require Ingress backends that present valid certificates — ensure your cert-manager ClusterIssuer is deployed on VKS before converting these (as documented in Part 1, Section 3.3).

1.6  OpenShift-Specific Operators and CRDs

OpenShift ships dozens of cluster operators that manage platform capabilities via CRDs in the openshift.io, operator.openshift.io, and config.openshift.io API groups. Any application that directly interacts with these CRDs — or that was installed via OperatorHub using an OLM (Operator Lifecycle Manager) subscription — must be assessed.

Run the following to get a consolidated view of non-core CRD usage:

kubectl api-resources --verbs=list --namespaced -o name |
grep -E 'openshift.io|operator.openshift.io' |
xargs -I {} kubectl get {} -A --no-headers 2>/dev/null |
grep -v 'No resources'

For OLM-managed operators, check whether an equivalent operator is available in OperatorHub for upstream Kubernetes / VKS, or whether the operator vendor provides a Helm chart alternative. Most major ISV operators (cert-manager, Velero, Prometheus Operator, Argo CD, Vault) ship upstream Helm charts that are fully supported on VKS.

OpenShift Feature Gap Analysis vs. VKS

The table below extends the feature mapping from Part 1 with OpenShift-specific capabilities. Migration effort ratings reflect typical complexity for a well-resourced platform team.

Phase 2: Target Environment — OpenShift-Specific Considerations

The VCF / VKS cluster provisioning steps from Part 1 (Section 2) apply without modification. The following additions are specific to receiving OpenShift workloads.

2.1  Pod Security Admission Configuration

VKS clusters enforce Kubernetes Pod Security Admission (PSA) at the namespace level. Before migrating any OpenShift workload, configure PSA labels on target namespaces based on your SCC audit findings (Section 1.1):

# Namespace with baseline PSA (equivalent to OpenShift 'restricted' SCC)
kubectl label namespace my-app
pod-security.kubernetes.io/enforce=baseline
pod-security.kubernetes.io/warn=restricted
pod-security.kubernetes.io/audit=restricted

# For workloads that required 'anyuid' SCC — target is to eliminate this
# Temporarily label as privileged during migration, with a remediation deadline
kubectl label namespace legacy-app
pod-security.kubernetes.io/enforce=privileged

Resist the temptation to label all namespaces as privileged to make the migration faster. This trades a short-term convenience for a long-term security debt that is politically difficult to remediate after go-live.

2.2  Deploy OPA Gatekeeper or Kyverno for SCC Parity

Kubernetes PSA is a binary enforcement mechanism — it cannot replicate the fine-grained controls that OpenShift SCCs provide (e.g., allowing a specific UID range, controlling allowedCapabilities per namespace). Deploy OPA Gatekeeper or Kyverno to fill this gap:

• Use the Gatekeeper Policy Library or Kyverno Policy Library as a starting point — both include SCC-equivalent policies for common scenarios.
• Write custom ConstraintTemplates (Gatekeeper) or ClusterPolicies (Kyverno) for workloads with unusual SCC requirements identified in your audit.
• Deploy policies in audit mode first, then enforce mode after workload validation — the same progressive approach used for traffic cutover in Part 1.

2.3  Image Registry Migration and Re-tagging

If workloads currently pull from OpenShift’s integrated registry (image-registry.openshift-image-registry.svc), those images must be re-tagged and pushed to your external registry before VKS deployment. A systematic approach:

1. Extract the list of images from the OpenShift integrated registry: oc get imagestreams -A -o jsonpath='{range .items[*]}{.status.dockerImageRepository}n{end}’
2. Pull each image using skopeo or docker pull with credentials for the OpenShift registry route.
3. Re-tag and push to your target registry (ACR, Harbor, Quay). Maintain the same tag structure to minimize Deployment manifest changes.
4. Update all Deployment / StatefulSet image references from image-registry.openshift-image-registry.svc:5000/<ns>/<name>:<tag> to your new registry FQDN.
5. Create imagePullSecrets on the target VKS namespaces and patch the default ServiceAccount to reference them (or use VKS node-level registry credentials).

Phase 3: Workload Migration — The OpenShift-Specific Steps

The Velero-based PVC migration, cert-manager deployment, and Istio migration steps from Part 1 (Sections 3.1 – 3.4) apply here with minimal modification. The following steps are additive — they address OpenShift-specific resource types that have no equivalent in the Part 1 Rancher playbook.

3.1  Converting DeploymentConfigs to Deployments

Use the oc convert (or oc-migrate) tooling to generate initial Deployment YAML from each DeploymentConfig, then review the output manually:

# Export DeploymentConfig
oc get dc my-app -n my-namespace -o yaml > my-app-dc.yaml

# Convert to Deployment (requires oc v4.12+ or the convert plugin)
oc convert -f my-app-dc.yaml --local -o yaml > my-app-deployment.yaml

# Review output — manually check:
#   – ImageChange triggers → replace with Argo CD image updater or CI pipeline
#   – ConfigChange triggers → remove (Deployments reconcile on spec change natively)
#   – Lifecycle hooks (pre/mid/post) → convert to initContainers or Jobs
#   – replicas / revisionHistoryLimit settings

Do not apply converted Deployments to the target VKS cluster until image references have been updated to the new registry (Section 2.3) and SCC-to-PSA remediation is complete.

3.2  Converting Routes to Ingress Resources

The following conversion patterns cover the majority of Route configurations encountered in enterprise OpenShift deployments:

Edge TLS Route → Ingress + cert-manager Certificate: Direct one-to-one mapping. Replace spec.tls.termination: edge with a standard Ingress TLS stanza and a cert-manager Certificate annotation. The hostname is preserved. As noted in Part 1 (Section 3.3), cert-manager re-issues TLS certificates automatically on the VKS target cluster.

Passthrough Route → NGINX Ingress with ssl-passthrough: Add the annotation nginx.ingress.kubernetes.io/ssl-passthrough: ‘true’ to the Ingress resource. Ensure your NGINX Ingress controller is deployed with the –enable-ssl-passthrough flag (not enabled by default).

Reencrypt Route → Istio Gateway TLS MUTUAL / SIMPLE: Model the reencrypt pattern as an Istio Gateway with tls.mode: SIMPLE (VKS terminates TLS) plus a DestinationRule with tls.mode: ISTIO_MUTUAL (re-encrypt to the backend using mTLS). This requires Istio sidecar injection on the backend service — ensure namespace labels are applied before pod scheduling (Part 1, Section 3.4).

3.3  Replacing BuildConfigs with CI Pipelines

BuildConfig replacement is a pre-migration prerequisite — you cannot migrate a workload whose image is produced exclusively by an OpenShift BuildConfig, because the build infrastructure no longer exists on VKS. This work must happen before cluster decommission.

Recommended pipeline targets by build strategy:

• Docker strategy → GitHub Actions workflow using docker/build-push-action or a Tekton Pipeline with a Kaniko / Buildah Task. Image is pushed to your external registry (ACR, Harbor) and tagged for both environment promotion and immutable digest references.
• S2I strategy → Paketo Buildpacks (cloud-native buildpacks) is the most faithful replacement. The pack build CLI or the Tanzu Build Service operator (available on VKS via Broadcom) replicates the S2I “detect and build” lifecycle without requiring a Dockerfile.
• Binary strategy (pushing local artifacts into a build) → Replace with a Tekton Pipeline stage that fetches artifacts from Nexus / Artifactory and layers them into a base image using a multi-stage Dockerfile.

⚠️  BuildConfig replacement is frequently underestimated in project planning. In environments that have grown organically over years of OpenShift 3.x usage, it is common to find dozens of BuildConfigs that have never been documented as application dependencies. Complete the BuildConfig audit (Section 1.2) early and allocate dedicated sprint capacity for pipeline rewrites.

3.4  Identity and Authentication Migration

OpenShift ships its own OAuth server that integrates with HTPasswd, LDAP, GitHub, GitLab, Google, and OpenID Connect identity providers. On VKS, authentication is delegated to vCenter SSO for platform-level RBAC, but application-level OIDC integrations should be migrated to a standalone identity provider:

• If your organization runs Azure AD / Entra ID, configure VKS API server OIDC integration directly against Entra ID using the –oidc-issuer-url flag on the TanzuKubernetesCluster spec. This is the lowest-friction path for AKS-adjacent environments.
• For on-premises LDAP or complex identity federation, deploy Dex or Keycloak as an OIDC bridge on VKS. Both are supported upstream and can federate against the same LDAP directory that OpenShift’s OAuth server was using.
• Audit and migrate service account tokens used by applications for OpenShift API access (oc sa get-token). On VKS, replace with short-lived projected service account tokens and IRSA / Workload Identity patterns where applicable.

Phase 4: Traffic Cutover — Additional Considerations

The progressive DNS weight-shift strategy from Part 1 (Section 4) applies without modification. The following considerations are OpenShift-specific.

4.1  Router vs. NSX ALB VIP Behavior Differences

OpenShift’s HAProxy Router accumulates routes dynamically and handles wildcard DNS domains (*.apps.<cluster-domain>) automatically. NSX Advanced Load Balancer on VKS creates discrete VIPs per Ingress resource. If your DNS cutover relied on a single wildcard A record pointing to the OpenShift Router VIP, you will need to either:

• Create individual DNS records for each hostname during migration — more explicit, lower blast radius per service.
• Configure ExternalDNS on VKS (as documented in the broader VKS GitOps baseline) to automatically manage DNS records from Ingress resources, effectively replicating the OpenShift wildcard DNS behavior programmatically.

4.2  Monitoring Golden Signals Across Both Platforms

OpenShift’s forked Prometheus Operator exposes metrics under different label schemas than the upstream kube-prometheus-stack. If you are federating metrics into a central Thanos or Grafana instance (as recommended in Part 1, Section 4.2), update your recording rules and dashboards to account for label differences:

• OpenShift labels pods with openshift_io_* labels that do not appear on VKS. Adjust PromQL queries referencing these labels before go-live.
• OpenShift’s user workload monitoring uses a separate Prometheus instance (openshift-user-workload-monitoring). On VKS, a single kube-prometheus-stack instance handles both platform and user workload metrics — consolidate your Alertmanager routing rules accordingly.

Phase 5: Post-Migration Hardening — OpenShift-Specific Items

The Kubescape / Trivy / kube-bench security validation, RBAC rationalisation, and Rancher decommission checklist from Part 1 (Section 5) apply here. The following items are additions specific to OpenShift migrations.

5.1  Validate SCC-to-PSA/Gatekeeper Policy Coverage

Run a final Kubescape scan with the OpenShift DISA STIG framework (if applicable to your compliance posture) alongside the NSA/CISA framework used in Part 1. Cross-reference Gatekeeper/Kyverno audit mode violation reports against your SCC migration inventory to confirm no workloads are operating outside their intended security boundary.

5.2  Remove OpenShift Annotation Residue

Just as Rancher injects cattle.io annotations (Part 1, Phase 3.1), OpenShift injects openshift.io/*, build.openshift.io/*, and image.openshift.io/* annotations into workload resources. Strip these using a Kustomize patch applied at the GitOps layer:

# kustomize/patches/strip-openshift-annotations.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: PLACEHOLDER
  annotations:
    openshift.io/deployment-config.name: null
    openshift.io/deployment-config.latest-version: null
    openshift.io/deployment.phase: null
    image.openshift.io/triggers: null

5.3  Decommission OpenShift Infrastructure

The OpenShift decommission sequence differs from Rancher’s (Part 1, Section 5.3) because OpenShift clusters are self-hosted — they include etcd, the API server, and infrastructure operators that must be shut down in the correct order:

6. Drain all worker nodes and scale MachineSet replicas to 0 in the openshift-machine-api namespace.
7. Scale control plane replicas to 0 via the Machine API or manually power off control plane VMs (vSphere VMs if IPI-deployed).
8. Delete the OpenShift cluster using the openshift-install destroy cluster command with the original install-config.yaml to ensure all cloud/vSphere resources (load balancers, DNS records, vSphere folders) are cleaned up.
9. Revoke the vCenter service account used for OpenShift IPI provisioning.
10. Release NSX segments and IP address pools previously allocated to the OpenShift SDN (OVN-Kubernetes or OpenShift SDN).
11. Remove the OpenShift pull secret from your secrets management platform (Vault, Azure Key Vault) and notify Red Hat to deactivate the subscription entitlement.

Side-by-Side: Rancher Migration vs. OpenShift Migration

The table below summarizes the key differences between the two migration paths across each phase of the Part 1 framework.

OpenShift-Specific Pitfalls

▸  Assuming SCC = PSA: Security Context Constraints and PodSecurity Standards are not equivalent. A workload that ran successfully under OpenShift’s restricted SCC may still fail PSA baseline/restricted enforcement due to differences in allowedCapabilities, runAsNonRoot enforcement, and seccompProfile requirements. Test every workload in PSA audit mode before enforcing.

▸  Migrating DeploymentConfigs without removing ImageChange triggers: ImageChange triggers reference ImageStream tags that do not exist on VKS. A converted Deployment with a stale imageChangeParams annotation will not cause an immediate failure — but it will confuse operators and break automation that parses these annotations. Remove all OpenShift trigger annotations from converted Deployments.

▸  Underestimating Maistra divergence from upstream Istio: OpenShift Service Mesh is based on a fork of Istio (Maistra) that ships additional CRDs (ServiceMeshControlPlane, ServiceMeshMemberRoll) and modifies the namespace injection model. Migrating Istio config from OpenShift Service Mesh to upstream Istio requires translating Maistra-specific resources — not just re-applying existing VirtualServices.

▸  Forgetting the OpenShift pull secret scope: OpenShift nodes authenticate to Red Hat registries (registry.redhat.io, registry.access.redhat.com) using the cluster pull secret. After migration, workloads that reference Red Hat base images must either pull from a mirrored registry or use image pull secrets with valid Red Hat credentials — the OpenShift cluster pull secret does not transfer to VKS.

▸  Network policy gaps from OpenShift SDN to Antrea: OpenShift SDN and OVN-Kubernetes implement NetworkPolicy semantics slightly differently from Antrea, particularly around egress CIDR blocking and namespace-scoped egress rules. Validate all NetworkPolicies in Antrea audit mode after migration — do not assume identical behavior.

Conclusion

An OpenShift-to-VKS migration is categorically more complex than a Rancher-to-VKS migration — not because VKS is a more difficult target, but because OpenShift’s PaaS model creates significantly deeper application coupling to platform-specific APIs. The Rancher migration documented in Part 1 is primarily an infrastructure and operational migration. The OpenShift migration is partly an application modernization project.

The teams that navigate this most successfully are those that treat the migration as an opportunity to align with upstream Kubernetes patterns: replacing BuildConfigs with portable CI pipelines, replacing DeploymentConfigs with standard Deployments, replacing Routes with Ingress resources, and replacing the OpenShift identity layer with a standards-based OIDC provider. Each of these changes reduces long-term operational complexity and improves the portability of your workloads — whether the next platform is VKS, AKS, or something not yet announced.

The five-phase framework from Part 1 remains your migration backbone. This article documents the additional work items layered on top of it. Used together, the two articles give you a complete migration playbook for both major Kubernetes platform migration scenarios into VKS on VCF.

📖  Missed Part 1? Read “Migrating Applications from Rancher to vSphere Kubernetes Service on VMware Cloud Foundation” at capstone-s.com/insights/ for the foundational migration framework this article builds upon.

📬  Planning an OpenShift migration? Capstone-S provides SCC audit tooling, BuildConfig conversion playbooks, and hands-on migration engineering for OpenShift-to-VKS transitions. Contact us at insights@capstone-s.com or visit capstone-s.com/contact.

Published on capstone-s.com/insights/  ·  Part 2 of the VKS Migration Series  ·  © 2026 Capstone-S. All rights reserved.