openshift-app

name: openshift-app description: >- Package applications for OpenShift deployment: container images (UBI, arbitrary UID, multi-stage builds), packaging formats (Helm, Kustomize, Operators, OLM v1), CI/CD (Tekton, ArgoCD, Shipwright, Conforma), security (SCC, PSA, supply chain, image signing, secrets), operations (Routes, probes, scaling, monitoring, storage), disconnected/air-gapped patterns, and critical gotchas. Also when an app "works on Kubernetes but fails on OpenShift" (SCC denied, random/arbitrary UID, permission errors). Covers OCP 4.14-4.21. NOT for cluster installation or infrastructure management.

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

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:

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

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

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