Skip to content

Showcase – EGF Governed Deploy (Connectivity‑Gated Ansible Change)

1. Who this is for

  • Reviewers and hiring managers – to see what a governed Ansible change looks like end‑to‑end, with records you can drill into.
  • Platform and SRE engineers – to understand how the Environment Guard Framework (EGF) wires into normal playbooks and CI jobs.
  • Learners / Academy track – to replay the same scenario in a lab and see how governance, connectivity checks, and verification work together.

This is deliberately practical: a single governed deploy flow, with screenshots, JSON snippets, and links to real run records.

2. Scenario in 90 seconds

Story: “Before any meaningful change runs, we verify we are in the right environment, select the right hosts, and confirm connectivity. Only then do we deploy, and we keep records of every step.”

We walk through one governed Ansible run that:

  1. Enters via Env Guard (which validates the target environment and risk level).
  2. Runs a connectivity gate against cicd_test hosts.
  3. Proceeds to an application playbook only if the gate passes.
  4. Writes structured evidence under <runtime-root>/logs/ansible/... and <runtime-root>/logs/....

2.1 Screenshot placeholder – pipeline view

Replace this image with an actual screenshot from Jenkins or your CI of a successful EGF governed run.

Placeholder: EGF governed deploy CI pipeline summary screenshot

Suggested source for the final screenshot:

  • A single CI job view showing stages such as Env Guard → Connectivity Gate → Deploy → Evidence archive.
  • Highlight the correlation ID (CID) in logs or stage metadata.

2.2 Video walkthrough placeholder

Replace this link once a short walkthrough is recorded.

  • Video walkthrough (placeholder): “EGF governed deploy – from gate to verification”
    [YouTube – EGF governed deploy](https://example.com/egf-governed-deploy-video-placeholder)

Keep the video under 5–7 minutes and focus on the story: “what runs, what’s being checked, and where the evidence goes”.

3. Architecture at a glance

This scenario uses the Environment Guard Framework (EGF) roles from hybridops.common to wrap a normal deploy playbook.

3.1 Diagram placeholder

Replace this diagram once rendered from the Mermaid source or exported from your drawing tool.

Placeholder: EGF governed deploy architecture overview diagram

Suggested contents for the final diagram:

  • Left: Trigger – Jenkins job, make deploy, or GitHub Actions workflow.
  • Middle: EGF chain – env_guard → host_selector → connectivity_test → deploy_role.
  • Right: Targets – cicd_test VMs (for example generic-linux, generic-win) and, later, real platform hosts.
  • Bottom: Record sinks – <runtime-root>/logs/ansible/env_guard_logs, <runtime-root>/logs/ansible/connectivity_logs, <runtime-root>/logs/....

3.2 Key components

  • Ansible collections (hybridops.*)
  • hybridops.common.env_guard – governance entry point.
  • hybridops.common.host_selector – validated host targeting.
  • hybridops.common.connectivity_test – ICMP / TCP / HTTP reachability checks.

  • Application roles from hybridops.app (for example jenkins_controller, rke2_server).

  • Platform repository (hybridops-platform)

  • deployment/inventories/core/cicd-test.ini – CI test inventory targeting generic VMs.
  • deployment/ci/playbooks/cicd_connectivity_gate.yml – CI gate using connectivity_test.

  • Domain playbooks under deployment/linux, deployment/netbox, etc.

  • Verification model

  • Logs under <runtime-root>/logs/ansible/*_logs/<run_id>/.
  • Runtime records under <runtime-root>/logs/... for selected scenarios.

4. What a governed run looks like

This section ties together the end‑to‑end flow: from trigger to verification.

4.1 High‑level flow

  1. Trigger – A CI job or make target kicks off the run, passing ENV / HOS_ENV and any change‑specific parameters.
  2. Env Guard – Validates environment, risk level, and timing; seeds a correlation ID (CID).
  3. Host selection – host_selector expands and validates the target hosts or patterns.
  4. Connectivity gate – connectivity_test runs reachability checks and writes JSON/JSONL under <runtime-root>/logs/ansible/connectivity_logs/<run_id>/.
  5. Deploy – If and only if the gate passes, the pipeline includes downstream application roles / playbooks.
  6. Record publishing – Runtime records and CID are surfaced in CI logs and, where needed, copied into <runtime-root>/logs/ci/....

4.2 Example playbook sketch

This is illustrative only; the exact file names may differ in the live repo:

- name: Governed connectivity gate and deploy
  hosts: localhost
  gather_facts: false
  roles:
    - hybridops.common.env_guard
    - hybridops.common.host_selector

- name: Connectivity gate against selected hosts
  hosts: "{{ egf_selected_hosts | default('cicd_test') }}"
  gather_facts: false
  roles:
    - hybridops.common.connectivity_test

- name: Application deploy (only runs after gate)
  hosts: "{{ egf_selected_hosts | default('cicd_test') }}"
  gather_facts: true
  roles:
    - hybridops.app.jenkins_controller

The actual CI playbooks (for example deployment/ci/playbooks/cicd_connectivity_gate.yml) are more detailed, but follow the same pattern and make heavy use of the EGF roles.

4.3 Screenshot placeholder – connectivity report

Replace this image with an excerpt from a real JSON report rendered in a viewer or captured from logs.

Placeholder: connectivity report snippet screenshot

Suggested source material:

  • A small subset of connectivity_report.json or connectivity_report.jsonl, showing success/failure per host.
  • Highlight the correlation ID, environment, and test matrix (ICMP / HTTP / SSH).

5. Evidence map for this showcase

This scenario is backed by real records in the platform repository. Adjust paths as you finalise the evidence layout; the structure below follows ADR‑0600.

5.1 Logs and records

  • Env Guard logs and reports
  • <runtime-root>/logs/ansible/env_guard_logs/<run_id>/env_guard_audit.jsonl

  • <runtime-root>/logs/ansible/env_guard_logs/<run_id>/env_guard_report.md

  • Connectivity checks

  • <runtime-root>/logs/ansible/connectivity_logs/<run_id>/connectivity_report.json

  • <runtime-root>/logs/ansible/connectivity_logs/<run_id>/connectivity_report.jsonl

  • CI evidence bundles (optional)

  • <runtime-root>/logs/ci/egf-governed-deploy/<run_id>/ – tarballs or curated subsets of logs and reports for this specific scenario.

Once you have a stable run (or two), capture it in the documentation site:

  • Evidence index page (example):
    docs/evidence/platform-runs/egf-governed-deploy.md

That page should:

  • Link back to this showcase.
  • Pin one or two known‑good run IDs.

  • Embed small JSON / log snippets to show what “good” looks like.

  • Optional external links:

  • GitHub Actions / Jenkins build URLs for the showcased run.
  • Screenshots of dashboards or log explorers, if used.

6. How to replay this scenario

From ctrl-01 (or your equivalent control node) in the hybridops-platform repository:

# 1. Ensure cicd_test inventory exists (generic-* VMs)
cd "$HOME/hybridops-platform"
make netbox.export_infra    # or the equivalent helper target
ls deployment/inventories/core/cicd-test.ini

# 2. Install hybridops.* collections for the current platform version
ansible-galaxy collection install -r deployment/requirements.yml

# 3. Run the connectivity gate via CI playbook (non-destructive)
cd deployment
ansible-playbook \
  -i inventories/core/cicd-test.ini \
  ci/playbooks/cicd_connectivity_gate.yml

# 4. Run a governed deploy that uses the same EGF chain
#    (replace with the actual playbook and variables in your repo)
ansible-playbook \
  -i inventories/core/cicd-test.ini \
  linux/playbooks/example-governed-deploy.yml \
  -e env=dev

Then inspect the evidence paths described above and compare them to the screenshots and snippets on this page.

For a self‑contained Academy lab version, a minimal replay script can live alongside the lab materials and call into the same roles, but with lighter‑weight targets (single VM, small change).

7. What to review and how

7.1 For reviewers / hiring managers

When reviewing this showcase, focus on:

  • Governance clarity – It should be obvious where the gate is, how it works, and what happens when checks fail.
  • Traceability – One correlation ID links CI output, logs, and records.
  • Evidence discipline – Runtime records land in predictable, documented locations under the active runtime root.

If you only have a few minutes, use this sequence:

  1. Look at the pipeline screenshot for a successful run.
  2. Skim the connectivity JSON snippet to see how hosts are reported.
  3. Open the Env Guard report and confirm environment / risk context.

7.2 For engineers and learners

Engineers and Academy participants should pay attention to:

  • How EGF roles are wired into normal playbooks.
  • How connectivity failures are surfaced (per host) and how they block downstream tasks.
  • How to add a new governed pipeline by reusing the same roles and evidence structure.

A good exercise is to:

  1. Run the governed scenario end‑to‑end.
  2. Intentionally break connectivity to one host.
  3. Observe how the gate fails, what records are written, and how the CID helps you find the right logs quickly.

8. References