update golang docs on CRD scoping

Signed-off-by: Jonathan Berkhahn <[email protected]>

Author: jberkhahn

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=<resource>,scope=Cluster`, or if already present replace `scope={Namespaced -> Cluster}`, 
-above the CRD's Go type definition in `api/<version>/<kind>_types.go` or `apis/<group>/<version>/<kind>_types.go` 
-if you are using the [multigroup][multigroup-kubebuilder-doc] layout. Note that the `<resource>` 
-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/<version>/<kind>_types.go` or `apis/<group>/<version>/<kind>_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/<group>.<domain>_<kind>.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/<version>/<kind>_types.go` by adding the 
-marker `//+kubebuilder:resource:path=<resource>,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
+[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/