Air-Gapped OpenShift 4.x Installation Guide

techhadoop OCP

An air-gapped (disconnected) installation of OpenShift 4.x requires mirroring the official Red Hat release payloads, Operator catalogs, and RHCOS images into a local, accessible container registry (such as Red Hat Quay, Harbor, or Nexus) on your internal network before running the installer.

Prerequisites & Architecture Overview

Plaintext

┌─────────────────────────┐               ┌─────────────────────────┐
│   CONNECTED NETWORK     │               │   DISCONNECTED NETWORK  │
│                         │  Sneakernet   │                         │
│  ┌───────────────────┐  │   or DMZ      │  ┌───────────────────┐  │  ┌───────────────────┐
│  │ Red Hat Registry  │ ─┼───────────────┼─►│ Internal Mirror   │ ─┼─►│ Target OpenShift  │
│  │ (registry.redhat) │  │  oc-mirror    │  │ Registry (Quay)   │  │  │ Cluster Nodes     │
│  └───────────────────┘  │               │  └───────────────────┘  │  └───────────────────┘
└─────────────────────────┘               └─────────────────────────┘
  1. Bastion Host / Mirror Host: A machine with internet access (or access to a DMZ mirror host) to pull official images, and network access to your internal mirror registry.
  2. Internal Mirror Registry: An enterprise v2-2 compliant registry (e.g., Red Hat Quay, Harbor) reachable by all nodes in the disconnected cluster environment.
  3. oc-mirror CLI Plugin: The official OpenShift CLI tool used to manage image mirror sets.

1.Install the oc-mirror CLI Plugin:Connected Environment.

On your connected mirror host, download and install the oc-mirror binary:

Bash

# Download the OpenShift client and oc-mirror plugin
wget https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/stable/oc-mirror.tar.gz
tar -xvf oc-mirror.tar.gz -C /usr/local/bin/
chmod +x /usr/local/bin/oc-mirror
# Verify plugin installation
oc mirror version

Verification: Running oc mirror version returns the current version matching your client tools.

2.Create the Image Set Configuration:Connected Environment.

Create an ImageSetConfiguration file defining the exact OCP version and Operator catalogs you need to mirror.

YAML

# imageset-config.yaml
apiVersion: mirror.openshift.io/v1alpha2
kind: ImageSetConfiguration
storageConfig:
  local:
    path: /home/user/ocp-mirror-data
mirror:
  platform:
    architectures:
      - amd64
    channels:
      - name: stable-4.16
        minVersion: 4.16.0
        maxVersion: 4.16.0
  operators:
    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.16
      packages:
        - name: local-storage-operator
        - name: odf-operator
  additionalImages:
    - name: registry.redhat.io/ubi8/ubi:latest

3.Mirror Images to Local Disk or Target Registry:Connected Environment.

Combine your Red Hat pull secret and target mirror registry credentials into a single local ~/.docker/config.json.

Option A: Direct Mirror (If mirror host connects to both internet and internal registry):

Bash

oc mirror --config=imageset-config.yaml docker://registry.internal.corp:5000/openshift/release

Option B: File-based Mirror (If using removable media / physical transport):

Bash

# 1. Download payloads to tar archive
oc mirror --config=imageset-config.yaml file://mirror-archive
# 2. Transport tar file to the air-gapped network, then push to internal registry:
oc mirror --from=./mirror-archive/mirror_seq1_000000.tar docker://registry.internal.corp:5000/openshift/release

Verification: When the mirroring finishes, oc-mirror outputs an oc-mirror-workspace directory containing generated manifests (imageContentSourcePolicy.yaml and catalogSource.yaml).

4.Configure install-config.yaml for Disconnected Install:Disconnected Environment.

Create your cluster installation configuration file, updating the pullSecret to use credentials for your internal mirror registry, setting trust for internal CA certificates, and providing the mirror location.

YAML

# install-config.yaml
apiVersion: v1
baseDomain: internal.corp
metadata:
  name: ocp-airgap
compute:
  - name: worker
    replicas: 3
controlPlane:
  name: master
  replicas: 3
platform:
  vsphere:
    vCenter: vcenter.internal.corp
    # ... standard platform settings ...
pullSecret: '{"auths":{"registry.internal.corp:5000":{"auth":"dXNlcjpwYXNz"}}}'
additionalTrustBundle: |
  -----BEGIN CERTIFICATE-----
  MIIE... (Your Internal Mirror Registry Certificate CA)
  -----END CERTIFICATE-----
imageContentSources:
  - mirrors:
      - registry.internal.corp:5000/openshift/release
    source: quay.io/openshift-release-dev/ocp-release
  - mirrors:
      - registry.internal.corp:5000/openshift/release
    source: registry.redhat.io/multicluster-engine

5.Launch the Installation:Disconnected Environment.

Execute the installer using your custom install-config.yaml:

Bash

openshift-install create cluster --dir=. --log-level=info

The cluster nodes will boot, pull RHCOS and system images exclusively from registry.internal.corp:5000, and establish the control plane without contacting the internet.

6.Apply Operator Catalog Sources:Post-Install Automation.

Apply the generated ImageContentSourcePolicy (ICSP) / ImageDigestMirrorSet (IDMS) and CatalogSource manifests created by oc-mirror to enable offline OperatorHub access:

Bash

oc apply -f ./oc-mirror-workspace/results-*/imageContentSourcePolicy.yaml
oc apply -f ./oc-mirror-workspace/results-*/catalogSource-*.yaml

Verification: Check that your local Operator catalog appears in OpenShift:

Bash

oc get catalogsource -n openshift-marketplace

Leave a Reply