Use TYPE instead of RESOURCE in help string #10742

hurf · 2015-07-06T11:39:21Z

Fixes: #10630
For get and describe command in kubectl, use KIND in help string.

k8s-bot · 2015-07-06T11:41:05Z

Can one of the admins verify that this patch is reasonable to test? (reply "ok to test", or if you trust the user, reply "add to whitelist")

If this message is too spammy, please complain to ixdy.

erictune · 2015-07-09T18:15:41Z

LGTM

erictune · 2015-07-09T18:15:47Z

ok to test

k8s-bot · 2015-07-09T18:35:03Z

GCE e2e build/test passed for commit eb31fb891362215432d1eb31eae3213c9e291d3d.

derekwaynecarr · 2015-07-10T01:11:22Z

I don't get this change.

You call "kubectl get pods foo"

The RESOURCE is "pods". The returned KIND is "Pod". When you create a
pod, you get back "RESOURCE/NAME" in CLI response. For example,
"pods/foo". When we register a storage object with the rest server, we map
a RESOURCE string not a KIND to a URL endpoint. In the future, we could
have multiple RESOURCE endpoints return the same KIND of object so it will
be even more confusing if we make this change.

@deads2k @smarterclayton let me know if i am missing something here,
wouldn't be the first time, but this seems incorrect.

On Thursday, July 9, 2015, Kubernetes Bot notifications@github.com wrote:

GCE e2e build/test passed for commit eb31fb8
eb31fb8
.

Build Log
https://storage.cloud.google.com/kubernetes-jenkins/pr-logs/eb31fb891362215432d1eb31eae3213c9e291d3d/kubernetes-pull-build-test-e2e-gce/2132/build-log.txt

Test Artifacts
https://console.developers.google.com/storage/browser/kubernetes-jenkins/pr-logs/eb31fb891362215432d1eb31eae3213c9e291d3d/kubernetes-pull-build-test-e2e-gce/2132/_artifacts/

Internal Jenkins Results
http://goto.google.com/prkubekins/job/kubernetes-pull-build-test-e2e-gce//2132

—
Reply to this email directly or view it on GitHub
#10742 (comment)
.

hurf · 2015-07-10T01:30:04Z

Something like 'kubectl get pods/foo' looks stranges, use plural to request and get one member, it's not natural. I think the reason ctl accept plurals is for user's ease, not to restrict them. Accept that we have obvious distinction between resources and kind internally. But for MM interface, would a way following natural language be better?

derekwaynecarr · 2015-07-10T01:55:03Z

If your change did what you suggested I would be less inclined to argue, but it just changes help text by making the help text incorrect with the current structure of kubectl which is a relatively thin wrapper over the Rest API at this time. We could argue that it should take KIND but the fact remains that it actually aligns with RESOURCE for v1.

erictune · 2015-07-10T02:41:47Z

@derekwaynecarr
Okay, I understand why you don't want to call this KIND. And I don't mind if we drop this change. But, I don't think "pods" in this context is a resource either. Here are two definitions:

docs/api-conventions.md defines resource as "a representation of a system entity, sent or retrieved as JSON via HTTP to the server."
rfc 3986 says a resource is "anything that might be identified by a URI".
pods as a word by itself does not meet either definition.

smarterclayton · 2015-07-10T03:07:35Z

To be even more precise, we're talking about the resource collection name
(pods). We definitely have a 1-1 mapping between kinds and resource
collection names (for all primary resource types), and a 1-1 primary
mapping for most resource collection names to kinds. But there can and
will be resource collection names that don't correspond to Kinds and vice
versa.

You can feed a kind to the generic commands, but you can also give it a
resource collection name which does not match the kind it returns (which is
a perfectly reasonable restful thing to do).

One benefit of KIND is that it's much shorter... There may be an argument
on that alone for being a little imprecise.

On Jul 9, 2015, at 10:42 PM, Eric Tune notifications@github.com wrote:

@derekwaynecarr https://github.com/derekwaynecarr

Okay, I understand why you don't want to call this KIND. And I don't mind
if we drop this change. But, I don't think "pods" in this context is a
resource either. Here are two definitions:

docs/api-conventions.md defines resource as "a representation of a
system entity, sent or retrieved as JSON via HTTP to the server."
- rfc 3986 https://tools.ietf.org/html/rfc3986 says a resource is
  "anything that might be identified by a URI". pods as a word by itself
  does not meet either definition.

—
Reply to this email directly or view it on GitHub
#10742 (comment)
.

deads2k · 2015-07-10T11:51:35Z

Something like 'kubectl get pods/foo' looks stranges, use plural to request and get one member

Singular values are accepted (kubectl get service/foo) and #10652 is adding a utility method to convert to singular resource names, so output can be cleaned up as well.

k8s-bot · 2015-07-17T22:45:10Z

Can one of the admins verify that this patch is reasonable to test? (reply "ok to test", or if you trust the user, reply "add to whitelist")

If this message is too spammy, please complain to ixdy.

k8s-bot · 2015-07-17T23:51:10Z

Can one of the admins verify that this patch is reasonable to test? (reply "ok to test", or if you trust the user, reply "add to whitelist")

If this message is too spammy, please complain to ixdy.

erictune · 2015-07-24T22:06:42Z

please rebase

bgrant0607 · 2015-07-27T05:51:06Z

Do we have a consensus that this a good or at least reasonable change to make?

If so, please rebase and look carefully for all occurrences:

$ grep -r RESOURCE pkg/kubectl
pkg/kubectl/cmd/scale.go:               Use: "scale [--resource-version=version] [--current-replicas=count] --replicas=COUNT RESOURCE NAME",
pkg/kubectl/cmd/scale.go:               return cmdutil.UsageError(cmd, "--replicas=COUNT RESOURCE NAME")
pkg/kubectl/cmd/expose.go:              Use:     "expose RESOURCE NAME --port=port [--protocol=TCP|UDP] [--target-port=number-or-name] [--name=name] [--public-ip=ip] [--type=type]",
pkg/kubectl/cmd/label.go:               Use:     "label [--overwrite] RESOURCE NAME KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]",
pkg/kubectl/cmd/describe.go:$ kubectl describe RESOURCE NAME_PREFIX
pkg/kubectl/cmd/describe.go:will first check for an exact match on RESOURCE and NAME_PREFIX. If no such resource
pkg/kubectl/cmd/describe.go:            Use:     "describe (RESOURCE NAME_PREFIX | RESOURCE/NAME)",
pkg/kubectl/cmd/stop.go:                Use:     "stop (-f FILENAME | RESOURCE (NAME | -l label | --all))",
pkg/kubectl/cmd/patch.go:               Use:     "patch RESOURCE NAME -p PATCH",
pkg/kubectl/cmd/delete.go:              Use:     "delete ([-f FILENAME] | (RESOURCE [(NAME | -l label | --all)]",
pkg/kubectl/cmd/get.go:         Use:     "get [(-o|--output=)json|yaml|template|wide|...] (RESOURCE [NAME] | RESOURCE/NAME ...)",

We should also document the resource/name syntax more consistently.

smarterclayton · 2015-07-28T18:51:02Z

I'm ok with KIND (I reserve the right to regret my decision later)

On Mon, Jul 27, 2015 at 1:51 AM, Brian Grant notifications@github.com
wrote:

Do we have a consensus that this a good or at least reasonable change to
make?

If so, please rebase and look carefully for all occurrences:

$ grep -r RESOURCE pkg/kubectl
pkg/kubectl/cmd/scale.go: Use: "scale [--resource-version=version] [--current-replicas=count] --replicas=COUNT RESOURCE NAME",
pkg/kubectl/cmd/scale.go: return cmdutil.UsageError(cmd, "--replicas=COUNT RESOURCE NAME")
pkg/kubectl/cmd/expose.go: Use: "expose RESOURCE NAME --port=port [--protocol=TCP|UDP] [--target-port=number-or-name] [--name=name] [--public-ip=ip] [--type=type]",
pkg/kubectl/cmd/label.go: Use: "label [--overwrite] RESOURCE NAME KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]",
pkg/kubectl/cmd/describe.go:$ kubectl describe RESOURCE NAME_PREFIX
pkg/kubectl/cmd/describe.go:will first check for an exact match on RESOURCE and NAME_PREFIX. If no such resource
pkg/kubectl/cmd/describe.go: Use: "describe (RESOURCE NAME_PREFIX | RESOURCE/NAME)",
pkg/kubectl/cmd/stop.go: Use: "stop (-f FILENAME | RESOURCE (NAME | -l label | --all))",
pkg/kubectl/cmd/patch.go: Use: "patch RESOURCE NAME -p PATCH",
pkg/kubectl/cmd/delete.go: Use: "delete ([-f FILENAME] | (RESOURCE [(NAME | -l label | --all)]",
pkg/kubectl/cmd/get.go: Use: "get [(-o|--output=)json|yaml|template|wide|...](RESOURCE [NAME] | RESOURCE/NAME ...)",

We should also document the resource/name syntax more consistently.

—
Reply to this email directly or view it on GitHub
#10742 (comment)
.

Clayton Coleman | Lead Engineer, OpenShift

derekwaynecarr · 2015-07-28T20:52:30Z

Can it be called something other than KIND or RESOURCE? It seems clear to me that it is neither.

bgrant0607 · 2015-07-28T21:33:06Z

Type or object: https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/devel/api-conventions.md#types-kinds

Or we could introduce "collection".

But I honestly wouldn't be too pedantic for a CLI where most users won't read and internalize the API specification.

erictune · 2015-07-29T03:59:15Z

Any objections to TYPE?

hurf · 2015-07-29T09:07:31Z

I rebased the change with KIND. If there're other ideas, I'm happy to modify it again.
Personally instead of KIND or TYPE I prefer RESOURCE_TYPE, from a user's perspective I feel it's more clear.

derekwaynecarr · 2015-07-29T18:49:05Z

+1 TYPE

erictune · 2015-07-29T19:59:21Z

Fine with RESOURCE_TYPE too.

bgrant0607 · 2015-07-29T20:01:30Z

RESOURCE_TYPE is clear, but kind of wide.

smarterclayton · 2015-07-29T20:34:22Z

In the CLI context TYPE or KIND seem ok - RESOURCE_TYPE is too long and
also still vague (what's a resource). TYPE is more generic than KIND, and
would be more familiar to most users.

On Wed, Jul 29, 2015 at 4:01 PM, Brian Grant notifications@github.com
wrote:

RESOURCE_TYPE is clear, but kind of wide.

—
Reply to this email directly or view it on GitHub
#10742 (comment)
.

Clayton Coleman | Lead Engineer, OpenShift

hurf · 2015-07-30T07:54:19Z

Since most people are positive with TYPE, changed with TYPE.

erictune · 2015-08-04T23:53:51Z

pkg/kubectl/cmd/get.go

@@ -32,7 +32,7 @@ import (
 const (
 	get_long = `Display one or many resources.

-Possible resources include (case insensitive): pods (po), services (svc),
+Possible resource kinds include (case insensitive): pods (po), services (svc),


s/resource kinds/types/

erictune · 2015-08-04T23:54:16Z

One change and then regen docs and then it will look good to me.

For commands in kubectl, use TYPE in help string.

erictune · 2015-08-05T21:55:54Z

lgtm, thanks for the fix.

Use TYPE instead of RESOURCE in help string

googlebot added the cla: yes label Jul 6, 2015

hurf mentioned this pull request Jul 6, 2015

Fix hits in help strings of kubectl get command #10743

Merged

yujuhong assigned erictune Jul 6, 2015

bgrant0607 added the kind/documentation Categorizes issue or PR as related to documentation. label Jul 13, 2015

erictune modified the milestones: v1.0, v1.0-post Jul 14, 2015

bgrant0607 removed this from the v1.0-post milestone Jul 24, 2015

bgrant0607 added the area/kubectl label Jul 27, 2015

hurf force-pushed the help_kind branch from eb31fb8 to b81076e Compare July 29, 2015 09:01

hurf force-pushed the help_kind branch from b81076e to 52937b1 Compare July 30, 2015 07:53

erictune reviewed Aug 4, 2015
View reviewed changes

hurf force-pushed the help_kind branch 2 times, most recently from 213af55 to 33fb617 Compare August 5, 2015 08:33

Use TYPE instead of RESOURCE in help string

33fb617

For commands in kubectl, use TYPE in help string.

erictune added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 5, 2015

dchen1107 changed the title ~~Use KIND instead of RESOURCE in help string~~ Use TYPE instead of RESOURCE in help string Aug 5, 2015

dchen1107 added a commit that referenced this pull request Aug 5, 2015

Merge pull request #10742 from hurf/help_kind

ec7d0a9

Use TYPE instead of RESOURCE in help string

dchen1107 merged commit ec7d0a9 into kubernetes:master Aug 5, 2015

hurf mentioned this pull request Aug 6, 2015

Synchronize help message between describe and get #12332

Merged

hurf deleted the help_kind branch August 24, 2015 13:51

erictune added the release-note Denotes a PR that will be considered when it comes time to generate release notes. label Sep 11, 2015

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use TYPE instead of RESOURCE in help string #10742

Use TYPE instead of RESOURCE in help string #10742

hurf commented Jul 6, 2015

k8s-bot commented Jul 6, 2015

erictune commented Jul 9, 2015

erictune commented Jul 9, 2015

k8s-bot commented Jul 9, 2015

derekwaynecarr commented Jul 10, 2015

hurf commented Jul 10, 2015

derekwaynecarr commented Jul 10, 2015

erictune commented Jul 10, 2015

smarterclayton commented Jul 10, 2015

deads2k commented Jul 10, 2015

k8s-bot commented Jul 17, 2015

k8s-bot commented Jul 17, 2015

erictune commented Jul 24, 2015

bgrant0607 commented Jul 27, 2015

smarterclayton commented Jul 28, 2015

derekwaynecarr commented Jul 28, 2015

bgrant0607 commented Jul 28, 2015

erictune commented Jul 29, 2015

hurf commented Jul 29, 2015

derekwaynecarr commented Jul 29, 2015

erictune commented Jul 29, 2015

bgrant0607 commented Jul 29, 2015

smarterclayton commented Jul 29, 2015

hurf commented Jul 30, 2015

erictune Aug 4, 2015

erictune commented Aug 4, 2015

erictune commented Aug 5, 2015

Use TYPE instead of RESOURCE in help string #10742

Use TYPE instead of RESOURCE in help string #10742

Conversation

hurf commented Jul 6, 2015

k8s-bot commented Jul 6, 2015

erictune commented Jul 9, 2015

erictune commented Jul 9, 2015

k8s-bot commented Jul 9, 2015

derekwaynecarr commented Jul 10, 2015

hurf commented Jul 10, 2015

derekwaynecarr commented Jul 10, 2015

erictune commented Jul 10, 2015

smarterclayton commented Jul 10, 2015

deads2k commented Jul 10, 2015

k8s-bot commented Jul 17, 2015

k8s-bot commented Jul 17, 2015

erictune commented Jul 24, 2015

bgrant0607 commented Jul 27, 2015

smarterclayton commented Jul 28, 2015

derekwaynecarr commented Jul 28, 2015

bgrant0607 commented Jul 28, 2015

erictune commented Jul 29, 2015

hurf commented Jul 29, 2015

derekwaynecarr commented Jul 29, 2015

erictune commented Jul 29, 2015

bgrant0607 commented Jul 29, 2015

smarterclayton commented Jul 29, 2015

hurf commented Jul 30, 2015

erictune Aug 4, 2015

Choose a reason for hiding this comment

erictune commented Aug 4, 2015

erictune commented Aug 5, 2015