Skip to content

Operate EVE-NG Service (HyOps)

  • Purpose: Install/configure EVE-NG on an existing Ubuntu 22.04 host using platform/linux/eve-ng. Owner: Platform engineering

  • Trigger: Lab platform bring-up, baseline refresh, or controlled environment rebuild

  • Impact: Modifies the target host (packages, sysctl, services) to support EVE-NG

  • Severity: P2 Pre-reqs: Target host is Ubuntu 22.04 (Jammy), reachable via SSH, runtime vault decrypt working, Ansible deps installed.

  • Rollback strategy: Run hyops destroy with the same module and input overlay (best-effort), or rebuild the host from a clean Jammy baseline.

Context

This runbook covers module-level operations for:

  • Preferred module: platform/linux/eve-ng
  • Compatibility alias: platform/onprem/eve-ng
  • Driver: config/ansible
  • Scope: configure EVE-NG on an existing Ubuntu 22.04 host (no VM provisioning)

HyOps validates the target OS via SSH during preflight/apply and fails fast if it is not Ubuntu 22.04.

Optional follow-on modules build on the same target contract after the base EVE-NG runtime is ready:

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

Preconditions and safety checks

  • Installed hyops (via install.sh) can be run from any working directory.
  • If you want to use the shipped example overlays, set:
    export HYOPS_CORE_ROOT="${HYOPS_CORE_ROOT:-$HOME/.hybridops/core/app}"

For source checkout usage, set HYOPS_CORE_ROOT to your hybridops-core checkout root instead. - Correct environment selected (--env dev|staging|prod). - Target host is Ubuntu 22.04 (Jammy). - Target host is reachable via SSH from the runner. - Required secrets are available via shell env or runtime vault: - EVENG_ROOT_PASSWORD - EVENG_ADMIN_PASSWORD - load_vault_env defaults to true; if those secrets are not seeded, validate/preflight stop before connectivity or package changes.

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

  1. Select an overlay

Use one of:

  • $HYOPS_CORE_ROOT/modules/platform/linux/eve-ng/examples/inputs.min.yml

  • Seed secrets (recommended: runtime vault)

    hyops secrets set --env dev \
  EVENG_ROOT_PASSWORD='...' \
  EVENG_ADMIN_PASSWORD='...'

If your target lives on a private on-prem management subnet, prefer ssh_proxy_jump_auto: true or set an explicit bastion. HyOps now defers that bastion resolution to preflight instead of timing out on a guessed direct SSH path.

  1. Preflight

    hyops preflight --env dev --strict \
  --module platform/linux/eve-ng \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/linux/eve-ng/examples/inputs.min.yml"

  2. Deploy / converge

    hyops apply --env dev \
  --module platform/linux/eve-ng \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/linux/eve-ng/examples/inputs.min.yml"

  3. Verify outputs and run records

    cat $HOME/.hybridops/envs/dev/state/modules/platform__linux__eve-ng/latest.json

Check:

  • status is ok
  • outputs.eveng_url is present
  • cap.lab.eveng = ready is present

For the current role implementation, the service is published over http:// by default unless you add your own TLS termination.

  1. Destroy (best-effort cleanup)

    hyops destroy --env dev \
  --module platform/linux/eve-ng \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/linux/eve-ng/examples/inputs.min.yml"

  2. Rebuild (destroy then apply)

    hyops rebuild --env dev --yes \
  --confirm-module platform/linux/eve-ng \
  --module platform/linux/eve-ng \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/linux/eve-ng/examples/inputs.min.yml"

Verification

Primary state:

  • $HOME/.hybridops/envs/<env>/state/modules/platform__linux__eve-ng/latest.json

Primary logs:

  • $HOME/.hybridops/envs/<env>/logs/module/platform__linux__eve-ng/<run_id>/

Optional content modules

After the base EVE-NG host is ready, you can layer:

  • platform/linux/eve-ng-images to load device images
  • platform/linux/eve-ng-labs to stage lab content
  • platform/linux/eve-ng-healthcheck to publish a concise health result

Notes on destroy semantics

Destroy is best-effort:

  • Package removal and directory cleanup are attempted.
  • Some host-level changes (for example swap/fstab edits) may not be reverted automatically.

For fully governed environments, the recommended “hard rollback” is to rebuild the VM from a clean Jammy baseline.

References