Skip to content

Commit

Permalink
add server-side print docs
Browse files Browse the repository at this point in the history
  • Loading branch information
juanvallejo committed Mar 8, 2018
1 parent 7dd01bd commit 8596fc7
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 0 deletions.
57 changes: 57 additions & 0 deletions docs/reference/api-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,63 @@ For example, if there are 1,253 pods on the cluster and the client wants to rece
Note that the `resourceVersion` of the list remains constant across each request, indicating the server is showing us a consistent snapshot of the pods. Pods that are created, updated, or deleted after version `10245` would not be shown unless the user makes a list request without the `continue` token. This allows clients to break large requests into smaller chunks and then perform a watch operation on the full set without missing any updates.


## Receiving resources as Tables

`kubectl get` is a simple tabular representation of one or more instances of a particular resource type. In the past, clients were required to reproduce the tabular and describe output implemented in `kubectl` to perform simple lists of objects.
A few limitations of that approach include non-trivial logic when dealing with certain objects. Additionally, types provided by API aggregation or third party rersources are not known at compile time. This means that generic implementations had to be in place for types unrecognized by a client.

In order to avoid potential limitations as described above, clients may request the Table representation of objects, delegating specific details of printing to the server. The Kubernetes API implements standard HTTP content type negotiation: passing an `Accept` header containing a value of `application/json;as=Table;g=meta.k8s.io;v=v1beta1` with a `GET` call will request that the server return objects in the Table content type.

For example:

1. List all of the pods on a cluster in the Table format.

GET /api/v1/pods
Accept: application/json;as=Table;v=meta.k8s.io;g=v1beta1
---
200 OK
Content-Type: application/json
{
"kind": "Table",
"apiVersion": "meta.k8s.io/v1beta1",
...
"columnDefinitions": [
...
]
}

For API resource types that do not have a custom Table definition on the server, a default Table response is returned by the server, consisting of the resource's `name` and `creationTimestamp` fields.

GET /apis/crd.example.com/v1alpha1/namespaces/default/resources
---
200 OK
Content-Type: application/json
...
{
"kind": "Table",
"apiVersion": "meta.k8s.io/v1beta1",
...
"columnDefinitions": [
{
"name": "Name",
"type": "string",
...
},
{
"name": "Created At",
"type": "date",
...
}
]
}

Table responses are available beginning in version 1.10 of the kube-apiserver. As such, not all API resource types will support a Table response, specifically when using a client against older clusters. Clients that must work against all resource types, or can potentially deal with older clusters, should specify multiple content types in their `Accept` header to support fallback to non-Tabular JSON:

```
Accept: application/json;as=Table;v=meta.k8s.io;g=v1beta1, application/json
```


## Alternate representations of resources

By default Kubernetes returns objects serialized to JSON with content type `application/json`. This is the default serialization format for the API. However, clients may request the more efficient Protobuf representation of these objects for better performance at scale. The Kubernetes API implements standard HTTP content type negotiation: passing an `Accept` header with a `GET` call will request that the server return objects in the provided content type, while sending an object in Protobuf to the server for a `PUT` or `POST` call takes the `Content-Type` header. The server will return a `Content-Type` header if the requested format is supported, or the `406 Not acceptable` error if an invalid content type is provided.
Expand Down
23 changes: 23 additions & 0 deletions docs/reference/kubectl/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,6 +192,26 @@ NAME RSRC
submit-queue 610995
```

#### Server-side columns

`kubectl` supports receiving specific column information from the server about objects.
This means that for any given resource, the server will return columns and rows relevant to that resource, for the client to print.
This allows for consistent human-readable output across clients used against the same cluster, by having the server encapsulate the details of printing.

To output object information using this feature, you can add the `--experimental-server-print` flag to a supported `kubectl` command.

##### Examples

```shell
$ kubectl get pods <pod-name> --experimental-server-print
```

The result of running this command is:

```shell
NAME READY STATUS RESTARTS AGE
pod-name 1/1 Running 0 1m

### Sorting list objects

To output objects to a sorted list in your terminal window, you can add the `--sort-by` flag to a supported `kubectl` command. Sort your objects by specifying any numeric or string field with the `--sort-by` flag. To specify a field, use a [jsonpath](/docs/user-guide/jsonpath) expression.
Expand Down Expand Up @@ -245,6 +265,9 @@ $ kubectl get ds --include-uninitialized
// List all pods running on node server01
$ kubectl get pods --field-selector=spec.nodeName=server01
// List all pods in plain-text output format, delegating the details of printing to the server
$ kubectl get pods --experimental-server-print
```

`kubectl describe` - Display detailed state of one or more resources, including the uninitialized ones by default.
Expand Down

0 comments on commit 8596fc7

Please sign in to comment.