Skip to content

GitOps Bootstrap Script

This script bootstraps the OpenShift GitOps operator on a ROSA HCP cluster using Helm charts. It is idempotent and can be run multiple times safely.

Features

  • Idempotent: Can be run multiple times safely - checks for existing resources before creating
  • Standalone: Can be run independently or via Makefile / Terraform outputs
  • Environment Variable Based: All configuration via environment variables
  • ACM Support: Supports hub, spoke, and standalone cluster modes
  • Short-lived bootstrap login: Prefer BOOTSTRAP_USERNAME / BOOTSTRAP_PASSWORD / CLUSTER_API_URL from bootstrap-admin.sh (created by make cluster.<name>.bootstrap). Break-glass Secrets Manager credentials are optional and not used for primary hub/standalone bootstrap.

Prerequisites

  • oc CLI installed and in PATH
  • helm CLI installed and in PATH
  • jq installed (for JSON parsing)
  • aws CLI installed and configured (spoke mode / optional break-glass secret)
  • Cluster must be in ready state

Usage

make cluster.<name>.bootstrap

This:

  1. Writes Helm values from Terraform outputs
  2. Creates a short-lived HTPasswd bootstrap admin (bootstrap-admin.sh create)
  3. Runs this script with BOOTSTRAP_* env vars
  4. Always tears down the bootstrap admin afterward

Standalone Execution

The bootstrap script requires a values file generated by Terraform. Prefer the Makefile path above. Manual flow:

cd terraform

CLUSTER_DIR="public"  # Your cluster directory (clusters/<name>/)
mkdir -p "../clusters/$CLUSTER_DIR"
ACM_MODE=$(terraform output -raw gitops_bootstrap_acm_mode)
if [ "$ACM_MODE" = "spoke" ]; then
  terraform output -raw gitops_bootstrap_spoke_values
else
  terraform output -raw gitops_bootstrap_hub_values
fi > "../clusters/$CLUSTER_DIR/cluster-bootstrap-values.yaml"
export BOOTSTRAP_VALUES_FILE="$PWD/../clusters/$CLUSTER_DIR/cluster-bootstrap-values.yaml"
eval "$(terraform output -raw gitops_bootstrap_env_exports)"

# Create short-lived bootstrap admin and export BOOTSTRAP_* / CLUSTER_API_URL
eval "$(../scripts/cluster/bootstrap-admin.sh "$CLUSTER_DIR" create)"

"$(terraform output -raw gitops_bootstrap_script_path)"
GITOPS_RC=$?

../scripts/cluster/bootstrap-admin.sh "$CLUSTER_DIR" destroy || true
exit "$GITOPS_RC"

Optional: Secrets Manager login

If BOOTSTRAP_USERNAME / BOOTSTRAP_PASSWORD / CLUSTER_API_URL are unset, the script can fall back to a Secrets Manager secret named in CREDENTIALS_SECRET (break-glass or hub credentials). Spoke mode still uses HUB_CREDENTIALS_SECRET for the hub.

export CLUSTER_NAME="my-cluster"
export CREDENTIALS_SECRET="my-cluster-credentials"   # optional fallback
export AWS_REGION="us-east-1"
export ACM_MODE="noacm"  # or "hub" or "spoke"
export BOOTSTRAP_VALUES_FILE="/path/to/clusters/my-cluster/cluster-bootstrap-values.yaml"

./scripts/cluster/bootstrap-gitops.sh

Environment Variables

Required Variables

Variable Description Example
CLUSTER_NAME Name of the ROSA HCP cluster my-cluster
AWS_REGION AWS region where the cluster is located us-east-1
BOOTSTRAP_VALUES_FILE Path to Helm values file (from Terraform bootstrap values outputs) clusters/my-cluster/cluster-bootstrap-values.yaml

Login credentials (one of)

Variable Description
BOOTSTRAP_USERNAME, BOOTSTRAP_PASSWORD, CLUSTER_API_URL Short-lived bootstrap admin (preferred; set by bootstrap-admin.sh create)
CREDENTIALS_SECRET AWS Secrets Manager secret name for break-glass / fallback login JSON

ACM Configuration

Variable Description Default Required When
ACM_MODE ACM mode: hub, spoke, or noacm noacm Always
HUB_CREDENTIALS_SECRET Hub cluster credentials secret name - ACM_MODE=spoke
ACM_REGION AWS region where ACM hub is located - ACM_MODE=spoke

Helm Chart Configuration

Variable Description Default
HELM_REPO_NAME Name for Helm repository helm_repo_new
HELM_REPO_URL Helm repository URL https://rh-mobb.github.io/validated-pattern-helm-charts/
HELM_CHART Helm chart name (hub/standalone) cluster-bootstrap
HELM_CHART_VERSION Helm chart version 0.5.19

ACM Spoke Helm Charts

Variable Description Default
HELM_CHART_ACM_SPOKE ACM spoke chart name cluster-bootstrap-acm-spoke
HELM_CHART_ACM_SPOKE_VERSION ACM spoke chart version 0.6.14
HELM_CHART_ACM_HUB_REGISTRATION Hub registration chart name cluster-bootstrap-acm-hub-registration
HELM_CHART_ACM_HUB_REGISTRATION_VERSION Hub registration chart version 0.2.2
HELM_CHART_AWSPCA AWS Private CA Issuer chart name aws-privateca-issuer
HELM_CHART_AWSPCA_VERSION AWS Private CA Issuer chart version 1.6.1

See script source and Terraform outputs for additional optional variables.

What the script does

Hub / standalone (ACM_MODE=hub or noacm)

  1. Logs into the cluster (bootstrap env or credentials secret)
  2. Waits for worker nodes to be Ready
  3. Installs the cluster-bootstrap Helm chart
  4. Waits for Argo CD instances

ACM Spoke (ACM_MODE=spoke)

  1. Logs into spoke cluster
  2. Installs cluster-bootstrap-acm-spoke Helm chart on spoke
  3. Logs into hub cluster (HUB_CREDENTIALS_SECRET)
  4. Installs hub registration chart
  5. Retrieves ACM import manifests
  6. Applies ACM CRDs and import manifest to spoke
  7. Verifies ArgoCD integration

Cleanup

To cleanup resources, set ENABLE=false:

export ENABLE="false"
export CLUSTER_NAME="my-cluster"
export AWS_REGION="us-east-1"
export ACM_MODE="spoke"  # If cleaning up spoke cluster
export HUB_CREDENTIALS_SECRET="hub-credentials"
export ACM_REGION="us-east-1"
export BOOTSTRAP_VALUES_FILE="/path/to/cluster-bootstrap-values.yaml"
# Login: BOOTSTRAP_* or CREDENTIALS_SECRET

./scripts/cluster/bootstrap-gitops.sh

Error Handling

  • Validation: Validates required environment variables before execution
  • Retry Logic: Polls cluster login until HTPasswd propagates (override with BOOTSTRAP_LOGIN_MAX_ATTEMPTS / BOOTSTRAP_LOGIN_SLEEP)
  • Error Messages: Provides clear error messages with line numbers
  • Exit Codes: Returns JSON status for programmatic use

Output

  • Success: {"status": "success", "message": "..."}
  • Failure: {"status": "failure", "message": "..."}

Troubleshooting

Cluster Login Fails

  • Prefer Makefile bootstrap so bootstrap-admin.sh creates a fresh IDP/user
  • Wait for HTPasswd propagation (login is polled automatically)
  • Verify cluster is ready: rosa describe cluster -c ${CLUSTER_NAME}
  • If using CREDENTIALS_SECRET, confirm enable_cluster_admin = true and the secret format

Helm Install Fails

  • Confirm BOOTSTRAP_VALUES_FILE exists and matches Terraform outputs
  • Confirm Helm repo URL is reachable from your network
  • Ensure enough worker nodes are Ready before install
  • Authentication — break-glass vs bootstrap
  • scripts/cluster/bootstrap-admin.sh — short-lived HTPasswd lifecycle
  • modules/infrastructure/htpasswd-idp/ — shared IDP module