From 3c6d14dd7ad33f9ab0649056b328b2aff5e07a30 Mon Sep 17 00:00:00 2001
From: "Dr. Stefan Schimanski" <stefan.schimanski@gmail.com>
Date: Tue, 19 Jun 2018 10:39:14 +0200
Subject: [PATCH] Document CustomResourceDefinition additionalPrinterColumns

---
 .../extend-api-custom-resource-definitions.md | 94 ++++++++++++++++++-
 1 file changed, 90 insertions(+), 4 deletions(-)

diff --git a/content/en/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md b/content/en/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md
index 24f10bd2c5c6f..28e2a6b76cfb1 100644
--- a/content/en/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md
+++ b/content/en/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md
@@ -201,7 +201,7 @@ The first delete request on an object with finalizers merely sets a value for th
 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 
+This will be represented via polling update requests for that
 object, until all finalizers have been removed and the resource is deleted.
 
 The time period of polling update can be controlled by `metadata.deletionGracePeriodSeconds`.
@@ -226,7 +226,7 @@ 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
 ```
 
@@ -330,6 +330,94 @@ 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. This means that the server decides which
+columns are to be printed by `kubectl get`. These columns can be customized in a CustomResourceDefinition:
+
+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
+```
+
+and create it:
+
+```shell
+kubectl create -f resourcedefinition.yaml
+```
+
+Finally, create an instance using the `my-crontab.yaml` from the previous section.
+
+Now invoke the server-side printing via:
+
+```shell
+kubectl get crontab my-new-cron-object
+```
+
+and see the output of the custom columns:
+
+```
+NAME                 SPEC        REPLICAS   AGE
+my-new-cron-object   * * * * *   1          7s
+```
+
+Note, that the name column is implicit and does not have to be defined in the CRD.
+
+Also note, that there is a `priority` field for each column. In Kubernetes 1.11 this
+only differentiates between those columns shown in standard view (all those with priority `0`)
+and those which are shown in addition in `-o wide` view (all those with priority `> 0`).
+
+The following types are available to be used in the `type` field of columns (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` – renderend differentially as a the time since this timestamp.
+
+If the value inside a CustomResource does not match the type specified for the column,
+the value is omitted. Hence, it is highly suggested to use CRD validation to ensure
+that the value types are correct.
+
+The following formats are available to be used in the `format` field of columns:
+
+- `int32`
+- `int64`
+- `float`
+- `double`
+- `byte`
+- `date`
+- `date-time`
+- `password`.
+
+These influence the printing style in kubectl.
+
 ### Subresources
 
 Custom resources support `/status` and `/scale` subresources.
@@ -547,5 +635,3 @@ crontabs/my-new-cron-object   3s
 * Learn how to [Migrate a ThirdPartyResource to CustomResourceDefinition](/docs/tasks/access-kubernetes-api/migrate-third-party-resource/).
 * See [CustomResourceDefinition](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#customresourcedefinition-v1beta1-apiextensions-k8s-io).
 {{% /capture %}}
-
-