Change apiversion of CRD from v1beta1 to v1

- Update CRDs (crd.yaml, crd-status-subresource.yaml) to match requirements of current release - Add `versions` field and structures `schema` as made mandatory in apiextensions/v1 - Add annotation for api-approved.kubernetes.io since CRD is under *k8s.io domain - Delete crd-validation.yaml since structured schema is mandatory in v1 - Update README Signed-off-by: Madhav Jivrajani <[email protected]> Kubernetes-commit: fd0ac9c8d169169c8072639970565cda9fb9499a
am6737 · May 10, 2021 · cba5d7c · cba5d7c
1 parent 53528ac
commit cba5d7c
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 49 deletions.
diff --git a/README.md b/README.md
@@ -59,7 +59,7 @@ cd sample-controller
 ```
 
 Note, however, that if you intend to
-[generate code](#changes-to-the-types) then you will also need the
+generate code then you will also need the
 code-generator repo to exist in an old-style location.  One easy way
 to do this is to use the command `go mod vendor` to create and
 populate the `vendor` directory.
@@ -128,36 +128,21 @@ type User struct {
 
 ## Validation
 
-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.
+To validate custom resources, use the [`CustomResourceValidation`](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#validation) feature. Validation in the form of a [structured schema](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema) is mandatory to be provided for `apiextensions.k8s.io/v1`.
 
 ### Example
 
-The schema in [`crd-validation.yaml`](./artifacts/examples/crd-validation.yaml) applies the following validation on the custom resource:
+The schema in [`crd.yaml`](./artifacts/examples/crd.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
-# create a CustomResourceDefinition supporting validation
-kubectl create -f artifacts/examples/crd-validation.yaml
-```
-
 ## Subresources
 
-Custom Resources support `/status` and `/scale` subresources as a [beta feature](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#subresources) in v1.11 and is enabled by default.
-This feature is [alpha](https://v1-10.docs.kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#subresources) in v1.10 and to enable it you need to set the `CustomResourceSubresources` feature gate on the [kube-apiserver](https://kubernetes.io/docs/admin/kube-apiserver):
-
-```sh
---feature-gates=CustomResourceSubresources=true
-```
+Custom Resources support `/status` and `/scale` [subresources](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#subresources). The `CustomResourceSubresources` feature is in GA from v1.16.
 
 ### Example
 
-The CRD in [`crd-status-subresource.yaml`](./artifacts/examples/crd-status-subresource.yaml) enables the `/status` subresource
-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.
+The CRD in [`crd-status-subresource.yaml`](./artifacts/examples/crd-status-subresource.yaml) enables the `/status` subresource for custom resources.
+This means that [`UpdateStatus`](./controller.go) 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/sig-architecture/api-conventions.md#spec-and-status).
 
@@ -168,11 +153,15 @@ In the above steps, use `crd-status-subresource.yaml` to create the CRD:
 kubectl create -f artifacts/examples/crd-status-subresource.yaml
 ```
 
+## A Note on the API version
+The [group](https://kubernetes.io/docs/reference/using-api/#api-groups) version of the custom resource in `crd.yaml` is `v1alpha`, this can be evolved to a stable API version, `v1`, using [CRD Versioning](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/).
+
 ## Cleanup
 
 You can clean up the created CustomResourceDefinition with:
-
-    kubectl delete crd foos.samplecontroller.k8s.io
+```sh
+kubectl delete crd foos.samplecontroller.k8s.io
+```
 
 ## Compatibility
 

diff --git a/artifacts/examples/crd-status-subresource.yaml b/artifacts/examples/crd-status-subresource.yaml
@@ -1,13 +1,41 @@
-apiVersion: apiextensions.k8s.io/v1beta1
+apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition
 metadata:
   name: foos.samplecontroller.k8s.io
+  # for more information on the below annotation, please see
+  # https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/2337-k8s.io-group-protection/README.md
+  annotations:
+    "api-approved.kubernetes.io": "unapproved, experimental-only; please get an approval from Kubernetes API reviewers if you're trying to develop a CRD in the *.k8s.io or *.kubernetes.io groups"
 spec:
   group: samplecontroller.k8s.io
-  version: v1alpha1
+  versions:
+    - name: v1alpha1
+      served: true
+      storage: true
+      schema:
+        # schema used for validation
+        openAPIV3Schema:
+          type: object
+          properties:
+            spec:
+              type: object
+              properties:
+                deploymentName:
+                  type: string
+                replicas:
+                  type: integer
+                  minimum: 1
+                  maximum: 10
+            status:
+              type: object
+              properties:
+                availableReplicas:
+                  type: integer
+      # subresources for the custom resource
+      subresources:
+        # enables the status subresource
+        status: {}
   names:
     kind: Foo
     plural: foos
   scope: Namespaced
-  subresources:
-    status: {}
diff --git a/artifacts/examples/crd-validation.yaml b/artifacts/examples/crd-validation.yaml
diff --git a/artifacts/examples/crd.yaml b/artifacts/examples/crd.yaml
@@ -1,10 +1,36 @@
-apiVersion: apiextensions.k8s.io/v1beta1
+apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition
 metadata:
   name: foos.samplecontroller.k8s.io
+  # for more information on the below annotation, please see
+  # https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/2337-k8s.io-group-protection/README.md
+  annotations:
+    "api-approved.kubernetes.io": "unapproved, experimental-only; please get an approval from Kubernetes API reviewers if you're trying to develop a CRD in the *.k8s.io or *.kubernetes.io groups"
 spec:
   group: samplecontroller.k8s.io
-  version: v1alpha1
+  versions:
+    - name: v1alpha1
+      served: true
+      storage: true
+      schema:
+        # schema used for validation
+        openAPIV3Schema:
+          type: object
+          properties:
+            spec:
+              type: object
+              properties:
+                deploymentName:
+                  type: string
+                replicas:
+                  type: integer
+                  minimum: 1
+                  maximum: 10
+            status:
+              type: object
+              properties:
+                availableReplicas:
+                  type: integer
   names:
     kind: Foo
     plural: foos