Skip to content

Init GCP credentials with hyops init gcp

Purpose: Initialise GCP runtime inputs so Terraform/Terragrunt stacks can run with ADC + impersonation. Owner: Platform operations Trigger: First-time environment bootstrap, new workstation/runner. Impact: Without GCP auth and impersonation, GCP stacks cannot apply. Severity: P3 Pre-reqs: gcloud installed; access to the target project; permission to impersonate GCP_TERRAFORM_SA_EMAIL (when configured). Rollback strategy: Remove the generated credentials file under <root>/credentials/ and re-run init.

Context

hyops init gcp writes:

  • Non-secret config: <root>/config/gcp.conf
  • Credentials tfvars: <root>/credentials/gcp.credentials.tfvars (mode 0600)
  • Readiness marker: <root>/meta/gcp.ready.json

The tfvars file is designed for Terraform provider impersonation flows.

The readiness marker may also carry a non-secret SSH public key for cloud VM bootstrap flows. This lets shipped blueprints stay free of embedded operator keys.

Preconditions and safety checks

  • Ensure you are targeting the correct environment: 

    echo "HYOPS_ENV=$HYOPS_ENV"

  • Confirm required tools exist: 

    command -v gcloud

Notes: - If you are bootstrapping a brand new project (project does not exist yet), set GCP_ADC_QUOTA_PROJECT_ID in <root>/config/gcp.conf to an existing accessible project to avoid interactive quota project selection during ADC flows.

Steps

1) Generate the config template (first run only)

  • Command: 

    hyops init gcp --env dev

  • Expected result:

  • If the config does not exist, HyOps writes a template and exits with guidance.
  • Edit <root>/config/gcp.conf (required: GCP_PROJECT_ID, GCP_REGION) and re-run.
  • Optional but recommended: set GCP_SSH_PUBLIC_KEY if the local machine does not already have ~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub.
  • GCP_TERRAFORM_SA_EMAIL is optional (recommended for steady-state). If omitted, HyOps can derive it from org/gcp/project-factory module state after that module has been applied.

2) Interactive bootstrap (workstations)

  • Option A (manual login): 

    gcloud auth login
gcloud auth application-default login
hyops init gcp --env dev

  • Option B (allow HyOps to invoke login flows): 

    hyops init gcp --env dev --with-cli-login

Note: - if GCP_TERRAFORM_SA_EMAIL is explicitly set, impersonation validation still fails hard when permissions are wrong - if the service account is only auto-derived from org/gcp/project-factory state, HyOps can fall back to direct ADC and continue

3) Non-interactive mode (CI/runners)

  • Action: ensure ADC is already configured on the runner and impersonation is permitted. Common CI pattern:
  • set GOOGLE_APPLICATION_CREDENTIALS to a runner service-account JSON key file
  • ensure the runner identity can impersonate GCP_TERRAFORM_SA_EMAIL (roles/iam.serviceAccountTokenCreator)

  • ensure GCP_TERRAFORM_SA_EMAIL is set (via <root>/config/gcp.conf or GCP_TERRAFORM_SA_EMAIL env var)

  • Command: 

    hyops init gcp --env dev --non-interactive

Verification

  • Confirm the readiness marker includes context.ssh_public_key when a public key is discoverable or configured: 

    jq -r ".context.ssh_public_key" ~/.hybridops/envs/dev/meta/gcp.ready.json

  • Confirm readiness marker exists: 

    cat ~/.hybridops/envs/dev/meta/gcp.ready.json

  • Confirm credentials file exists: 

    ls -la ~/.hybridops/envs/dev/credentials/gcp.credentials.tfvars

Notes: - HyOps validates ADC and impersonation without persisting access tokens to evidence.

Troubleshooting

gcloud organizations list returns Listed 0 items.

This is common on personal/trial Google accounts without a Cloud Organization.

  • You can still use HyOps with an existing project:
  • Create a project manually in the Cloud Console (or ask an admin to create one).

  • Set GCP_PROJECT_ID in <root>/config/gcp.conf and re-run hyops init gcp.

  • You can still use org/gcp/project-factory if you have permission to create projects and attach billing:

  • Leave org_id and folder_id unset in the project-factory inputs (project lands under “No organization”).
  • You still need a valid/open billing account ID.

gcloud beta billing accounts list is empty / billing is closed

org/gcp/project-factory needs an open billing account to create a new project.

  • Confirm your billing account is open: 
    gcloud beta billing accounts list
  • If you do not have one, create a billing account in the Cloud Console (or ask an admin).

Project-factory apply fails with permission errors

Typical causes:

  • You cannot create projects (resourcemanager.projects.create), or
  • You cannot link the project to the billing account.

Options:

  • Use an existing project and skip project-factory.
  • Ask an admin to grant the required permissions, or have them run project-factory once for you.

References

Maintainer: HybridOps.Studio License: MIT-0 for code, CC-BY-4.0 for documentation