Disconnected Installation Guide

This guide provides instructions for installing OpenShift in disconnected or air-gapped environments.

Overview

A disconnected installation is useful when your environment:

Prerequisites

Hardware Requirements

Registry Options

You can use several container registry solutions for your disconnected environment:

  1. Red Hat Quay - Enterprise container registry platform
  2. Harbor Registry - Cloud native registry project
  3. JFrog Artifactory - Universal artifact repository
  4. Docker Registry - Basic container registry

For automated registry setup and disconnected installation assistance, you can use the OpenShift 4 Disconnected Helper tool, which provides:

Software Requirements

# Install required packages
sudo dnf install -y \
  podman \
  httpd-tools \
  openssl \
  jq \
  skopeo

Setup Steps

1. Configure Mirror Registry

Choose one of the following registry setup options:

Option 1: Basic Docker Registry

# Create registry certificates
mkdir -p /opt/registry/certs
openssl req -newkey rsa:4096 -nodes -sha256 \
  -keyout /opt/registry/certs/registry.key \
  -x509 -days 365 -out /opt/registry/certs/registry.crt \
  -subj "/CN=registry.example.com"

# Create registry auth
mkdir -p /opt/registry/auth
htpasswd -bBc /opt/registry/auth/htpasswd admin password

# Start the registry
podman run --name mirror-registry \
  -p 5000:5000 \
  -v /opt/registry/data:/var/lib/registry:z \
  -v /opt/registry/auth:/auth:z \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  -v /opt/registry/certs:/certs:z \
  -e "REGISTRY_HTTP_TLS_CERTIFICATE=/certs/registry.crt" \
  -e "REGISTRY_HTTP_TLS_KEY=/certs/registry.key" \
  -d docker.io/library/registry:2

Option 2: Red Hat Quay

For Quay installation instructions, see Installing Red Hat Quay on RHEL.

Option 3: Harbor Registry

For Harbor setup using the disconnected helper:

# Using the disconnected helper tool
git clone https://github.com/tosin2013/ocp4-disconnected-helper
cd ocp4-disconnected-helper
ansible-playbook -i inventory setup-harbor-registry.yml

Option 4: JFrog Registry

For JFrog setup using the disconnected helper:

# Using the disconnected helper tool
git clone https://github.com/tosin2013/ocp4-disconnected-helper
cd ocp4-disconnected-helper
ansible-playbook -i inventory setup-jfrog-registry.yml

2. Mirror OpenShift Images

# Set environment variables
export LOCAL_REGISTRY="registry.example.com:5000"
export LOCAL_REPOSITORY="ocp4/openshift4"
export PRODUCT_REPO="openshift-release-dev"
export RELEASE_NAME="ocp-release"
export OCP_RELEASE="4.14.0"
export ARCHITECTURE="x86_64"
export REMOVABLE_MEDIA_PATH="/path/to/media"

# Mirror images
oc adm release mirror \
  -a ${LOCAL_SECRET_JSON} \
  --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \
  --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \
  --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}

3. Configure Image Content Sources

# imageContentSources section in install-config.yaml
imageContentSources:
- mirrors:
  - registry.example.com:5000/ocp4/openshift4
  source: quay.io/openshift-release-dev/ocp-release
- mirrors:
  - registry.example.com:5000/ocp4/openshift4
  source: quay.io/openshift-release-dev/ocp-v4.0-art-dev

4. Configure Additional Trust Bundle

# additionalTrustBundle section in install-config.yaml
additionalTrustBundle: |
  -----BEGIN CERTIFICATE-----
  # Registry certificate content
  -----END CERTIFICATE-----

Installation Process

1. Prepare Installation Files

# Create installation directory
mkdir ~/disconnected-install
cd ~/disconnected-install

# Create install-config.yaml
cat << EOF > install-config.yaml
apiVersion: v1
baseDomain: example.com
metadata:
  name: disconnected-cluster
platform:
  none: {}
pullSecret: '{"auths":{"registry.example.com:5000": {"auth": "BASE64_AUTH_STRING"}}}'
sshKey: 'SSH_PUBLIC_KEY'
imageContentSources:
- mirrors:
  - registry.example.com:5000/ocp4/openshift4
  source: quay.io/openshift-release-dev/ocp-release
additionalTrustBundle: |
  -----BEGIN CERTIFICATE-----
  # Registry certificate content
  -----END CERTIFICATE-----
EOF

2. Generate Installation Assets

# Create manifests
openshift-install create manifests --dir=.

# Create ignition configs
openshift-install create ignition-configs --dir=.

3. Configure Network

# Example network configuration in nodes.yml
networkConfig:
  interfaces:
    - name: eno1
      type: ethernet
      state: up
      ipv4:
        enabled: true
        address:
          - ip: 192.168.1.10
            prefix-length: 24
        dhcp: false
  dns-resolver:
    config:
      server:
        - 192.168.1.53
  routes:
    config:
      - destination: 0.0.0.0/0
        next-hop-address: 192.168.1.1
        next-hop-interface: eno1

Post-Installation Configuration

1. Configure Image Registry

oc patch configs.imageregistry.operator.openshift.io cluster \
  --type merge \
  --patch '{"spec":{"storage":{"emptyDir":{}}}}'

2. Configure Operators

# Create CatalogSource for disconnected operators
cat << EOF | oc apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: disconnected-operators
  namespace: openshift-marketplace
spec:
  sourceType: grpc
  image: registry.example.com:5000/olm/redhat-operators:v1
  displayName: Disconnected Operator Catalog
  publisher: Red Hat
EOF

Troubleshooting

Common Issues

Registry Certificate Issues

# Check certificate validity
openssl x509 -in /opt/registry/certs/registry.crt -text -noout

# Verify trust bundle
oc get configmap custom-ca -n openshift-config -o yaml

Image Pull Failures

# Check image pull secret
oc get secret pull-secret -n openshift-config -o yaml

# Test image pull
podman pull --tls-verify=false registry.example.com:5000/ocp4/openshift4:latest

Network Connectivity

# Test registry connectivity
curl -k https://registry.example.com:5000/v2/_catalog

# Check DNS resolution
dig registry.example.com

External Resources