Skip to content

Init annex: GCP

Status: Stable (Public) Version: 1.2

This annex defines the GCP-specific inputs, validation and outputs for hyops init gcp. Global behaviour is defined by the hyops init contract.

1. Configuration

Default path:

  • <root>/config/gcp.conf

The file uses line-oriented KEY=value entries.

1.1 Required values

  • GCP_PROJECT_ID Project used for the environment.
  • GCP_REGION Default region for regional resources.

1.2 Optional values

  • GCP_ZONE Default zone for zonal resources. Interactive initialization lists available zones in the selected region.
  • GCP_BILLING_ACCOUNT_ID Billing account used when initialization creates a project.
  • GCP_RUNTIME_SA_EMAIL Delegated runtime identity. Existing projects may use validated direct credentials when this value is absent.
  • GCP_QUOTA_PROJECT_ID Project used for credential quota attribution.
  • GCP_CREDENTIALS_OUT Override for the protected runtime-credentials output path.
  • GCP_SSH_PUBLIC_KEY Public key written to readiness metadata for VM bootstrap. When absent, initialization SHOULD look for ~/.ssh/id_ed25519.pub and ~/.ssh/id_rsa.pub. An interactive run SHOULD create ~/.ssh/id_ed25519 automatically when no public key exists.

Names used before v0.1.3 remain accepted as compatibility aliases but MUST NOT be written into new configuration templates.

2. Interactive behaviour

With --with-cli-login, initialization MAY:

  • obtain or refresh the selected Google identity and application authorization;
  • list accessible projects;
  • accept a project by number, project ID or unique project name;
  • create a project when the requested ID is available and an open billing account has been selected;
  • list open billing accounts when project creation requires one;
  • list available zones in the selected region;
  • generate ~/.ssh/id_ed25519 when no public key exists.

An existing project does not require a billing-account selection. A new project MUST NOT be created without an open billing account.

Automatic key generation MUST NOT overwrite an existing private or public key. Non-interactive initialization MUST NOT generate a key. Callers that need VM bootstrap access SHOULD provide --ssh-public-key, set GCP_SSH_PUBLIC_KEY, or create the key before initialization.

When --force is used, stored project, region, zone and billing values MUST be reviewed and revalidated before the readiness marker is replaced.

If interactive input or authorization is required but unavailable, initialization MUST fail with guidance.

3. Non-interactive behaviour

With --non-interactive, initialization MUST NOT prompt. It MUST validate:

  • GCP support is installed;
  • application authorization is available;
  • the configured project is accessible;
  • GCP_RUNTIME_SA_EMAIL is set and delegated access succeeds;
  • required project, region and zone values are present.

4. Validation

Initialization MUST confirm that:

  • the selected identity is usable;
  • the project is accessible or has been created successfully;
  • billing is enabled for a ready project;
  • the selected region and zone are valid;
  • delegated access works when GCP_RUNTIME_SA_EMAIL is configured;
  • the credentials file can be written with mode 0600.

Direct credentials MAY be used for an accessible existing project when no delegated runtime identity is configured. Governed environments MAY require a delegated identity through operating policy.

5. Outputs

5.1 Protected runtime credentials

Default path:

  • <root>/credentials/gcp.credentials.tfvars

The file MUST use mode 0600 and include:

  • project_id;
  • region;
  • impersonate_service_account, which may be empty for validated direct credentials.

5.2 Readiness marker

Default path:

  • <root>/meta/gcp.ready.json

The marker MUST report status=ready only after validation and credential writing succeed. Its context SHOULD include:

  • zone;
  • ssh_public_key;
  • auth_mode;
  • impersonation_validated;
  • billing_account_id when configured;
  • runtime_sa_email when delegated access is configured.

Modules that set ssh_keys_from_init: true SHOULD NOT also provide explicit ssh_keys.

5.3 Run records

Run records MUST be written under:

  • <root>/logs/init/gcp/<run_id>/

Run records MUST NOT include access tokens.

6. Failure semantics

  • Failed interactive authorization returns exit code 20.
  • Failed credential writing returns exit code 30.
  • Missing operator input, inaccessible projects and unavailable billing return an operator error without writing a ready marker.