# vmware/pinniped architecture

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

- Interactive diagram: https://gitdiagram.com/vmware/pinniped
- Repository: https://github.com/vmware/pinniped

## Overview

1. **What this repository is**
   Pinniped is a Kubernetes identity platform. It adds two main server-side components—**Supervisor** and **Concierge**—plus a **CLI**. The architecture centers on brokering identity from external identity providers into Kubernetes authentication flows.

2. **Top-level system split**
   The repo is organized around two distinct runtime planes:
   - **Supervisor**: handles user-facing login and federation to upstream identity providers.
   - **Concierge**: runs inside or near target clusters and turns validated identity into Kubernetes credentials or impersonation-friendly auth.
   This split is the main boundary to show in an architecture diagram.

3. **Supervisor subsystem**
   The Supervisor is the OIDC federation layer. It manages CRDs for configuration such as:
   - `FederationDomain`
   - `OIDCClient`
   - upstream IdPs: `OIDCIdentityProvider`, `LDAPIdentityProvider`, `ActiveDirectoryIdentityProvider`, `GitHubIdentityProvider`
   It exposes browser-oriented endpoints for discovery, login, callback, JWKS, token exchange, and IDP selection under `internal/federationdomain/endpoints`.

4. **Supervisor data flow**
   A login flow typically goes:
   - user/browser hits Supervisor discovery/login endpoints
   - Supervisor chooses or discovers an upstream IdP
   - user authenticates with the upstream provider
   - Supervisor stores/derives session state, issues OIDC responses, and serves JWKS for signing keys
   - downstream clients use the resulting OIDC artifacts
   The Supervisor relies on Fosite-style OAuth/OIDC state and token storage under `internal/fositestorage` and `internal/federationdomain/storage`.

5. **Concierge subsystem**
   The Concierge is the cluster-side authentication service. It exposes Kubernetes-style APIs and custom resources for:
   - `JWTAuthenticator`
   - `WebhookAuthenticator`
   - `CredentialIssuer`
   - identity/login requests such as `TokenCredentialRequest` and `WhoAmIRequest`
   Its role is to authenticate users against cluster-configured mechanisms and produce credentials or identity responses usable by kubectl and cluster clients.

6. **Concierge data flow**
   Concierge receives auth-related requests through its aggregated API surface, then:
   - resolves configured authenticators from CRDs
   - validates tokens or calls webhooks
   - may issue cluster credentials or respond with identity info
   - can support impersonation-oriented access flows
   It also includes certificate and API-service management controllers so the aggregated API remains reachable and trusted.

7. **Controller layer**
   Most operational behavior is implemented as controllers under `internal/controller/*`, all built on a reusable controller framework in `internal/controllerlib`.
   Major controller groups include:
   - **Supervisor config controllers**: watch IdP and FederationDomain resources, build secrets, JWKS, TLS material, and resolved provider state
   - **Authenticator controllers**: cache and reconcile JWT/webhook authenticators
   - **API cert controllers**: manage serving certs and APIService registration
   - **Kube cert agent controllers**: support credential/cert distribution for the concierge kube-cert-agent
   - **Storage cleanup controllers**: garbage collect or clean up old storage artifacts

8. **Generated Kubernetes API surface**
   The `generated/<k8s-version>/...` directories contain versioned, generated clients, informers, listers, deepcopy/conversion code, and CRD YAMLs for each supported Kubernetes minor version. This is a clear boundary between:
   - **handwritten business logic** in `internal/`
   - **generated API machinery** used to compile against multiple Kubernetes versions
   The generated artifacts materially affect how the project stays compatible across clusters.

9. **CLI subsystem**
   The `cmd/pinniped` tree builds the main user CLI. It provides login and discovery-oriented commands such as:
   - `login`
   - OIDC login flows
   - `whoami`
   - Kubernetes credential/kubeconfig helpers
   It uses `pkg/oidcclient` for browser-based OIDC login, PKCE/state/nonce handling, and `pkg/conciergeclient` to talk to the Concierge APIs.

10. **Supporting internal libraries**
   Several shared packages underpin both servers and CLI:
   - `internal/crypto/ptls` and `internal/certauthority` for TLS and certificate handling
   - `internal/kubeclient` and `internal/kubeclient/*` for Kubernetes API access
   - `internal/httputil`, `internal/net/phttp`, `internal/plog` for HTTP behavior and logging
   - `internal/dynamiccert`, `internal/dynamiccertauthority`, `internal/secret`, `internal/ownerref` for runtime-managed Kubernetes secrets and certs
   These are infrastructure-heavy cross-cutting concerns, not separate products.

11. **External dependencies and integration points**
   The system depends on:
   - the **Kubernetes API server** and aggregated APIs/CRDs
   - upstream **identity providers** via OIDC, LDAP, Active Directory, and GitHub
   - browser-based redirects and callbacks for login
   - Kubernetes RBAC, service accounts, and cert secret management
   These external boundaries are central to the architecture; most flows bridge Kubernetes control-plane APIs with identity-provider protocols.

12. **Deployment model**
   The `deploy/` manifests show the runtime packaging for:
   - Supervisor
   - Concierge
   - local-user-authenticator
   The repo also includes Docker build assets and Carvel package templates, indicating that install/upgrade is treated as part of the system architecture, not just build tooling.

13. **Testing and validation structure**
   The architecture is heavily validated through integration tests in `test/integration` and reusable test helpers in `test/testlib` and `internal/testutil`. This reflects the product’s reliance on end-to-end behavior across Kubernetes, TLS, CRDs, and OIDC redirects, rather than isolated unit-only logic.

14. **How to diagram it**
   A good diagram should show:
   - users/kubectl/CLI on one side
   - Supervisor as the federation/OIDC broker
   - Concierge as the cluster auth/credential service
   - Kubernetes API server and CRDs as the control-plane store and API surface
   - external IdPs as upstream auth providers
   - controller loops watching CRDs/secrets and reconciling certs, JWKS, auth configs, and cached state
   The key architectural idea is that Pinniped translates external identity into Kubernetes authentication via a split Supervisor/Concierge control plane.

Main entry points: [`internal/concierge/server`](https://github.com/vmware/pinniped/tree/main/internal/concierge/server) (Concierge), [`internal/supervisor/server`](https://github.com/vmware/pinniped/tree/main/internal/supervisor/server) (Supervisor), [`internal/federationdomain/endpoints`](https://github.com/vmware/pinniped/tree/main/internal/federationdomain/endpoints) (OIDC endpoints), [`generated/latest`](https://github.com/vmware/pinniped/tree/main/generated/latest) (Versioned APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_users["Clients"]
  node_node_cli["CLI<br/>user tool"]
  node_node_browser(("Browser<br/>login client"))
  node_node_kubectl(("kubectl<br/>k8s client"))
end

subgraph group_grp_supervisor["Supervisor"]
  node_node_supervisor_server["Supervisor<br/>oidc broker"]
  node_node_supervisor_endpoints["OIDC endpoints<br/>http handlers"]
  node_node_supervisor_config["Config reconcilers<br/>controllers"]
  node_node_supervisor_storage[("Fosite storage<br/>oauth state")]
  node_node_supervisor_oidc{{"OIDC strategy<br/>signing/codec"}}
  node_node_supervisor_upstreams[("Upstream IdPs<br/>external providers")]
end

subgraph group_grp_concierge["Concierge"]
  node_node_concierge_server["Concierge<br/>auth service"]
  node_node_concierge_apis["Auth APIs<br/>k8s apis"]
  node_node_concierge_auth["Authenticator cache<br/>controllers"]
  node_node_concierge_apicerts["API certs<br/>controllers"]
  node_node_concierge_kubeagent["Kube cert agent<br/>controllers"]
end

subgraph group_grp_shared["Shared libs"]
  node_node_shared_tls{{"TLS & certs<br/>shared infra"}}
  node_node_shared_kube{{"Kube client<br/>shared infra"}}
  node_node_shared_http{{"HTTP utils<br/>shared infra"}}
  node_node_shared_identity{{"Identity libs<br/>shared infra"}}
end

subgraph group_grp_generated["Generated APIs"]
  node_node_generated["Versioned APIs<br/>generated machinery"]
end

subgraph group_grp_ops["Packaging"]
  node_node_deploy["Deployments<br/>packaging"]
  node_node_tests["Integration tests<br/>validation"]
end

node_node_cli -->|"login/discovery"| node_node_supervisor_server
node_node_cli -->|"whoami/credentials"| node_node_concierge_server
node_node_browser -->|"redirects"| node_node_supervisor_endpoints
node_node_kubectl -->|"auth requests"| node_node_concierge_server
node_node_supervisor_server -->|"serves"| node_node_supervisor_endpoints
node_node_supervisor_server -->|"reconciles"| node_node_supervisor_config
node_node_supervisor_server -->|"persists state"| node_node_supervisor_storage
node_node_supervisor_server -->|"signs tokens"| node_node_supervisor_oidc
node_node_supervisor_config -->|"watches"| node_node_supervisor_upstreams
node_node_supervisor_config -->|"tls material"| node_node_shared_tls
node_node_supervisor_config -->|"CRDs/clients"| node_node_generated
node_node_supervisor_endpoints -->|"federates"| node_node_supervisor_upstreams
node_node_supervisor_endpoints -->|"http behavior"| node_node_shared_http
node_node_supervisor_endpoints -->|"oidc state"| node_node_shared_identity
node_node_concierge_server -->|"exposes"| node_node_concierge_apis
node_node_concierge_server -->|"uses"| node_node_concierge_auth
node_node_concierge_server -->|"serving trust"| node_node_concierge_apicerts
node_node_concierge_server -->|"cert agent"| node_node_concierge_kubeagent
node_node_concierge_auth -->|"watches CRDs"| node_node_generated
node_node_concierge_apicerts -->|"certs"| node_node_shared_tls
node_node_concierge_apicerts -->|"apiservice"| node_node_shared_kube
node_node_concierge_kubeagent -->|"kube access"| node_node_shared_kube
node_node_shared_tls -->|"cert CRDs"| node_node_generated
node_node_shared_kube -->|"clients"| node_node_generated
node_node_shared_identity -->|"upstream auth"| node_node_supervisor_upstreams
node_node_shared_http -.->|"browser login"| node_node_cli
node_node_deploy -->|"packages"| node_node_supervisor_server
node_node_deploy -->|"packages"| node_node_concierge_server
node_node_deploy -->|"installs CRDs"| node_node_generated
node_node_tests -->|"validates"| node_node_supervisor_server
node_node_tests -->|"validates"| node_node_concierge_server

click node_node_cli "https://github.com/vmware/pinniped/tree/main/cmd/pinniped"
click node_node_supervisor_server "https://github.com/vmware/pinniped/tree/main/internal/supervisor/server"
click node_node_supervisor_endpoints "https://github.com/vmware/pinniped/tree/main/internal/federationdomain/endpoints"
click node_node_supervisor_config "https://github.com/vmware/pinniped/tree/main/internal/controller/supervisorconfig"
click node_node_supervisor_storage "https://github.com/vmware/pinniped/tree/main/internal/federationdomain/storage"
click node_node_supervisor_oidc "https://github.com/vmware/pinniped/tree/main/internal/federationdomain"
click node_node_supervisor_upstreams "https://github.com/vmware/pinniped/tree/main/apis/supervisor/idp/v1alpha1"
click node_node_concierge_server "https://github.com/vmware/pinniped/tree/main/internal/concierge/server"
click node_node_concierge_apis "https://github.com/vmware/pinniped/tree/main/apis/concierge"
click node_node_concierge_auth "https://github.com/vmware/pinniped/tree/main/internal/controller/authenticator"
click node_node_concierge_apicerts "https://github.com/vmware/pinniped/tree/main/internal/controller/apicerts"
click node_node_concierge_kubeagent "https://github.com/vmware/pinniped/tree/main/internal/controller/kubecertagent"
click node_node_shared_tls "https://github.com/vmware/pinniped/tree/main/internal/certauthority"
click node_node_shared_kube "https://github.com/vmware/pinniped/tree/main/internal/kubeclient"
click node_node_shared_http "https://github.com/vmware/pinniped/tree/main/internal/httputil"
click node_node_shared_identity "https://github.com/vmware/pinniped/tree/main/pkg/oidcclient"
click node_node_generated "https://github.com/vmware/pinniped/tree/main/generated/latest"
click node_node_deploy "https://github.com/vmware/pinniped/tree/main/deploy"
click node_node_tests "https://github.com/vmware/pinniped/tree/main/test/integration"

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_node_cli,node_node_browser,node_node_kubectl toneBlue
class node_node_supervisor_server,node_node_supervisor_endpoints,node_node_supervisor_config,node_node_supervisor_storage,node_node_supervisor_oidc,node_node_supervisor_upstreams toneAmber
class node_node_concierge_server,node_node_concierge_apis,node_node_concierge_auth,node_node_concierge_apicerts,node_node_concierge_kubeagent toneMint
class node_node_shared_tls,node_node_shared_kube,node_node_shared_http,node_node_shared_identity toneRose
class node_node_generated toneIndigo
class node_node_deploy,node_node_tests toneTeal
```

## Components

### Clients

Human and machine entrypoints into Pinniped.

- [CLI](https://github.com/vmware/pinniped/tree/main/cmd/pinniped): user tool · Main pinniped command-line client for login, whoami, and kubeconfig flows. · `cmd/pinniped`
- **Browser**: login client · Browser-based redirect and callback participant in OIDC login flows.
- **kubectl**: k8s client · Downstream Kubernetes client that consumes credentials produced by Pinniped.

### Supervisor

Federation and upstream identity brokering plane.

- [Supervisor](https://github.com/vmware/pinniped/tree/main/internal/supervisor/server): oidc broker · User-facing federation plane that fronts external identity providers and serves OIDC endpoints. · `internal/supervisor/server`
- [OIDC endpoints](https://github.com/vmware/pinniped/tree/main/internal/federationdomain/endpoints): http handlers · Discovery, login, callback, token, JWKS, choose-IDP, and token exchange handlers. · `internal/federationdomain/endpoints`
- [Config reconcilers](https://github.com/vmware/pinniped/tree/main/internal/controller/supervisorconfig): controllers · Watches FederationDomain, OIDCClient, and upstream IdP resources to derive secrets, JWKS, TLS, and resolved provider state. · `internal/controller/supervisorconfig`
- [Fosite storage](https://github.com/vmware/pinniped/tree/main/internal/federationdomain/storage): oauth state · OAuth/OIDC state, code, token, and session storage used by the Supervisor. · `internal/federationdomain/storage`
- [OIDC strategy](https://github.com/vmware/pinniped/tree/main/internal/federationdomain): signing/codec · OIDC signing, HMAC, ECDSA, CSRF, state, and downstream session mechanics. · `internal/federationdomain`
- [Upstream IdPs](https://github.com/vmware/pinniped/tree/main/apis/supervisor/idp/v1alpha1): external providers · OIDC, LDAP, Active Directory, and GitHub identity providers configured for federation. · `apis/supervisor/idp/v1alpha1`

### Concierge

Cluster-side authentication and credential issuance plane.

- [Concierge](https://github.com/vmware/pinniped/tree/main/internal/concierge/server): auth service · Cluster-side authentication service that exposes Kubernetes-style APIs and credential issuance. · `internal/concierge/server`
- [Auth APIs](https://github.com/vmware/pinniped/tree/main/apis/concierge): k8s apis · JWTAuthenticator, WebhookAuthenticator, CredentialIssuer, TokenCredentialRequest, and WhoAmIRequest surfaces. · `apis/concierge`
- [Authenticator cache](https://github.com/vmware/pinniped/tree/main/internal/controller/authenticator): controllers · Reconciles JWT and webhook authenticators and maintains authn cache state. · `internal/controller/authenticator`
- [API certs](https://github.com/vmware/pinniped/tree/main/internal/controller/apicerts): controllers · Manages serving certificates and APIService registration for the aggregated API. · `internal/controller/apicerts`
- [Kube cert agent](https://github.com/vmware/pinniped/tree/main/internal/controller/kubecertagent): controllers · Supports certificate distribution and pod-based certificate agent behavior. · `internal/controller/kubecertagent`

### Shared libs

Cross-cutting TLS, Kubernetes, HTTP, and identity helpers.

- [TLS & certs](https://github.com/vmware/pinniped/tree/main/internal/certauthority): shared infra · Certificate authorities, dynamic certs, and TLS profile handling. · `internal/certauthority`
- [Kube client](https://github.com/vmware/pinniped/tree/main/internal/kubeclient): shared infra · Kubernetes API access, schemes, and request middleware. · `internal/kubeclient`
- [HTTP utils](https://github.com/vmware/pinniped/tree/main/internal/httputil): shared infra · HTTP behavior, logging, security headers, and request/response helpers. · `internal/httputil`
- [Identity libs](https://github.com/vmware/pinniped/tree/main/pkg/oidcclient): shared infra · OIDC client, upstream provider, token, and identity transformation helpers. · `pkg/oidcclient`

### Generated APIs

Versioned Kubernetes API machinery and CRDs.

- [Versioned APIs](https://github.com/vmware/pinniped/tree/main/generated/latest): generated machinery · Generated clients, informers, listers, deepcopy, conversion, openapi, and CRDs for supported Kubernetes versions. · `generated/latest`

### Packaging

Deployment manifests and release packaging.

- [Deployments](https://github.com/vmware/pinniped/tree/main/deploy): packaging · Manifests and Carvel package templates for Supervisor, Concierge, and local-user-authenticator. · `deploy`
- [Integration tests](https://github.com/vmware/pinniped/tree/main/test/integration): validation · End-to-end tests that exercise Kubernetes, CRDs, TLS, OIDC redirects, and auth flows. · `test/integration`

## Connections

- CLI → Supervisor: login/discovery · CLI initiates login and discovery flows against the Supervisor.
- CLI → Concierge: whoami/credentials · CLI exchanges credentials and identity requests with the Concierge.
- Browser → OIDC endpoints: redirects · Browser follows OIDC login, callback, and form-post endpoints.
- kubectl → Concierge: auth requests · Kubernetes clients consume credential issuance and identity endpoints.
- Supervisor → OIDC endpoints: serves · Supervisor runtime mounts the browser-facing OIDC handlers.
- Supervisor → Config reconcilers: reconciles · Supervisor depends on config controllers to build resolved federation state.
- Supervisor → Fosite storage: persists state · OIDC state and session data are stored through Fosite-backed storage.
- Supervisor → OIDC strategy: signs tokens · OIDC strategy and session logic underpin discovery, login, JWKS, and token issuance.
- Config reconcilers → Upstream IdPs: watches · Reconcilers watch IdP and FederationDomain CRDs to derive provider state.
- Config reconcilers → TLS & certs: tls material · Supervisor config reconciliation produces or consumes serving certs and CA material.
- Config reconcilers → Versioned APIs: CRDs/clients · Controller logic uses generated APIs, informers, and versioned CRDs.
- OIDC endpoints → Upstream IdPs: federates · Login and IDP-selection handlers route users to upstream identity providers.
- OIDC endpoints → HTTP utils: http behavior · Handlers use shared HTTP utilities, security headers, and logging.
- OIDC endpoints → Identity libs: oidc state · Endpoints rely on OIDC client helpers for PKCE, state, and nonce handling.
- Concierge → Auth APIs: exposes · Concierge serves aggregated authentication, login, and identity APIs.
- Concierge → Authenticator cache: uses · Cluster auth behavior is driven by authenticator reconciliation and cache filling.
- Concierge → API certs: serving trust · API cert controllers keep the aggregated API reachable and trusted.
- Concierge → Kube cert agent: cert agent · Concierge can coordinate kube-cert-agent behavior for credential distribution.
- Authenticator cache → Versioned APIs: watches CRDs · Authenticator controllers consume versioned Kubernetes auth resources.
- API certs → TLS & certs: certs · Serving certificate and CA handling is shared with TLS infrastructure.
- API certs → Kube client: apiservice · APIService registration and Kubernetes client access are managed through kube APIs.
- Kube cert agent → Kube client: kube access · Kube-cert-agent controllers interact with the Kubernetes API and pods.
- TLS & certs → Versioned APIs: cert CRDs · Deployment and reconciliation rely on generated Kubernetes API types and CRDs.
- Kube client → Versioned APIs: clients · Shared kubeclient code is built on generated clientsets and schemes.
- Identity libs → Upstream IdPs: upstream auth · Shared identity helpers implement OIDC, LDAP, AD, and GitHub provider integrations.
- HTTP utils → CLI: browser login · CLI uses shared HTTP primitives indirectly through browser-based OIDC flows.
- Deployments → Supervisor: packages · Deployment manifests package the Supervisor runtime.
- Deployments → Concierge: packages · Deployment manifests package the Concierge runtime.
- Deployments → Versioned APIs: installs CRDs · Manifests include generated CRDs and overlays for supported versions.
- Integration tests → Supervisor: validates · Integration tests exercise login, discovery, upstream federation, and storage flows.
- Integration tests → Concierge: validates · Integration tests cover credential issuance, authn/authz, API serving certs, and whoami flows.
