Skip to content

Init annex: Terraform Cloud

Status: Stable (Public)
Version: 1.0

This annex defines Terraform Cloud specific requirements and outputs for hyops init terraform-cloud.

Global rules are defined in hyops init contract.

1. Config

Default config path:

  • <root>/config/terraform-cloud.conf

Config format is line-oriented KEY=value.

1.1 Required keys

  • TFC_HOST
    Terraform Cloud hostname (default: app.terraform.io).

  • TFC_ORG
    Terraform Cloud organisation name.

1.2 Optional keys

  • WORKSPACE_PREFIX (optional; used for naming conventions)
  • TFC_CREDENTIALS_FILE (default: ~/.terraform.d/credentials.tfrc.json)

2. Vault keys

Default vault path:

  • <root>/vault/bootstrap.vault.env

Secrets used:

  • TFC_TOKEN

Rules:

  • In --non-interactive mode, TFC_TOKEN MUST be present in the vault.
  • In interactive mode, if TFC_TOKEN exists it MUST be validated and reused.

3. Behaviour

3.1 Token validation

When a token is obtained from any source, it MUST be validated against TFC_HOST and TFC_ORG before being accepted for use.

Validation is successful when an authenticated request to the organisation endpoint returns success.

3.2 Interactive token acquisition

In interactive mode, when no valid token is available:

  • terraform login <TFC_HOST> MUST be executed to obtain a token.
  • The token MUST be extracted from TFC_CREDENTIALS_FILE.
  • The token MUST be validated.
  • The token MUST be persisted to the vault as TFC_TOKEN.

3.3 Non-interactive mode

When --non-interactive is set:

  • the vault MUST be decrypted
  • a valid TFC_TOKEN MUST be available
  • terraform login MUST NOT be executed

3.4 Credentials file rendering

After a valid token is available, the Terraform CLI credentials file MUST be present and include the token for TFC_HOST.

Norms:

  • Parent directory MUST be created if missing.
  • File mode MUST be 0600.
  • Existing credentials for other hosts MUST be preserved.

4. Outputs

4.1 Readiness marker

Default path:

  • <root>/meta/terraform-cloud.ready.json

The marker MUST reflect status=ready only when:

  • a valid token is available, and
  • vault persistence (if required) has completed, and
  • the credentials file is written successfully.

4.2 Evidence

Evidence MUST be written under:

  • <root>/logs/init/terraform-cloud/<run_id>/

Evidence MUST NOT include TFC_TOKEN.

5. Failure semantics

  • If --non-interactive is set and TFC_TOKEN is missing or invalid, init MUST fail with exit code 21.
  • If terraform login fails in interactive mode, init MUST fail with exit code 20.
  • If credentials file writing fails, init MUST fail with exit code 30.