# kubernetes/sample-controller architecture

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

- Interactive diagram: https://gitdiagram.com/kubernetes/sample-controller
- Repository: https://github.com/kubernetes/sample-controller

## Overview

#### Purpose and Entry Points
This Go repository is a Kubernetes sample controller for one CRD-backed resource, `Foo`. It demonstrates the standard client-go controller pattern: watch `Foo`, reconcile its desired replica count into an `apps/v1` Deployment, and publish observed replica state. The binary entry point is `main.go`; controller construction and reconciliation are in `controller.go`.

#### API Contract and CRD Boundary
`Foo` is the external API owned by this controller, under the `samplecontroller.k8s.io/v1alpha1` group/version. Its Go type, `Spec`, and `Status` define the typed contract used by the controller and generated clients:
- `pkg/apis/samplecontroller/v1alpha1/types.go`
- `pkg/apis/samplecontroller/v1alpha1/doc.go`

Cluster installation is an explicit boundary: Kubernetes must first accept the CRD manifests, optionally with a `/status` subresource:
- `artifacts/examples/crd.yaml`
- `artifacts/examples/crd-status-subresource.yaml`
- `artifacts/examples/example-foo.yaml`

#### Process Startup and Kubernetes Connectivity
`main.go` parses runtime settings such as kubeconfig, constructs Kubernetes and custom-resource clients, creates informer factories, initializes the controller, starts informers, and blocks on signal-driven shutdown. It can use a supplied kubeconfig or in-cluster configuration. Shutdown handling is isolated in:
- `main.go`
- `pkg/signals/signal.go`
- `pkg/signals/signal_posix.go`

Material runtime dependencies are Go, a reachable Kubernetes API server, and Kubernetes client-go/apimachinery libraries declared in `go.mod`.

#### Event Ingestion, Cache, and Work Queue
The controller subscribes to `Foo` informer add/update/delete events. Event handlers enqueue keys rather than performing API work inline. Shared informers maintain local caches; listers read from those caches during reconciliation; worker goroutines consume a rate-limiting queue and retry failed keys. This separates watch delivery from reconciliation and minimizes direct API reads:
- `controller.go`
- `pkg/generated/informers/externalversions/samplecontroller/v1alpha1/foo.go`
- `pkg/generated/listers/samplecontroller/v1alpha1/foo.go`

#### Reconciliation and Deployment Ownership
For each queued `Foo` key, reconciliation fetches the cached `Foo`, determines the expected Deployment, and creates or updates that Deployment to match `Foo.Spec.Replicas`. The Deployment is controlled via Kubernetes owner references, so deletion of a `Foo` permits Kubernetes garbage collection of its dependent Deployment. Deployment state is read through the core Kubernetes typed client:
- `controller.go`
- `pkg/apis/samplecontroller/v1alpha1/types.go`

The principal external service boundary is the Kubernetes API: custom-resource operations target the CRD API endpoint, while managed workload operations target `apps/v1` Deployments.

#### Status Feedback
After observing the associated Deployment, the controller writes the actual available replica count to `Foo.Status.AvailableReplicas`. When the CRD’s status subresource is enabled, this uses a status-only update, keeping user-authored desired state (`spec`) separate from controller-authored observed state (`status`):
- `controller.go`
- `artifacts/examples/crd-status-subresource.yaml`
- `pkg/apis/samplecontroller/v1alpha1/types.go`

#### Generated Kubernetes Integration Layer
Code generation converts the API type into the Kubernetes integration surface: scheme registration, typed CRUD/status client, informer, lister, apply configuration, deepcopy, and OpenAPI artifacts. These generated packages are consumed by startup and reconciliation rather than hand-maintained:
- `pkg/generated/clientset/versioned/clientset.go`
- `pkg/generated/informers/externalversions/factory.go`
- `pkg/generated/applyconfiguration/samplecontroller/v1alpha1/foo.go`

Generation is sourced from the API definitions via `hack/update-codegen.sh`; generated outputs under `pkg/generated/` and `zz_generated.*` are not intended for manual editing.

Main entry points: [`controller.go`](https://github.com/kubernetes/sample-controller/blob/master/controller.go) (Foo controller), [`main.go`](https://github.com/kubernetes/sample-controller/blob/master/main.go) (Controller binary), [`hack/update-codegen.sh`](https://github.com/kubernetes/sample-controller/blob/master/hack/update-codegen.sh) (Code generation), [`pkg/generated/clientset/versioned/clientset.go`](https://github.com/kubernetes/sample-controller/blob/master/pkg/generated/clientset/versioned/clientset.go) (Foo typed client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Foo API &amp; Installation"]
  node_foo_api["Foo types<br/>CRD API contract<br/>[types.go]"]
  node_api_doc["API group/version<br/>Go API package<br/>[doc.go]"]
  node_crd["Foo CRD manifest<br/>cluster installation<br/>[crd.yaml]"]
  node_status_crd["Status subresource manifest<br/>CRD variant"]
  node_example_foo["Example Foo<br/>custom resource manifest<br/>[example-foo.yaml]"]
end

subgraph group_runtime["Controller Runtime"]
  node_main["Controller binary<br/>Go entry point<br/>[main.go]"]
  node_signals["Signal shutdown<br/>lifecycle helper<br/>[signal.go]"]
  node_controller["Foo controller<br/>reconciler<br/>[controller.go]"]
  node_queue["Rate-limiting queue<br/>work queue<br/>[controller.go]"]
end

subgraph group_generated["Generated Integration"]
  node_codegen{{"Code generation<br/>generation script<br/>[update-codegen.sh]"}}
  node_custom_client["Foo typed client<br/>generated clientset<br/>[clientset.go]"]
  node_informer_factory["Foo informer factory<br/>generated informer<br/>[factory.go]"]
  node_foo_informer["Foo informer<br/>generated informer<br/>[foo.go]"]
  node_foo_lister["Foo lister<br/>generated cache reader<br/>[foo.go]"]
end

subgraph group_cluster["Kubernetes Cluster"]
  node_kube_api{{"Kubernetes API server<br/>external API"}}
  node_foo_resource[("Foo resources<br/>custom resources")]
  node_deployment["Managed Deployment<br/>apps/v1 workload"]
end

node_main -->|"waits for shutdown"| node_signals
node_main -->|"constructs"| node_custom_client
node_main -->|"starts"| node_informer_factory
node_main -->|"initializes and runs"| node_controller
node_informer_factory -->|"provides"| node_foo_informer
node_foo_informer -->|"watch events"| node_controller
node_controller -->|"enqueues keys"| node_queue
node_queue -->|"workers consume"| node_controller
node_controller -->|"reads cached Foo"| node_foo_lister
node_controller -->|"updates Foo status"| node_custom_client
node_controller -->|"creates or updates Deployment"| node_kube_api
node_custom_client -->|"Foo API calls"| node_kube_api
node_kube_api -->|"stores"| node_foo_resource
node_kube_api -->|"stores"| node_deployment
node_foo_resource -->|"owner reference and desired replicas"| node_deployment
node_deployment -->|"available replicas observed"| node_controller
node_foo_api -->|"belongs to"| node_api_doc
node_foo_api -->|"generation input"| node_codegen
node_codegen -->|"generates"| node_custom_client
node_codegen -->|"generates"| node_informer_factory
node_codegen -->|"generates"| node_foo_lister
node_crd -->|"installs Foo API"| node_kube_api
node_status_crd -->|"enables status endpoint"| node_kube_api
node_example_foo -.->|"creates example"| node_foo_resource

click node_main "https://github.com/kubernetes/sample-controller/blob/master/main.go"
click node_signals "https://github.com/kubernetes/sample-controller/blob/master/pkg/signals/signal.go"
click node_controller "https://github.com/kubernetes/sample-controller/blob/master/controller.go"
click node_queue "https://github.com/kubernetes/sample-controller/blob/master/controller.go"
click node_foo_api "https://github.com/kubernetes/sample-controller/blob/master/pkg/apis/samplecontroller/v1alpha1/types.go"
click node_api_doc "https://github.com/kubernetes/sample-controller/blob/master/pkg/apis/samplecontroller/v1alpha1/doc.go"
click node_crd "https://github.com/kubernetes/sample-controller/blob/master/artifacts/examples/crd.yaml"
click node_status_crd "https://github.com/kubernetes/sample-controller/blob/master/artifacts/examples/crd-status-subresource.yaml"
click node_example_foo "https://github.com/kubernetes/sample-controller/blob/master/artifacts/examples/example-foo.yaml"
click node_codegen "https://github.com/kubernetes/sample-controller/blob/master/hack/update-codegen.sh"
click node_custom_client "https://github.com/kubernetes/sample-controller/blob/master/pkg/generated/clientset/versioned/clientset.go"
click node_informer_factory "https://github.com/kubernetes/sample-controller/blob/master/pkg/generated/informers/externalversions/factory.go"
click node_foo_informer "https://github.com/kubernetes/sample-controller/blob/master/pkg/generated/informers/externalversions/samplecontroller/v1alpha1/foo.go"
click node_foo_lister "https://github.com/kubernetes/sample-controller/blob/master/pkg/generated/listers/samplecontroller/v1alpha1/foo.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_foo_api,node_api_doc,node_crd,node_status_crd,node_example_foo toneBlue
class node_main,node_signals,node_controller,node_queue toneAmber
class node_codegen,node_custom_client,node_informer_factory,node_foo_informer,node_foo_lister toneMint
class node_kube_api,node_foo_resource,node_deployment toneRose
```

## Components

### Foo API & Installation

- [Foo types](https://github.com/kubernetes/sample-controller/blob/master/pkg/apis/samplecontroller/v1alpha1/types.go): CRD API contract · Defines Foo spec replicas and observed available replicas. · `pkg/apis/samplecontroller/v1alpha1/types.go`
- [API group/version](https://github.com/kubernetes/sample-controller/blob/master/pkg/apis/samplecontroller/v1alpha1/doc.go): Go API package · `pkg/apis/samplecontroller/v1alpha1/doc.go`
- [Foo CRD manifest](https://github.com/kubernetes/sample-controller/blob/master/artifacts/examples/crd.yaml): cluster installation · Registers samplecontroller.k8s.io/v1alpha1 Foo. · `artifacts/examples/crd.yaml`
- [Status subresource manifest](https://github.com/kubernetes/sample-controller/blob/master/artifacts/examples/crd-status-subresource.yaml): CRD variant · Enables status-only updates. · `artifacts/examples/crd-status-subresource.yaml`
- [Example Foo](https://github.com/kubernetes/sample-controller/blob/master/artifacts/examples/example-foo.yaml): custom resource manifest · `artifacts/examples/example-foo.yaml`

### Controller Runtime

- [Controller binary](https://github.com/kubernetes/sample-controller/blob/master/main.go): Go entry point · Builds clients, informers, controller, and shutdown lifecycle. · `main.go`
- [Signal shutdown](https://github.com/kubernetes/sample-controller/blob/master/pkg/signals/signal.go): lifecycle helper · `pkg/signals/signal.go`
- [Foo controller](https://github.com/kubernetes/sample-controller/blob/master/controller.go): reconciler · Queues Foo events and reconciles Deployments and status. · `controller.go`
- [Rate-limiting queue](https://github.com/kubernetes/sample-controller/blob/master/controller.go): work queue · Workers retry failed Foo keys. · `controller.go`

### Generated Integration

- [Code generation](https://github.com/kubernetes/sample-controller/blob/master/hack/update-codegen.sh): generation script · Produces Kubernetes integration code from Foo API definitions. · `hack/update-codegen.sh`
- [Foo typed client](https://github.com/kubernetes/sample-controller/blob/master/pkg/generated/clientset/versioned/clientset.go): generated clientset · Performs Foo CRUD and status API operations. · `pkg/generated/clientset/versioned/clientset.go`
- [Foo informer factory](https://github.com/kubernetes/sample-controller/blob/master/pkg/generated/informers/externalversions/factory.go): generated informer · Maintains watched Foo cache. · `pkg/generated/informers/externalversions/factory.go`
- [Foo informer](https://github.com/kubernetes/sample-controller/blob/master/pkg/generated/informers/externalversions/samplecontroller/v1alpha1/foo.go): generated informer · Delivers Foo add, update, and delete events. · `pkg/generated/informers/externalversions/samplecontroller/v1alpha1/foo.go`
- [Foo lister](https://github.com/kubernetes/sample-controller/blob/master/pkg/generated/listers/samplecontroller/v1alpha1/foo.go): generated cache reader · Reads Foo from the local informer cache. · `pkg/generated/listers/samplecontroller/v1alpha1/foo.go`

### Kubernetes Cluster

- **Kubernetes API server**: external API · Serves CRD and apps/v1 Deployment endpoints.
- **Foo resources**: custom resources · Desired replicas in spec and observed replicas in status.
- **Managed Deployment**: apps/v1 workload · Owned by its Foo and scaled to desired replicas.

## Connections

- Controller binary → Signal shutdown: waits for shutdown
- Controller binary → Foo typed client: constructs
- Controller binary → Foo informer factory: starts
- Controller binary → Foo controller: initializes and runs
- Foo informer factory → Foo informer: provides
- Foo informer → Foo controller: watch events
- Foo controller → Rate-limiting queue: enqueues keys
- Rate-limiting queue → Foo controller: workers consume
- Foo controller → Foo lister: reads cached Foo
- Foo controller → Foo typed client: updates Foo status
- Foo controller → Kubernetes API server: creates or updates Deployment
- Foo typed client → Kubernetes API server: Foo API calls
- Kubernetes API server → Foo resources: stores
- Kubernetes API server → Managed Deployment: stores
- Foo resources → Managed Deployment: owner reference and desired replicas
- Managed Deployment → Foo controller: available replicas observed
- Foo types → API group/version: belongs to
- Foo types → Code generation: generation input
- Code generation → Foo typed client: generates
- Code generation → Foo informer factory: generates
- Code generation → Foo lister: generates
- Foo CRD manifest → Kubernetes API server: installs Foo API
- Status subresource manifest → Kubernetes API server: enables status endpoint
- Example Foo → Foo resources: creates example
