Bind an Exact Workload Revision to a Verified Compute Lifecycle

Module ref: platform/linux/pinned-workload

Requires HybridOps.Core v0.1.6-rc.1 or newer.

This procedure binds one Git commit, its execution inputs and its declared result paths to a HybridOps environment. The workload repository remains responsible for its topology, operation and acceptance checks. HybridOps records the resolved commit, execution target, exit status, declared container-image identities and checksum of the retained result bundle. Infrastructure run records establish compute release and replacement.

Preconditions

• The target is a reachable Linux host or the current Linux or WSL2 host.
• The workload has an executable repository-relative entry point.
• The workload commit is a full 40-character SHA.
• Every required result path is relative to the repository root.
• The target user can perform the declared privileged work.
• Required images and protected runtime files are available from authorised controller-side sources or their existing authoritative locations.

For a Containerlab workload, prepare the execution environment first:

• Operate GCP Containerlab
• Operate Local Containerlab

1. Initialise the workload inputs

Use a separate state instance for each workload binding:

ENV=<environment>
INSTANCE=<workload-id>
INPUTS="$HOME/.hybridops/envs/$ENV/config/modules/platform__linux__pinned-workload/instances/$INSTANCE.inputs.yml"

hyops module init \
  --env "$ENV" \
  --module platform/linux/pinned-workload \
  --state-instance "$INSTANCE"

nano "$INPUTS"

Declare the workload contract:

pinned_workload_id: "<workload-id>"
pinned_workload_repository: "https://github.com/<owner>/<repository>.git"
pinned_workload_revision: "<full-40-character-commit-sha>"
pinned_workload_owner: "opsadmin"
pinned_workload_entrypoint: "scripts/acceptance.sh"
pinned_workload_arguments: []
pinned_workload_environment: {}
pinned_workload_packages: []
pinned_workload_evidence_paths:
  - "reports"
pinned_workload_timeout_s: 14400

Do not place passwords, tokens, private keys or licence content in the Git URL, argument list or environment map.

2. Select the target

Use one target form in the same input file.

GCP Containerlab host

Resolve the private VM from the existing blueprint state:

inventory_state_ref: "platform/gcp/platform-vm#gcp_containerlab_vm"
inventory_vm_groups:
  targets:
    - "containerlab-01"
target_user: "opsadmin"
ssh_private_key_file: "~/.ssh/id_ed25519"
ssh_access_mode: "gcp-iap"
connectivity_wait_s: 90

Direct on-prem host

target_host: "<host-or-address>"
target_user: "<ssh-user>"
ssh_private_key_file: "~/.ssh/id_ed25519"
ssh_access_mode: "direct"
pinned_workload_owner: "<workload-user>"

Current Linux or WSL2 host

target_host: "127.0.0.1"
local_execution: true
connectivity_check: false
target_user: "<linux-user>"
pinned_workload_owner: "<linux-user>"

3. Declare protected inputs when required

Stage a controller-side runtime file inside the checkout without adding its contents to the execution manifest:

pinned_workload_runtime_files:
  - src: "/absolute/controller/path/runtime.vault.yml"
    dest: "group_vars/all/runtime.vault.yml"
    mode: "0600"

Keep each protected destination separate from every retained evidence path. Exact, parent and child path collisions fail before the checkout is materialised. Symbolic-link indirection is rejected before protected files are staged or evidence is retained.

Load an authorised container-image archive and require its expected identity:

pinned_workload_container_image_archives:
  - path: "/absolute/controller/path/workload-images.tar"
    sha256: "<archive-sha256>"
    images:
      - image: "<repository>:<tag>"
        image_id: "sha256:<image-id>"

Leave this list empty when the selected Containerlab blueprint already manages the required images. The same image must not have competing declarations.

4. Execute the first acceptance run

hyops validate \
  --env "$ENV" \
  --module platform/linux/pinned-workload \
  --state-instance "$INSTANCE" \
  --inputs "$INPUTS"

hyops preflight \
  --env "$ENV" \
  --module platform/linux/pinned-workload \
  --state-instance "$INSTANCE" \
  --inputs "$INPUTS"

hyops apply \
  --env "$ENV" \
  --module platform/linux/pinned-workload \
  --state-instance "$INSTANCE" \
  --inputs "$INPUTS"

Inspect the resulting state:

hyops show module \
  --env "$ENV" \
  "platform/linux/pinned-workload#$INSTANCE"

Proceed only when the module reports status=ok, the resolved commit equals the declared revision, the entry point returns zero and every declared evidence path is retained. A failed entry point or missing result path is a stop condition; keep the target available for diagnosis.

The retained workload files are under:

~/.hybridops/envs/<environment>/artifacts/workloads/<workload-id>/

5. Replace the compute

For a running GCP Containerlab environment, use the protected rebuild:

hyops blueprint rebuild \
  --env "$ENV" \
  --ref gcp/containerlab@v1 \
  --execute

This verifies the selected lab recovery set off-host, removes the original VM, creates fresh compute, restores the lab and reruns platform health checks.

For local Containerlab, preserve and restore the managed lab on the current Linux or WSL2 host:

hyops blueprint destroy \
  --env "$ENV" \
  --ref linux/containerlab@v1 \
  --execute

hyops blueprint deploy \
  --env "$ENV" \
  --ref linux/containerlab@v1 \
  --execute \
  --restore-labs

Select preservation and verification when the destroy command presents the recovery choices.

This local path verifies workload and lab restoration on the same host. Use a protected cloud rebuild or replacement on-prem target to verify compute replacement.

For replacement on-prem compute, complete the platform replacement first. Update only the target binding in INPUTS; retain the workload commit, entry point, runtime inputs, image identities and evidence paths.

6. Repeat and compare

Run the same validate, preflight and apply commands against the replacement target, then inspect the new module state and retained manifest.

Acceptance requires:

• the same declared and resolved commit;
• the expected container-image identities;
• infrastructure records showing release of the original compute and readiness of its replacement, when compute replacement is in scope;
• zero exit status in both runs;
• every declared evidence path in both retained bundles;
• workload-specific checks passing on the resulting target; and
• successful final infrastructure cleanup.

Differences in generated timestamps or run identifiers are expected. Treat a change in a workload-declared topology digest, source-of-truth digest, image identity or acceptance result as a failed continuity check unless the workload contract permits it.

7. Clean up

Remove a managed checkout when the target host will remain in service:

hyops destroy \
  --env "$ENV" \
  --module platform/linux/pinned-workload \
  --state-instance "$INSTANCE" \
  --inputs "$INPUTS"

Release disposable lab compute through its blueprint destroy command. Retain the controller-side workload manifests, checksummed evidence bundles and infrastructure run records until the comparison is complete.

References

• Pinned workload module
• Verify network-lab continuity
• Preserve and release a network-lab environment

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