Skip to content

Initialise GCP with hyops init gcp

Execution context: Run this procedure from a terminal where hyops --help succeeds. If HybridOps.Core is not installed, complete the Quickstart. For deployment support, use GitHub Discussions.

  • Purpose: Prepare a validated GCP environment for HybridOps modules.
  • Owner: Platform operations
  • Trigger: First use, a new workstation, or a change of Google identity or project.
  • Impact: GCP preflight and deployment remain blocked until initialization is ready.
  • Pre-reqs: hyops setup gcp completed and access to the intended Google account.
  • Rollback: Remove the generated files under the environment's credentials/ and meta/ directories, then rerun initialization.

What it prepares

For the selected environment, initialization writes:

  • config/gcp.conf;
  • credentials/gcp.credentials.tfvars, protected with mode 0600;
  • meta/gcp.ready.json;
  • a run record under logs/init/gcp/.

Use one environment name throughout initialization, preflight, deploy, access and destroy.

Interactive setup

Run:

hyops init gcp \
  --env <env> \
  --with-cli-login

The flow:

  1. confirms the Google identity;
  2. lists accessible projects or accepts a new project ID;
  3. requires an open billing account before creating a project;
  4. confirms the region and lists available zones;
  5. generates an SSH key when no public key is available;
  6. validates access and writes the readiness marker.

An existing project with billing enabled does not require a billing-account selection. If the account has no open billing account, initialization stops before project creation and provides the Google Cloud billing and free-trial links.

For an existing environment, revalidate the stored values:

hyops init gcp \
  --env <env> \
  --with-cli-login \
  --force

--force displays the stored project, region and billing selection before replacement. An inaccessible project is not recorded as ready.

Non-interactive setup

For a runner, provide the required project, region, zone and runtime identity through config/gcp.conf or environment variables, then run:

hyops init gcp \
  --env <env> \
  --non-interactive

Non-interactive initialization does not open sign-in or selection prompts.

Verification

Run:

hyops show init --env <env> gcp
hyops preflight --env <env>

For a blueprint, follow with:

hyops blueprint preflight \
  --env <env> \
  --ref <blueprint-ref>

A ready result confirms project access, billing, location, runtime credentials and the readiness marker. Workload-specific checks remain the responsibility of blueprint preflight.

Common recovery paths

The selected identity is not the intended account

Reject the identity when prompted and choose the sign-in option. Initialization returns to identity confirmation before project discovery.

No open billing account is available

Activate the Google Cloud free trial, open a billing account, or ask an administrator to provide access. Rerun initialization afterwards.

The stored project is inaccessible

Reinitialize with the intended project:

hyops init gcp \
  --env <env> \
  --with-cli-login \
  --force \
  --project-id <project-id> \
  --region <region>

A VM shape is unavailable in the selected zone

Rerun initialization with --force, select another listed zone in the same region, then repeat blueprint preflight and deployment. Successfully completed upstream stages remain resumable.

No SSH public key is available

Interactive initialization creates ~/.ssh/id_ed25519 automatically. Existing keys are never overwritten. For a non-interactive run, pass --ssh-public-key or set GCP_SSH_PUBLIC_KEY.

References

License: MIT-0 for code, CC-BY-4.0 for documentation