Proposal: Server-side `kubectl get` #363

smarterclayton · 2017-02-13T03:31:33Z

This proposal discusses how the kubectl get operation can be moved to the server to allow multiple clients to more easily show simple lists of objects.

Part of kubernetes/kubernetes#12143 and general work under api-machinery.

Depends on:

Proposal: Alternate API representations for resources #123

Related to:

Implement export functionality server-side for all resources kubernetes#24855

Prototype:

Add a server side Get operation kubernetes#40848

Some WIP items left, including a sketch of describe to contrast the two approaches.

smarterclayton · 2017-02-13T03:41:20Z

@kubernetes/sig-api-machinery-proposals

smarterclayton · 2017-02-13T03:41:58Z

@kubernetes/sig-cli-proposals @jwforres

soltysh · 2017-02-22T13:50:06Z

contributors/design-proposals/server-get.md

+
+Clients that wish to print in an advanced manner may continue to fetch the normal resources.
+
+Third-party resources can more easily implement `get` in this fashion - instead of web dashboards and


I'd like to see a more in-depth description how this will work for TPR or all objects, in general. The proposal is very good, but what worries me is the same concern I raised in the Alternate API representations PR, how the server will know what to return for the user. Obviously for k8s objects, we can hardcode it, but I'm hoping that's not the direction here? I'd prefer seeing some sort of openapi extensions allowing us to express these printing options in the schema. I hope that makes sense.

@pwittrock has a proposal about extending get and describe for TPR in #308, there seems to be some overlap between these.

yes, and I think what @pwittrock suggested is for this case.

Expectation would be:

On the server side, we would implement TPR printing by looking at the swagger spec or the TPR definition. The client wouldn't have to have a JSONPath library, they'd just get fields. If we wanted to implement a webhook for that, we could, and it would be transparent to clients (shameless plug to distract brendan)

This seems like a problem that can be fixed with localized improvements to TPR so I'm not too worried about it.

fabianofranz · 2017-02-22T17:13:39Z

@kubernetes/sig-cli-proposals

fabianofranz · 2017-03-07T15:14:44Z

contributors/design-proposals/server-get.md

+## Goals
+
+* Make it easy for a simple client to get a list of resources for a web UI or CLI output
+* Support all existing options, leave open the door for future extension and experimentation


Support all existing options

Things not mentioned: sorting, display kind along with the name (this could be client-side).

Sorting can be done client based on the type (numeric). I'm not sure what to do about Kind - a client can figure that out pretty well, and how clients specify kind is special (jessica isn't going to use pods/foo, she's going to do a link to the pods web page).

I have a bunch of other client side things to list here, will do that shortly.

Cool, no issues with Kind being done on the client.

About sorting, doing on the client works for now, but we need to have sorting in mind when (if ever) server-side paging gets implemented.

I don't think we're ever going to implement sort with server-side paging. Etcd doesn't support it natively without us dramatically increasing complexity, so it's not going to happen ;)

In general, I'd like generic (resource-independent) rendering to be done in the client. Resource-specific computation and filtering of data to present should be on the server. For both get and describe.

Where we have complex computations in kubectl today (e.g., printPodBase), we need to add API fields. This new mechanism should just be returning existing data in a different format.

Resource independent rendering is fairly difficult to do across the three major clients (IDE, CLI, and web UI) correctly for things like custom columns. But I agree it is simpler to let that be a per client decision. The tradeoff was allowing the object transformation to return the object itself (wrapped), since we don't want clients to have to do two LISTs and then merge them.

fabianofranz · 2017-03-07T15:29:24Z

contributors/design-proposals/server-get.md

+        ...
+    ],
+    "items": [
+        {"cells": ["pod1", "Failed - unable to start", ...]},


Alternatively make it a hash and key it with the value of "name" in the header, otherwise you have to rely on the ordering. Not a big issue since it's arrays though.

{"cells": {"Name": "pod1", "Status": "Failed - unable to start", ...}},

I want to explicitly force clients to follow the rules. Mapping by name encourages people to get clever.

I agree w/ the proposal as written. Tables should be indexed by row/column index not by row/name IMO. Also it's more bandwidth efficient this way.

bgrant0607 · 2017-03-09T22:05:15Z

There is no @kubernetes/sig-api-machinery-proposals team. :-(

adohe-zz · 2017-03-15T12:15:37Z

contributors/design-proposals/server-get.md

+}
+```
+
+To allow label columns, and to enable integrators to build effective UIs, each row may contain object metadata:


how to define metadata for each type? what metadata we should return for TPR resources?

This would be standard object metadata, OR it could be a runtime.Object and you have to ask for the object metadata. Note that this object is in metav1 / metaalphav1, which is an API that evolves. So until we break object meta, you can use this, and then in the future you can just ask for metav2.

I think the server should produce a standardized metadata--clients shouldn't have to do something special if the resource is a TPR/AA.

smarterclayton · 2017-03-16T22:18:28Z

Current unsolved problem - custom columns. If we let people send us arbitrary JSONPath templates, that could be a DoS attack area or resource amplification. Since the custom column has to be per object, it's really not that much more expensive than other expensive operations (creating a pod causes way more network traffic and general cluster load). We could potentially rate limit custom column requests if we had to.

bgrant0607 · 2017-04-14T17:26:47Z

@smarterclayton @fabianofranz Do we have anyone lined up to implement this in 1.7?

bgrant0607 · 2017-04-14T17:33:28Z

cc @bryk, since I imagine similar issues for the UI

bgrant0607 · 2017-04-14T17:41:32Z

contributors/design-proposals/server-get.md

+    "apiVersion": "meta.k8s.io/v1alpha1",
+    "headers": [
+        ...
+        {"name": "Node Name", "type": "string", "description": "The node the pod is scheduled on, empty if the pod is not yet scheduled", "priority": 1},


Get headers and column values shouldn't contain spaces:

https://github.com/kubernetes/community/blob/master/contributors/devel/kubectl-conventions.md#output-conventions

We use dashes instead of spaces in headers.

We also capitalize headers, but could do that generically in the client.

We can normalize that in the client. I'm thinking of web uis, which have other affordances for communicating the difference between header and content. That's an important part of this proposal, not over normalizing for a cli

Unless people will be copy-pasting headers in ways I don't expect I agree w/ Clayton.

bgrant0607 · 2017-04-14T17:44:05Z

contributors/design-proposals/server-get.md

+```
+$ curl https://localhost:8443/api/v1/pods -H "Accept: application/json+vnd.kubernetes.as+meta.k8s.io+v1alpha1+TableList"
+{
+    "kind": "TableList",


We have this problem with Lists also, but we're going to need to be able to paginate these. #2349

I think the only difference here is that subsequent pages could omit the headers.

bgrant0607 · 2017-04-14T17:46:01Z

contributors/design-proposals/server-get.md

+
+## Future considerations
+
+* When we introduce server side paging, TableList would be paged similar to how PodList or other types are paged.


Right. Please cite issues.k8s.io/2349

smarterclayton · 2017-04-15T06:32:48Z

Re: custom columns.

I think the way to solve this is adding a new field object to each row / item. By default, the value of that field is PartialObjectMetadata (discussed in Alternate API representations) - basically a generic representation of any object with ObjectMeta for a generic client to deal with. That allows ResourceVersion, UID, labels, selfLink, and other special behaviors to be handled generically by most clients. If a client needs to perform generic transformations on the object (JSONPath columns), it sets includeObjects=true which is a parameter specific to the table transformation. Instead of returning the typed PartialObjectMetadata, the server returns the serialized object.

So there is a simple path from:

build naive generic client that displays tabular values
use additional standard ObjectMeta for each item ("metadata") to integrate with other operations
pull down object as well for additional processing in complex client

lavalamp

/lgtm, most comments are minor

lavalamp · 2017-05-10T05:46:48Z

contributors/design-proposals/server-get.md

+
+## Specification of server-side `get`
+
+The server would return a `TableList` object (working-name) that contains metadata for columns and one or more


A TableList would be a list of tables. This is just a single table (right?). Perhaps Table or TabularList?

I wanted it to have List so it obeys our "list like behavior". Tabular sounds like Tubular, but maybe this could just be Table (and you always get a Table back). Will try with Table.

lavalamp · 2017-05-10T05:51:38Z

contributors/design-proposals/server-get.md

+        ...
+    ],
+    "items": [
+        {"cells": ["pod1", "Failed - unable to start", ...]},


I agree w/ the proposal as written. Tables should be indexed by row/column index not by row/name IMO. Also it's more bandwidth efficient this way.

lavalamp · 2017-05-10T05:56:17Z

contributors/design-proposals/server-get.md

+{
+    "kind": "TableList",
+    "apiVersion": "meta.k8s.io/v1alpha1",
+    // headers are not returned here


Have you considered making this a separate kind?

Also, if someone uses this format and wojtekt's bulk watch, it's going to be impossible for clients to figure out what headers an object should have. I'm a little worried about not leaving a breadcrumb here to help them.

Fair. Although in bulk watch you'll have the index on the wrapping event, so it's

Event index: 0 Object: Table ...

lavalamp · 2017-05-10T05:58:09Z

contributors/design-proposals/server-get.md

+    "apiVersion": "meta.k8s.io/v1alpha1",
+    "headers": [
+        ...
+        {"name": "Node Name", "type": "string", "description": "The node the pod is scheduled on, empty if the pod is not yet scheduled", "priority": 1},


Unless people will be copy-pasting headers in ways I don't expect I agree w/ Clayton.

lavalamp · 2017-05-10T05:59:48Z

contributors/design-proposals/server-get.md

+}
+```
+
+To allow label columns, and to enable integrators to build effective UIs, each row may contain object metadata:


I think the server should produce a standardized metadata--clients shouldn't have to do something special if the resource is a TPR/AA.

lavalamp · 2017-05-10T06:03:31Z

contributors/design-proposals/server-get.md

+
+## Specification of server-side `describe`
+
+TBD


I would like to see here a statement that the server will be sending links to the client rather than performing the fan out itself, so we know the general shape of this.

lavalamp · 2017-05-10T06:05:10Z

contributors/design-proposals/server-get.md

+```
+$ curl https://localhost:8443/api/v1/pods -H "Accept: application/json+vnd.kubernetes.as+meta.k8s.io+v1alpha1+TableList"
+{
+    "kind": "TableList",


I think the only difference here is that subsequent pages could omit the headers.

lavalamp · 2017-05-10T06:05:39Z

contributors/design-proposals/server-get.md

+## Future considerations
+
+* When we introduce server side paging, TableList would be paged similar to how PodList or other types are paged.
+* More advanced output could in the future be provided by an external call-out or an aggregation API (which simply)


(cliffhanger)

lavalamp · 2017-05-10T06:09:03Z

contributors/design-proposals/server-get.md

+header to indicate they want the simpler version, and if they receive a TableList perform the new path, otherwise
+fall back to client side functions.
+
+Server side code would reuse the existing display functions but replace TabWriter with either a structured writer


this is a little light on detail but that can wait for the PR ;)

PR is already up!

lavalamp · 2017-05-10T06:09:45Z

contributors/design-proposals/server-get.md

@@ -0,0 +1,170 @@
+# Expose `get` and `describe` output from the server


This title is a little ambitious given that this doesn't really cover describe :)

I know. I'll refine.

Moved to a future consideration and descoped the design.

Discuss how to move `kubectl get` to the server.

smarterclayton · 2017-05-11T16:58:57Z

Proposal has been updated with all extant feedback and clarified the specific features of kubectl get and how they can / should be implemented

This patch adds support for the "server-side GET operation" introduced by pull/40848 and proposed by kubernetes/community#363.

Proposal: Server-side `kubectl get`

Automatic merge from submit-queue Proposal for adding PVC info to VolumeStats Flushes out details for part 1 of the changes described in [kubernetes#855](kubernetes#855) Feature: [kubernetes#363](kubernetes/enhancements#363)

Automatic merge from submit-queue (batch tested with PRs 44520, 45253, 45838, 44685, 45901) API for server side tabular output These are the APIs necessary to implement propsoal kubernetes/community#363 They consist of a new meta group (v1alpha1) that indicates these are alpha apis for the server as a whole, a new kind `TableList` which is a simple row + header arranged table capable of returning both object and columnar data, a `TableListOptions` for altering the behavior of the return, and `PartialObjectMetadata` which is an "interface" style API object which allows a client to ask any object for their metadata (without having to know how to parse the object or perform gymnastics). Extracted from #40848 A few minor tweaks still required. Kubernetes-commit: 6f4e0b66a7bfe1f0982722bced4f4b02807ac773

Automatic merge from submit-queue (batch tested with PRs 46432, 46701, 46326, 40848, 46396) Add a server side Get operation Implement proposal kubernetes/community#363 ```release-note The Kubernetes API supports retrieving tabular output for API resources via a new mime-type `application/json;as=Table;v=v1alpha1;g=meta.k8s.io`. The returned object (if the server supports it) will be of type `meta.k8s.io/v1alpha1` with `Table`, and contain column and row information related to the resource. Each row will contain information about the resource - by default it will be the object metadata, but callers can add the `?includeObject=Object` query parameter and receive the full object. In the future kubectl will use this to retrieve the results of `kubectl get`. ``` Kubernetes-commit: 97a5d378410f62437ea03c3db980a9a0af8a65ca

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Feb 13, 2017

smarterclayton force-pushed the serverside_get branch from 6b6346e to 694d671 Compare February 13, 2017 03:36

smarterclayton changed the title ~~WIP - Server-side get proposal~~ Proposal: Server-side kubectl get Feb 13, 2017

smarterclayton mentioned this pull request Feb 13, 2017

Support list/get/watch ObjectMeta in api server kubernetes/kubernetes#30180

Closed

smarterclayton force-pushed the serverside_get branch from 694d671 to 31ecb4e Compare February 13, 2017 03:44

soltysh reviewed Feb 22, 2017

View reviewed changes

fabianofranz reviewed Mar 7, 2017

View reviewed changes

fabianofranz mentioned this pull request Mar 8, 2017

kubectl get and kubectl describe extensions #308

Merged

deads2k mentioned this pull request Mar 9, 2017

Proposal: better output when getting 3prs kubernetes/kubernetes#31343

Closed

adohe-zz reviewed Mar 15, 2017

View reviewed changes

soltysh mentioned this pull request Mar 15, 2017

Add optional colors for kubectl printing... kubernetes/kubernetes#40963

Closed

liggitt mentioned this pull request Apr 5, 2017

Proposal - kubectl commands for the Service Catalog #481

Closed

bgrant0607 reviewed Apr 14, 2017

View reviewed changes

smarterclayton mentioned this pull request Apr 19, 2017

API for server side tabular output kubernetes/kubernetes#44685

Merged

lavalamp self-assigned this May 10, 2017

lavalamp reviewed May 10, 2017

View reviewed changes

Server-side get proposal

550ae37

Discuss how to move `kubectl get` to the server.

smarterclayton force-pushed the serverside_get branch from 31ecb4e to 550ae37 Compare May 11, 2017 16:58

juanvallejo added a commit to juanvallejo/kubernetes that referenced this pull request Feb 23, 2018

handle Table response in client

9946374

This patch adds support for the "server-side GET operation" introduced by pull/40848 and proposed by kubernetes/community#363.

jingxu97 pushed a commit to jingxu97/kubernetes that referenced this pull request Mar 13, 2018

handle Table response in client

9021692

This patch adds support for the "server-side GET operation" introduced by pull/40848 and proposed by kubernetes/community#363.

MadhavJivrajani pushed a commit to MadhavJivrajani/community that referenced this pull request Nov 30, 2021

Merge pull request kubernetes#363 from smarterclayton/serverside_get

449db77

Proposal: Server-side `kubectl get`


		Clients that wish to print in an advanced manner may continue to fetch the normal resources.

		Third-party resources can more easily implement `get` in this fashion - instead of web dashboards and


		## Future considerations

		* When we introduce server side paging, TableList would be paged similar to how PodList or other types are paged.


		## Specification of server-side `get`

		The server would return a `TableList` object (working-name) that contains metadata for columns and one or more

		@@ -0,0 +1,170 @@
		# Expose `get` and `describe` output from the server

Proposal: Server-side kubectl get #363

Proposal: Server-side kubectl get #363

Conversation

smarterclayton commented Feb 13, 2017 • edited Loading

smarterclayton commented Feb 13, 2017 • edited by bgrant0607 Loading

smarterclayton commented Feb 13, 2017 • edited by bgrant0607 Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fabianofranz commented Feb 22, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bgrant0607 commented Mar 9, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smarterclayton commented Mar 16, 2017

bgrant0607 commented Apr 14, 2017

bgrant0607 commented Apr 14, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smarterclayton commented Apr 15, 2017

lavalamp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smarterclayton commented May 11, 2017

Proposal: Server-side `kubectl get` #363

Proposal: Server-side `kubectl get` #363

smarterclayton commented Feb 13, 2017 •

edited

Loading

smarterclayton commented Feb 13, 2017 •

edited by bgrant0607

Loading

smarterclayton commented Feb 13, 2017 •

edited by bgrant0607

Loading