# cncf/automation architecture

> Architecture diagram of the GitHub repository cncf/automation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cncf/automation
- Repository: https://github.com/cncf/automation

## Overview

CNCF Automation is a collection of independent operational tools rather than one application. Its major capabilities include ephemeral self-hosted GitHub runners, project bootstrap and validation, cross-tool lifecycle audits, landscape updates and MCP access, and Kubestronaut/ambassador administration. The excerpts show runner provisioning and project-tool entry points, plus selected Kubestronaut and MCP behavior; many other listed utilities are unsampled, so their internal links are omitted. The README documents several cross-tool audit sources and project-level-move automation, but that agent workflow is not present in the supplied tree.

Main entry points: [`utilities/landscape-mcp-server/main.go`](https://github.com/cncf/automation/blob/main/utilities/landscape-mcp-server/main.go) (Landscape MCP server), [`Kubestronaut/AddGoldenKubestronauts.py`](https://github.com/cncf/automation/blob/main/Kubestronaut/AddGoldenKubestronauts.py) (Kubestronaut administration), [`ci/cloudrunners/oci/main.go`](https://github.com/cncf/automation/blob/main/ci/cloudrunners/oci/main.go) (Cloud runners), [`utilities/landscape-mcp-server/dataset_loader.go`](https://github.com/cncf/automation/blob/main/utilities/landscape-mcp-server/dataset_loader.go) (Dataset loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runners["Self-hosted runners"]
  node_runner_vm["VM image runner<br/>[main.go]"]
  node_runner_vm_oci["OCI VM image runner<br/>[main.go]"]
  node_cloudrunners["Cloud runners<br/>[main.go]"]
  node_kubevirt_runner["KubeVirt runner<br/>[main.go]"]
  node_gcp_runner["GCP runner<br/>[main.go]"]
  node_ephemeral_vm["Ephemeral machines"]
end

subgraph group_project_ops["Project operations"]
  node_bootstrap["Project bootstrap<br/>[main.go]"]
  node_scaffold["Project scaffold"]
  node_validator_cli["Project validator CLI<br/>[main.go]"]
  node_validation["Project validation<br/>[validator.go]"]
  node_landscape_updater["Landscape updater<br/>[main.go]"]
end

subgraph group_landscape["Landscape services"]
  node_lifecycle_audit["Lifecycle audit"]
  node_audit_sources["Audit source checks"]
  node_landscape_sync["Landscape sync<br/>[main.go]"]
  node_mcp_server["Landscape MCP server<br/>[main.go]"]
  node_dataset_loader["Dataset loading<br/>[dataset_loader.go]"]
  node_mcp_tools["MCP tools<br/>[tools.go]"]
end

subgraph group_programs["Community programs"]
  node_kubestronaut_ops["Kubestronaut administration"]
  node_shipping_ack["Shipping acknowledgements"]
  node_shopify_cart["Shopify cart generation"]
  node_people_json["People records"]
  node_ambassadors["Ambassador records"]
end

node_github(("GitHub Actions"))
node_landscape_data[("Landscape dataset")]
node_kubestronaut_sheets[("Program spreadsheets")]

node_github -.->|"triggers"| node_runner_vm
node_github -.->|"triggers"| node_runner_vm_oci
node_github -.->|"triggers"| node_cloudrunners
node_github -.->|"triggers"| node_kubevirt_runner
node_github -.->|"triggers"| node_gcp_runner
node_cloudrunners -->|"creates and deletes"| node_ephemeral_vm
node_bootstrap -.->|"generates"| node_scaffold
node_validator_cli -->|"runs"| node_validation
node_landscape_updater -.->|"updates"| node_landscape_data
node_lifecycle_audit -->|"cross-checks"| node_audit_sources
node_landscape_sync -->|"fetches and compares"| node_landscape_data
node_mcp_server -->|"loads and refreshes"| node_dataset_loader
node_mcp_server -.->|"dispatches requests"| node_mcp_tools
node_dataset_loader -.->|"loads"| node_landscape_data
node_kubestronaut_ops -->|"reads and updates"| node_kubestronaut_sheets
node_shipping_ack -->|"annotates shipment"| node_kubestronaut_sheets
node_shopify_cart -.->|"reads orders"| node_kubestronaut_sheets
node_kubestronaut_ops -.->|"updates records"| node_people_json

click node_runner_vm "https://github.com/cncf/automation/blob/main/ci/gha-runner-vm/main.go"
click node_runner_vm_oci "https://github.com/cncf/automation/blob/main/ci/gha-runner-vm-oci/main.go"
click node_cloudrunners "https://github.com/cncf/automation/blob/main/ci/cloudrunners/oci/main.go"
click node_kubevirt_runner "https://github.com/cncf/automation/blob/main/ci/cloudrunners/kubevirt/main.go"
click node_gcp_runner "https://github.com/cncf/automation/blob/main/ci/cloudrunners/gcp/main.go"
click node_ephemeral_vm "https://github.com/cncf/automation/blob/main/ci/cloudrunners/oci/pkg/oci/ephemeralmachine.go"
click node_bootstrap "https://github.com/cncf/automation/blob/main/utilities/dot-project/cmd/bootstrap/main.go"
click node_scaffold "https://github.com/cncf/automation/blob/main/utilities/dot-project/bootstrap_scaffold.go"
click node_validator_cli "https://github.com/cncf/automation/blob/main/utilities/dot-project/cmd/validator/main.go"
click node_validation "https://github.com/cncf/automation/blob/main/utilities/dot-project/validator.go"
click node_landscape_updater "https://github.com/cncf/automation/blob/main/utilities/dot-project/cmd/landscape-updater/main.go"
click node_lifecycle_audit "https://github.com/cncf/automation/blob/main/utilities/audit_project_lifecycle_across_tools/scripts/audit_landscape_status.py"
click node_audit_sources "https://github.com/cncf/automation/tree/main/utilities/audit_project_lifecycle_across_tools/scripts"
click node_landscape_sync "https://github.com/cncf/automation/blob/main/utilities/landscape-sync/main.go"
click node_mcp_server "https://github.com/cncf/automation/blob/main/utilities/landscape-mcp-server/main.go"
click node_dataset_loader "https://github.com/cncf/automation/blob/main/utilities/landscape-mcp-server/dataset_loader.go"
click node_mcp_tools "https://github.com/cncf/automation/blob/main/utilities/landscape-mcp-server/tools.go"
click node_kubestronaut_ops "https://github.com/cncf/automation/blob/main/Kubestronaut/AddGoldenKubestronauts.py"
click node_shipping_ack "https://github.com/cncf/automation/blob/main/Kubestronaut/AckKubestronautAndGKSwagShipped.py"
click node_shopify_cart "https://github.com/cncf/automation/blob/main/Kubestronaut/GenerateShopifyCartFromSpreadsheet.py"
click node_people_json "https://github.com/cncf/automation/blob/main/Kubestronaut/CNCFInsertKubestronautInPeople_json.py"
click node_ambassadors "https://github.com/cncf/automation/blob/main/Ambassadors/CNCFInsertAmbassadorInPeople_json.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner_vm,node_runner_vm_oci,node_cloudrunners,node_kubevirt_runner,node_gcp_runner,node_ephemeral_vm toneBlue
class node_bootstrap,node_scaffold,node_validator_cli,node_validation,node_landscape_updater,node_landscape_data,node_kubestronaut_sheets toneAmber
class node_lifecycle_audit,node_audit_sources,node_landscape_sync,node_mcp_server,node_dataset_loader,node_mcp_tools toneMint
class node_kubestronaut_ops,node_shipping_ack,node_shopify_cart,node_people_json,node_ambassadors toneRose
class node_github toneIndigo
```

## Components

### Self-hosted runners

- [VM image runner](https://github.com/cncf/automation/blob/main/ci/gha-runner-vm/main.go): `ci/gha-runner-vm/main.go`
- [OCI VM image runner](https://github.com/cncf/automation/blob/main/ci/gha-runner-vm-oci/main.go): `ci/gha-runner-vm-oci/main.go`
- [Cloud runners](https://github.com/cncf/automation/blob/main/ci/cloudrunners/oci/main.go): `ci/cloudrunners/oci/main.go`
- [KubeVirt runner](https://github.com/cncf/automation/blob/main/ci/cloudrunners/kubevirt/main.go): `ci/cloudrunners/kubevirt/main.go`
- [GCP runner](https://github.com/cncf/automation/blob/main/ci/cloudrunners/gcp/main.go): `ci/cloudrunners/gcp/main.go`
- [Ephemeral machines](https://github.com/cncf/automation/blob/main/ci/cloudrunners/oci/pkg/oci/ephemeralmachine.go): `ci/cloudrunners/oci/pkg/oci/ephemeralmachine.go`

### Project operations

- [Project bootstrap](https://github.com/cncf/automation/blob/main/utilities/dot-project/cmd/bootstrap/main.go): `utilities/dot-project/cmd/bootstrap/main.go`
- [Project scaffold](https://github.com/cncf/automation/blob/main/utilities/dot-project/bootstrap_scaffold.go): `utilities/dot-project/bootstrap_scaffold.go`
- [Project validator CLI](https://github.com/cncf/automation/blob/main/utilities/dot-project/cmd/validator/main.go): `utilities/dot-project/cmd/validator/main.go`
- [Project validation](https://github.com/cncf/automation/blob/main/utilities/dot-project/validator.go): `utilities/dot-project/validator.go`
- [Landscape updater](https://github.com/cncf/automation/blob/main/utilities/dot-project/cmd/landscape-updater/main.go): `utilities/dot-project/cmd/landscape-updater/main.go`

### Landscape services

- [Lifecycle audit](https://github.com/cncf/automation/blob/main/utilities/audit_project_lifecycle_across_tools/scripts/audit_landscape_status.py): `utilities/audit_project_lifecycle_across_tools/scripts/audit_landscape_status.py`
- [Audit source checks](https://github.com/cncf/automation/tree/main/utilities/audit_project_lifecycle_across_tools/scripts): `utilities/audit_project_lifecycle_across_tools/scripts`
- [Landscape sync](https://github.com/cncf/automation/blob/main/utilities/landscape-sync/main.go): `utilities/landscape-sync/main.go`
- [Landscape MCP server](https://github.com/cncf/automation/blob/main/utilities/landscape-mcp-server/main.go): `utilities/landscape-mcp-server/main.go`
- [Dataset loading](https://github.com/cncf/automation/blob/main/utilities/landscape-mcp-server/dataset_loader.go): `utilities/landscape-mcp-server/dataset_loader.go`
- [MCP tools](https://github.com/cncf/automation/blob/main/utilities/landscape-mcp-server/tools.go): `utilities/landscape-mcp-server/tools.go`

### Community programs

- [Kubestronaut administration](https://github.com/cncf/automation/blob/main/Kubestronaut/AddGoldenKubestronauts.py): `Kubestronaut/AddGoldenKubestronauts.py`
- [Shipping acknowledgements](https://github.com/cncf/automation/blob/main/Kubestronaut/AckKubestronautAndGKSwagShipped.py): `Kubestronaut/AckKubestronautAndGKSwagShipped.py`
- [Shopify cart generation](https://github.com/cncf/automation/blob/main/Kubestronaut/GenerateShopifyCartFromSpreadsheet.py): `Kubestronaut/GenerateShopifyCartFromSpreadsheet.py`
- [People records](https://github.com/cncf/automation/blob/main/Kubestronaut/CNCFInsertKubestronautInPeople_json.py): `Kubestronaut/CNCFInsertKubestronautInPeople_json.py`
- [Ambassador records](https://github.com/cncf/automation/blob/main/Ambassadors/CNCFInsertAmbassadorInPeople_json.py): `Ambassadors/CNCFInsertAmbassadorInPeople_json.py`

### Other components

- **GitHub Actions**
- **Landscape dataset**
- **Program spreadsheets**

## Connections

- GitHub Actions → VM image runner: triggers
- GitHub Actions → OCI VM image runner: triggers
- GitHub Actions → Cloud runners: triggers
- GitHub Actions → KubeVirt runner: triggers
- GitHub Actions → GCP runner: triggers
- Cloud runners → Ephemeral machines: creates and deletes (evidence: `ci/cloudrunners/oci/main.go`)
- Project bootstrap → Project scaffold: generates
- Project validator CLI → Project validation: runs (evidence: `utilities/dot-project/cmd/validator/main.go`)
- Landscape updater → Landscape dataset: updates
- Lifecycle audit → Audit source checks: cross-checks (evidence: `README.md`)
- Landscape sync → Landscape dataset: fetches and compares (evidence: `utilities/landscape-sync/main.go`)
- Landscape MCP server → Dataset loading: loads and refreshes (evidence: `utilities/landscape-mcp-server/main.go`)
- Landscape MCP server → MCP tools: dispatches requests
- Dataset loading → Landscape dataset: loads
- Kubestronaut administration → Program spreadsheets: reads and updates (evidence: `Kubestronaut/AddGoldenKubestronauts.py`)
- Shipping acknowledgements → Program spreadsheets: annotates shipment (evidence: `Kubestronaut/AckKubestronautAndGKSwagShipped.py`)
- Shopify cart generation → Program spreadsheets: reads orders
- Kubestronaut administration → People records: updates records
