Skip to content

Run cloud and on-prem init environment scripts

Purpose: Prepare Azure, GCP, and Proxmox so Terraform/Terragrunt and other tooling can consume consistent *.credentials.tfvars and evidence from the init--env scripts.
Owner: Platform engineering / HybridOps.Studio maintainer
Trigger: Before first Terraform apply in a new environment, after rotating cloud credentials, or after changing Proxmox API tokens.
Impact: Until this completes successfully, Terraform plans/applies may fail or use stale credentials.
Severity: P3 (blocking for new environments, non-urgent once steady-state is reached).
Pre-reqs: Git repo cloned, toolchain installed, Azure/GCP accounts with required privileges, Proxmox API token present.
Rollback strategy:* Rerun the script with corrected config; rotate or revoke generated credentials if a run is misconfigured.

Context

This runbook covers the one-time (and occasionally repeated) bootstrap of cloud and on-prem environments using:

  • init-azure-env.sh
  • init-gcp-env.sh
  • init-proxmox-env.sh

Each script:

  • Validates CLI access (Azure CLI, gcloud, Proxmox API).
  • Writes environment configuration for Terraform into infra/env/*.credentials.tfvars.
  • Emits logs under output/logs/platform/... and human-readable evidence under output/artifacts/platform/....

It does not cover:

  • Terraform/Terragrunt plans or applies.
  • Creating or funding cloud billing accounts.
  • Day-2 lifecycle of service principals or service accounts (use separate security/compliance runbooks).

Preconditions and safety checks

Before running any init script:

  • Repo and branch
  • git status is clean or only has expected local changes.

  • You are on the intended branch (for example main or a feature branch with reviewed changes).

  • Tooling installed

  • From platform repo root: 
    make prereq.check

  • Confirm Azure CLI, gcloud, and Python are listed as installed where required.

  • Azure account

  • You can authenticate interactively with az login.

  • Your account has permission to create and manage a service principal and assign roles in the target subscription.

  • GCP account

  • You can authenticate with gcloud auth login.

  • Your account is Owner (or has equivalent IAM permissions) on the target project.

  • Proxmox

  • infra/env/proxmox.credentials.tfvars (or successor config) exists and contains a valid API token with least-privilege access to required nodes.

  • You can reach the Proxmox API (for example from the control node).

  • Secrets hygiene

  • control/secrets.vault.env exists (or will be created/updated) and is excluded by .gitignore.
  • control/tools/provision/init/.conf/keys.local/ is present or creatable and is excluded by .gitignore.

Steps

1) Verify toolchain and environment

  1. From the platform repository root:
  2. Action: Confirm prerequisites and Python venv.
  3. Command: 
    cd ~/hybridops-studio/hybridops-platform
make prereq.check
  4. Expected result: Azure CLI, gcloud, Terraform, Packer, and Python3 are reported as installed; .venv is present or can be created via make prereq.python.env.
  5. Evidence: Optional screenshot or terminal capture saved under output/artifacts/decision/ if this is part of a formal review.

2) Initialise Azure environment

  1. Run the Azure init script:
  2. Action: Log into Azure (if needed), ensure a bootstrap service principal, and write azure.credentials.tfvars and evidence.
  3. Command: 
    cd ~/hybridops-studio/hybridops-platform
./control/tools/provision/init/init-azure-env.sh
  4. Expected result:
    • Azure CLI opens a login flow if not already authenticated.
    • On success, the script reports:
    • Configuration: infra/env/azure.credentials.tfvars
    • Secrets: control/secrets.vault.env
    • Log: output/logs/platform/cloud/azure/init-env/<timestamp>-init-azure.log

  5. Evidence:

    • Log: output/logs/platform/cloud/azure/init-env/<timestamp>-init-azure.log
    • Proof bundle: output/artifacts/platform/cloud/azure/init-env/<timestamp>/
      (with latest symlink pointing to the most recent successful run).

  6. Sanity-check generated configuration:

  7. Command: 
    sed -n '1,20p' infra/env/azure.credentials.tfvars
  8. Expected result: Subscription, tenant, client ID, client secret, and location fields present and non-empty (secrets remain only in local files, not committed).

3) Initialise GCP environment

  1. Run the GCP init script:
  2. Action: Log into GCP (if needed), ensure a Terraform service account, generate a JSON key, and write gcp.credentials.tfvars.
  3. Command: 
    cd ~/hybridops-studio/hybridops-platform
./control/tools/provision/init/init-gcp-env.sh

  4. Notes:

    • If not authenticated, gcloud auth login --no-launch-browser will print a URL and verification code.
    • Copy the URL into a browser, complete sign-in, then paste the code back into the terminal prompt.
    • Press Ctrl+C to cancel if you need to abort the login.

  5. Expected result:

    • Service account terraform-hybridops@<project>.iam.gserviceaccount.com exists (or is confirmed).
    • A credentials JSON is written to:
    • control/tools/provision/init/.conf/keys.local/terraform-hybridops.json
    • The script reports:
    • Configuration: infra/env/gcp.credentials.tfvars
    • Log: output/logs/platform/cloud/gcp/init-env/<timestamp>-init-gcp.log

  6. Evidence:

    • Log: output/logs/platform/cloud/gcp/init-env/<timestamp>-init-gcp.log
    • Proof bundle: output/artifacts/platform/cloud/gcp/init-env/<timestamp>/
      (with latest symlink for the most recent successful run).

  7. Sanity-check generated configuration and key file:

  8. Command: 
    sed -n '1,20p' infra/env/gcp.credentials.tfvars
ls -l control/tools/provision/init/.conf/keys.local/
  9. Expected result:
    • project_id, region, and credentials_file entries present.
    • JSON key file exists with appropriate permissions (for example 600).

4) Initialise Proxmox environment

  1. Run the Proxmox init script:
  2. Action: Validate API connectivity, discover nodes/storage, and generate Proxmox env configuration and evidence.
  3. Command: 
    cd ~/hybridops-studio/hybridops-platform
./control/tools/provision/init/init-proxmox-env.sh
  4. Expected result:
    • Script completes without error.
    • Proxmox-specific env/config files under infra/env/ are updated or confirmed.
    • Log is written under:
    • output/logs/platform/onprem/proxmox/init-env/<timestamp>-init-proxmox.log

  5. Evidence:

    • Proof bundle under:
    • output/artifacts/platform/onprem/proxmox/init-env/<timestamp>/
      (with latest symlink pointing at the latest successful run).

  6. Sanity-check Proxmox discovery output:

  7. Command: 
    sed -n '1,40p' infra/env/proxmox.credentials.tfvars 2>/dev/null || echo "Using new Proxmox env format; see infra/env/ for details."
  8. Expected result: Node and storage settings match the intended Proxmox cluster (no hard-coded test values).

Verification

To confirm the init scripts completed successfully:

  • Terraform env files exist and are non-empty
  • infra/env/azure.credentials.tfvars
  • infra/env/gcp.credentials.tfvars

  • Proxmox env files under infra/env/

  • Evidence locations are populated

  • Azure:
    • output/logs/platform/cloud/azure/init-env/latest-init-azure.log (via symlink)
    • output/artifacts/platform/cloud/azure/init-env/latest/
  • GCP:
    • output/logs/platform/cloud/gcp/init-env/latest-init-gcp.log (via symlink)
    • output/artifacts/platform/cloud/gcp/init-env/latest/

  • Proxmox:

    • output/logs/platform/onprem/proxmox/init-env/latest-init-proxmox.log (naming may vary)
    • output/artifacts/platform/onprem/proxmox/init-env/latest/

  • Dry-run a Terraform/Terragrunt call (optional but recommended)

  • From a small stack (for example a dev or sandbox layer), run terragrunt plan or terraform plan and confirm:
    • Backend initialises cleanly.
    • No authentication or permission errors for Azure, GCP, or Proxmox.

Post-actions and clean-up

  • Secrets and credentials
  • Confirm .gitignore correctly excludes:
    • control/secrets.vault.env
    • control/tools/provision/init/.conf/keys.local/

  • Store any exported keys or *.credentials.tfvars snapshots only in approved, encrypted locations.

  • Cloud sessions

  • Optionally sign out of interactive sessions after confirming init evidence: 

    az logout
gcloud auth revoke --all

  • Documentation and tickets

  • If this run was part of a change or onboarding task, attach:
    • Paths to the latest evidence bundles for Azure, GCP, and Proxmox.
    • A note confirming Terraform/Terragrunt plan completed successfully against at least one stack.

References