Still WIP

As mentioned in #12143 (and #11617) we want to move printers to the server so that all clients can benefit from them, the naive client implementation is simpler, and so we can avoid having to perform external -> internal conversions in the client.

Considerations

• A kubectl get is an alternative representation of the underlying API object or objects - in HTTP and REST this is most commonly treated as another representation of the same resource.
  • We need to support alternate representations of both the list (kubectl get pods) and the individual item (kubectl get pod).
• The representation returned must be structured (an API object) and we need to potentially handle the desire to change that API over time.
• We want to support both command line clients and web clients, and that requires an internal structure
  • command line clients may add additional value like wrapping within the terminal window boundaries, or showing and hiding headers
  • web clients will wish to transform the response in HTML and need a structured format
• We already enable clients dealing with JSON and YAML - a serialization in either of those formats would be easily consumed (with a preference for JSON)
• We will need to support additional parameters to these representations, parameters that only make sense when viewing this representation (for instance, wide vs narrow). Other parameters may be common (paging, sorting, filtering).
• There are two primary mechanisms for conveying "alternate return type of content" for RESTful objects.
  • One is a query parameter (?table=1) and one is the content type (Accept: application/json;tabular=1).
  • We have support for both mechanisms - the former is easier for naive clients, the latter is more "correct" in HTTP vocabulary.
  • We support Accept: application/json;pretty=1 and ?pretty=1 today, which are roughly equivalent.
• We already have export, which is implemented as a query parameter. Export always returns the same object schema as the normal GET request.
• We have watch, which is implemented as a query parameter, but which returns a different content-type and object schema as a normal GET request.
• We want the serialization choice to be obvious to a swagger API consumer (which means it can either be content type or query parameter, although query parameters have more doc).
• Since this is a variant of the object, I believe we should avoid a subresource (since we would have to create a subresource of a list, which would conflict with resource names).

Proposed:

Support both content type and query parameter for selecting an alternate representation of the object. Supporting content-type means we can in the future add new representations AND allow the user to request multiple serializations in order.

Example:

$ curl -H "Accept: application/json;table=wide" https://server/v1/namespaces/default/pods?table=wide
Content-Type: application/json;table=wide
{
  "kind": "Table",
  "apiVersion": "printers.k8s.io/v1",
  "metadata": {
    "resourceVersion": "395",
    "selfLink": "https://server/v1/namespaces/default/pods"
  },
  "columns": [
    {"name": "Name"},
    {"name": "Age"},
  ],
  "items": [
    {
      "values": ["hello", "3d"],
    }
  ]
}

ISSUE: Do we want to continue the inlining of schemas (return v1 for v1 resources), or explicitly return a different schema type? The latter is easier for generic clients. The former is easier for versioned clients.

It would be valid to specify ?watch=1 or ?export=1 with ?table= in the future. Tabular output is a transformation of the resulting object from a Get.

This is a reasonably simple table schema (it's possible to extend values in the future) but in the near term additional descriptive metadata could be hung off "columns". The use of the table parameter aligns with the requested schema. For instance, the "default filter" concept needs to be implemented server side, which means each row needs a descriptive field (filtered or not).

Implementation (more details needed)

• Server
  • Create a new API group printers.k8s.io with a v1 version that accepts this object.
  • Add a new method TransformTable(context api.Context, obj runtime.Object) (api.Table, error) to RESTStorage
  • Provide a default implementation of TransformTable on generic.Etcd that handles fields supported by ObjectMeta
• Client
  • Move kubectl.Printers into a package outside of pkg/kubectl where it can be reused by both
  • Add functionality to resource.Helper to request tabular output.
    • Invoke DecodeInto(..., &v1.Table{}) to decode the response (which should error if v1.Table is not recognized)
  • Alter kubectl get to invoke the generic helper.