# open-policy-agent/kube-mgmt architecture

> Architecture diagram of the GitHub repository open-policy-agent/kube-mgmt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-policy-agent/kube-mgmt
- Repository: https://github.com/open-policy-agent/kube-mgmt

## Overview

##### Project type and purpose
- This is a backend Kubernetes‐native management service (no UI) for loading Open Policy Agent (OPA) policies and data and replicating Kubernetes resources into OPA.
- Written in Go, packaged as a CLI (`cmd/kube-mgmt`), with a Helm chart (`charts/opa-kube-mgmt`) for deployment into a K8s cluster.

##### File structure
- Top-level directories:
- cmd/kube-mgmt: entry point and flag parsing
- pkg/ & internal/: core logic for watching ConfigMaps, Kubernetes resources, and interacting with OPA
- charts/opa-kube-mgmt: Helm chart templates for Deployment, Service, RBAC, WebhookConfiguration, etc.
- test/, examples/: e2e fixtures, unit tests, usage examples
- Key config files: `justfile`, `skaffold.yaml`, Helm values schemas.
- CI pipeline in `.github/workflows` builds Docker images & publishes Helm chart.

##### README for additional insights
- kube-mgmt watches ConfigMaps labeled for policy/data and replicates arbitrary K8s resources.
- It uses the Kubernetes API (via client‐go) to LIST/WATCH ConfigMaps and resources.
- It calls OPA’s HTTP API (PUT/DELETE for policies, PUT/PATCH for data).
- It supports Admission Control as a validating webhook.

##### Main components
a. Kubernetes Control Plane
- API Server (authenticates & authorizes kube-mgmt’s service account)
- etcd (persistent store for K8s resources) – optional detail
b. kube-mgmt Pod
- Watches ConfigMaps & specified resources via K8s client
- Internals:
- ConfigMap watcher → policy/data loader
- Resource replicator → caches objects
- OPA client → PUT/DELETE v1/policy and PUT/PATCH v1/data
c. OPA Pod or sidecar
- Exposes REST API (`/v1/data`, `/v1/policy`, `/health`, `/metrics`)
- Hosts admission webhook server (via Kubernetes WebhookConfiguration)
d. Kubernetes Resources
- ConfigMaps (labeled `openpolicyagent.org/policy=rego` or `openpolicyagent.org/data=opa`)
- Namespaced & cluster‐scoped resources (Pods, Services, CRDs) being replicated
e. External clients
- Kubernetes API Server calling OPA for admission decisions
- Other clients querying OPA for policy decisions (optional)

##### Architectural patterns and design principles
- Event‐driven design: uses K8s watch API to react to resource changes
- Single responsibility: kube-mgmt focuses solely on syncing policies/data and replication
- Declarative deployment: Helm chart expresses Deployment, RBAC, Service, WebhookConfiguration
- Observability: exposes `/metrics` endpoint for Prometheus, `/health` for liveness/readiness

##### Detail level
- ConfigMap → annotation update loop
- Flag/config schema influencing behavior (`--namespaces`, `--replicate`, `--replicate-path`)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Kubernetes Control Plane
    subgraph "Kubernetes Control Plane"
        API["API Server"]:::cp
        ETCD["etcd"]:::cp
    end

    %% Application Layer
    subgraph "Application Layer"
        subgraph "kube-mgmt Pod"
            CLI["kube-mgmt CLI"]:::km
            CMWatcher["ConfigMap Watcher"]:::km
            DataLoader["Data Loader"]:::km
            Replicator["Dynamic Resource Replicator"]:::km
            OPAClient["OPA HTTP Client"]:::km
            Types["Core Types"]:::km
            Version["Version Module"]:::km
        end
        subgraph "OPA Pod"
            APIREST["OPA REST API\n(/v1/data, /v1/policy, /health, /metrics)"]:::opa
            Admission["Admission Webhook Server"]:::opa
        end
    end

    %% Kubernetes Resources
    ConfigMap["ConfigMaps\n(policy/data)"]:::res
    Resources["Kubernetes Resources\n(Pods, Services, CRDs)"]:::res
    External["External Clients"]:::ext

    %% Helm Chart
    Helm["Helm Chart\n(charts/opa-kube-mgmt)"]:::chart

    %% Interactions
    API -->|"LIST/WATCH ConfigMaps"| CMWatcher
    API -->|"LIST/WATCH Resources"| Replicator
    CMWatcher -->|"load/unload policy/data"| OPAClient
    Replicator -->|"cache objects"| OPAClient
    OPAClient -->|"PUT/DELETE policies\nPUT/PATCH data"| APIREST
    API -->|"AdmissionReview"| Admission
    External -->|"policy queries"| APIREST
    CMWatcher -->|"annotate status"| API
    Helm -->|"deploys"| CLI
    Helm -->|"deploys"| APIREST
    Helm -->|"deploys"| Admission

    %% Resource Inputs
    ConfigMap --> CMWatcher
    Resources --> Replicator

    %% Click Events
    click CLI "https://github.com/open-policy-agent/kube-mgmt/blob/master/cmd/kube-mgmt/main.go"
    click CMWatcher "https://github.com/open-policy-agent/kube-mgmt/blob/master/pkg/configmap/configmap.go"
    click DataLoader "https://github.com/open-policy-agent/kube-mgmt/blob/master/pkg/data/generic.go"
    click Replicator "https://github.com/open-policy-agent/kube-mgmt/blob/master/pkg/dynamicdata/dynamicdata.go"
    click OPAClient "https://github.com/open-policy-agent/kube-mgmt/blob/master/pkg/opa/opa.go"
    click Types "https://github.com/open-policy-agent/kube-mgmt/blob/master/pkg/types/types.go"
    click Version "https://github.com/open-policy-agent/kube-mgmt/blob/master/pkg/version/version.go"
    click Helm "https://github.com/open-policy-agent/kube-mgmt/tree/master/charts/opa-kube-mgmt/"

    %% Styles
    classDef cp fill:#e0ffe0,stroke:#0a5500
    classDef km fill:#ffe0b2,stroke:#b25800
    classDef opa fill:#bbdefb,stroke:#0a3f78
    classDef chart fill:#f3e5f5,stroke:#6a1b9a,stroke-dasharray: 5 5
    classDef res fill:#fff3e0,stroke:#e65100,stroke-dasharray: 2 2
    classDef ext fill:#f0f4c3,stroke:#827717,stroke-dasharray: 4 2
```
