Operate GCP Containerlab

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

For execution on the current Ubuntu or Windows WSL2 host, use the local Containerlab runbook.

Existing-lab migration commands require HybridOps.Core 0.1.5 or newer. Verify the installed version with hyops --version before capture or import.

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.

For authorised Cisco IOL-XE sources, keep each loose CML binary beside its image-definition YAML, or retain the standard iol-xe or ioll2-xe OCI archive name. Set the folder once in the blueprint:

containerlab_lab_local_image_dir: "/absolute/controller/path/x64_IOL"
containerlab_lab_local_image_dir_authorised_use: true

HybridOps derives the L2 or L3 type, version, checksum, build tag and verification input. Use the explicit build declarations in the blueprint only for a non-standard folder layout.

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. For a HybridOps-built source, use --user opsadmin --become; OpenSSH uses the operator key installed during deployment. --become requires passwordless sudo. A password remains valid for an independently managed source. The output path can be absolute; changing the working directory is not required.

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 configuration files 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 inspecting the replacement and confirming that the existing archive or staged recovery set is no longer required.

4. Select recovery behaviour

Set containerlab_recovery_mode in the environment blueprint:

• rebuild retains the source tree, supported copied configurations and the inspected native lab directory. 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"

Note the local endpoint printed by the command. In a second terminal, use its port for SSH. For example, when the endpoint is 127.0.0.1:60092:

ssh -p 60092 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.

The installed Cisco IOL example uses Containerlab's default username admin and password admin. Password input is not echoed by SSH. Save changes to device startup configuration before testing recovery. For example:

enable
configure terminal
interface Loopback101
 description HYBRIDOPS-RESTORE-TEST
 ip address 10.101.0.1 255.255.255.255
exit
router ospf 1
 network 10.101.0.1 0.0.0.0 area 0
end
copy running-config startup-config

Press Enter without entering a value when IOS asks for the destination filename. Confirm the saved state:

show startup-config | section Loopback101

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. The recovery gate presents three choices:

recovery state:
  1. Keep the environment running
  2. Preserve declared recovery state, verify, then destroy
  3. Destroy without preserving recovery state
Choose [1-3]:
Type "destroy demo-lab" to confirm:

Keep the environment when more tests remain. The second choice invokes native configuration save and retains the inspected native lab directory with the declared source tree. Destruction begins only after the exact confirmation. It verifies the off-host recovery set before releasing the GCP resources. A failed recovery gate retains the environment. The third choice bypasses preservation.

Limit an access session

Set an optional access deadline:

hyops blueprint access \
  --env "$ENV" \
  --ref "$REF" \
  --session-minutes 120 \
  --on-expiry protected-release

Keep the command running. At expiry, HybridOps preserves the declared recovery state before releasing the environment. A failed preservation or teardown retains the environment.

Manage the session from another terminal:

hyops blueprint session status --env "$ENV" --ref "$REF"
hyops blueprint session extend --env "$ENV" --ref "$REF" --minutes 30
hyops blueprint session cancel --env "$ENV" --ref "$REF"

cancel removes the expiry action without closing access.

7. Preserve and reconstruct

Use rebuild when the environment is still running:

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, restores the retained native lab directory, performs one Containerlab deployment and reruns health checks.

To inspect the boundary between destruction and reconstruction, run the phases separately:

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

ls -lh "$HOME/.hybridops/envs/$ENV/artifacts/containerlab/recovery"

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

Before recovery, HybridOps compares the archived topology with the declared controller source. If they differ, interactive deployment selects the archive, the controller source without saved state, or cancellation. The controller file is not rewritten. For unattended deployment, use --restore-labs for the archive or --skip-lab-restore for the controller source. A configured but missing controller topology is rejected before execution.

Do not run rebuild after the environment has already been destroyed. Container images remain external dependencies, so their registry or authorised local source must remain available.

After reconstruction, reopen automation access and verify both the running and startup configuration:

show running-config | section Loopback101
show startup-config | section Loopback101
show ip ospf neighbor

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. Use this final destroy without a following deployment when the lab session is complete. 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
• Containerlab GUI

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