From a711b852fe086f7ee1ee2b8b4a63198dcf623b48 Mon Sep 17 00:00:00 2001 From: Jonathan Berkhahn Date: Mon, 19 Apr 2021 15:37:06 -0700 Subject: [PATCH 1/2] update golang docs on CRD scoping Signed-off-by: Jonathan Berkhahn --- .../building-operators/golang/crds-scope.md | 108 +++++++++--------- 1 file changed, 53 insertions(+), 55 deletions(-) diff --git a/website/content/en/docs/building-operators/golang/crds-scope.md b/website/content/en/docs/building-operators/golang/crds-scope.md index b312609af3..07e4d2b6ab 100644 --- a/website/content/en/docs/building-operators/golang/crds-scope.md +++ b/website/content/en/docs/building-operators/golang/crds-scope.md @@ -6,29 +6,61 @@ weight: 60 ## Overview -The CustomResourceDefinition (CRD) scope can also be changed for cluster-scoped operators so that there is only a single -instance (for a given name) of the Custom Resource (CR) to manage across the cluster. +Custom Resource Definitions (CRDs) contain a scope field that determines whether the resulting Custom Resource (CR) +is cluster or namespace scoped. Operators can be built using this feature that then are available either on the entire cluster, +or only in one or more namespaces. This might be done for several reasons: an operator author might use a namespaced-scoped operator +to restrict access to a CR to a single namespace, or to have different versions of similar CRs accessible in different namespaces. +Alternatively, an operator author might want a cluster-scoped operator so all users can see and use a single operator.: +This page details the various methods to control the scope of an operator. -The CRD manifests are generated in `config/crd/bases`. For each CRD that needs to be cluster-scoped, its manifest -should specify `spec.scope: Cluster`. +The CRD manifests are generated by operator-sdk in `config/crd/bases`. The `spec.scope` field can be set to `Cluster` or `Namespaced` +to determine how the CR will be scoped. For further information on this field, see [the core k8s CRD docs][k8s_crd_scope]. +For an Operator-sdk Golang project, this can be done by setting `--namespaced` when creating the api, by editing the Golang +`types.go` file for the resource, or by editing the YAML manifest for the CRD. -To ensure that the CRD is always generated with `scope: Cluster`, add the marker -`//+kubebuilder:resource:path=,scope=Cluster`, or if already present replace `scope={Namespaced -> Cluster}`, -above the CRD's Go type definition in `api//_types.go` or `apis///_types.go` -if you are using the [multigroup][multigroup-kubebuilder-doc] layout. Note that the `` -element must be the same lower-case plural value of the CRD's Kind, `spec.names.plural`. +## Set `create api` --namespaced flag -**NOTE**: When a `Manager` instance is created in the `main.go` file, it receives the namespace(s) as Options. +When creating a new API, the `--namespaced` flag controls whether the resulting Custom Resource will be cluster or namespace scoped. +By default, `--namespaced` is set to `true`. An example command to create a cluster-scoped API would be: + +```bash +$ operator-sdk create api --group cache --version v1alpha1 --kind Memcached --resource=true --controller=true --namespaced=false +``` + +## Set Scope Marker in types.go + +You can also manually set the scope in the Golang types.go file by adding a [kubebuilder scope marker][kubebuilder_crd_markers] +to your resource. This file is usually located in `api//_types.go` or `apis///_types.go` if +you are using the [multigroup][multigroup-kubebuilder-doc] layout. Once this marker is set, the CRD files will be generated with the approriate scope. +Here is an example memcached type with the marker set to cluster scope: + +```golang +//+kubebuilder:object:root=true +//+kubebuilder:subresource:status +//+kubebuilder:resource:scope=Cluster + +// Memcached is the Schema for the memcacheds API +type Memcached struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec MemcachedSpec `json:"spec,omitempty"` + Status MemcachedStatus `json:"status,omitempty"` +} +``` +To set the scope to namespaced, the marker would be set to `//+kubebuilder:resource:scope=Namespace` instead. + +**NOTE**: When a Manager instance is created in the `main.go` file, it receives the namespace(s) as Options. These namespace(s) should be watched and cached for the Client which is provided by the Controllers. Only clients provided by cluster-scoped projects where the `Namespace` attribute is `""` will be able to manage cluster-scoped CRs. For more information see the [Manager][manager_user_guide] topic in the user guide and the [Manager Options][manager_options]. -## Example for changing the CRD scope from Namespaced to Cluster +## Set scope in CRD YAML file -- Check the `spec.names.plural` in the CRD's Kind YAML file +The scope can also be manually set directly in the CRD's Kind YAML file, normally located in `config/crd/bases/._.yaml`. +An example YAML file for a namespace-scoped CRD is shown below: -* `/config/crd/bases/cache.example.com_memcacheds.yaml` ```YAML apiVersion: apiextensions.k8s.io/v1beta1 kind: CustomResourceDefinition @@ -50,48 +82,14 @@ spec: ... ``` -- Update the `apis//_types.go` by adding the -marker `//+kubebuilder:resource:path=,scope=Cluster` +**NOTE** This file will be overwritten if you regenerate the YAML manifests by running `make manifests` and haven't changed the corresponding resources in the types.go file. +Take care not to unintentionally overwrite your changes. -* `api/v1alpha1/memcached_types.go` +**NOTE** As above, you must also take care that the Manager in your `main.go` is configured to correctly have access to your resources. -```Go -// Memcached is the Schema for the memcacheds API -//+kubebuilder:resource:path=memcacheds,scope=Cluster -type Memcached struct { - metav1.TypeMeta `json:",inline"` - metav1.ObjectMeta `json:"metadata,omitempty"` - - Spec MemcachedSpec `json:"spec,omitempty"` - Status MemcachedStatus `json:"status,omitempty"` -} -``` -- Run `make manifests`, to update the CRD manifest with the cluster scope setting, as in the following example: - -* `/config/crd/bases/cache.example.com_memcacheds.yaml` - -```YAML -apiVersion: apiextensions.k8s.io/v1beta1 -kind: CustomResourceDefinition -metadata: - annotations: - controller-gen.kubebuilder.io/version: v0.2.5 - creationTimestamp: null - name: memcacheds.cache.example.com -spec: - group: cache.example.com - names: - kind: Memcached - listKind: MemcachedList - plural: memcacheds - singular: memcached - scope: Cluster - subresources: - status: {} -... -``` - -[RBAC]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ -[manager_user_guide]:/docs/building-operators/golang/tutorial/#manager [manager_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Options -[multigroup-kubebuilder-doc]: https://book.kubebuilder.io/migration/multi-group.html \ No newline at end of file +[manager_user_guide]:/docs/building-operators/golang/tutorial/#manager +[k8s_crd_scope]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#create-a-customresourcedefinition +[kubebuilder_crd_markers]: https://book.kubebuilder.io/reference/markers/crd.html +[kubebuilder_multigroup]: https://book.kubebuilder.io/migration/multi-group.html +[RBAC]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ From a7c2fc04c37880250106cbb748d924353b9b7ec8 Mon Sep 17 00:00:00 2001 From: Jonathan Berkhahn Date: Wed, 28 Apr 2021 13:48:03 -0700 Subject: [PATCH 2/2] add estroz suggestions Co-authored-by: Eric Stroczynski Signed-off-by: Jonathan Berkhahn --- .../building-operators/golang/crds-scope.md | 37 +++++++------------ 1 file changed, 14 insertions(+), 23 deletions(-) diff --git a/website/content/en/docs/building-operators/golang/crds-scope.md b/website/content/en/docs/building-operators/golang/crds-scope.md index 07e4d2b6ab..729587efd5 100644 --- a/website/content/en/docs/building-operators/golang/crds-scope.md +++ b/website/content/en/docs/building-operators/golang/crds-scope.md @@ -6,33 +6,32 @@ weight: 60 ## Overview +This page details the various methods to control the scope of a CRD. See the [operator scope doc](/docs/building-operators/golang/operator-scope/) for information on configuring operator scope, such as which namespaces to watch. + Custom Resource Definitions (CRDs) contain a scope field that determines whether the resulting Custom Resource (CR) -is cluster or namespace scoped. Operators can be built using this feature that then are available either on the entire cluster, -or only in one or more namespaces. This might be done for several reasons: an operator author might use a namespaced-scoped operator -to restrict access to a CR to a single namespace, or to have different versions of similar CRs accessible in different namespaces. -Alternatively, an operator author might want a cluster-scoped operator so all users can see and use a single operator.: -This page details the various methods to control the scope of an operator. +is cluster or namespace scoped. An operator author might use a namespaced-scoped CRD +to restrict access to a CR to certain namespaces, or to have different versions of CRs accessible in different namespaces. +Alternatively, an operator author might want a cluster-scoped CRD so all namespaces have visibility and access to CRs. -The CRD manifests are generated by operator-sdk in `config/crd/bases`. The `spec.scope` field can be set to `Cluster` or `Namespaced` -to determine how the CR will be scoped. For further information on this field, see [the core k8s CRD docs][k8s_crd_scope]. -For an Operator-sdk Golang project, this can be done by setting `--namespaced` when creating the api, by editing the Golang -`types.go` file for the resource, or by editing the YAML manifest for the CRD. +The CRD manifests are generated by the `operator-sdk create api` command in `config/crd/bases`. A CRD's `spec.scope` field controls API scope; valid values are [`Cluster` and `Namespaced`](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#create-a-customresourcedefinition). +For an Operator-sdk Go project, this value is determined by the `operator-sdk create api --namespaced` boolean flag, which edits the +`types.go` file for the resource. For other operator types, the command edits `spec.scope` in the CRD's YAML manifest directly. ## Set `create api` --namespaced flag -When creating a new API, the `--namespaced` flag controls whether the resulting Custom Resource will be cluster or namespace scoped. -By default, `--namespaced` is set to `true`. An example command to create a cluster-scoped API would be: +When creating a new API, the `--namespaced` flag controls whether the resulting CRD will be cluster or namespace scoped. +By default, `--namespaced` is set to `true` which sets the scope to `Namespaced`. An example command to create a cluster-scoped API would be: -```bash +```console $ operator-sdk create api --group cache --version v1alpha1 --kind Memcached --resource=true --controller=true --namespaced=false ``` ## Set Scope Marker in types.go -You can also manually set the scope in the Golang types.go file by adding a [kubebuilder scope marker][kubebuilder_crd_markers] +You can also manually set the scope in the Go `types.go` file by adding or changing the [kubebuilder scope marker][kubebuilder_crd_markers] to your resource. This file is usually located in `api//_types.go` or `apis///_types.go` if you are using the [multigroup][multigroup-kubebuilder-doc] layout. Once this marker is set, the CRD files will be generated with the approriate scope. -Here is an example memcached type with the marker set to cluster scope: +Here is an example API type with the marker set to cluster scope: ```golang //+kubebuilder:object:root=true @@ -50,15 +49,10 @@ type Memcached struct { ``` To set the scope to namespaced, the marker would be set to `//+kubebuilder:resource:scope=Namespace` instead. -**NOTE**: When a Manager instance is created in the `main.go` file, it receives the namespace(s) as Options. -These namespace(s) should be watched and cached for the Client which is provided by the Controllers. Only clients -provided by cluster-scoped projects where the `Namespace` attribute is `""` will be able to manage cluster-scoped CRs. -For more information see the [Manager][manager_user_guide] topic in the user guide and the -[Manager Options][manager_options]. ## Set scope in CRD YAML file -The scope can also be manually set directly in the CRD's Kind YAML file, normally located in `config/crd/bases/._.yaml`. +The scope can be manually set directly in the CRD's Kind YAML file, normally located in `config/crd/bases/._.yaml`. An example YAML file for a namespace-scoped CRD is shown below: ```YAML @@ -82,10 +76,7 @@ spec: ... ``` -**NOTE** This file will be overwritten if you regenerate the YAML manifests by running `make manifests` and haven't changed the corresponding resources in the types.go file. -Take care not to unintentionally overwrite your changes. -**NOTE** As above, you must also take care that the Manager in your `main.go` is configured to correctly have access to your resources. [manager_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Options [manager_user_guide]:/docs/building-operators/golang/tutorial/#manager