diff --git a/Godeps/Godeps.json b/Godeps/Godeps.json index fe3e2fef..52a46bae 100644 --- a/Godeps/Godeps.json +++ b/Godeps/Godeps.json @@ -476,15 +476,15 @@ }, { "ImportPath": "k8s.io/api", - "Rev": "8c6483ecf45e" + "Rev": "8672a591239a" }, { "ImportPath": "k8s.io/apimachinery", - "Rev": "96c076bf1d97" + "Rev": "4c2cee4b928c" }, { "ImportPath": "k8s.io/client-go", - "Rev": "9a82c6a51a32" + "Rev": "253f58be506d" }, { "ImportPath": "k8s.io/code-generator", diff --git a/README.md b/README.md index 9e7035b1..346c8f73 100644 --- 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 index af74dbc5..90b70d14 100644 --- 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 deleted file mode 100644 index 36469161..00000000 --- a/artifacts/examples/crd-validation.yaml +++ /dev/null @@ -1,20 +0,0 @@ -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 diff --git a/artifacts/examples/crd.yaml b/artifacts/examples/crd.yaml index 4a457068..8ac6e60c 100644 --- 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 diff --git a/go.mod b/go.mod index a79a4311..531de9da 100644 --- a/go.mod +++ b/go.mod @@ -5,16 +5,16 @@ module k8s.io/sample-controller go 1.16 require ( - k8s.io/api v0.0.0-20210506172159-8c6483ecf45e - k8s.io/apimachinery v0.0.0-20210518100457-96c076bf1d97 - k8s.io/client-go v0.0.0-20210518102928-9a82c6a51a32 + k8s.io/api v0.0.0-20210518101624-8672a591239a + k8s.io/apimachinery v0.0.0-20210518100458-4c2cee4b928c + k8s.io/client-go v0.0.0-20210518102935-253f58be506d k8s.io/code-generator v0.0.0-20210518095634-f57bba428cbd k8s.io/klog/v2 v2.8.0 ) replace ( - k8s.io/api => k8s.io/api v0.0.0-20210506172159-8c6483ecf45e - k8s.io/apimachinery => k8s.io/apimachinery v0.0.0-20210518100457-96c076bf1d97 - k8s.io/client-go => k8s.io/client-go v0.0.0-20210518102928-9a82c6a51a32 + k8s.io/api => k8s.io/api v0.0.0-20210518101624-8672a591239a + k8s.io/apimachinery => k8s.io/apimachinery v0.0.0-20210518100458-4c2cee4b928c + k8s.io/client-go => k8s.io/client-go v0.0.0-20210518102935-253f58be506d k8s.io/code-generator => k8s.io/code-generator v0.0.0-20210518095634-f57bba428cbd ) diff --git a/go.sum b/go.sum index 9ad15873..ff419913 100644 --- a/go.sum +++ b/go.sum @@ -427,12 +427,12 @@ honnef.co/go/tools v0.0.0-20190418001031-e561f6794a2a/go.mod h1:rf3lG4BRIbNafJWh honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= honnef.co/go/tools v0.0.1-2019.2.3/go.mod h1:a3bituU0lyd329TUQxRnasdCoJDkEUEAqEt0JzvZhAg= honnef.co/go/tools v0.0.1-2020.1.3/go.mod h1:X/FiERA/W4tHapMX5mGpAtMSVEeEUOyHaw9vFzvIQ3k= -k8s.io/api v0.0.0-20210506172159-8c6483ecf45e h1:qHyhF6qKQVHrfQmOto8W6vEj7OASwoH8x1+p0l/81Dk= -k8s.io/api v0.0.0-20210506172159-8c6483ecf45e/go.mod h1:IgKLK42qxUHnMxdcdbEBFOo+TfTANemQTLg3gcGe8/M= -k8s.io/apimachinery v0.0.0-20210518100457-96c076bf1d97 h1:hKyy5Pr8MoGjcqM5AYHQjpizciRmC8dz4N3XG4LZwuQ= -k8s.io/apimachinery v0.0.0-20210518100457-96c076bf1d97/go.mod h1:fBRSkoylGO2QUTae8Wb2wac6pZ83/r+tL6HFSXGbzfs= -k8s.io/client-go v0.0.0-20210518102928-9a82c6a51a32 h1:pIQGgo4Zwcfxal6+QhaEb7qeCKzdqL1AuvN/1J0/DVY= -k8s.io/client-go v0.0.0-20210518102928-9a82c6a51a32/go.mod h1:VAUK6xq/o8PmTB8fQVPDh2Mb+05oZs9sXSh8opEUMqc= +k8s.io/api v0.0.0-20210518101624-8672a591239a h1:EEW042DxiuHtcAqQyp3Pk2w5/3Kc/b8DyrymbscceAM= +k8s.io/api v0.0.0-20210518101624-8672a591239a/go.mod h1:y+gvByfVKNWO6mErcyYTqghJvmW73GJQPxjlYKfOuio= +k8s.io/apimachinery v0.0.0-20210518100458-4c2cee4b928c h1:4cylLlCjbU4MC+jV8O68gmICP2kk8agE4tceRMAljVs= +k8s.io/apimachinery v0.0.0-20210518100458-4c2cee4b928c/go.mod h1:fBRSkoylGO2QUTae8Wb2wac6pZ83/r+tL6HFSXGbzfs= +k8s.io/client-go v0.0.0-20210518102935-253f58be506d h1:C41agJxt80kox7Ofjqku7YyR3uJOGpR1XnAkUW/7S+U= +k8s.io/client-go v0.0.0-20210518102935-253f58be506d/go.mod h1:+PVVaE0ruVk5zAJUxGxhQdexBY4v0yNqYsEShnm3q1Y= k8s.io/code-generator v0.0.0-20210518095634-f57bba428cbd h1:9Fmm+5AYUpdfhkwg996JQEOcDP3ch8seQcVwupl/kVg= k8s.io/code-generator v0.0.0-20210518095634-f57bba428cbd/go.mod h1:tHNeGA58jE3nJvZLDN0c/5k7P3NlYdjbWuJYK9QiU3s= k8s.io/gengo v0.0.0-20200413195148-3a45101e95ac/go.mod h1:ezvh/TsK7cY6rbqRK0oQQ8IAqLxYwwyPxAX1Pzy0ii0=