sample-controller: add status subresource support

- Add an example to show how to use status subresources
with custom resources.
- Update the comment in the controller to mention that
`UpdateStatus` can now be used.
- Generate `UpdateStatus` for Foo.
- Update the README to remove feature gate information for
CRD validation since the current example requires a v1.9
cluster and it is enabled by default.
- Update the README to add feature gate information for
CustomResourceSubResources.

Kubernetes-commit: 7c06d6fb17ee46f587c1facff93b9bb185522855

README.md

@@ -79,17 +79,44 @@ type User struct {
 
 To validate custom resources, use the [`CustomResourceValidation`](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#validation) feature.
 
-This feature is beta and enabled by default in v1.9. If you are using v1.8, enable the feature using
+This feature is beta and enabled by default in v1.9.
-the `CustomResourceValidation` feature gate on the [kube-apiserver](https://kubernetes.io/docs/admin/kube-apiserver):
+
+### Example
+
+The schema in [`crd-validation.yaml`](./artifacts/examples/crd-validation.yaml) applies the following validation on the custom resource:
+`spec.replicas` must be an integer and must have a minimum value of 1 and a maximum value of 10.
+
+In the above steps, use `crd-validation.yaml` to create the CRD:
 
 ```sh
---feature-gates=CustomResourceValidation=true
+# create a CustomResourceDefinition supporting validation
+$ kubectl create -f artifacts/examples/crd-validation.yaml
+```
+
+## Subresources
+
+Custom Resources support `/status` and `/scale` subresources as an
+[alpha feature](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#subresources) in v1.10.
+Enable this feature using the `CustomResourceSubresources` feature gate on the [kube-apiserver](https://kubernetes.io/docs/admin/kube-apiserver):
+
+```sh
+--feature-gates=CustomResourceSubresources=true
 ```
 
 ### Example
 
-The schema in the [example CRD](./artifacts/examples/crd.yaml) applies the following validation on the custom resource:
+The CRD in [`crd-status-subresource.yaml`](./artifacts/examples/crd-status-subresource.yaml) enables the `/status` subresource
-`spec.replicas` must be an integer and must have a minimum value of 1 and a maximum value of 10.
+for custom resources.
+This means that [`UpdateStatus`](./controller.go#L330) can be used by the controller to update only the status part of the custom resource.
+
+To understand why only the status part of the custom resource should be updated, please refer to the [Kubernetes API conventions](https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status).
+
+In the above steps, use `crd-status-subresource.yaml` to create the CRD:
+
+```sh
+# create a CustomResourceDefinition supporting the status subresource
+$ kubectl create -f artifacts/examples/crd-status-subresource.yaml
+```
 
 ## Cleanup
 

artifacts/examples/crd-status-subresource.yaml

@@ -0,0 +1,13 @@
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  name: foos.samplecontroller.k8s.io
+spec:
+  group: samplecontroller.k8s.io
+  version: v1alpha1
+  names:
+    kind: Foo
+    plural: foos
+  scope: Namespaced
+  subresources:
+    status: {}

artifacts/examples/crd-validation.yaml

@@ -0,0 +1,20 @@
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  name: foos.samplecontroller.k8s.io
+spec:
+  group: samplecontroller.k8s.io
+  version: v1alpha1
+  names:
+    kind: Foo
+    plural: foos
+  scope: Namespaced
+  validation:
+    openAPIV3Schema:
+      properties:
+        spec:
+          properties:
+            replicas:
+              type: integer
+              minimum: 1
+              maximum: 10

artifacts/examples/crd.yaml

@@ -9,12 +9,3 @@ spec:
     kind: Foo
     plural: foos
   scope: Namespaced
-  validation:
-    openAPIV3Schema:
-      properties:
-        spec:
-          properties:
-            replicas:
-              type: integer
-              minimum: 1
-              maximum: 10

controller.go

@@ -327,10 +327,10 @@ func (c *Controller) updateFooStatus(foo *samplev1alpha1.Foo, deployment *appsv1
 	// Or create a copy manually for better performance
 	fooCopy := foo.DeepCopy()
 	fooCopy.Status.AvailableReplicas = deployment.Status.AvailableReplicas
-	// Until #38113 is merged, we must use Update instead of UpdateStatus to
+	// If the CustomResourceSubresources feature gate is not enabled,
-	// update the Status block of the Foo resource. UpdateStatus will not
+	// we must use Update instead of UpdateStatus to update the Status block of the Foo resource.
-	// allow changes to the Spec of the resource, which is ideal for ensuring
+	// UpdateStatus will not allow changes to the Spec of the resource,
-	// nothing other than resource status has been updated.
+	// which is ideal for ensuring nothing other than resource status has been updated.
 	_, err := c.sampleclientset.SamplecontrollerV1alpha1().Foos(foo.Namespace).Update(fooCopy)
 	return err
 }

pkg/apis/samplecontroller/v1alpha1/types.go

@@ -21,7 +21,6 @@ import (
 )
 
 // +genclient
-// +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
 // Foo is a specification for a Foo resource