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 a supplied or imported 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. Initialise the blueprint

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

For an existing environment blueprint:

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

The supported fields and commented examples are maintained in the GCP Containerlab blueprint.

3. Select the lab source

New 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/"

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"

The source directory includes the topology and any relative files it uses. Container images remain native image references in that topology. containerlab_lab_required_images can verify those references before deploy; containerlab_lab_pull_missing_images permits registry pulls when enabled. Use only images and licence assets you are authorised to run.

Existing Containerlab lab

Capture an existing lab when its authoritative topology and local assets are on another host. The capture reads the source through SSH and does not modify the source tree. Leave containerlab_lab_source_dir empty so the imported recovery set supplies the target source tree.

SOURCE_HOST=<existing-host>
SOURCE_ROOT=/srv/containerlab/<lab>
TOPOLOGY=lab.clab.yml
ARCHIVE="$HOME/HybridOps-Labs/containerlab-lab.tar.gz"

mkdir -p "$(dirname "$ARCHIVE")"

hyops lab migrate capture \
  --platform containerlab \
  --host "$SOURCE_HOST" \
  --user <ssh-user> \
  --source-root "$SOURCE_ROOT" \
  --topology-relpath "$TOPOLOGY" \
  --output "$ARCHIVE"

OpenSSH uses configured agents and keys, or prompts for the account password in an interactive terminal. HybridOps does not store the password. Add --identity-file <path> for a specific key. Add --become only when the account needs passwordless sudo to read the source.

Capture assesses the requested source data and destination free space before transfer. Insufficient space stops the operation before an archive is published.

Capture retains the topology source tree and asks Containerlab to copy supported saved configurations into the archive. Existing saved configurations remain present. Generated top-level clab-* runtime directories are excluded.

If the source host sets CLAB_LABDIR_BASE, pass that value with --source-labdir-base. The target defaults to /var/lib/hybridops/containerlab/labdirs. If the target blueprint declares a different containerlab_lab_labdir_base, pass the same value with --target-labdir-base during capture.

Container images are not copied. Image references remain in the topology and must be available to the target through an authorised registry or image-load process. Local startup configurations and other relative assets under the source root are included. Remote assets remain at their authoritative source and must be reachable from the target.

Inspect the completed archive before import:

hyops lab migrate inspect \
  --platform containerlab \
  --archive "$ARCHIVE"

The inspection reports the topology identity, retained image references and archive checksum. Import the verified archive into the initialised environment:

hyops lab migrate import \
  --env "$ENV" \
  --ref "$REF" \
  --platform containerlab \
  --archive "$ARCHIVE"

The archive topology path must match containerlab_lab_topology_relpath, and its target labdir base must match containerlab_lab_labdir_base. Import publishes the archive through the normal latest-recovery contract. A normal blueprint deployment restores the source tree and deploys the topology; no separate migration deployment mode is required.

Capture and import do not replace existing output or recovery data silently. Use --force only after confirming that the existing archive or staged recovery set can be replaced.

4. 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.

5. 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.

6. 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.

7. 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.

8. 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.
• Correct topology-path or labdir-base mismatches before importing a lab.
• 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 blueprint
• Containerlab lifecycle validation
• Containerlab documentation

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