From b6fcf2913faebbd5c15a1c6d162efa38f76be0df Mon Sep 17 00:00:00 2001 From: "Dr. Stefan Schimanski" Date: Tue, 19 Jun 2018 10:39:14 +0200 Subject: [PATCH] Document CustomResourceDefinition additionalPrinterColumns --- .../custom-resource-definitions.md | 121 ++++++++++++++++-- 1 file changed, 109 insertions(+), 12 deletions(-) diff --git a/content/en/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions.md b/content/en/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions.md index 8b2e97da8f41b..f0c6b4c66019b 100644 --- a/content/en/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions.md +++ b/content/en/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions.md @@ -208,23 +208,26 @@ metadata: Finalizers are arbitrary string values, that when present ensure that a hard delete of a resource is not possible while they exist. -The first delete request on an object with finalizers merely sets a value for the -`metadata.deletionTimestamp` field instead of deleting it. Once this value is set, +The first delete request on an object with finalizers sets a value for the +`metadata.deletionTimestamp` field but does not delete it. Once this value is set, entries in the `finalizer` list can only be removed. -This triggers controllers watching the object to execute any finalizers they handle. -This will be represented via polling update requests for that -object, until all finalizers have been removed and the resource is deleted. +When the `metadata.deletionTimestamp` field is set, controllers watching the object +execute any finalizers they handle, by polling update requests for that +object. When all finalizers have been executed, the resource is deleted. -The time period of polling update can be controlled by `metadata.deletionGracePeriodSeconds`. +The value of `metadata.deletionGracePeriodSeconds` controls the interval between +polling updates. It is the responsibility of each controller to removes its finalizer from the list. -Kubernetes will only finally delete the object if the list of finalizers is empty, -meaning all finalizers are done. +Kubernetes only finally deletes the object if the list of finalizers is empty, +meaning all finalizers have been executed. ### Validation +{{< feature-state state="beta" for_kubernetes_version="1.9" >}} + Validation of custom objects is possible via [OpenAPI v3 schema](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject). Additionally, the following restrictions are applied to the schema: @@ -234,11 +237,10 @@ Additionally, the following restrictions are applied to the schema: - The field `uniqueItems` cannot be set to true. - The field `additionalProperties` cannot be set to false. -This feature is __beta__ in v1.9. You can disable this feature using the `CustomResourceValidation` feature gate on the [kube-apiserver](/docs/admin/kube-apiserver): -``` +``` --feature-gates=CustomResourceValidation=false ``` @@ -346,6 +348,103 @@ kubectl create -f my-crontab.yaml crontab "my-new-cron-object" created ``` +### Additional printer columns + +Starting with Kubernetes 1.11, kubectl uses server-side printing. The server decides which +columns are shown by the `kubectl get` command. You can customize these columns using a +CustomResourceDefinition. The following example adds the `Spec`, `Replicas`, and `Age` +columns. + +1. Save the CustomResourceDefinition to `resourcedefinition.yaml`. + ```yaml + apiVersion: apiextensions.k8s.io/v1beta1 + kind: CustomResourceDefinition + metadata: + name: crontabs.stable.example.com + spec: + group: stable.example.com + version: v1 + scope: Namespaced + names: + plural: crontabs + singular: crontab + kind: CronTab + shortNames: + - ct + additionalPrinterColumns: + - name: Spec + type: string + description: The cron spec defining the interval a CronJob is run + JSONPath: .spec.cronSpec + - name: Replicas + type: integer + description: The number of jobs launched by the CronJob + JSONPath: .spec.replicas + - name: Age + type: date + JSONPath: .metadata.creationTimestamp + ``` + +2. Create the CustomResourceDefinition: + + ```shell + kubectl create -f resourcedefinition.yaml + ``` + +3. Create an instance using the `my-crontab.yaml` from the previous section. + +4. Invoke the server-side printing: + + ```shell + kubectl get crontab my-new-cron-object + ``` + + Notice the `NAME`, `SPEC`, `REPLICAS`, and `AGE` columns in the output: + + ``` + NAME SPEC REPLICAS AGE + my-new-cron-object * * * * * 1 7s + ``` + +The `NAME` column is implicit and does not need to be defined in the CustomResourceDefinition. + +#### Priority + +Each column includes a `priority` field for each column. Currently, the priority +differentiates between columns shown in standard view or wide view (using the `-o wide` flag). + +- Columns with priority `0` are shown in standard view. +- Columns with priority greater than `0` are shown only in wide view. + +#### Type + +A column's `type` field can be any of the following (compare [OpenAPI v3 data types](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#dataTypes)): + +- `integer` – non-floating-point numbers +- `number` – floating point numbers +- `string` – strings +- `boolean` – true or false +- `date` – rendered differentially as time since this timestamp. + +If the value inside a CustomResource does not match the type specified for the column, +the value is omitted. Use CustomResource validation to ensure that the value +types are correct. + +#### Format + +A column's `format` field can be any of the following: + +- `int32` +- `int64` +- `float` +- `double` +- `byte` +- `date` +- `date-time` +- `password` + +The column's `format` controls the style used when `kubectl` prints the value. + ### Subresources Custom resources support `/status` and `/scale` subresources. @@ -569,5 +668,3 @@ crontabs/my-new-cron-object 3s * Serve [multiple versions](/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning/) of a CustomResourceDefinition {{% /capture %}} - -