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..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,69 +6,54 @@ 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. +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. -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`. +Custom Resource Definitions (CRDs) contain a scope field that determines whether the resulting Custom Resource (CR) +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. -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`. +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. -**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 `create api` --namespaced flag -## Example for changing the CRD scope from Namespaced to Cluster +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: -- Check the `spec.names.plural` in the CRD's Kind YAML file +```console +$ operator-sdk create api --group cache --version v1alpha1 --kind Memcached --resource=true --controller=true --namespaced=false +``` -* `/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: Namespaced - subresources: - status: {} -... -``` +## Set Scope Marker in types.go -- Update the `apis//_types.go` by adding the -marker `//+kubebuilder:resource:path=,scope=Cluster` +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 API type with the marker set to cluster scope: -* `api/v1alpha1/memcached_types.go` +```golang +//+kubebuilder:object:root=true +//+kubebuilder:subresource:status +//+kubebuilder:resource:scope=Cluster -```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"` + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` - Spec MemcachedSpec `json:"spec,omitempty"` - Status MemcachedStatus `json:"status,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` +``` +To set the scope to namespaced, the marker would be set to `//+kubebuilder:resource:scope=Namespace` instead. + + +## Set scope in CRD YAML file + +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 apiVersion: apiextensions.k8s.io/v1beta1 @@ -85,13 +70,17 @@ spec: listKind: MemcachedList plural: memcacheds singular: memcached - scope: Cluster + scope: Namespaced 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/