Scaffolding
The first step typically in writing a new controller is to generate the scaffolding for it. The scaffolding covers functionality which is common to all controllers. Its purpose is not only to reduce the boilerplate required to write a new controller, but also to guarantee consistency of behaviour across APIs.
Note
While it is possible to write this code manually, any controller requiring this is potentially stretching assumptions made throughout the project. If this is required, consider if changes can be made such that it is not required, or if further design work is required in the scaffolding or generic controller code.
The first step is to add the new resource to allResources
in cmd/resource-generator/main.go
and run:
make generate-resources
This will generate 3 files for you:
api/<version>/zz_generated.<resource>-resource.go
internal/controllers/<resource>/zz_generated.adapter.go
internal/controllers/<resource>/zz_generated.controller.go
Note
These files are generated using a very simplistic text templating system in cmd/resource-generator
. If you are wondering why we didn't use generics, which are widely used throughout the rest of the code, it's because controller-gen
, which generates CRDs from the API, doesn't yet support them. Consequently we generate manually what generics would have generated implicitly. This code may be rewritten in the future if controller-gen
gains support for generics.
The code will not compile at this point, as the generated code will refer to code you have not yet written. You will also have to write the following, covered in more detail in subsequent sections of this documentation:
The API
This is typically principally defined in:
api/v1alpha1/<resourcename>_types.go
Controller initialisation
These are typically defined in:
internal/controllers/<resource>/controller.go
internal/controllers/<resource>/reconcile.go
The actuator
This is typically defined in:
internal/controllers/<resource>/actuator.go
The status writer
This is typically defined in:
internal/controllers/<resource>/status.go