Operate GCP Containerlab

Run this procedure from a workstation where hyops --help succeeds. Complete the Quickstart first when Core is not installed.

The blueprint creates private GCP compute, installs Containerlab 0.78.0, deploys the supplied topology, verifies health and protects the selected recovery state before compute release.

Containerlab owns topology and node behaviour. HybridOps owns host readiness, private access, recovery verification, rebuild order and GCP resource release.

1. Prepare the environment

ENV=demo-lab
REF=gcp/containerlab@v1

hyops setup gcp
hyops init gcp --env "$ENV" --with-cli-login

2. Prepare the topology

The source directory must contain lab.clab.yml and any local files referenced by the topology. To use the installed two-node example:

mkdir -p "$HOME/HybridOps-Labs"

cp -R \
  "$HOME/.hybridops/core/app/blueprints/gcp/containerlab@v1/examples/two-node-linux" \
  "$HOME/HybridOps-Labs/"

Initialise and open the environment blueprint:

hyops blueprint init \
  --env "$ENV" \
  --ref "$REF" \
  --edit

For an existing environment blueprint:

hyops blueprint edit --env "$ENV" --ref "$REF"

Set gcp_containerlab_lab.inputs.containerlab_lab_source_dir to the absolute controller-side topology directory. For the example on macOS:

containerlab_lab_source_dir: "/Users/<user>/HybridOps-Labs/two-node-linux"

Use only images and licence assets you are authorised to run. Reference them through the native Containerlab topology rather than embedding secrets in the runtime blueprint.

3. Select recovery behaviour

Set containerlab_recovery_mode in the environment blueprint:

• rebuild retains the source tree and native saved configuration. This is the default.
• snapshot also retains supported vrnetlab snapshots.
• ephemeral rebuilds from source intent without mutable runtime state.

4. Validate and deploy

hyops blueprint validate --env "$ENV" --ref "$REF"
hyops blueprint plan --env "$ENV" --ref "$REF"
hyops blueprint preflight --env "$ENV" --ref "$REF"
hyops blueprint deploy --env "$ENV" --ref "$REF" --execute

Deployment completes after private networking, compute, KVM readiness, Containerlab installation, topology deployment, health and recovery readiness have passed.

5. Access and verify

Keep the private access session running in the first terminal:

hyops blueprint access --env "$ENV" --ref "$REF"

In a second terminal:

ssh -p 2222 opsadmin@127.0.0.1

On the managed host:

sudo containerlab inspect --all

For direct node access, keep an automation session running:

hyops blueprint access --env "$ENV" --ref "$REF" --automation

In another terminal:

hyops blueprint device list --env "$ENV" --ref "$REF"
hyops blueprint device edit --env "$ENV" --ref "$REF"
hyops blueprint device ping --env "$ENV" --ref "$REF" <device-name-or-address>
hyops blueprint device ssh --env "$ENV" --ref "$REF" <device-name>
hyops blueprint device web --env "$ENV" --ref "$REF" <device-name-or-address> --scheme http --port 80
hyops blueprint device shell --env "$ENV" --ref "$REF"

HybridOps reads node addresses from Containerlab inspection output. The blueprint defaults to Containerlab's 172.20.20.0/24 management network. Edit the runtime blueprint when the topology declares another subnet. Use device edit to correct node usernames or add operator-defined targets.

device web maps private interfaces to temporary loopback URLs. Use device edit to declare each target's web service; the generated file documents the available fields. Pass target names together or use --all. One Ctrl-C closes every tunnel. Add --open-all to open every URL in the workstation browser.

Confirm that the expected lab and nodes are present. Exit the SSH session and close access with Ctrl-C. HybridOps then offers to keep the environment or continue through its protected recovery and teardown flow. Keep the environment when more tests remain.

6. Test reconstruction

hyops blueprint rebuild \
  --env "$ENV" \
  --ref "$REF" \
  --execute

The rebuild must verify the selected recovery set off-host before deleting the original VM. It then creates fresh compute, imports the retained state, performs one native Containerlab deployment and reruns health checks.

After rebuild, reopen access and run sudo containerlab inspect --all again.

7. Release the environment

hyops blueprint destroy \
  --env "$ENV" \
  --ref "$REF" \
  --execute

The recovery gate runs before host deletion. A failed copy or checksum leaves the compute available for diagnosis. Confirm that all declared resources reach destroyed or absent state after a successful run.

Failure boundaries

• Fix GCP authentication, billing, quota or IAP failures before deployment.
• Stop when KVM or package verification fails.
• Correct topology and image access failures without replacing the source tree.
• Keep the host when recovery copy or checksum verification fails.
• Treat GCP billing as authoritative for realised spend.

Validation record

The accepted GCP lifecycle covered private IAP access, KVM readiness, Containerlab installation, native topology deployment, off-host recovery verification, original VM deletion, reconstruction on a new VM, final health and compute cleanup.

See Core PR #303 for the implementation and acceptance record.

References

• GCP Containerlab implementation
• Containerlab lifecycle validation
• Containerlab documentation

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