# yannicksiewe/k8s-iam-operator architecture

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

- Interactive diagram: https://gitdiagram.com/yannicksiewe/k8s-iam-operator
- Repository: https://github.com/yannicksiewe/k8s-iam-operator

## Overview

k8s-iam-operator reconciles Kubernetes User, Group, and Role custom resources into ServiceAccounts, namespaces, RBAC bindings, optional quotas and network policies, and kubeconfigs. The principal workflow runs from Kubernetes events through Kopf handlers and domain services to Kubernetes API repositories. Separate branches cover namespace-triggered reconciliation, health and metrics endpoints, audit logging, and tracing. The README documents the layer structure; source excerpts confirm selected service-to-repository calls. Several subsystems are represented from documented capabilities and the source index, not inspected implementation details.

Main entry points: [`app/services/user_service.py`](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/services/user_service.py) (User lifecycle), [`app/container.py`](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/container.py) (Dependency container), [`app/repositories/base.py`](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/base.py) (Kubernetes client base), [`app/kopf_handlers/user_handlers.py`](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/kopf_handlers/user_handlers.py) (User handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator events"]
  node_user_handler["User handler<br/>[user_handlers.py]"]
  node_group_handler["Group handler<br/>[group_handlers.py]"]
  node_role_handler["Role handler<br/>[role_handlers.py]"]
  node_ns_handler["Namespace handler"]
  node_container["Dependency container<br/>[container.py]"]
  node_config["Operator configuration<br/>[config.py]"]
  node_exceptions["Error handling<br/>[exceptions.py]"]
end

subgraph group_domain["IAM domain"]
  node_user_service["User lifecycle<br/>[user_service.py]"]
  node_group_service["Group access<br/>[group_service.py]"]
  node_role_service["Role definitions<br/>[role_service.py]"]
  node_rbac_service["RBAC bindings<br/>[rbac_service.py]"]
  node_kubeconfig_service["Kubeconfig generation"]
  node_user_model["User resource model<br/>[user.py]"]
  node_group_model["Group resource model<br/>[group.py]"]
  node_role_model["Role resource model<br/>[role.py]"]
  node_validation["CRD validation<br/>[validators.py]"]
end

subgraph group_k8s["Kubernetes access"]
  node_namespace_repo["Namespace repository"]
  node_sa_repo["ServiceAccount repository"]
  node_rbac_repo["RBAC repository<br/>[rbac_repository.py]"]
  node_quota_repo["Quota repository"]
  node_policy_repo["Network policy repository"]
  node_repo_base["Kubernetes client base<br/>[base.py]"]
end

subgraph group_ops["Operations"]
  node_audit["Audit logging<br/>[audit.py]"]
  node_metrics["Prometheus metrics<br/>[metrics.py]"]
  node_health["Health endpoint<br/>[health.py]"]
  node_tracing["Tracing<br/>[tracing.py]"]
end

node_k8s_events(("Kubernetes events"))
node_kube_api[("Kubernetes API")]
node_prometheus(("Prometheus"))

node_k8s_events -->|"dispatches"| node_user_handler
node_k8s_events -->|"dispatches"| node_group_handler
node_k8s_events -->|"dispatches"| node_role_handler
node_k8s_events -->|"dispatches"| node_ns_handler
node_user_handler -->|"handles via"| node_user_service
node_group_handler -->|"handles via"| node_group_service
node_role_handler -->|"handles via"| node_role_service
node_ns_handler -->|"reconciles through"| node_rbac_service
node_user_service -->|"creates bindings"| node_rbac_service
node_user_service -->|"generates config"| node_kubeconfig_service
node_group_service -->|"uses"| node_rbac_service
node_role_service -->|"manages roles"| node_rbac_repo
node_rbac_service -->|"creates bindings"| node_rbac_repo
node_user_service -->|"creates accounts"| node_sa_repo
node_user_service -->|"provisions namespace"| node_namespace_repo
node_user_service -.->|"sets quotas"| node_quota_repo
node_user_service -->|"sets policies"| node_policy_repo
node_repo_base -->|"configures client"| node_kube_api
node_rbac_repo -->|"inherits"| node_repo_base
node_namespace_repo -->|"inherits"| node_repo_base
node_quota_repo -->|"inherits"| node_repo_base
node_policy_repo -->|"inherits"| node_repo_base
node_sa_repo -->|"inherits"| node_repo_base
node_user_handler -->|"gets services"| node_container
node_group_handler -->|"gets services"| node_container
node_role_handler -->|"gets services"| node_container
node_ns_handler -->|"gets services"| node_container
node_container -->|"wires logger"| node_audit
node_user_service -->|"validates input"| node_validation
node_user_handler -->|"parses resource"| node_user_model
node_group_handler -->|"parses resource"| node_group_model
node_role_handler -.->|"parses resource"| node_role_model
node_metrics -->|"exposes metrics"| node_prometheus
node_user_service -->|"records events"| node_audit
node_rbac_service -->|"records changes"| node_audit
node_user_handler -.->|"instrumented by"| node_tracing
node_container -.->|"configures services"| node_config

click node_user_handler "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/kopf_handlers/user_handlers.py"
click node_group_handler "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/kopf_handlers/group_handlers.py"
click node_role_handler "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/kopf_handlers/role_handlers.py"
click node_ns_handler "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/kopf_handlers/namespace_handlers.py"
click node_user_service "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/services/user_service.py"
click node_group_service "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/services/group_service.py"
click node_role_service "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/services/role_service.py"
click node_rbac_service "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/services/rbac_service.py"
click node_kubeconfig_service "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/services/kubeconfig_service.py"
click node_user_model "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/models/user.py"
click node_group_model "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/models/group.py"
click node_role_model "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/models/role.py"
click node_validation "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/validators.py"
click node_namespace_repo "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/namespace_repository.py"
click node_sa_repo "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/serviceaccount_repository.py"
click node_rbac_repo "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/rbac_repository.py"
click node_quota_repo "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/resource_quota_repository.py"
click node_policy_repo "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/network_policy_repository.py"
click node_repo_base "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/base.py"
click node_container "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/container.py"
click node_config "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/config.py"
click node_exceptions "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/exceptions.py"
click node_audit "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/utils/audit.py"
click node_metrics "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/api/metrics.py"
click node_health "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/api/health.py"
click node_tracing "https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/utils/tracing.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_user_handler,node_group_handler,node_role_handler,node_ns_handler,node_container,node_config,node_exceptions toneBlue
class node_user_service,node_group_service,node_role_service,node_rbac_service,node_kubeconfig_service,node_user_model,node_group_model,node_role_model,node_validation,node_kube_api toneAmber
class node_namespace_repo,node_sa_repo,node_rbac_repo,node_quota_repo,node_policy_repo,node_repo_base toneMint
class node_audit,node_metrics,node_health,node_tracing toneRose
class node_k8s_events,node_prometheus toneIndigo
```

## Components

### Operator events

- [User handler](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/kopf_handlers/user_handlers.py): `app/kopf_handlers/user_handlers.py`
- [Group handler](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/kopf_handlers/group_handlers.py): `app/kopf_handlers/group_handlers.py`
- [Role handler](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/kopf_handlers/role_handlers.py): `app/kopf_handlers/role_handlers.py`
- [Namespace handler](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/kopf_handlers/namespace_handlers.py): `app/kopf_handlers/namespace_handlers.py`
- [Dependency container](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/container.py): `app/container.py`
- [Operator configuration](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/config.py): `app/config.py`
- [Error handling](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/exceptions.py): `app/exceptions.py`

### IAM domain

- [User lifecycle](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/services/user_service.py): `app/services/user_service.py`
- [Group access](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/services/group_service.py): `app/services/group_service.py`
- [Role definitions](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/services/role_service.py): `app/services/role_service.py`
- [RBAC bindings](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/services/rbac_service.py): `app/services/rbac_service.py`
- [Kubeconfig generation](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/services/kubeconfig_service.py): `app/services/kubeconfig_service.py`
- [User resource model](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/models/user.py): `app/models/user.py`
- [Group resource model](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/models/group.py): `app/models/group.py`
- [Role resource model](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/models/role.py): `app/models/role.py`
- [CRD validation](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/validators.py): `app/validators.py`

### Kubernetes access

- [Namespace repository](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/namespace_repository.py): `app/repositories/namespace_repository.py`
- [ServiceAccount repository](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/serviceaccount_repository.py): `app/repositories/serviceaccount_repository.py`
- [RBAC repository](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/rbac_repository.py): `app/repositories/rbac_repository.py`
- [Quota repository](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/resource_quota_repository.py): `app/repositories/resource_quota_repository.py`
- [Network policy repository](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/network_policy_repository.py): `app/repositories/network_policy_repository.py`
- [Kubernetes client base](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/repositories/base.py): `app/repositories/base.py`

### Operations

- [Audit logging](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/utils/audit.py): `app/utils/audit.py`
- [Prometheus metrics](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/api/metrics.py): `app/api/metrics.py`
- [Health endpoint](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/api/health.py): `app/api/health.py`
- [Tracing](https://github.com/yannicksiewe/k8s-iam-operator/blob/main/app/utils/tracing.py): `app/utils/tracing.py`

### Other components

- **Kubernetes events**
- **Kubernetes API**
- **Prometheus**

## Connections

- Kubernetes events → User handler: dispatches (evidence: `README.md`)
- Kubernetes events → Group handler: dispatches (evidence: `README.md`)
- Kubernetes events → Role handler: dispatches (evidence: `README.md`)
- Kubernetes events → Namespace handler: dispatches (evidence: `app/kopf_handlers/namespace_handlers.py`)
- User handler → User lifecycle: handles via (evidence: `README.md`)
- Group handler → Group access: handles via (evidence: `README.md`)
- Role handler → Role definitions: handles via (evidence: `README.md`)
- Namespace handler → RBAC bindings: reconciles through (evidence: `app/kopf_handlers/namespace_handlers.py`)
- User lifecycle → RBAC bindings: creates bindings (evidence: `app/services/user_service.py`)
- User lifecycle → Kubeconfig generation: generates config (evidence: `app/services/user_service.py`)
- Group access → RBAC bindings: uses (evidence: `app/services/group_service.py`)
- Role definitions → RBAC repository: manages roles (evidence: `app/services/role_service.py`)
- RBAC bindings → RBAC repository: creates bindings (evidence: `app/services/rbac_service.py`)
- User lifecycle → ServiceAccount repository: creates accounts (evidence: `app/services/user_service.py`)
- User lifecycle → Namespace repository: provisions namespace (evidence: `app/services/user_service.py`)
- User lifecycle → Quota repository: sets quotas (evidence: `app/services/user_service.py`)
- User lifecycle → Network policy repository: sets policies (evidence: `app/services/user_service.py`)
- Kubernetes client base → Kubernetes API: configures client (evidence: `app/repositories/base.py`)
- RBAC repository → Kubernetes client base: inherits (evidence: `app/repositories/rbac_repository.py`)
- Namespace repository → Kubernetes client base: inherits (evidence: `app/repositories/namespace_repository.py`)
- Quota repository → Kubernetes client base: inherits (evidence: `app/repositories/resource_quota_repository.py`)
- Network policy repository → Kubernetes client base: inherits (evidence: `app/repositories/network_policy_repository.py`)
- ServiceAccount repository → Kubernetes client base: inherits (evidence: `app/repositories/serviceaccount_repository.py`)
- User handler → Dependency container: gets services (evidence: `app/kopf_handlers/user_handlers.py`)
- Group handler → Dependency container: gets services (evidence: `app/kopf_handlers/group_handlers.py`)
- Role handler → Dependency container: gets services (evidence: `app/kopf_handlers/role_handlers.py`)
- Namespace handler → Dependency container: gets services (evidence: `app/kopf_handlers/namespace_handlers.py`)
- Dependency container → Audit logging: wires logger (evidence: `app/container.py`)
- User lifecycle → CRD validation: validates input (evidence: `app/services/user_service.py`)
- User handler → User resource model: parses resource (evidence: `app/kopf_handlers/user_handlers.py`)
- Group handler → Group resource model: parses resource (evidence: `app/kopf_handlers/group_handlers.py`)
- Role handler → Role resource model: parses resource
- Prometheus metrics → Prometheus: exposes metrics (evidence: `README.md`)
- User lifecycle → Audit logging: records events (evidence: `app/services/user_service.py`)
- RBAC bindings → Audit logging: records changes (evidence: `app/services/rbac_service.py`)
- User handler → Tracing: instrumented by
- Dependency container → Operator configuration: configures services
