# h3xcat/h3xinfra architecture

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

- Interactive diagram: https://gitdiagram.com/h3xcat/h3xinfra
- Repository: https://github.com/h3xcat/h3xinfra

## Overview

H3x Infra is an Ansible-based deployment and operations project for a dual-stack, three-node K3s cluster. An operator configures production inventory and invokes the stack deployment command; Ansible uses that inventory to prepare servers and deploy cluster foundations and services. The resulting cluster provides networking, load balancing, TLS, DNS, gateway routing, storage, email, and identity capabilities. The graph follows the README’s documented stages and capabilities; detailed wiring within unsampled playbooks and charts is not inferred.

Main entry points: [`playbooks/stack-standup.yml`](https://github.com/h3xcat/h3xinfra/blob/main/playbooks/stack-standup.yml) (Stack deployment), [`bin/h3xinfra-deploy-stack`](https://github.com/h3xcat/h3xinfra/blob/main/bin/h3xinfra-deploy-stack) (Stack deploy command), [`playbooks/00-prep`](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/00-prep) (Server preparation), [`playbooks/01-k3s`](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/01-k3s) (K3s cluster)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deploy["Deployment"]
  node_inventory["Production inventory"]
  node_deploy_cmd["Stack deploy command"]
  node_stack["Stack deployment<br/>[stack-standup.yml]"]
end

subgraph group_foundation["Cluster foundation"]
  node_prep["Server preparation"]
  node_k3s["K3s cluster"]
end

subgraph group_network["Networking and access"]
  node_cilium["Cilium networking"]
  node_metallb["MetalLB load balancing"]
  node_certmanager["Certificate management"]
  node_externaldns["External DNS"]
  node_gateway["Envoy Gateway"]
end

subgraph group_services["Cluster services"]
  node_smb["SMB/CIFS driver"]
  node_longhorn["Longhorn storage"]
  node_mailu["Mailu email"]
  node_keycloak["Keycloak identity"]
end

subgraph group_operations["Operations"]
  node_updates["Server updates"]
  node_utilities["Cluster utilities"]
end

node_operator(("Operator"))
node_cluster_hosts(("Cluster servers"))
node_cloudflare(("Cloudflare"))

node_operator -->|"invokes"| node_deploy_cmd
node_operator -->|"configures"| node_inventory
node_deploy_cmd -->|"runs"| node_stack
node_stack -->|"uses"| node_inventory
node_stack -->|"deploys"| node_prep
node_stack -->|"deploys"| node_k3s
node_stack -->|"deploys"| node_cilium
node_stack -->|"deploys"| node_metallb
node_stack -->|"deploys"| node_certmanager
node_stack -->|"deploys"| node_externaldns
node_stack -->|"deploys"| node_gateway
node_stack -->|"deploys"| node_smb
node_stack -->|"deploys"| node_longhorn
node_stack -->|"deploys"| node_mailu
node_stack -->|"deploys"| node_keycloak
node_prep -->|"prepares"| node_cluster_hosts
node_k3s -->|"installs on"| node_cluster_hosts
node_certmanager -.->|"uses DNS provider"| node_cloudflare
node_externaldns -.->|"updates DNS"| node_cloudflare
node_operator -->|"invokes"| node_updates
node_operator -->|"invokes"| node_utilities

click node_inventory "https://github.com/h3xcat/h3xinfra/tree/main/inventory/production"
click node_deploy_cmd "https://github.com/h3xcat/h3xinfra/blob/main/bin/h3xinfra-deploy-stack"
click node_stack "https://github.com/h3xcat/h3xinfra/blob/main/playbooks/stack-standup.yml"
click node_prep "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/00-prep"
click node_k3s "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/01-k3s"
click node_cilium "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/02-cilium"
click node_metallb "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/03-metallb"
click node_certmanager "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/05-certmanager"
click node_externaldns "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/06-externaldns"
click node_gateway "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/07-gateway"
click node_smb "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/08-smb"
click node_longhorn "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/09-longhorn"
click node_mailu "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/10-mailu"
click node_keycloak "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/10-keycloak"
click node_updates "https://github.com/h3xcat/h3xinfra/blob/main/bin/h3xinfra-update-servers"
click node_utilities "https://github.com/h3xcat/h3xinfra/tree/main/playbooks/99-utils"

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_inventory,node_deploy_cmd,node_stack toneBlue
class node_prep,node_k3s toneAmber
class node_cilium,node_metallb,node_certmanager,node_externaldns,node_gateway,node_cluster_hosts toneMint
class node_smb,node_longhorn,node_mailu,node_keycloak toneRose
class node_updates,node_utilities,node_operator,node_cloudflare toneIndigo
```

## Components

### Deployment

- [Production inventory](https://github.com/h3xcat/h3xinfra/tree/main/inventory/production): `inventory/production`
- [Stack deploy command](https://github.com/h3xcat/h3xinfra/blob/main/bin/h3xinfra-deploy-stack): `bin/h3xinfra-deploy-stack`
- [Stack deployment](https://github.com/h3xcat/h3xinfra/blob/main/playbooks/stack-standup.yml): `playbooks/stack-standup.yml`

### Cluster foundation

- [Server preparation](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/00-prep): `playbooks/00-prep`
- [K3s cluster](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/01-k3s): `playbooks/01-k3s`

### Networking and access

- [Cilium networking](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/02-cilium): `playbooks/02-cilium`
- [MetalLB load balancing](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/03-metallb): `playbooks/03-metallb`
- [Certificate management](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/05-certmanager): `playbooks/05-certmanager`
- [External DNS](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/06-externaldns): `playbooks/06-externaldns`
- [Envoy Gateway](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/07-gateway): `playbooks/07-gateway`

### Cluster services

- [SMB/CIFS driver](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/08-smb): `playbooks/08-smb`
- [Longhorn storage](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/09-longhorn): `playbooks/09-longhorn`
- [Mailu email](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/10-mailu): `playbooks/10-mailu`
- [Keycloak identity](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/10-keycloak): `playbooks/10-keycloak`

### Operations

- [Server updates](https://github.com/h3xcat/h3xinfra/blob/main/bin/h3xinfra-update-servers): `bin/h3xinfra-update-servers`
- [Cluster utilities](https://github.com/h3xcat/h3xinfra/tree/main/playbooks/99-utils): `playbooks/99-utils`

### Other components

- **Operator**
- **Cluster servers**
- **Cloudflare**

## Connections

- Operator → Stack deploy command: invokes
- Operator → Production inventory: configures
- Stack deploy command → Stack deployment: runs
- Stack deployment → Production inventory: uses
- Stack deployment → Server preparation: deploys
- Stack deployment → K3s cluster: deploys
- Stack deployment → Cilium networking: deploys
- Stack deployment → MetalLB load balancing: deploys
- Stack deployment → Certificate management: deploys
- Stack deployment → External DNS: deploys
- Stack deployment → Envoy Gateway: deploys
- Stack deployment → SMB/CIFS driver: deploys
- Stack deployment → Longhorn storage: deploys
- Stack deployment → Mailu email: deploys
- Stack deployment → Keycloak identity: deploys
- Server preparation → Cluster servers: prepares
- K3s cluster → Cluster servers: installs on
- Certificate management → Cloudflare: uses DNS provider
- External DNS → Cloudflare: updates DNS
- Operator → Server updates: invokes
- Operator → Cluster utilities: invokes