Installation Guide

A comprehensive guide for installing OpenShift using the Agent-based Installer, covering all major deployment scenarios and configurations.

Important: OpenShift documentation will be moving to docs.redhat.com on March 12, 2025. Links will be updated accordingly. For the current status of all external links used in this documentation, please refer to External Links.

Related ADR: ADR-0001: Agent-based Installation Approach

Overview
Prerequisites
Installation Methods
- Declarative Method
- Manual Method
Post-installation
Troubleshooting

Overview

The OpenShift Agent-based Installer Helper provides utilities to easily leverage the OpenShift Agent-Based Installer. It supports bare metal, vSphere, and platform=none deployments in SNO/3 Node/HA configurations.

Related ADR: ADR-0012: Deployment Patterns and Configurations

Prerequisites

System Requirements

Base System:
- RHEL system for installation host
- Network access to target nodes

Software Requirements:

# Install required packages
sudo dnf install -y \
 nmstate \
 ansible-core \
 bind-utils \
 libguestfs-tools \
 podman

# Install OpenShift CLI Tools
./download-openshift-cli.sh
sudo cp ./bin/* /usr/local/bin/

# Install Ansible Collections
ansible-galaxy collection install -r playbooks/collections/requirements.yml

Required Files:
- Red Hat OpenShift Pull Secret
- Any additional pull secrets for disconnected registries (if needed)

Installation Methods

Declarative Method

Prepare Configuration:
- Create a directory in examples/ with your cluster configuration
- Add cluster.yml and nodes.yml files based on examples
Generate Installation Media:
```
./hack/create-iso.sh $FOLDER_NAME
```

This will:

Generate templates with Ansible
Create the ISO
Provide next-step instructions

Manual Method

Generate Manifests:

# Navigate to playbooks directory
cd playbooks/

# Create manifests using your configuration
ansible-playbook -e "@your-cluster-vars.yml" create-manifests.yml

Create Installation ISO:

# Generate ISO
openshift-install agent create image --dir ./generated_manifests/<cluster_name>

# Monitor bootstrap process
openshift-install agent wait-for bootstrap-complete --dir ./generated_manifests/<cluster_name>

# Monitor installation
openshift-install agent wait-for install-complete --dir ./generated_manifests/<cluster_name>

Configuration Examples

Basic Cluster Configuration (cluster.yml)

pull_secret_path: ~/ocp-install-pull-secret.json

# Cluster metadata
base_domain: example.com
cluster_name: test-cluster

# Platform configuration
platform_type: baremetal  # Options: baremetal, vsphere, none

# Network configuration
api_vips:
  - 192.168.1.5
app_vips:
  - 192.168.1.6

# Network settings
cluster_network_cidr: 10.128.0.0/14
cluster_network_host_prefix: 23
service_network_cidrs:
  - 172.30.0.0/16
machine_network_cidrs:
  - 192.168.1.0/24
network_type: OVNKubernetes

Node Configuration (nodes.yml)

# Node counts
control_plane_replicas: 3
app_node_replicas: 2

# Node definitions
nodes:
  - hostname: master-0
    role: master
    rootDeviceHints:
      deviceName: /dev/sda
    interfaces:
      - name: enp1s0
        mac_address: "52:54:00:00:00:01"
    networkConfig:
      interfaces:
        - name: enp1s0
          type: ethernet
          state: up
          ipv4:
            enabled: true
            address:
              - ip: 192.168.1.10
                prefix-length: 24

Post-installation

Verify Installation:

# Check cluster status
oc get clusterversion
oc get nodes
oc get co

Configure Additional Features:
- Identity Management
- Storage
- Networking
- Monitoring

Troubleshooting

Common Issues

Installation Failures:
- Check installation logs
- Verify network connectivity
- Review node configurations
Network Issues:
- Verify VIP accessibility
- Check DNS resolution
- Validate network configurations

Diagnostic Commands

# Review bootstrap progress
openshift-install agent wait-for bootstrap-complete --dir ./generated_manifests/<cluster_name> --debug

# Check node status
oc get nodes -o wide

# View cluster operators
oc get co

# Check pod status
oc get pods --all-namespaces

Internal References

ADR References

OpenShift Documentation

Platform-Specific Guides

Red Hat Documentation

Tools and Utilities

Best Practices and Guidelines

Support Matrix

Feature	SNO	3-Node	HA Cluster
Bare Metal	✓	✓	✓
vSphere	✓	✓	✓
Platform None	✓	✓	✓
Bond Networking	✓	✓	✓
VLAN Support	✓	✓	✓
Disconnected	✓	✓	✓

Note: For detailed examples of networking configurations (VLAN, Bond, Bond+VLAN), refer to the Network Configuration Guide.