From ba7f4b4473168b2011fea7f3fa0b7d9c574b1cda Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Tue, 24 Apr 2018 19:43:49 -0700 Subject: [PATCH] Better documentation on watching things --- README.md | 30 ++++++++++++++----- cmd/kubebuilder/create/resource/controller.go | 14 +++++++-- cmd/kubebuilder/create/resource/resource.go | 2 ++ 3 files changed, 36 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index e0fa9e6ef7..89152dff9f 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,10 @@ Subpackages of apis are created when running the following command to create a n kubebuilder create resource --group mygroup --version v1beta1 --kind MyKind ``` +**Note:** While `create resource` automatically runs the code generators for the user, when +the user changes the resource file or adds `// +kubebuilder` annotations to the controller, +they will need to run `kubebuilder generate` to rerun the code generators. + ### pkg/controllers **Users must edit packages under this package** @@ -119,6 +123,10 @@ kubebuilder create resource --group mygroup --version v1beta1 --kind MyKind See documentation and examples of annotations in godoc format here: - [gen/controller](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller#example-package) +**Note:** While `create resource` automatically runs the code generators for the user, when +the user changes the resource file or adds `// +kubebuilder` annotations to the controller, +they will need to run `kubebuilder generate` to rerun the code generators. + ### pkg/inject *Most users do not need to edit this package.* @@ -201,20 +209,26 @@ this example: [GenericController](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/controller#example-GenericController) -Use the following annotation to start additional informers for any resources you are watching in your controller. -```go -// +informers:group=apps,version=v1,kind=Deployment -``` +To Watch additional resources from your controller do the following in your controller.go: -Use the following annotation to generate RBAC rules to allow your controller to read and write resources when -running in a container in a Kubernetes cluster. +1. Add a `gc.Watch*` call to the `ProvideController`. e.g. Call gc.[WatchTransformationKeyOf](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/controller#example-GenericController-WatchTransformationKeyOf) + - This will trigger Reconcile calls for events +2. Add an [// +informers:](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller#example-package) annotation + to the `type Controller struct` with the type of the resource you are watching + - This will make sure the informers that watch for events are started +3. Add an [// +rbac:](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller#example-package) + annotation to the `type Controller struct` with the type of the resource you are watching + - This will make sure the RBAC rules that allow the controller to watch events in a cluster are generated + +Example: ```go -// +rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete +// +kubebuilder:rbac:groups="",resources=pods,verbs=get;watch;list +// +kubebuilder:informers:group=core,version=v1,kind=Pod +type FooController struct{} ``` - ### Watching resources Controllers watch resources to trigger reconcile functions. It is common for controllers to reconcile a single resource diff --git a/cmd/kubebuilder/create/resource/controller.go b/cmd/kubebuilder/create/resource/controller.go index 29ae80d118..9451d0465e 100644 --- a/cmd/kubebuilder/create/resource/controller.go +++ b/cmd/kubebuilder/create/resource/controller.go @@ -90,8 +90,18 @@ func ProvideController(arguments args.InjectArgs) (*controller.GenericController return gc, err } - // INSERT ADDITIONAL WATCHES HERE BY CALLING gc.Watch.*() FUNCTIONS - // NOTE: Informers for Kubernetes resources *MUST* be registered in the pkg/inject package so that they are started. + // IMPORTANT: + // To watch additional resource types - such as those created by your controller - add gc.Watch* function calls here + // Watch function calls will transform each object event into a {{.Kind}} Key to be reconciled by the controller. + // + // ********** + // For any new Watched types, you MUST add the appropriate // +kubebuilder:informer and // +kubebuilder:rbac + // annotations to the {{.Kind}}Controller and run "kubebuilder generate. + // This will generate the code to start the informers and create the RBAC rules needed for running in a cluster. + // See: + // https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller#example-package + // ********** + return gc, nil } ` diff --git a/cmd/kubebuilder/create/resource/resource.go b/cmd/kubebuilder/create/resource/resource.go index 6aa48636c3..9fcfc19103 100644 --- a/cmd/kubebuilder/create/resource/resource.go +++ b/cmd/kubebuilder/create/resource/resource.go @@ -62,11 +62,13 @@ import ( // {{.Kind}}Spec defines the desired state of {{.Kind}} type {{.Kind}}Spec struct { // INSERT ADDITIONAL SPEC FIELDS - desired state of cluster + // Important: Run "kubebuilder generate" to regenerate code after modifying this file } // {{.Kind}}Status defines the observed state of {{.Kind}} type {{.Kind}}Status struct { // INSERT ADDITIONAL STATUS FIELD - define observed state of cluster + // Important: Run "kubebuilder generate" to regenerate code after modifying this file } // +genclient