Deploy EVE-NG (HyOps Blueprint)

• Purpose: Deploy a working EVE-NG foundation using a repeatable blueprint run.
• Owner: Platform engineering
• Trigger: Lab platform bring-up, baseline refresh, or controlled environment rebuild
• Impact: Consumes shared SDN/NetBox authority, builds Jammy template image (if needed), provisions an EVE-NG VM, configures EVE-NG, and proves live health
• Severity: P2
• Pre-reqs: Proxmox init completed for the environment, vault decrypt working, NetBox authority is ready (authoritative IPAM), Ansible deps installed, EVE-NG target is Ubuntu 22.04.
• Rollback strategy: hyops blueprint destroy tears down all steps in reverse order. See §Teardown.

Context

This runbook covers the current EVE-NG blueprint pair:

• onprem/eve-ng@v1
• gcp/eve-ng@v1

Both blueprints converge on the same provider-neutral config and health modules:

• platform/linux/eve-ng
• platform/linux/eve-ng-healthcheck

For the GCP variant, treat the zone and VM shape as environment choices, not fixed defaults. The EVE-NG host needs a nested-virtualization-capable shape, and both zonal capacity and project CPU quota can shift. Keep the env overlay authoritative for the selected zone and shape, and rerun the VM step if GCP capacity or quota constraints change.

Preconditions and safety checks

• Installed hyops (via install.sh) can be run from any working directory.
• Source-checkout usage should export HYOPS_CORE_ROOT=/path/to/hybridops-core.
• Correct environment selected (--env dev|staging|prod).
• Secrets available via shell env or runtime vault:
• EVENG_ROOT_PASSWORD
• EVENG_ADMIN_PASSWORD
• Those secrets should be seeded before preflight. The base EVE module defaults to load_vault_env: true and fails early if they are missing.
• EVE-NG VM must be Ubuntu 22.04 (Jammy). HyOps enforces this during preflight/apply.

NetBox foundation is required for IPAM:

• This blueprint allocates the EVE-NG VM IP from NetBox (no hardcoded per-VM IPs) and consumes the shared SDN authority state.
• By default, HyOps expects NetBox authority in --env shared. If it is not ready yet, run:

  hyops blueprint deploy --env shared --ref onprem/bootstrap-netbox@v1 --execute
  

This also seeds the shared SDN foundation and NetBox IPAM/inventory datasets consumed by this blueprint.

For gcp/eve-ng@v1, the config and healthcheck phases are intentionally rerun on deploy, and the VM step now verifies provider state even when the step is skipped on historical ok state. Historical green config state is not enough evidence after a VM replacement or a project/zone rehome.

In constrained projects, use an env-scoped proof profile rather than rewriting the shipped blueprint baseline. For example, a project with a low global CPU quota can use:

• zone: europe-west2-a
• machine_type: n2-standard-2
• eveng_resource_profile: minimal

That keeps the source blueprint aligned to the intended standard host while allowing a smaller live proof lane in the env overlay.

If the shared Proxmox SDN authority drifts on the host side (for example the vnetmgmt bridge exists but the expected 10.10.0.1/24 gateway is missing), dependent VM steps now fail early with a remediation to re-run core/onprem/network-sdn using a fresh host_reconcile_nonce.

Install/update Ansible runtime deps for the env:

# If you installed via install.sh (default runs setup-all), this is already done.
# To (re)install Ansible Galaxy deps for an env:
hyops setup ansible --env dev

Steps

Substitute --ref onprem/eve-ng@v1 or --ref gcp/eve-ng@v1 depending on target surface. The on-prem variant requires the authoritative foundation (NetBox, shared SDN) deployed first. The GCP variant uses static addressing and can run without NetBox.

1. Validate and plan

   # On-prem
   hyops blueprint validate --ref onprem/eve-ng@v1
   hyops blueprint plan --ref onprem/eve-ng@v1
   
   # GCP
   hyops blueprint validate --ref gcp/eve-ng@v1
   hyops blueprint plan --ref gcp/eve-ng@v1
   

2. Preflight

   hyops blueprint preflight --env dev \
     --ref onprem/eve-ng@v1   # or gcp/eve-ng@v1
   

3. Execute

   hyops blueprint deploy --env dev \
     --ref onprem/eve-ng@v1 \   # or gcp/eve-ng@v1
     --execute
   

hyops blueprint deploy --execute now runs a blueprint preflight gate first. If contracts/resolution fail, execution stops before the first module step. Use --skip-preflight only for controlled break-glass runs.

During long module phases, HyOps prints:

• progress: logs=... (active driver log file)
• progress: phase=preflight|apply|destroy|...
• periodic heartbeat lines for long-running streamed commands

Optional tuning:

export HYOPS_PROGRESS_INTERVAL_S=30

1. Verify (GCP state instance example)

   cat $HOME/.hybridops/envs/dev/state/modules/platform__linux__eve-ng/instances/gcp_eve_ng_config.json \
     | python3 -m json.tool | grep -E '"status"|"outputs"' -A10
   

Verification

Success indicators:

• foundation state is ok
• outputs.eveng_url is present
• outputs.cap.lab.eveng is ready
• healthcheck state is ok
• outputs.eveng_health_status is healthy

Current live verification

Use this when you need current proof for the active GCP-backed EVE-NG lane.

Verify VM state

gcloud compute instances describe platform-labs-eve-ng-01 \
  --project hybridops-dev-gcp-03 \
  --zone europe-west2-a \
  --format='yaml(name,status,machineType,advancedMachineFeatures.enableNestedVirtualization,networkInterfaces[0].networkIP,networkInterfaces[0].accessConfigs[0].natIP)'

Expected:

• status: RUNNING
• the VM name platform-labs-eve-ng-01 is published
• the current internal IPv4 address 10.72.16.20 is published
• the current public IPv4 address 34.13.41.164 is published
• the active machine type n2-standard-2 is published
• enableNestedVirtualization: true is published

Verify EVE-NG config and health

cat $HOME/.hybridops/envs/dev/state/modules/platform__linux__eve-ng/instances/gcp_eve_ng_config.json \
  | python3 -m json.tool

cat $HOME/.hybridops/envs/dev/state/modules/platform__linux__eve-ng-healthcheck/instances/gcp_eve_ng_healthcheck.json \
  | python3 -m json.tool

Expected:

• platform/linux/eve-ng#gcp_eve_ng_config is status=ok
• cap.lab.eveng: ready
• eveng_url: http://platform-labs-eve-ng-01/
• platform/linux/eve-ng-healthcheck#gcp_eve_ng_healthcheck is status=ok
• eveng_health_status: healthy

Verify HTTP reachability

For the current GCP proof lane, verify reachability over IAP from the operator workstation:

gcloud compute ssh opsadmin@platform-labs-eve-ng-01 \
  --project hybridops-dev-gcp-03 \
  --zone europe-west2-a \
  --tunnel-through-iap \
  --command 'curl -fsSI http://127.0.0.1/'

Expected:

• the endpoint responds with HTTP/1.1 200 OK
• the returned headers identify the EVE-NG Apache surface
• the live GCP lane is reachable through the governed operator access path

Teardown

Destroy all blueprint resources in reverse order using the blueprint file:

hyops blueprint destroy --env dev \
  --file "$HOME/.hybridops/envs/dev/config/blueprints/gcp-eve-ng.yml" \
  --execute

For the on-prem variant, substitute the corresponding initialized blueprint file. Steps are destroyed in the order: healthcheck → config → VM. Steps with no recorded state are skipped automatically. Use --yes to skip the confirmation prompt in non-interactive contexts.

Follow-on modules

The blueprint now verifies base health as part of the foundation run. Typical next steps after that are:

• platform/linux/eve-ng-images
• platform/linux/eve-ng-labs That separation keeps the blueprint reusable across instructor, academy, and shared lab lanes without baking specific image libraries or lab content into the base foundation.

References

• Runbook - Operate EVE-NG Service (HyOps)
• Runbook - Load EVE-NG Images (HyOps)
• Runbook - Load EVE-NG Labs (HyOps)
• Runbook - Verify EVE-NG Health (HyOps)
• Runbook - Build Proxmox VM Templates (HyOps)