Skip to content
Repository for sample controller. Complements sample-apiserver
Branch: master
Clone or download
k8s-publishing-bot Merge pull request #75577 from mars1024/bugfix/use_add_in_enqueue
replace AddRateLimited with Add in enqueue func

Kubernetes-commit: ab35bd06689744ee275fbec4d43cc7a30f5cca4d
Latest commit 0e5b089 Mar 22, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
Godeps Merge pull request #75577 from mars1024/bugfix/use_add_in_enqueue Mar 22, 2019
artifacts/examples sample-controller: add status subresource support Feb 18, 2018
docs delete all duplicate empty blanks Feb 22, 2019
hack sample-controller: generate into pkg/generated package Feb 15, 2019
pkg Regenerate clients Feb 21, 2019
vendor Merge pull request #75577 from mars1024/bugfix/use_add_in_enqueue Mar 22, 2019 delete all duplicate empty blanks Feb 22, 2019
LICENSE Add sample CustomResourceDefinition controller Oct 9, 2017
OWNERS Updated OWNERS files to include link to docs Jan 30, 2019
SECURITY_CONTACTS Add to staging repos Dec 20, 2017
controller.go replace AddRateLimited with Add in enqueue func Mar 22, 2019


This repository implements a simple controller for watching Foo resources as defined with a CustomResourceDefinition (CRD).

Note: go-get or vendor this package as

This particular example demonstrates how to perform basic operations such as:

  • How to register a new custom resource (custom resource type) of type Foo using a CustomResourceDefinition.
  • How to create/get/list instances of your new resource type Foo.
  • How to setup a controller on resource handling create/update/delete events.

It makes use of the generators in to generate a typed client, informers, listers and deep-copy functions. You can do this yourself using the ./hack/ script.

The update-codegen script will automatically generate the following files & directories:

  • pkg/apis/samplecontroller/v1alpha1/zz_generated.deepcopy.go
  • pkg/client/

Changes should not be made to these files manually, and when creating your own controller based off of this implementation you should not copy these files and instead run the update-codegen script to generate your own.


The sample controller uses client-go library extensively. The details of interaction points of the sample controller with various mechanisms from this library are explained here.


This is an example of how to build a kube-like controller with a single type.


Prerequisite: Since the sample-controller uses apps/v1 deployments, the Kubernetes cluster version should be greater than 1.9.

# assumes you have a working kubeconfig, not required if operating in-cluster
$ go get
$ cd $GOPATH/src/
$ go build -o sample-controller .
$ ./sample-controller -kubeconfig=$HOME/.kube/config

# create a CustomResourceDefinition
$ kubectl create -f artifacts/examples/crd.yaml

# create a custom resource of type Foo
$ kubectl create -f artifacts/examples/example-foo.yaml

# check deployments created through the custom resource
$ kubectl get deployments

Use Cases

CustomResourceDefinitions can be used to implement custom resource types for your Kubernetes cluster. These act like most other Resources in Kubernetes, and may be kubectl apply'd, etc.

Some example use cases:

  • Provisioning/Management of external datastores/databases (eg. CloudSQL/RDS instances)
  • Higher level abstractions around Kubernetes primitives (eg. a single Resource to define an etcd cluster, backed by a Service and a ReplicationController)

Defining types

Each instance of your custom resource has an attached Spec, which should be defined via a struct{} to provide data format validation. In practice, this Spec is arbitrary key-value data that specifies the configuration/behavior of your Resource.

For example, if you were implementing a custom resource for a Database, you might provide a DatabaseSpec like the following:

type DatabaseSpec struct {
	Databases []string `json:"databases"`
	Users     []User   `json:"users"`
	Version   string   `json:"version"`

type User struct {
	Name     string `json:"name"`
	Password string `json:"password"`


To validate custom resources, use the CustomResourceValidation feature.

This feature is beta and enabled by default in v1.9.


The schema in crd-validation.yaml applies the following validation on the custom resource: spec.replicas must be an integer and must have a minimum value of 1 and a maximum value of 10.

In the above steps, use crd-validation.yaml to create the CRD:

# create a CustomResourceDefinition supporting validation
$ kubectl create -f artifacts/examples/crd-validation.yaml


Custom Resources support /status and /scale subresources as a beta feature in v1.11 and is enabled by default. This feature is alpha in v1.10 and to enable it you need to set the CustomResourceSubresources feature gate on the kube-apiserver:



The CRD in crd-status-subresource.yaml enables the /status subresource for custom resources. This means that UpdateStatus can be used by the controller to update only the status part of the custom resource.

To understand why only the status part of the custom resource should be updated, please refer to the Kubernetes API conventions.

In the above steps, use crd-status-subresource.yaml to create the CRD:

# create a CustomResourceDefinition supporting the status subresource
$ kubectl create -f artifacts/examples/crd-status-subresource.yaml


You can clean up the created CustomResourceDefinition with:

$ kubectl delete crd


HEAD of this repository will match HEAD of and

Where does it come from?

sample-controller is synced from Code changes are made in that location, merged into and later synced here.

You can’t perform that action at this time.