Document CustomResourceDefinition additionalPrinterColumns

sttts · Misty Linville · commit b6fcf2913fae · 2018-07-16T09:37:51.000-07:00
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
@@ -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 %}}
-
-
