# ca-gip/kubi architecture

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

- Interactive diagram: https://gitdiagram.com/ca-gip/kubi
- Repository: https://github.com/ca-gip/kubi

## Overview

Kubi provides LDAP-backed Kubernetes token issuance and authentication, plus an operator that converts LDAP group conventions into tenant resources and optionally provisions network policies. The principal flow is credentials → LDAP identity and membership checks → token/config response, followed by Kubernetes TokenReview validation. Operator controllers and custom-resource support are included as separate product stages. Wiring for unsampled operator and token-provider internals is based only on README capabilities and the available tree.

Main entry points: [`internal/ldap/client.go`](https://github.com/ca-gip/kubi/blob/master/internal/ldap/client.go) (LDAP Client), [`internal/services/project-provisionner.go`](https://github.com/ca-gip/kubi/blob/master/internal/services/project-provisionner.go) (Tenant Provisioning), [`cmd/operator/main.go`](https://github.com/ca-gip/kubi/blob/master/cmd/operator/main.go) (Operator Runtime), [`cmd/api/main.go`](https://github.com/ca-gip/kubi/blob/master/cmd/api/main.go) (API HTTP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Token API"]
  node_api_entry["API HTTP Server<br/>[main.go]"]
  node_basic_auth["Basic Auth<br/>[httpauth.go]"]
  node_token_issuer["Token Issuer<br/>[token-provider.go]"]
end

subgraph group_authn["Token Authentication"]
  node_authn_entry["Authentication Webhook<br/>[main.go]"]
  node_authn_handler["TokenReview Handler"]
end

subgraph group_operator["Tenant Operator"]
  node_operator_entry["Operator Runtime<br/>[main.go]"]
  node_project_sync["LDAP Project Sync"]
  node_provision["Tenant Provisioning"]
  node_namespace_service["Namespace Resources<br/>[namespaces.go]"]
  node_rolebindings["Role Bindings<br/>[rolebindings.go]"]
  node_serviceaccounts["Service Accounts<br/>[serviceaccounts.go]"]
  node_netpol_watch["Policy Config Watcher"]
  node_netpol_service["Network Policies<br/>[netpols.go]"]
end

subgraph group_core["Shared Domain"]
  node_ldap_client["LDAP Client<br/>[client.go]"]
  node_memberships["Group Memberships<br/>[membership.go]"]
  node_project_parse["Group Parser<br/>[constructors.go]"]
  node_crd_types["Kubi CRD Types<br/>[types.go]"]
  node_clientset["CRD Client<br/>[clientset.go]"]
  node_config["Runtime Configuration<br/>[config.go]"]
end

node_cli(("Kubi CLI"))
node_api_server(("API Server"))
node_ldap_service[("LDAP / AD")]
node_kube_api[("Kubernetes API")]

node_cli -->|"requests tokens"| node_api_entry
node_api_entry -->|"routes protected endpoints"| node_basic_auth
node_basic_auth -->|"authenticates user"| node_ldap_client
node_ldap_client -->|"binds and searches"| node_ldap_service
node_ldap_client -->|"loads memberships"| node_memberships
node_basic_auth -->|"invokes protected handlers"| node_token_issuer
node_api_entry -->|"loads settings"| node_config
node_api_server -->|"posts TokenReview"| node_authn_entry
node_authn_entry -->|"routes request"| node_authn_handler
node_authn_handler -->|"verifies token"| node_token_issuer
node_authn_handler -->|"returns review status"| node_api_server
node_operator_entry -->|"starts project watch"| node_project_sync
node_project_sync -->|"lists LDAP projects"| node_ldap_client
node_ldap_client -->|"parses group names"| node_project_parse
node_project_sync -->|"reconciles projects"| node_provision
node_provision -->|"manages namespaces"| node_namespace_service
node_provision -->|"manages bindings"| node_rolebindings
node_provision -->|"creates accounts"| node_serviceaccounts
node_namespace_service -->|"writes resources"| node_kube_api
node_rolebindings -->|"writes resources"| node_kube_api
node_serviceaccounts -->|"writes resources"| node_kube_api
node_operator_entry -.->|"starts optional watcher"| node_netpol_watch
node_netpol_watch -->|"watches configuration"| node_clientset
node_clientset -->|"handles CRDs"| node_crd_types
node_netpol_watch -->|"reconciles policies"| node_netpol_service
node_netpol_service -->|"writes policies"| node_kube_api
node_operator_entry -->|"loads settings"| node_config

click node_api_entry "https://github.com/ca-gip/kubi/blob/master/cmd/api/main.go"
click node_basic_auth "https://github.com/ca-gip/kubi/blob/master/internal/middlewares/httpauth.go"
click node_ldap_client "https://github.com/ca-gip/kubi/blob/master/internal/ldap/client.go"
click node_memberships "https://github.com/ca-gip/kubi/blob/master/internal/ldap/membership.go"
click node_token_issuer "https://github.com/ca-gip/kubi/blob/master/internal/services/token-provider.go"
click node_authn_entry "https://github.com/ca-gip/kubi/blob/master/cmd/authorization-webhook/main.go"
click node_authn_handler "https://github.com/ca-gip/kubi/blob/master/internal/services/webhook-tokenauthenticator.go"
click node_operator_entry "https://github.com/ca-gip/kubi/blob/master/cmd/operator/main.go"
click node_project_sync "https://github.com/ca-gip/kubi/blob/master/internal/services/project-operator.go"
click node_project_parse "https://github.com/ca-gip/kubi/blob/master/internal/project/constructors.go"
click node_provision "https://github.com/ca-gip/kubi/blob/master/internal/services/project-provisionner.go"
click node_namespace_service "https://github.com/ca-gip/kubi/blob/master/internal/services/namespaces.go"
click node_rolebindings "https://github.com/ca-gip/kubi/blob/master/internal/services/rolebindings.go"
click node_serviceaccounts "https://github.com/ca-gip/kubi/blob/master/internal/services/serviceaccounts.go"
click node_netpol_watch "https://github.com/ca-gip/kubi/blob/master/internal/services/netpolconfig-operator.go"
click node_netpol_service "https://github.com/ca-gip/kubi/blob/master/internal/services/netpols.go"
click node_crd_types "https://github.com/ca-gip/kubi/blob/master/pkg/apis/cagip/v1/types.go"
click node_clientset "https://github.com/ca-gip/kubi/blob/master/pkg/generated/clientset/versioned/clientset.go"
click node_config "https://github.com/ca-gip/kubi/blob/master/internal/utils/config.go"

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_api_entry,node_basic_auth,node_token_issuer toneBlue
class node_authn_entry,node_authn_handler,node_ldap_service,node_kube_api toneAmber
class node_operator_entry,node_project_sync,node_provision,node_namespace_service,node_rolebindings,node_serviceaccounts,node_netpol_watch,node_netpol_service,node_api_server toneMint
class node_ldap_client,node_memberships,node_project_parse,node_crd_types,node_clientset,node_config toneRose
class node_cli toneIndigo
```

## Components

### Token API

- [API HTTP Server](https://github.com/ca-gip/kubi/blob/master/cmd/api/main.go): `cmd/api/main.go`
- [Basic Auth](https://github.com/ca-gip/kubi/blob/master/internal/middlewares/httpauth.go): `internal/middlewares/httpauth.go`
- [Token Issuer](https://github.com/ca-gip/kubi/blob/master/internal/services/token-provider.go): `internal/services/token-provider.go`

### Token Authentication

- [Authentication Webhook](https://github.com/ca-gip/kubi/blob/master/cmd/authorization-webhook/main.go): `cmd/authorization-webhook/main.go`
- [TokenReview Handler](https://github.com/ca-gip/kubi/blob/master/internal/services/webhook-tokenauthenticator.go): `internal/services/webhook-tokenauthenticator.go`

### Tenant Operator

- [Operator Runtime](https://github.com/ca-gip/kubi/blob/master/cmd/operator/main.go): `cmd/operator/main.go`
- [LDAP Project Sync](https://github.com/ca-gip/kubi/blob/master/internal/services/project-operator.go): `internal/services/project-operator.go`
- [Tenant Provisioning](https://github.com/ca-gip/kubi/blob/master/internal/services/project-provisionner.go): `internal/services/project-provisionner.go`
- [Namespace Resources](https://github.com/ca-gip/kubi/blob/master/internal/services/namespaces.go): `internal/services/namespaces.go`
- [Role Bindings](https://github.com/ca-gip/kubi/blob/master/internal/services/rolebindings.go): `internal/services/rolebindings.go`
- [Service Accounts](https://github.com/ca-gip/kubi/blob/master/internal/services/serviceaccounts.go): `internal/services/serviceaccounts.go`
- [Policy Config Watcher](https://github.com/ca-gip/kubi/blob/master/internal/services/netpolconfig-operator.go): `internal/services/netpolconfig-operator.go`
- [Network Policies](https://github.com/ca-gip/kubi/blob/master/internal/services/netpols.go): `internal/services/netpols.go`

### Shared Domain

- [LDAP Client](https://github.com/ca-gip/kubi/blob/master/internal/ldap/client.go): `internal/ldap/client.go`
- [Group Memberships](https://github.com/ca-gip/kubi/blob/master/internal/ldap/membership.go): `internal/ldap/membership.go`
- [Group Parser](https://github.com/ca-gip/kubi/blob/master/internal/project/constructors.go): `internal/project/constructors.go`
- [Kubi CRD Types](https://github.com/ca-gip/kubi/blob/master/pkg/apis/cagip/v1/types.go): `pkg/apis/cagip/v1/types.go`
- [CRD Client](https://github.com/ca-gip/kubi/blob/master/pkg/generated/clientset/versioned/clientset.go): `pkg/generated/clientset/versioned/clientset.go`
- [Runtime Configuration](https://github.com/ca-gip/kubi/blob/master/internal/utils/config.go): `internal/utils/config.go`

### Other components

- **Kubi CLI**
- **API Server**
- **LDAP / AD**
- **Kubernetes API**

## Connections

- Kubi CLI → API HTTP Server: requests tokens
- API HTTP Server → Basic Auth: routes protected endpoints
- Basic Auth → LDAP Client: authenticates user
- LDAP Client → LDAP / AD: binds and searches
- LDAP Client → Group Memberships: loads memberships
- Basic Auth → Token Issuer: invokes protected handlers
- API HTTP Server → Runtime Configuration: loads settings
- API Server → Authentication Webhook: posts TokenReview
- Authentication Webhook → TokenReview Handler: routes request
- TokenReview Handler → Token Issuer: verifies token
- TokenReview Handler → API Server: returns review status
- Operator Runtime → LDAP Project Sync: starts project watch
- LDAP Project Sync → LDAP Client: lists LDAP projects
- LDAP Client → Group Parser: parses group names
- LDAP Project Sync → Tenant Provisioning: reconciles projects
- Tenant Provisioning → Namespace Resources: manages namespaces
- Tenant Provisioning → Role Bindings: manages bindings
- Tenant Provisioning → Service Accounts: creates accounts
- Namespace Resources → Kubernetes API: writes resources
- Role Bindings → Kubernetes API: writes resources
- Service Accounts → Kubernetes API: writes resources
- Operator Runtime → Policy Config Watcher: starts optional watcher
- Policy Config Watcher → CRD Client: watches configuration
- CRD Client → Kubi CRD Types: handles CRDs
- Policy Config Watcher → Network Policies: reconciles policies
- Network Policies → Kubernetes API: writes policies
- Operator Runtime → Runtime Configuration: loads settings