# trailsamuel/k8s-policy-lab architecture

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

- Interactive diagram: https://gitdiagram.com/trailsamuel/k8s-policy-lab
- Repository: https://github.com/trailsamuel/k8s-policy-lab

## Overview

k8s-policy-lab is a learning lab that demonstrates how Kubernetes security controls evolve: a local kind cluster first accepts risky workloads, RBAC limits identities but permits a dangerous pod-creation action, and Kyverno admission policies reject unsafe objects. The documented workflow also includes repeatable policy tests and CIS Benchmark mapping. Paths and relationships below follow the README; source excerpts were unavailable, so undocumented implementation links are omitted.

Main entry points: [`workloads/privileged-pod.yaml`](https://github.com/trailsamuel/k8s-policy-lab/blob/main/workloads/privileged-pod.yaml) (Workload manifests), [`workloads/app-pod.yaml`](https://github.com/trailsamuel/k8s-policy-lab/blob/main/workloads/app-pod.yaml) (Application pod), [`rbac/01-overpermissioned-role.yaml`](https://github.com/trailsamuel/k8s-policy-lab/blob/main/rbac/01-overpermissioned-role.yaml) (Over-permissioned role), [`tests/kyverno-test.yaml`](https://github.com/trailsamuel/k8s-policy-lab/blob/main/tests/kyverno-test.yaml) (Policy test suite)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cluster["Cluster Lab"]
  node_kind["kind cluster<br/>[kind-config.yaml]"]
  node_api["Kubernetes API server"]
  node_workloads["Workload manifests"]
  node_app["Application pod<br/>[app-pod.yaml]"]
end

subgraph group_identity["Identity and RBAC"]
  node_namespaces["dev and prod<br/>[00-namespaces.yaml]"]
  node_role["Over-permissioned role"]
  node_rbac["RBAC authorization"]
end

subgraph group_admission["Admission Controls"]
  node_kyverno["Kyverno admission"]
  node_privileged["Block privileged pods"]
  node_hostns["Block host namespaces"]
  node_hostpath["Block host paths"]
  node_nonroot["Require non-root"]
end

subgraph group_assurance["Policy Assurance"]
  node_testdefs["Policy test suite<br/>[kyverno-test.yaml]"]
  node_testresources["Test resources"]
  node_cis["CIS control mapping<br/>[cis-mapping.md]"]
end

node_operator(("Lab operator"))

node_operator -->|"creates cluster"| node_kind
node_operator -->|"applies manifests"| node_workloads
node_operator -->|"applies manifest"| node_app
node_workloads -->|"submits pod"| node_api
node_app -->|"submits pod"| node_api
node_operator -->|"applies setup"| node_namespaces
node_operator -->|"applies setup"| node_role
node_role -->|"grants permissions"| node_rbac
node_rbac -->|"authorizes requests"| node_api
node_api -->|"checks admission"| node_kyverno
node_kyverno -->|"checks policy"| node_privileged
node_kyverno -->|"checks policy"| node_hostns
node_kyverno -->|"checks policy"| node_hostpath
node_kyverno -->|"checks policy"| node_nonroot
node_operator -->|"runs tests"| node_testdefs
node_testdefs -->|"pairs resources"| node_testresources
node_operator -->|"consults mapping"| node_cis

click node_kind "https://github.com/trailsamuel/k8s-policy-lab/blob/main/cluster/kind-config.yaml"
click node_workloads "https://github.com/trailsamuel/k8s-policy-lab/blob/main/workloads/privileged-pod.yaml"
click node_app "https://github.com/trailsamuel/k8s-policy-lab/blob/main/workloads/app-pod.yaml"
click node_namespaces "https://github.com/trailsamuel/k8s-policy-lab/blob/main/rbac/00-namespaces.yaml"
click node_role "https://github.com/trailsamuel/k8s-policy-lab/blob/main/rbac/01-overpermissioned-role.yaml"
click node_privileged "https://github.com/trailsamuel/k8s-policy-lab/blob/main/policies/disallow-privileged.yaml"
click node_hostns "https://github.com/trailsamuel/k8s-policy-lab/blob/main/policies/disallow-host-namespaces.yaml"
click node_hostpath "https://github.com/trailsamuel/k8s-policy-lab/blob/main/policies/disallow-host-path.yaml"
click node_nonroot "https://github.com/trailsamuel/k8s-policy-lab/blob/main/policies/require-run-as-nonroot.yaml"
click node_testdefs "https://github.com/trailsamuel/k8s-policy-lab/blob/main/tests/kyverno-test.yaml"
click node_testresources "https://github.com/trailsamuel/k8s-policy-lab/blob/main/tests/bad-host-network.yaml"
click node_cis "https://github.com/trailsamuel/k8s-policy-lab/blob/main/docs/cis-mapping.md"

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_kind,node_api,node_workloads,node_app toneBlue
class node_namespaces,node_role,node_rbac toneAmber
class node_kyverno,node_privileged,node_hostns,node_hostpath,node_nonroot toneMint
class node_testdefs,node_testresources,node_cis toneRose
class node_operator toneIndigo
```

## Components

### Cluster Lab

- [kind cluster](https://github.com/trailsamuel/k8s-policy-lab/blob/main/cluster/kind-config.yaml): `cluster/kind-config.yaml`
- **Kubernetes API server**
- [Workload manifests](https://github.com/trailsamuel/k8s-policy-lab/blob/main/workloads/privileged-pod.yaml): `workloads/privileged-pod.yaml`
- [Application pod](https://github.com/trailsamuel/k8s-policy-lab/blob/main/workloads/app-pod.yaml): `workloads/app-pod.yaml`

### Identity and RBAC

- [dev and prod](https://github.com/trailsamuel/k8s-policy-lab/blob/main/rbac/00-namespaces.yaml): `rbac/00-namespaces.yaml`
- [Over-permissioned role](https://github.com/trailsamuel/k8s-policy-lab/blob/main/rbac/01-overpermissioned-role.yaml): `rbac/01-overpermissioned-role.yaml`
- **RBAC authorization**

### Admission Controls

- **Kyverno admission**
- [Block privileged pods](https://github.com/trailsamuel/k8s-policy-lab/blob/main/policies/disallow-privileged.yaml): `policies/disallow-privileged.yaml`
- [Block host namespaces](https://github.com/trailsamuel/k8s-policy-lab/blob/main/policies/disallow-host-namespaces.yaml): `policies/disallow-host-namespaces.yaml`
- [Block host paths](https://github.com/trailsamuel/k8s-policy-lab/blob/main/policies/disallow-host-path.yaml): `policies/disallow-host-path.yaml`
- [Require non-root](https://github.com/trailsamuel/k8s-policy-lab/blob/main/policies/require-run-as-nonroot.yaml): `policies/require-run-as-nonroot.yaml`

### Policy Assurance

- [Policy test suite](https://github.com/trailsamuel/k8s-policy-lab/blob/main/tests/kyverno-test.yaml): `tests/kyverno-test.yaml`
- [Test resources](https://github.com/trailsamuel/k8s-policy-lab/blob/main/tests/bad-host-network.yaml): `tests/bad-host-network.yaml`
- [CIS control mapping](https://github.com/trailsamuel/k8s-policy-lab/blob/main/docs/cis-mapping.md): `docs/cis-mapping.md`

### Other components

- **Lab operator**

## Connections

- Lab operator → kind cluster: creates cluster (evidence: `README.md`)
- Lab operator → Workload manifests: applies manifests (evidence: `README.md`)
- Lab operator → Application pod: applies manifest (evidence: `README.md`)
- Workload manifests → Kubernetes API server: submits pod (evidence: `README.md`)
- Application pod → Kubernetes API server: submits pod (evidence: `README.md`)
- Lab operator → dev and prod: applies setup (evidence: `README.md`)
- Lab operator → Over-permissioned role: applies setup (evidence: `README.md`)
- Over-permissioned role → RBAC authorization: grants permissions (evidence: `README.md`)
- RBAC authorization → Kubernetes API server: authorizes requests (evidence: `README.md`)
- Kubernetes API server → Kyverno admission: checks admission (evidence: `README.md`)
- Kyverno admission → Block privileged pods: checks policy (evidence: `README.md`)
- Kyverno admission → Block host namespaces: checks policy (evidence: `README.md`)
- Kyverno admission → Block host paths: checks policy (evidence: `README.md`)
- Kyverno admission → Require non-root: checks policy (evidence: `README.md`)
- Lab operator → Policy test suite: runs tests (evidence: `README.md`)
- Policy test suite → Test resources: pairs resources (evidence: `README.md`)
- Lab operator → CIS control mapping: consults mapping (evidence: `README.md`)