# ibm/ansible-openshift-provisioning architecture

> Architecture diagram of the GitHub repository ibm/ansible-openshift-provisioning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibm/ansible-openshift-provisioning
- Repository: https://github.com/ibm/ansible-openshift-provisioning

## Overview

##### Project type and purpose
- This is an open-source Ansible automation tool for provisioning OpenShift clusters on KVM and IBM zSystems/LinuxONE.
- It orchestrates virtual machines (LPARs, KVM guests), network services (DNS, HTTPD, HAProxy), and OpenShift installer workflows (bootstrapping, agent-based install, HCP integration).

##### File structure
- Top-level:
- playbooks/ – contains orchestration entry points (0_setup, create_lpar, create_kvm_host, site.yaml, etc.)
- roles/ – implements reusable actions (create_bastion, boot_LPAR, download_ocp_installer, haproxy, dns, etc.)
- inventories/ – host/inventory definitions, group_vars & host_vars templates
- collections/ – bundled Ansible collections (posix, community, IBM zhmc)
- docs/ – markdown documentation and images
- ansible.cfg, mkdocs.yaml, .github/ – configuration for linting, CI, documentation
- Patterns:
- IaC (Infrastructure as Code) using Ansible roles & playbooks
- Inventory-driven execution
- Modular roles organized by function (compute, network, storage, cluster install)
- Use of Jinja2 templates (.j2) for dynamic config files

##### Insights from README
- Purpose: automate OpenShift v4.x provisioning for multi-architecture (s390x, multi) on IBM platforms
- Key features: FIPS support, zVM Hipersocket for Hosted Control Plane (HCP), LPAR & KVM compute nodes
- Deprecation: openvpn, RHEL8

##### Components
a. Main components
- Ansible Control Node: the central orchestrator with playbooks, roles, collections, inventory
- Inventory Store: static/dynamic host definitions (LPAR hosts, KVM hosts, bastion, bootstrap, control-plane, compute)
- Virtualization Hosts: IBM zSystems LPAR manager, KVM hypervisor hosts
- Network Services: DNS server, HTTPD/mirror, HAProxy load balancer
- OpenShift Installer: external binaries/artifacts (downloaded via roles/get_ocp, download_rootfs)
- OpenShift Cluster: bootstrap node, control-plane nodes, compute nodes, agent service configs
- Hosted Control Plane (HCP) services (optional): InfraEnv namespace, agent namespace on HCP
b. Relationships and interactions
- Control Node → (SSH) → Virtualization Hosts & Bastion: run playbooks/roles to provision VMs
- Control Node → Inventory: read host groups & variables
- Control Node → External Repos: download installer binaries, container images, rootfs
- Control Node → DNS/HTTPD/HAProxy: configure and deploy services via templates
- Virtualization Hosts → VM guest network: connect to DNS, HTTPd, HAProxy
- Bootstrap & Agent VMs → Pull OpenShift installer → Communicate with Control Node during install
- HCP integration: Control Node posts agent configs to HCP API, monitors agent states
c. Architectural patterns and principles
- Infrastructure as Code (Idempotent, declarative)
- Modular & reusable roles
- Inventory-driven, group-vars/host-vars separation
- Template-based configuration
- Sequential orchestration: setup → create infra → bootstrap cluster → wait for completion → cleanup
d. Key technologies/frameworks
- Ansible Engine & Collections
- QEMU/KVM & IBM zhmc modules
- OpenShift Installer (ocp versions)
- Jinja2 templates for configs
- mkdocs for documentation, GitHub Actions for CI/lint

##### Detail and essential elements
- Break playbooks into phases: setup, create VM, configure network, deploy services, install cluster, verify, teardown
- Roles as sub-components of Ansible Control Node or group them by function
- Inventory groups (default, hcp, disconnected, abi) and key group_vars influencing flow
- Do not clutter with every single role; instead cluster similar roles (e.g., “LPAR provisioning,” “KVM provisioning,” “Cluster config,” “Network config,” “HCP integration”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Ansible Control Node
    subgraph "Ansible Control Node" 
        direction TB
        ACN_Playbooks["Playbooks"]:::control
        ACN_Roles["Roles"]:::control
        ACN_Collections["Collections"]:::control
        ACN_Config["ansible.cfg & .github"]:::control
    end

    %% Inventory Store
    Inventory["Inventory Store"]:::control

    %% Virtualization Hosts
    subgraph "Virtualization Hosts" 
        direction TB
        LPAR["IBM zSystems LPAR"]:::compute
        KVM["KVM Hypervisor"]:::compute
    end

    %% Network Services
    subgraph "Network Services"
        direction TB
        DNS["DNS Server"]:::network
        HTTPD["HTTPD / Mirror"]:::network
        HAProxy["HAProxy"]:::network
    end

    %% OpenShift Installer Artifacts
    Installer["OpenShift Installer Artifacts"]:::external

    %% OpenShift Cluster
    subgraph "OpenShift Cluster"
        direction TB
        Bootstrap["Bootstrap Node"]:::compute
        ControlPlane["Control-Plane Nodes"]:::compute
        ComputeNodes["Compute Nodes"]:::compute
        Agent["Agent Service"]:::compute
    end

    %% Hosted Control Plane
    HCP["Hosted Control Plane (HCP) API"]:::external

    %% Connections from Control Node
    ACN_Playbooks -->|"reads variables"| Inventory
    ACN_Playbooks -->|"executes roles"| LPAR
    ACN_Playbooks -->|"executes roles"| KVM
    ACN_Playbooks -->|"configures"| DNS
    ACN_Playbooks -->|"configures"| HTTPD
    ACN_Playbooks -->|"configures"| HAProxy
    ACN_Roles -->|"downloads binaries"| Installer
    ACN_Roles -->|"provisions cluster"| Bootstrap
    ACN_Roles -->|"provisions cluster"| ControlPlane
    ACN_Roles -->|"provisions cluster"| ComputeNodes
    ACN_Roles -->|"manages agents"| Agent
    ACN_Roles -->|"calls API"| HCP

    %% Virtualization Hosts to Network
    LPAR -->|"DNS/HTTP/HAProxy"| DNS
    LPAR --> DNS
    KVM --> DNS
    Bootstrap --> DNS
    Bootstrap --> HTTPD
    Bootstrap --> HAProxy

    %% Click Events - Ansible Control Node
    click ACN_Playbooks "https://github.com/ibm/ansible-openshift-provisioning/tree/main/playbooks/"
    click ACN_Roles "https://github.com/ibm/ansible-openshift-provisioning/tree/main/roles/"
    click ACN_Collections "https://github.com/ibm/ansible-openshift-provisioning/tree/main/collections/"
    click ACN_Config "https://github.com/ibm/ansible-openshift-provisioning/blob/main/ansible.cfg"

    %% Click Events - Inventory
    click Inventory "https://github.com/ibm/ansible-openshift-provisioning/tree/main/inventories/default/hosts"

    %% Click Events - Virtualization Hosts LPAR
    click LPAR "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/create_lpar/tasks/main.yaml"
    click LPAR "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/boot_LPAR/tasks/main.yaml"
    click LPAR "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/boot_zvm_nodes/tasks/main.yaml"
    click LPAR "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/boot_zvm_nodes/templates/boot_nodes.py"

    %% Click Events - Virtualization Hosts KVM
    click KVM "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/create_kvm_host/tasks/main.yaml"
    click KVM "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/create_kvm_host/templates/hmccreds.yaml.j2"
    click KVM "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/cleanup_kvm/tasks/main.yaml"
    click KVM "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/prep_kvm_guests/tasks/main.yaml"

    %% Click Events - Network Services DNS
    click DNS "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/dns/tasks/main.yaml"
    click DNS "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/dns/tasks/initial-resolv.yaml"
    click DNS "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/dns/templates/dns-named.conf.j2"
    click DNS "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/dns/templates/dns.db.j2"
    click DNS "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/dns/templates/dns.rev.j2"
    click DNS "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/dns/templates/resolv.conf.j2"

    %% Click Events - Network Services HTTPD
    click HTTPD "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/httpd/tasks/main.yaml"

    %% Click Events - Network Services HAProxy
    click HAProxy "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/haproxy/tasks/main.yaml"
    click HAProxy "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/haproxy/templates/haproxy.cfg.j2"
    click HAProxy "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/haproxy_update/tasks/main.yaml"

    %% Click Events - OpenShift Installer Artifacts
    click Installer "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/download_ocp_installer/tasks/main.yaml"
    click Installer "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/get_ocp/tasks/main.yaml"
    click Installer "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/get_ocp/templates/install-config.yaml.j2"
    click Installer "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/download_rootfs_hcp/tasks/main.yaml"

    %% Click Events - OpenShift Cluster Provisioning
    click Bootstrap "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/create_bootstrap/tasks/main.yaml"
    click ControlPlane "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/create_control_nodes/tasks/main.yaml"
    click ComputeNodes "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/create_compute_nodes/tasks/main.yaml"
    click Agent "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/create_agent/tasks/main.yml"
    click Agent "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/prepare_configs/templates/agent-config.yaml.j2"
    click Agent "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/prepare_configs/templates/install-config.yaml.j2"
    click Agent "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/wait_for_bootstrap/tasks/main.yaml"
    click Agent "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/wait_for_install_complete/tasks/main.yaml"
    click Agent "https://github.com/ibm/ansible-openshift-provisioning/blob/main/playbooks/create_agents_and_wait_for_install_complete.yaml"
    click Agent "https://github.com/ibm/ansible-openshift-provisioning/blob/main/playbooks/create_abi_cluster.yaml"
    click Agent "https://github.com/ibm/ansible-openshift-provisioning/blob/main/playbooks/create_hosted_cluster.yaml"

    %% Click Events - HCP
    click HCP "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/create_hcp_InfraEnv/tasks/main.yaml"
    click HCP "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/create_hcp_InfraEnv/templates/InfraEnv.yaml.j2"
    click HCP "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/create_agentserviceconfig_hcp/tasks/main.yaml"
    click HCP "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/create_agentserviceconfig_hcp/templates/agent_service_config.yaml.j2"
    click HCP "https://github.com/ibm/ansible-openshift-provisioning/blob/main/roles/add_hc_workers_to_haproxy_hcp/tasks/main.yaml"
    click HCP "https://github.com/ibm/ansible-openshift-provisioning/blob/main/playbooks/hcp.yaml"
    click HCP "https://github.com/ibm/ansible-openshift-provisioning/blob/main/playbooks/setup_for_hcp.yaml"

    %% Styles
    classDef control fill:#cce5ff,stroke:#004085,color:#004085;
    classDef compute fill:#d4edda,stroke:#155724,color:#155724;
    classDef network fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#1b1e21,color:#1b1e21;
```
