kube-controller-gen

kube-controller-gen

Generate utility code for writing Kubernetes controllers in Go.

How to use it

Write a controller-gen.yaml

This file describes the clientsets, APIs and Resources to watch. See below for documentation of this file.

Generate the controller code

kube-controller-gen -s

This creates two files:

• zz_generated_controller.go contains all the framework code. Do not touch this file - it will recreated completely every time you change controller-gen.yaml and run kube-controller-gen.
• zz_generated_sample.go is a sample for your main program. Rename this file to for example main.go and add the required functions.

If you change controller-gen.yaml, run kube-controller-gen again. Without the -s option, it will not generate the sample file again. Run it with the -s option if you would like to create a new sample file, copy the relevant portions to your main.go and remove the file zz_generated_sample.go again.

Write your controller

Write your controller code itself. The file zz_generated_sample.go can be used as a starting point. Generally, you will need a function that initializes the Controller data structure and starts the controllers.

c := &Controller{Kubernetes: clientset}

c.Initialize()
c.Start()

For every resource you want to watch (and you have declared in controller-gen.yaml), you need two functions that are called by the framework whenever your resource is created/updated or deleted:

func (c *Controller) XXXCreatedOrUpdated(x *XXX) error {
	// do something with your new or updated x
	return nil
}

func (c *Controller) XXXDeleted(x *XXX) error {
	// do something with your x as it is being deleted
	return nil
}

The sample file will contain such a function for every resource you declared.

See examples for complete examples.

Calling kube-controller-gen

kube-controller-gen supports the following options:

• -c the location of the configuration file (default: controller-gen.yaml in your current directory)
• -o output directory (default: the current directory)
• -s create the sample file zz_generated_sample.go (default: false). This will overwrite the file so do not add any code there!

controller-gen.yaml

Top level parameters:

• package is the packaged name used for the generated code.
• clientsets is a list of clientsets to use.
• controllerextra (string) anything you would like to add to the Controller type
• imports (string) additional imports

Clientsets:

• name is the name of the clientset to use. Use kubernetes to generate the standard kubernetes clientset. Custom resources are supported here, use a symbolic name for your clientset then.
• apis is a list of APIs used.
• import (CRD only) is the URL of the go package to import (base directory, excluding pkg)
• defaultresync controls how often to check your resources, in addition to reacting to events. In seconds. Set to 0 to disable resync.

APIs:

• name is the API name. For example, core for core Kubernetes resources like Pods or Services.
• version is the API version
• resources are the resources in API to watch.
• group is the API group name (empty for core)

Resources:

• name is the name, like Pod.
• plural is the plural of the name, like Pods.
• scope is Namespaced or Cluster.
• create / update / delete are booleans and control which of these event types you want to watch for your resource type.

Custom resources

The generated controller can use multiple clientsets, including custom resources. The included custom client is expected to have a structure as generated by https://github.com/kubernetes/code-generator, with listers and shared informer.