Openshift App

OpenShift Application Packaging

Package, build, secure, and deploy applications on OpenShift Container Platform 4.14-4.21. Covers container images, deployment manifests, CI/CD pipelines, security hardening, operational patterns, and disconnected environments.

Quick Decision Guide

| Task | Go to | |------|-------| | Build a container image for OpenShift | [Container Images](#container-image-essentials) below | | Choose Helm vs Kustomize vs Operator | [Packaging Decision Matrix](#packaging-decision-matrix) below | | Fix SCC / permission errors | references/security.md (Restricted-v2 section) | | Set up CI/CD pipeline | references/cicd-gitops.md | | Harden supply chain (sign, attest, scan) | references/security.md (Supply Chain section) | | Configure Routes, probes, scaling | references/operations.md | | Deploy in air-gapped / disconnected env | references/disconnected.md | | Migrate from DeploymentConfig | references/gotchas.md (DeploymentConfig section) | | Understand OCP version breaking changes | references/gotchas.md (Version Timeline section) |

Critical Gotchas (Read First)

1. Arbitrary UID -- The #1 "Works on K8s, Fails on OpenShift" Issue

OpenShift assigns a random UID from a namespace-specific range but always sets GID 0 (root group). Hardcoded USER 1000 in Dockerfiles will fail under restricted-v2 SCC.

# OpenShift-compatible Dockerfile pattern
FROM registry.access.redhat.com/ubi9/ubi-minimal:latest

COPY --chown=1001:0 app /app
RUN chmod -R g=u /app && \
    chgrp -R 0 /app

# Use 1001 as conventional non-root UID
# OpenShift ignores this and assigns its own UID, but vanilla K8s respects it
USER 1001
EXPOSE 8080
ENTRYPOINT ["/app/server"]

Key rules:

• Files: chgrp -R 0 && chmod -R g=u (mirror owner perms to root group)
• Ports: must be > 1023 (no privileged ports under restricted SCC)
• USER: set to 1001 for portability, but leave runAsUser empty in pod spec
• ENTRYPOINT: always use exec form ["binary"] (not shell form) for signal propagation
• /etc/passwd: if app needs username lookup, make it group-writable and use entrypoint to append dynamic entry
• /tmp: mount emptyDir if using readOnlyRootFilesystem: true

2. restricted-v2 SCC (Default Since OCP 4.11)

All authenticated users get restricted-v2. It is stricter than vanilla K8s PSS restricted:

| Field | restricted-v2 | K8s PSS restricted | |-------|--------------|-------------------| | Capabilities | Drop ALL | Drop some | | allowPrivilegeEscalation | false (enforced) | false | | seccompProfile | RuntimeDefault required | RuntimeDefault required | | runAsUser | MustRunAsRange (namespace range) | MustRunAsNonRoot | | Volume types | configMap, downwardAPI, emptyDir, PVC, projected, secret | Same + ephemeral |

Minimum compliant pod securityContext:

securityContext:
  runAsNonRoot: true
  # Do NOT set runAsUser -- let OpenShift assign from namespace range
  seccompProfile:
    type: RuntimeDefault
  allowPrivilegeEscalation: false
  capabilities:
    drop: ["ALL"]

PSA runs in parallel with SCCs. A pod must pass both. OpenShift auto-labels namespaces with PSA levels matching the most privileged SCC available.

3. Helm 4 Is NOT Usable with ArgoCD on OpenShift (2026)

• Helm 4.0.0 released November 2025 with Server-Side Apply as default
• OpenShift 4.19-4.21 still ships Helm 3 (web terminal bundles v3.17.1)
• ArgoCD (through v3.3 / GitOps 1.20) only supports Helm 3
• Helm 3 EOL: bug fixes July 2026, security fixes November 2026
• Recommendation: use Helm 3 now, plan Helm 4 migration after ArgoCD adds support

4. DeploymentConfig Is Deprecated (OCP 4.14)

Use Deployment for all new work. For ImageStream triggers on Deployments:

metadata:
  annotations:
    image.openshift.io/triggers: >-
      [{"from":{"kind":"ImageStreamTag","name":"myapp:latest"},
        "fieldPath":"spec.template.spec.containers[?(@.name==\"myapp\")].image"}]

Also set lookupPolicy.local: true on the ImageStream.

5. OpenShift SDN Removed in OCP 4.17

Must migrate to OVN-Kubernetes before upgrading. Key impacts:

• OVN reserves 100.64.0.0/16 and 100.88.0.0/16 (check for conflicts)
• MTU decreases by 50 bytes (OVN overlay overhead)
• Migration requires 2 node reboots (~double upgrade time)
• Egress policies that couldn't be enforced before now CAN be -- audit existing NetworkPolicies

6. cgroup v1 Removed in OCP 4.19

All nodes must run cgroup v2 before upgrading. cgroup v2 was the default for new installs since 4.14, deprecated in 4.16.

7. Logging 6.0 Removes EFK Stack Entirely

Elasticsearch, Fluentd, and Kibana are gone. Replaced by LokiStack + Vector + console UI plugin. Migration is NOT in-place -- deploy Loki/Vector in parallel, run both stacks during retention window, then retire Elasticsearch.

Container Image Essentials

UBI Base Image Selection

| Variant | Size (~compressed) | Package Manager | Use Case | |---------|-------------------|----------------|----------| | ubi9/ubi | ~80 MB | dnf/yum | Builder stages, development | | ubi9/ubi-minimal | ~36 MB | microdnf | Light runtime, need to install packages | | ubi9/ubi-micro | ~12 MB | None | Production runtime (multi-stage required) | | ubi9/ubi-init | ~80 MB | dnf/yum | systemd services (StopSignal: SIGRTMIN+3) |

Recommendation: UBI Micro for production runtime via multi-stage build. UBI Minimal as builder stage. UBI Micro is preferred over scratch because compliance scanners classify scratch images as unrecognizable.

UBI is freely redistributable without a Red Hat subscription.

Multi-Stage Build Pattern

# Stage 1: Build
FROM registry.access.redhat.com/ubi9/ubi-minimal:latest AS builder
RUN microdnf install -y --setopt=tsflags=nodocs --setopt=install_weak_deps=0 \
    golang && microdnf clean all
COPY . /src
WORKDIR /src
RUN CGO_ENABLED=0 go build -o /app/server ./cmd/server

# Stage 2: Runtime
FROM registry.access.redhat.com/ubi9/ubi-micro:latest
COPY --from=builder --chown=1001:0 /app/server /app/server
RUN chmod g=u /app/server
USER 1001
EXPOSE 8080
ENTRYPOINT ["/app/server"]

Red Hat Container Certification Requirements

If certifying for the Red Hat Ecosystem Catalog:

• Base image: must use UBI or RHEL base
• Required labels: name, vendor, version, release, summary, description
• Required directory: /licenses with software terms
• Layers: max 40 (recommended 5-20)
• Security: no critical/important CVEs in Red Hat components (dnf update-minimal --security --sec-severity=Important --sec-severity=Critical)
• Non-root: recommended (required for restricted-v2 SCC)
• Preflight checks: RunAsNonRoot, BasedOnUBI, HasLicense, HasRequiredLabel, LayerCountAcceptable, HasNoProhibitedPackages, etc.
• Recertification: every 12 months or when critical CVE > 3 months old

See references/container-images.md for full details.

Packaging Decision Matrix

| Format | When to Use | Limitations | |--------|------------|-------------| | Helm | Distribute to other teams/customers; values-driven config; OperatorHub Helm operators | Helm 3 only on OCP today; chart-verifier for certification | | Kustomize | Same-team env overlays (dev/staging/prod); GitOps prerequisite | No templating logic; oc apply -k does NOT support --enable-helm | | Helm + Kustomize | Dominant hybrid: Helm for packaging, Kustomize for env patches | Requires --enable-helm flag (only works in kustomize build or ArgoCD) | | Operator (Go) | Stateful apps needing Day-2 ops (backup/restore/scaling); L3-L5 maturity | Complex to develop; Operator SDK CLI deprecated in OCP 4.16 (upstream continues) | | Operator (Helm) | Simple operators for OperatorHub distribution | Limited to L1-L2 capability maturity | | OLM v1 ClusterExtension | Install operators on OCP 4.18+ | Requires user-provided ServiceAccount + RBAC; AllNamespaces only | | OpenShift Templates | Legacy only (NOT recommended for new work) | Not portable to vanilla K8s; Template Service Broker removed in 4.4 |

Helm on OpenShift -- Key Patterns

Detect OpenShift at template time:

{{- define "mychart.isOpenshift" -}}
{{- if .Capabilities.APIVersions.Has "security.openshift.io/v1" -}}true{{- end -}}
{{- end -}}

Conditional Route vs Ingress:

{{- if .Capabilities.APIVersions.Has "route.openshift.io/v1" }}
apiVersion: route.openshift.io/v1
kind: Route
{{- else }}
apiVersion: networking.k8s.io/v1
kind: Ingress
{{- end }}

SCC-compatible values (let OpenShift assign UIDs):

securityContext:
  runAsUser: null    # Do NOT hardcode
  fsGroup: null      # Do NOT hardcode
  runAsNonRoot: true

See references/packaging-formats.md for OLM v1, Kustomize patterns, and certified chart requirements.

Additional References

| Reference | Contents | |-----------|----------| | references/container-images.md | UBI variants, multi-stage builds, arbitrary UID, certification, Podman, ImageStreams | | references/packaging-formats.md | Helm on OCP, OLM v1 RBAC, Kustomize overlays, certified operators/charts | | references/security.md | SCC/PSA, supply chain (Sigstore/RHTAS/Conforma), secrets (ESO/Vault), FIPS, compliance, NetworkPolicy | | references/cicd-gitops.md | Tekton Pipelines, Chains, Pipelines-as-Code, ArgoCD Agent, Shipwright, image promotion | | references/operations.md | Routes/TLS, probes, HPA/KEDA/VPA, monitoring, logging, storage, sidecars, serverless, multi-arch | | references/gotchas.md | Version timeline (4.14-4.21), DeploymentConfig migration, SDN removal, networking changes | | references/disconnected.md | oc-mirror v2, registry mirroring, OCI GitOps, Tekton bundles, OSUS upgrades, air-gap patterns |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: air-gapped
• Source: air-gapped/skills
• License: MIT

Install and usage instructions live in the source repository linked above.