cli: standardize kubernetes resource parsing

[siggy]

Background

We're working towards new Kubernetes-aware cli commands, specificallly to stat (#627) and tap (#778). We need common patterns to describe Kubernetes objects in cli flags.

Requirements

Both of these commands require input of the following information

• primary resource
  • namespace
  • type
  • name
• source / from / destination resource
  • namespace
  • type
  • name

Current state

The APIs currently consume this input via inconsistent flags. Some examples:

stat

# Get all deployments in the test namespace.
conduit stat deployments -n test

# Get the hello1 deployment in the test namespace.
conduit stat deployments hello1 -n test

# Get the test namespace.
conduit stat namespaces test

# Get all deployments.
conduit stat --all-namespaces=true deployments

# Get the hello1 deployment in the test namespace, filtered by requests to ns2 / pod-123
conduit stat deployment hello1 -n test --to-namespace ns2 --to-resource pod --to pod-123

tap

# tap the web deployment in the default namespace
conduit tap deploy default/web

# tap the web-dlbvj pod in the default namespace
conduit tap pod default/web-dlbvj

Proposal

• All primary/target resource strings take the form (type) [name] or (type)/[name], where name is optional:
  • stat deploy
  • stat deploy/foo
  • stat deploy foo
• To/from/destination resources always use the compound form:
  • --to deploy
  • --to deploy/foo
  • --from deploy/foo
• When type != namespace, namespaces are specified by their own flags:
  • --namespace
  • --to-namepace
  • --from-namespace
• --all-namespaces behaves as it does today

Some examples:

# Get all deployments in the test namespace.
conduit stat -n test deploy

# Get the hello1 deployment in the test namespace.
conduit stat -n test deploy/hello1 

# Get the test namespace.
conduit stat ns/test

# Get all deployments.
conduit stat --all-namespaces=true deployments

# Get the hello1 deployment in the test namespace, filtered by requests to ns2 / pod-123
conduit stat -n test deploy/hello1 --to-namespace ns2 --to pod/pod-123

# tap the web deployment in the default namespace
conduit tap -n default deploy/web

# tap the web-dlbvj pod in the default namespace
conduit tap -n default pod/web-dlbvj

[klingerf]

Relates to #683 (comment)

[briansmith]

conduit stat -n test deploy/hello1 --to-namespace ns2 --to pod/pod-123

Instead of this, I would prefer (thinking as a user) to use deploy/ns2.hello1 instread of deploy/hello1 --to-namespace ns2, i.e. a syntax of the form <type>/[<namespace>.]<name> where <namespace> defaults to the default namespace that might be overridden with -n.

[klingerf]

I have a strong preference for using an established syntax for referencing these resources, and as far as I know <type>/[<namespace>.]<name> is not something that's used in other kubernetes tooling. If anything, I think <type>/<name>[.<namespace>] would be more consistent with kubernetes naming conventions. But that said, it should also be possible to specify the namespace without specifying a resource name or type, and I don't know how we do that easily without a separate namespace flag.

[briansmith]

I think /[.] would be more consistent with kubernetes naming conventions.

Yes, my mistake.

But that said, it should also be possible to specify the namespace without specifying a resource name or type, and I don't know how we do that easily without a separate namespace flag.

True.