Skip to content

Scripts Documentation

This directory contains bash scripts for managing ROSA HCP clusters. The scripts are organized by functionality and can be called directly from CI/CD pipelines or via the Makefile wrapper.

Script Structure

scripts/
├── common.sh              # Shared functions (colors, validation, helpers)
├── validate/              # Pre-deployment prerequisite validation
│   ├── account.sh         # Account, tools, ROSA linking, quotas
│   ├── byo-network.sh     # BYO VPC subnets, tags, endpoints
│   └── prereqs.sh         # Combined validation from cluster tfvars
├── cluster/               # Cluster management scripts
│   ├── init-infrastructure.sh
│   ├── plan-infrastructure.sh
│   ├── apply-infrastructure.sh
│   ├── destroy-infrastructure.sh
│   ├── cleanup-infrastructure.sh
│   └── bootstrap-gitops.sh
├── tunnel/               # Tunnel management scripts
│   ├── start.sh
│   ├── stop.sh
│   └── status.sh
├── utils/                # Utility scripts
│   ├── get-admin-password.sh
│   ├── get-k8s-token.sh
│   ├── get-infra-outputs.sh
│   ├── check-cluster.sh
│   └── get-network-config.sh
├── info/                 # Information scripts
│   ├── show-endpoints.sh
│   ├── show-credentials.sh
│   └── login.sh
└── verify_cluster.py     # Python script to verify cluster deployment and GitOps

Usage

Direct Script Usage

Scripts can be called directly from the command line:

# Initialize infrastructure
./scripts/cluster/init-infrastructure.sh my-cluster

# Plan infrastructure changes
./scripts/cluster/plan-infrastructure.sh my-cluster

# Apply infrastructure
./scripts/cluster/apply-infrastructure.sh my-cluster

Via Makefile

The Makefile provides a convenient wrapper:

# Initialize infrastructure
make cluster.my-cluster.init-infrastructure

# Plan infrastructure
make cluster.my-cluster.plan-infrastructure

# Apply infrastructure
make cluster.my-cluster.apply-infrastructure

# Validate prerequisites (account + VPC when applicable)
make cluster.my-cluster.validate

See Validation in the documentation site for flags and BYO VPC checks.

Script Details

Common Functions (common.sh)

Shared functions used across all scripts:

  • error(), warn(), info(), success() - Colored output functions
  • get_project_root() - Get repository root directory
  • get_cluster_dir() - Validate and return cluster directory path
  • get_terraform_dir() - Get terraform infrastructure directory
  • check_backend_config() - Check for remote backend config
  • check_required_tools() - Verify required tools are installed
  • get_tfvar() - Extract value from terraform.tfvars

Prerequisite Validation (validate/)

  • account.sh: AWS account readiness (tools, credentials, ROSA subscription, quotas)
  • byo-network.sh: VPC DNS, subnets, ROSA tags, endpoints, routes
  • prereqs.sh: Runs account + network checks using cluster terraform.tfvars
make cluster.egress-zero.validate
make cluster.byo-vpc.validate-network

Cluster Management Scripts

Infrastructure Scripts

  • init-infrastructure.sh: Initialize infrastructure Terraform backend
  • plan-infrastructure.sh: Plan infrastructure changes
  • apply-infrastructure.sh: Apply infrastructure changes
  • destroy-infrastructure.sh: Destroy infrastructure (with confirmation)
  • cleanup-infrastructure.sh: Sleep infrastructure (destroy with preserved resources, auto-approve, CI/CD friendly)

GitOps Bootstrap Scripts

  • bootstrap-admin.sh: Create/destroy short-lived HTPasswd bootstrap admin (used by Make bootstrap)
  • bootstrap-gitops.sh: Bootstrap GitOps operator on ROSA HCP cluster using Helm charts

Usage: 

# Via Makefile (recommended) — creates bootstrap admin, runs GitOps, tears admin down
make cluster.<cluster-name>.bootstrap

# Debug mode
DEBUG=true make cluster.<cluster-name>.bootstrap

See cluster/README-bootstrap-gitops.md for standalone usage and env vars.

Output: - Creates values file at clusters/<cluster-dir>/cluster-bootstrap-values.yaml for inspection - Installs OpenShift GitOps operator via Helm charts - Configures ArgoCD instances (cluster-gitops and application-gitops)

Utility Scripts

  • get-admin-password.sh: Get break-glass admin password from the cluster credentials Secrets Manager secret (cluster_credentials_secret_arn → JSON .password)
  • get-k8s-token.sh: Extract Kubernetes token via oc login with retry logic
  • get-infra-outputs.sh: Extract infrastructure outputs and export as TF_VAR_* environment variables
  • check-cluster.sh: Validate cluster directory exists
  • get-network-config.sh: Extract network_type and zero_egress from terraform.tfvars

Tunnel Scripts

  • start.sh: Start sshuttle tunnel (wrapper for existing tunnel-start.sh)
  • stop.sh: Stop sshuttle tunnel (wrapper for existing tunnel-stop.sh)
  • status.sh: Check tunnel status

Info Scripts

  • show-endpoints.sh: Show cluster API and console URLs
  • show-credentials.sh: Show break-glass admin credentials (requires enable_cluster_admin)
  • login.sh: oc login as break-glass admin (validates Terraform outputs; no terraform init)

Environment Variables

Backend Configuration

For remote S3 backend:

export TF_BACKEND_CONFIG_BUCKET="my-terraform-state-bucket"
export TF_BACKEND_CONFIG_REGION="us-east-1"
export TF_BACKEND_CONFIG_DYNAMODB_TABLE="terraform-state-lock"  # Optional

CI/CD Variables

  • AUTO_APPROVE=true: Skip confirmation prompts (used by sleep/cleanup scripts)
  • TF_VAR_k8s_token: Kubernetes token (if not set, script will obtain via oc login)
  • TF_VAR_admin_password_override: Override break-glass admin password when enable_cluster_admin = true (IDP must exist; override alone is not enough)

CI/CD Integration

GitHub Actions Example

name: Deploy Infrastructure

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Initialize infrastructure
        run: ./scripts/cluster/init-infrastructure.sh my-cluster

      - name: Plan infrastructure
        run: ./scripts/cluster/plan-infrastructure.sh my-cluster

      - name: Apply infrastructure
        run: ./scripts/cluster/apply-infrastructure.sh my-cluster

GitLab CI Example

stages:
  - infrastructure

variables:
  CLUSTER_NAME: my-cluster

infrastructure:
  stage: infrastructure
  script:
    - ./scripts/cluster/init-infrastructure.sh $CLUSTER_NAME
    - ./scripts/cluster/plan-infrastructure.sh $CLUSTER_NAME
    - ./scripts/cluster/apply-infrastructure.sh $CLUSTER_NAME

Destroy vs Sleep

  • destroy-*: Shows warnings, prompts for confirmation (interactive). For permanent cluster removal.
  • cleanup-* (used by make sleep): Same as destroy but uses -auto-approve flag (non-interactive). Designed for temporarily shutting down clusters while preserving resources.

Sleep preserves: - DNS domain (if enable_persistent_dns_domain=true) - Admin password in AWS Secrets Manager - IAM roles and OIDC configuration - KMS keys and EFS (if not explicitly destroyed) - GitOps configurations (automatically redeployed when cluster is recreated)

Note: Sleep does NOT hibernate the cluster - it destroys cluster resources. The cluster must be recreated using make apply to "wake" it. Since GitOps manages all important configurations and applications, they will be automatically redeployed.

For CI/CD pipelines, use cleanup-* scripts or set AUTO_APPROVE=true:

AUTO_APPROVE=true ./scripts/cluster/cleanup-infrastructure.sh my-cluster

Error Handling

All scripts use set -euo pipefail for strict error handling: - -e: Exit immediately if a command exits with a non-zero status - -u: Treat unset variables as an error - -o pipefail: Return value of a pipeline is the status of the last command to exit with a non-zero status

Script Standards

All scripts follow these standards:

  • Use set -euo pipefail for error handling
  • Source common.sh for shared functions
  • Validate inputs
  • Provide clear error messages
  • Return appropriate exit codes
  • Be idempotent where possible

Dependencies

Scripts require:

  • terraform - Terraform CLI
  • oc - OpenShift CLI (for cluster access)
  • aws - AWS CLI (for Secrets Manager access)
  • jq - JSON processor (for parsing terraform outputs)
  • sshuttle - VPN tunnel tool (for egress-zero clusters)

Troubleshooting

Script not found

Ensure scripts are executable:

chmod +x scripts/**/*.sh

Permission denied

Check script permissions and ensure you're running from the repository root:

ls -la scripts/cluster/init-infrastructure.sh

Backend configuration errors

Ensure backend environment variables are set correctly:

echo $TF_BACKEND_CONFIG_BUCKET
echo $TF_BACKEND_CONFIG_REGION

Tunnel issues

For egress-zero clusters, ensure:

  1. Bastion is deployed (enable_bastion=true)
  2. SSM agent is online
  3. VPC endpoints are configured
  4. sshuttle is installed

Check tunnel status:

./scripts/tunnel/status.sh my-cluster