From 6619e38852147e82656f773763572092a9e27d0f Mon Sep 17 00:00:00 2001 From: jberkhahn Date: Tue, 9 Apr 2024 15:28:05 -0700 Subject: [PATCH] Change docs to reflect updated controller runtime options for caching select namespaces Signed-off-by: jberkhahn --- .../golang/operator-scope.md | 35 +++++++++++-------- .../building-operators/golang/tutorial.md | 1 - 2 files changed, 21 insertions(+), 15 deletions(-) diff --git a/website/content/en/docs/building-operators/golang/operator-scope.md b/website/content/en/docs/building-operators/golang/operator-scope.md index 4e66f827ea..eeb8a3ad0a 100644 --- a/website/content/en/docs/building-operators/golang/operator-scope.md +++ b/website/content/en/docs/building-operators/golang/operator-scope.md @@ -19,7 +19,7 @@ as cluster-scoped. For example, the [cert-manager][cert-manager] operator is oft permissions and watches so that it can manage and issue certificates for an entire cluster. **IMPORTANT**: When a [Manager][ctrl-manager] instance is created in the `main.go` file, the -Namespaces are set via [Manager Options][ctrl-options] as described below. These Namespaces should be watched and +Namespaces are set via [Cache Config][cache-config] as described below. These Namespaces should be watched and cached for the Client which is provided by the Manager. Only clients provided by cluster-scoped Managers are able to manage cluster-scoped CRD's. For further information see: [CRD scope doc][crd-scope-doc]. @@ -27,7 +27,7 @@ to manage cluster-scoped CRD's. For further information see: [CRD scope doc][crd ### Watching resources in all Namespaces (default) -A [Manager][ctrl-manager] is initialized with no Namespace option specified, or `Namespace: ""` will +A [Manager][ctrl-manager] is initialized with no Cache option specified, or with a Cache.DefaultNamespaces of `Namespace: ""` will watch all Namespaces: ```go @@ -42,10 +42,10 @@ mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{ ... ``` -### Watching resources in a single Namespace +### Watching resources in specific Namespaces -To restrict the scope of the [Manager's][ctrl-manager] cache to a specific Namespace set the `Namespace` field -in [Options][ctrl-options]: +To restrict the scope of the [Manager's][ctrl-manager] cache to a specific Namespace set the `Cache.DefaultNamespaces' +field in [Options][ctrl-options]: ```go ... @@ -55,32 +55,39 @@ mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{ Port: 9443, LeaderElection: enableLeaderElection, LeaderElectionID: "f1c5ece8.example.com", - Namespace: "operator-namespace", + Cache: cache.Options{ + DefaultNamespaces: map[string]cache.Config{"operator-namespace": cache.Config{}}, + }, }) ... ``` ### Watching resources in a set of Namespaces -It is possible to use [`MultiNamespacedCacheBuilder`][multi-namespaced-cache-builder] from -[Options][ctrl-options] to watch and manage resources in a set of Namespaces: +It is also possible to use 'DefaultNamepsaces' to watch and manage resources in a set of Namespaces: ```go ... -namespaces := []string{"foo", "bar"} // List of Namespaces -... mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{ Scheme: scheme, MetricsBindAddress: metricsAddr, Port: 9443, LeaderElection: enableLeaderElection, LeaderElectionID: "f1c5ece8.example.com", - NewCache: cache.MultiNamespacedCacheBuilder(namespaces), + Cache: cache.Options{ + DefaultNamespaces: map[string]cache.Config{ + "operator-namespace1": cache.Config{}, + "operator-namespace2": cache.Config{}, + }, + }, }) ... ``` -In the above example, a CR created in a Namespace not in the set passed to `Options` will not be reconciled by -its controller because the [Manager][ctrl-manager] does not manage that Namespace. + +In the above example, a CR created in a Namespace not in the set passed to `Cache.DefaultNamespaces` will not be reconciled by +its controller because the [Manager][ctrl-manager] does not manage that Namespace. Further restrictions and qualifications +can created on a per-namespace basis by setting fields in the cache.Config object, for further information see the +[controller runtime docs][cache-config] **IMPORTANT:** Note that this is not intended to be used for excluding Namespaces, this is better done via a Predicate. @@ -299,10 +306,10 @@ If the operator can watch multiple namespaces, set the following in your `spec.i supported: true ``` +[cache-config]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/cache#Config [cert-manager]: https://github.com/jetstack/cert-manager [ctrl-manager]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/manager#Manager [ctrl-options]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/manager#Options -[multi-namespaced-cache-builder]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/cache#MultiNamespacedCacheBuilder [k8s-rbac]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ [kube-rbac-proxy]: https://github.com/brancz/kube-rbac-proxy [rbac-clusterrole]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole diff --git a/website/content/en/docs/building-operators/golang/tutorial.md b/website/content/en/docs/building-operators/golang/tutorial.md index 9d4b4ec274..ee0f9507dd 100644 --- a/website/content/en/docs/building-operators/golang/tutorial.md +++ b/website/content/en/docs/building-operators/golang/tutorial.md @@ -545,7 +545,6 @@ Next, check out the following: [markers]: https://book.kubebuilder.io/reference/markers.html [memcached_controller]: https://github.com/operator-framework/operator-sdk/blob/latest/testdata/go/v4/memcached-operator/internal/controller/memcached_controller.go [migration-guide]:/docs/building-operators/golang/migration -[multi-namespaced-cache-builder]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/cache#MultiNamespacedCacheBuilder [multigroup-kubebuilder-doc]: https://book.kubebuilder.io/migration/multi-group.html [olm-integration]: /docs/olm-integration [openapi-validation]: /docs/building-operators/golang/references/openapi-validation