# megandil/k8s-kyverno architecture

> Architecture diagram of the GitHub repository megandil/k8s-kyverno, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/megandil/k8s-kyverno
- Repository: https://github.com/megandil/k8s-kyverno

## Overview

##### Project type and purpose
- This is an infrastructure-as-code / DevOps demonstration project showing how to implement and operate the Kyverno policy engine on a lightweight Kubernetes cluster (K3s).
- It includes:
- Sample Kyverno policies (validation, mutation, generation) and test manifests in `/pruebas`.
- A GitOps delivery pipeline using ArgoCD to deploy Kyverno, Policy Reporter UI, and a sample “Temperaturas” app.
- A standalone JSON-to-PDF export pipeline (`/json2pdf`) that fetches Policy Reporter UI logs via its API, transforms them with Python + Asciidoc, and generates a PDF.

##### Analysis of file structure
- Top level:
- README.md – detailed architecture and workflow description.
- `json2pdf/` – shell script (`json2pdf.sh`), Asciidoc template (`logs.adoc`), Python processor (`py/tratar-json.py`), and sample output PDF.
- `pruebas/` – sample resource YAMLs for validation (`validacion`), mutation (`mutacion`), and generation (`generacion`) policies.
- No traditional “src” folder for an application—this is primarily a configuration and automation project.

##### Insights from the README
- Core components:
- K3s Kubernetes cluster
- Kyverno (as an admission controller via webhook)
- Policy Reporter UI (ingested via Helm into its own namespace)
- ArgoCD (four GitOps “Apps”: Control-apps, Kyverno-app, policy-reporter-ui-app, temp-app)
- Temperaturas application (frontend + backend containers)
- External Git repository (source of truth)
- JSON-to-PDF pipeline that calls Policy Reporter UI’s API

a. Main components
- External Git server (GitHub repo with manifests & policies)
- ArgoCD server & controller (deployed in cluster)
- K3s control plane (API server, etcd)
- Kyverno admission controller (webhook deployment)
- Policy Reporter UI service + API (with its own ingress)
- Sample app “Temperaturas” (frontend and backend Deployments + Services)
- Namespaces (e.g., `kyverno`, `policy-reporter`, `temperaturas`)
- JSON-to-PDF export pipeline (runs externally or via a dedicated Pod/Job)
- Ingress resources (for Policy Reporter UI and Temperaturas UI)

b. Relationships and interactions
1. Developer pushes YAMLs & policies to Git → ArgoCD detects changes (GitOps sync).
2. ArgoCD applies manifests in correct order (Sync-waves):
- Control-apps → Kyverno-app → Policy-reporter-ui-app → create temp-app’s namespace → temp-app.
3. Kubernetes API Server intercepts resource create/update requests → forwards to Kyverno webhook → Kyverno enforces or audits (validation/mutation/generation).
4. Kyverno writes results into PolicyReport CRDs.
5. Policy Reporter UI queries PolicyReport CRDs via Kubernetes API to build dashboard & logs.
6. JSON-to-PDF script calls Policy Reporter UI REST API → obtains logs in JSON → Python processes JSON → Asciidoc template → asciidoctor-pdf → output PDF.

c. Architectural patterns & design principles
- Admission-control via webhooks (separation of control plane & policy engine)
- GitOps (ArgoCD) for declarative, versioned deployments
- Micro-services layering: policy engine, reporting UI, sample application
- Automation pipeline (shell + Python + Asciidoc) for documentation generation

d. Key technologies/frameworks
- K3s (lightweight Kubernetes)
- Kyverno (Kubernetes-native policy engine)
- ArgoCD (GitOps controller)
- Policy Reporter UI (React + API server)
- Bash, Python 3.9, Asciidoc, Asciidoctor-pdf

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External GitOps Source
    subgraph "External Git Repository" 
        direction TB
        Git["Git Repo"]:::gitops
        README["README.md"]:::gitops
        images["images/"]:::gitops
        click README "https://github.com/megandil/k8s-kyverno/blob/main/README.md"
        click images "https://github.com/megandil/k8s-kyverno/tree/main/images/"
    end

    %% ArgoCD
    subgraph "GitOps Delivery (ArgoCD)" 
        direction TB
        ArgoCD["ArgoCD Server & Controller"]:::gitops
        Git -->|sync| ArgoCD
    end

    %% Kubernetes Cluster
    subgraph "K3s Cluster"
        direction TB
        subgraph "Control Plane" 
            direction TB
            APIServer["Kube API Server"]:::control
            Etcd["etcd"]:::control
            APIServer --> Etcd
        end

        subgraph "Namespace: kyverno"
            direction TB
            Kyverno["Kyverno Admission Controller (Webhook)"]:::control
        end

        subgraph "Namespace: policy-reporter"
            direction TB
            PRUI["Policy Reporter UI"]:::app
            PRAPI["Policy Reporter UI API"]:::app
            PRUI --> PRAPI
        end

        subgraph "Namespace: temperaturas"
            direction TB
            subgraph "Frontend"
                TFDep["Temperaturas Frontend Deployment"]:::app
                TFSer["Frontend Service"]:::app
                TFDep --> TFSer
            end
            subgraph "Backend"
                TBDep["Temperaturas Backend Deployment"]:::app
                TBSer["Backend Service"]:::app
                TBDep --> TBSer
            end
            TFSer -->|ingress| IngressTemp
            PRUI -->|ingress| IngressPR
        end

        %% CRD flow
        APIServer -->|webhook call| Kyverno
        Kyverno -->|writes PolicyReport CRD| APIServer
        PRAPI -->|queries CRDs| APIServer
    end

    %% Ingress resources
    IngressPR["Ingress: /policies"]:::app
    IngressTemp["Ingress: /"]:::app

    %% ArgoCD Sync Waves
    ArgoCD -->|Wave1: Control-apps| APIServer
    ArgoCD -->|Wave2: Kyverno-app| Kyverno
    ArgoCD -->|Wave3: policy-reporter-ui-app| PRUI
    ArgoCD -->|Wave4: temp-app| TFDep

    %% JSON-to-PDF Pipeline
    subgraph "External Automation: JSON-to-PDF" 
        direction TB
        Script["json2pdf.sh"]:::ext
        ADOC["logs.adoc"]:::ext
        Py["tratar-json.py"]:::ext
        PDF["logs.pdf"]:::ext
        PRAPI -->|REST API logs| Script
        Script --> ADOC
        ADOC --> Py
        Py --> PDF
        click Script "https://github.com/megandil/k8s-kyverno/blob/main/json2pdf/json2pdf.sh"
        click ADOC "https://github.com/megandil/k8s-kyverno/blob/main/json2pdf/logs.adoc"
        click Py "https://github.com/megandil/k8s-kyverno/blob/main/json2pdf/py/tratar-json.py"
        click PDF "https://github.com/megandil/k8s-kyverno/blob/main/json2pdf/logs.pdf"
    end

    %% Sample Policies and Tests
    subgraph "Sample Kyverno Policies & Tests" 
        direction TB
        subgraph "Validation"
            VNOK["namespace-correcto-label.yaml"]:::policy
            VNFAIL["namespace-falla-label.yaml"]:::policy
            VPOL["requiere-ns-etiqueta-dept.yaml"]:::policy
            click VNOK "https://github.com/megandil/k8s-kyverno/blob/main/pruebas/validacion/namespace-correcto-label.yaml"
            click VNFAIL "https://github.com/megandil/k8s-kyverno/blob/main/pruebas/validacion/namespace-falla-label.yaml"
            click VPOL "https://github.com/megandil/k8s-kyverno/blob/main/pruebas/validacion/policy/requiere-ns-etiqueta-dept.yaml"
        end
        subgraph "Mutation"
            MPOD["pod.yaml"]:::policy
            MPOL["cambiar-image-pull-policy.yaml"]:::policy
            click MPOD "https://github.com/megandil/k8s-kyverno/blob/main/pruebas/mutacion/pod.yaml"
            click MPOL "https://github.com/megandil/k8s-kyverno/blob/main/pruebas/mutacion/policy/cambiar-image-pull-policy.yaml"
        end
        subgraph "Generation"
            GNS["namespace.yaml"]:::policy
            GPOL["quota-limitrange.yaml"]:::policy
            click GNS "https://github.com/megandil/k8s-kyverno/blob/main/pruebas/generacion/namespace.yaml"
            click GPOL "https://github.com/megandil/k8s-kyverno/blob/main/pruebas/generacion/policy/quota-limitrange.yaml"
        end
    end

    %% Styles
    classDef gitops fill:#FFEDD5,stroke:#FB923C,color:#9A3412
    classDef control fill:#DBEAFE,stroke:#3B82F6,color:#1E40AF
    classDef app fill:#ECFCCB,stroke:#65A30D,color:#365314
    classDef ext fill:#F5F3FF,stroke:#8B5CF6,color:#4C1D95
    classDef policy fill:#FEF3C7,stroke:#F59E0B,color:#92400E
```
