How kubernetes/sample-controller works
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 Foo controller · main.go Controller binary · update-codegen.sh Code generation · clientset.go Foo typed client
Components 17
Foo API & Installation
- Foo types · Defines Foo spec replicas and observed available replicas.
pkg/apis/samplecontroller/v1alpha1/types.go - API group/version
pkg/apis/samplecontroller/v1alpha1/doc.go - Foo CRD manifest · Registers samplecontroller.k8s.io/v1alpha1 Foo.
artifacts/examples/crd.yaml - Status subresource manifest · Enables status-only updates.
artifacts/examples/crd-status-subresource.yaml - Example Foo
artifacts/examples/example-foo.yaml
Controller Runtime
- Controller binary · Builds clients, informers, controller, and shutdown lifecycle.
main.go - Signal shutdown
pkg/signals/signal.go - Foo controller · Queues Foo events and reconciles Deployments and status.
controller.go - Rate-limiting queue · Workers retry failed Foo keys.
controller.go
Generated Integration
- Code generation · Produces Kubernetes integration code from Foo API definitions.
hack/update-codegen.sh - Foo typed client · Performs Foo CRUD and status API operations.
pkg/generated/clientset/versioned/clientset.go - Foo informer factory · Maintains watched Foo cache.
pkg/generated/informers/externalversions/factory.go - Foo informer · Delivers Foo add, update, and delete events.
pkg/generated/informers/externalversions/samplecontroller/v1alpha1/foo.go - Foo lister · Reads Foo from the local informer cache.
pkg/generated/listers/samplecontroller/v1alpha1/foo.go
Kubernetes Cluster
- Kubernetes API server · Serves CRD and apps/v1 Deployment endpoints.
- Foo resources · Desired replicas in spec and observed replicas in status.
- Managed Deployment · Owned by its Foo and scaled to desired replicas.
Connections 24
- 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