Skip to content

Standardise environment bootstrap scripts for cloud and Proxmox credentials

Status

Accepted — Provider bootstrap is implemented as a small set of scripts that standardise how runtime inputs are generated for Azure, GCP, Proxmox, and Terraform Cloud.

1. Context

HybridOps.Studio spans multiple providers and control planes:

  • Azure and GCP for cloud resources.
  • Proxmox for on-prem compute.
  • Terraform Cloud as a remote state and policy backend.

Each provider exposes distinct identity models (service principals, service accounts, API tokens, user tokens) and CLI authentication flows.

Without standardisation:

  • Credential sourcing drifts across stacks and operators.
  • Bootstrap steps are difficult to reproduce and evidence.
  • Local workflows risk leaking secrets into committed files.

A consistent, automatable, and evidence-backed bootstrap layer is required to:

  • Acquire the minimum provider credentials and metadata needed for provisioning.
  • Produce deterministic tfvars inputs for Terraform/Terragrunt and Packer.
  • Capture logs and redacted artefacts for reviews and drills.

2. Decision

Bootstrap is standardised under control/tools/provision/init/:

  • Azure: init-azure-env.sh
  • GCP: gcp/init-gcp-bootstrap.sh (interactive) and gcp/init-gcp-ci.sh (non-interactive validation)
  • Proxmox: init-proxmox-env.sh
  • Terraform Cloud: init-tfc-env.sh

Each bootstrap script:

  • Reads non-secret configuration from control/tools/provision/init/.conf/.
  • Uses provider CLIs (az, gcloud, ssh/scp, terraform) to discover or create bootstrap identities.
  • Writes provider tfvars under infra/env/.
  • Emits logs and redacted artefacts under output/logs/ and output/artifacts/.

3. Conventions

3.1 Configuration and secrets

  • Non-secret wiring: control/tools/provision/init/.conf/*.conf
  • Local secrets caches and tokens:
  • control/secrets.vault.env where required by bootstrap tooling
  • Terraform Cloud credentials: ~/.terraform.d/credentials.tfrc.json
  • GCP ADC files under ~/.config/gcloud/

This ADR does not change the primary secrets strategy in ADR-0020 and ADR-0003. Bootstrap artefacts are connectivity inputs and must not become a source of truth for application secrets.

3.2 Runtime inputs

  • Azure: infra/env/azure.credentials.tfvars
  • GCP: infra/env/gcp.credentials.tfvars (impersonation inputs)
  • Proxmox: infra/env/proxmox.credentials.tfvars
  • Terraform Cloud: local credentials file plus optional TFC_TOKEN in control/secrets.vault.env

All files under infra/env/ are sensitive and uncommitted.

3.3 Evidence

  • Logs: output/logs/**/init-*/
  • Redacted artefacts: output/artifacts/**/init-*/ (with latest symlink)

4. Provider model

4.1 Azure

  • Identity: Terraform bootstrap service principal.
  • Output: infra/env/azure.credentials.tfvars.
  • Persistence: bootstrap SP values cached in control/secrets.vault.env for reuse where applicable.

4.2 GCP

  • Bootstrap (interactive): gcloud user login and ADC are used to run the project-factory stack and discover the Terraform runtime service account.
  • Runtime: Terraform uses service-account impersonation (no JSON key required for the Terraform runtime identity).
  • CI runner (optional): a dedicated CI runner service account may be created to authenticate non-interactively and impersonate the Terraform runtime service account.

4.3 Proxmox

  • Identity: Proxmox API token for automation user.
  • Output: infra/env/proxmox.credentials.tfvars.
  • Persistence: token secret cached in control/secrets.vault.env when generated.

4.4 Hetzner

init-hetzner-env.sh bootstraps credentials for the Hetzner Cloud hcloud Terraform provider.

  • Reads non-secret defaults from .conf/hetzner.conf.
  • Writes infra/env/hetzner.credentials.tfvars.
  • Writes logs and redacted artefacts under output/logs/platform/cloud/hetzner/init-env/ and output/artifacts/platform/cloud/hetzner/init-env/.

The token is provided out-of-band and is treated as non-rotatable until explicitly replaced.

4.5 Terraform Cloud

  • Identity: user token validated against Terraform Cloud API.
  • Output: ~/.terraform.d/credentials.tfrc.json plus optional TFC_TOKEN cache in control/secrets.vault.env.

5. Rationale

  • Consistent provider bootstrap reduces drift across stacks and operators.
  • Provider CLI flows are captured once, rather than repeated per stack or per pipeline.
  • Evidence generation supports reviewer verification and operational drills.
  • Separation of concerns keeps modules focused on infrastructure, with bootstrap handled by a dedicated layer.

6. Consequences

6.1 Benefits

  • Standardised bootstrap across providers and environments.
  • Predictable tfvars layout for Terraform/Terragrunt and Packer.
  • Reduced pipeline complexity by treating bootstrap as a reusable prerequisite step.
  • Improved auditability via logs and redacted artefacts.

6.2 Risks

  • Provider CLI/API changes may require script maintenance.
  • First-run bootstrap remains interactive for some providers and must be executed on an operator workstation.
  • Repository layout coupling increases the cost of future path changes.

7. Validation

  • Bootstrap scripts are re-runnable without unexpected prompts when valid credentials exist.
  • Terraform/Terragrunt plans execute using the expected identities per provider.
  • Evidence directories include timestamped runs and redacted tfvars/logs suitable for review.

8. References

  • ADR-0020: ./ADR-0020_secrets-strategy_akv-now_sops-fallback_vault-later.md
  • ADR-0003: ./ADR-0003-secrets-management-strategy-for-hybrid-kubernetes-and-platform-workloads.md
  • Runbook: ../ops/runbooks/platform/runbook-init-cloud-and-proxmox-env.md
  • HOWTO: ../howto/HOWTO_init_environment_bootstrap.md