Bare-metal OpenShift fleet with ACM GitOps

This repository scaffolds bare-metal managed-cluster provisioning from a Red Hat Advanced Cluster Management (ACM) hub. It follows the current ACM 2.17 and OpenShift Container Platform 4.22 flow:

1. Argo CD synchronizes a ClusterInstance and its namespace from Git.
2. The ACM SiteConfig Operator renders the supported Assisted Installer resources from ai-cluster-templates-v1 and ai-node-templates-v1.
3. The Assisted Installer provisions OpenShift on the bare-metal hosts.
4. ACM imports and manages the resulting cluster.

The legacy SiteConfig Kustomize generator is intentionally not used.

For a physically disconnected deployment, follow the separate air-gap runbook. The air-gap path adds content transfer, internal registry/Git configuration, RHCOS hosting, and offline verification.

Repository layout

bootstrap/
  argocd/                 Argo CD project, application, and controller RBAC
  enable-siteconfig.sh    Idempotently enable the ACM SiteConfig component
clusters/
  kustomization.yaml      Live fleet root watched by Argo CD (initially empty)
examples/
  sno/                    Copyable single-node OpenShift example
  ha-3-node/              Copyable compact three-control-plane example
docs/
  acm-2.17-analysis.md    Version analysis, prerequisites, and operations
scripts/
  preflight-airgap.sh     Air-gap-specific hub and endpoint checks
  preflight-hub.sh        Read-only hub capability and image-set checks
  validate.sh             Local render and consistency checks

Prerequisites

• An OpenShift hub supported by ACM 2.17, with ACM installed.

• Red Hat OpenShift GitOps installed in openshift-gitops.

• DNS, NTP, routable provisioning/management networking, and BMC access from the hub.

• A ClusterImageSet for the requested OpenShift release:

  oc get clusterimagesets.hive.openshift.io

• A pull secret and one BMC credential secret per host in the target cluster namespace. Never commit plaintext credentials.

• The ACM central infrastructure management service enabled, represented by the AgentServiceConfig/agent resource.

• Hub access to this Git repository. Configure Argo CD repository credentials separately when the repository is private.

Read the ACM analysis before provisioning.

Bootstrap the hub

Log in to the hub as a cluster administrator, then run:

./bootstrap/enable-siteconfig.sh
oc apply -k bootstrap/argocd
IMAGE_SET=openshift-4.22 ./scripts/preflight-hub.sh

Verify the component and its default Assisted Installer templates:

oc -n open-cluster-management get pods | grep siteconfig
oc -n open-cluster-management get configmap \
  ai-cluster-templates-v1 ai-node-templates-v1

The Argo CD application points at this repository's main branch and the clusters/ directory.

Add a managed cluster

Copy the topology closest to the intended cluster:

cp -R examples/ha-3-node clusters/site-a

Edit every value marked REPLACE_ME and all example IP, MAC, hostname, BMC, disk, DNS, NTP, and image-set values. Keep metadata.namespace, spec.clusterName, and the namespace resource name identical.

Provision credentials using your approved secret system. The example credential files are documentation only and are not included by Kustomize. For a one-time lab bootstrap, secrets can be created directly on the hub:

oc create namespace site-a
oc -n site-a create secret generic assisted-deployment-pull-secret \
  --type=kubernetes.io/dockerconfigjson \
  --from-file=.dockerconfigjson=/secure/path/pull-secret.json
oc -n site-a create secret generic node-0-bmc-secret \
  --from-literal=username="$BMC_USER" --from-literal=password="$BMC_PASSWORD"

Add the site to clusters/kustomization.yaml:

resources:
  - site-a

Validate and commit while spec.holdInstallation: true:

./scripts/validate.sh
oc apply --dry-run=server -k clusters
git add clusters
git commit -m "Add site-a bare-metal cluster"
git push

After Argo CD is synced, confirm that the ClusterInstance validates and that all secrets, image sets, network settings, and hardware identifiers are correct. Then change holdInstallation to false in a separate reviewed commit.

Destructive behavior: removing a live site from clusters/kustomization.yaml is pruned by Argo CD. Deleting its ClusterInstance starts deprovisioning. Use a pull-request approval rule for all changes under clusters/. Cluster namespaces are deliberately annotated with Prune=false; delete a namespace and its credentials manually only after deprovisioning and finalizer cleanup have completed.

What remains environment-specific

This scaffold cannot safely invent the following:

• supported hub/managed OpenShift version combination for your subscription;
• exact release image pullspec and ClusterImageSet;
• connected, proxy, or disconnected registry configuration and CA bundles;
• DNS records for api.<cluster>.<baseDomain> and *.apps.<cluster>.<baseDomain>;
• API/Ingress VIP ownership, routing, firewall rules, and BMC reachability;
• vendor-specific BMC URI/system path, TLS policy, firmware, and boot behavior;
• stable installation-disk identifiers and hardware sizing;
• production secret delivery such as External Secrets, Vault, or SOPS;
• Argo CD credentials for a private Git repository;
• Day 0 extra manifests and Day 2 ACM PolicyGenerator policies.

The repository is therefore a production-oriented baseline, not a site-complete deployment until these inputs are supplied and reviewed.

Observe provisioning

oc get clusterinstances.siteconfig.open-cluster-management.io -A
oc -n site-a get clusterinstance site-a -o yaml
oc -n site-a get agentclusterinstall,clusterdeployment,infraenv,bmh,nmstateconfig
oc get managedcluster site-a

The useful ClusterInstance conditions progress through validation, rendered template validation/application, provisioning, and installation completion.