diff --git a/contributors/design-proposals/sig-cli/kubectl-service-catalog.md b/contributors/design-proposals/sig-cli/kubectl-service-catalog.md new file mode 100644 index 00000000000..20c26d87c3d --- /dev/null +++ b/contributors/design-proposals/sig-cli/kubectl-service-catalog.md @@ -0,0 +1,227 @@ +# MVP - kubectl commands for the Service Catalog + +Status: Pending + +## Motivation + +The client binary for the service catalog must cover every [use case](use-cases.md) and provide +tools for every [persona](use-cases.md#personas) described. + +While in some use cases we will most likely rely on the base commands already present on `kubectl` - like +`create`, `get`, `describe`, and `delete` - in others we want to have subcommands dedicated +to interacting with the service catalog. It is expected that the "end-users" (the *Service Consumer* +persona, for example), have a set of subcommands that are simple to use and allow them to easily check +information about the services available on a catalog, request instances, bind them to apps, and +manage their installed instances in a simple and user-friendly way. + +This document proposes the way every use case is fulfilled by `kubectl` subcommands and/or extensions. + +## Proposal + +Below the [identified personas](use-cases.md#personas) and the commands that are expected to fulfill the use +cases for each one of them. + +Note that when relying on existing commands, some improvements to printers and describers of the involved +resources might be needed. For example, in the describer of a service instance we might want to display the +number of bindings that currently exists and other information useful to catalog operators. + +### Service consumer + +For this persona we want simple and user-friendly commands. Service consumers must be able to easily search the entire +catalog for services available, check the metadata for each service, request an instance of a given service and +bind it to apps, only through the command line without the need of json or yaml files. + +So the proposal is to have a new set of subcommands called + +``` +kubectl catalog +``` + +which could be aliased as `kubectl (catalog | servicecatalog | service-catalog)` and distributed as part of the main +`kubectl` binary or, preferably, as `kubectl` [binary plugins](#distribution) +(TBD, this feature is under discussion and not yet available). + +Note that `instances` and `bindings` are user-scoped, so they are applied in the context of current namespace (or what's +provided by the `--namespace` flag, etc). + +The list of proposed subcommands under `kubectl catalog` is: + +#### List and search the service catalog and existing service instances + +``` +Usage: + +kubectl catalog list (available | instances) [--search=TERM] + +Examples: + +# List all services in the catalog available to be instantiated +$ kubectl catalog list available + +## List all service instances in use by current namespace +$ kubectl catalog list instances + +# List all service instances in use by the "mine" namespace +$ kubectl catalog list instances --namespace=mine + +# Search the service catalog for services that match "foo" +$ kubectl catalog list available --search=foo + +# Search the service catalog for services that belong to the "database" catalog +$ kubectl catalog list available --catalog=database +$ kubectl catalog list available --search=catalog=database + +# Search the service instances in "mine" namespace provided by publisher "kube" +$ kubectl catalog list instances --publisher=kube --namespace=mine +$ kubectl catalog list instances --search=publisher=kube --namespace=mine +``` + +TBD if the top-level `list` will just print help for the 2 sub commands or run one of them by default, +so that I could for example list all services available in the catalog with just `kubectl catalog list`. + +#### Describe information about a given service in the catalog, including metadata, plans, etc + +``` +Usage: + +kubectl catalog describe SERVICE +``` + +List all metadata available about a given service in the catalog, well-formatted and suitable for +on-screen reading. Includes description, publisher information, plans, URL's, etc. The expected +metadata information will likely include: + +``` +* name +* short description +* long desciption +* documentation/support urls +* icon URL +* image URLs - a list of images that could be displayed in a UI +* TOS (terms of service) link +* a list of plans + * plan name + * plan description + * plan cost +* construction parameters + * name + * description + * default value +* category label/tags +* version +* publisher name +* publisher contact url +* publisher website +``` + +TBD by plan name? What's the user-friendly "key" of a service? +TBD can also be used to describe my instances? + +#### Request a service instance (and optionally binds it to an existing resource) + +Binding at the time of request is optional. If not bound immediately, it can be done in a separate +command call. + +``` +Usage: + +kubectl catalog provision SERVICE [--plan=PLAN] [--bind-to=TYPE/NAME] [--namespace=NAMESPACE] + +Examples: + +# Provision an instance of the "profiler" service in the "mine" namespace with the "2cores" plan +$ kubectl catalog provision profiler --plan=2cores --namespace=mine + +# Provision an instance of "mariadb" with "5G" plan and bind it to my existing (Kube) service "frontend" +$ kubectl catalog provision mariadb --plan=5G --bind-to=svc/frontend --namespace=mine +``` + +TBD services has server-side validation when plans are strictly required, optional, not available, etc? + +#### Bind an existing service instance + +If not bound immediately (or if I want to bind it to other resource), it can be done with this command. + +``` +Usage: + +kubectl catalog bind INSTANCE --to=TYPE/NAME [--namespace=NAMESPACE] + +Examples: + +# Bind the existing service instance "mysql" to the (Kube) service "frontend" +$ kubectl catalog bind mysql --to=svc/frontend --namespace=mine +``` + +Note that this command will likely print secrets, config maps and other resources created while binding, +so that I know how the bound service will be available to my resource. + +TBD by instance name? What's the user-friendly "key" of a service instance? + +#### Unbind, de-provision a service instance, etc + +``` +Usage: + +kubectl catalog unbind INSTANCE --from=TYPE/NAME [--namespace=NAMESPACE] +``` + +``` +Usage: + +kubectl catalog deprovision INSTANCE [--namespace=NAMESPACE] +``` + +### Catalog operator + +#### Register broker + +With existing command(s), create a `broker` resource from json or yaml with + +``` +kubectl create -f /path/to/broker.yaml +``` + +#### Update broker + +With existing command(s): + +``` +kubectl (edit | apply | patch | replace) +``` + +#### Get / list brokers + +With existing command(s): +``` +kubectl (get | describe) +``` + +#### Delete broker + +With existing command(s): + +``` +kubectl delete +``` + +### Service producer + +TBD, will probably use existing commands but might be worth creating a couple new subcommands under `kubectl create`. + +## Distribution + +It's arguable if the `kubectl catalog` set of commands should be part of the major distribution of the +`kubectl` binary. The most fitting distribution mechanism would probably be binary extensions, or "kubectl +plugins" like we use to call it. However binary plugins is a part of a major discussion regarding "kubectl +extensions" which is still at the proposal phase, although it does have a PoC implementation that looks +very similar to the solution adopted in Helm plugins. + +Relevant related links: + +* [kubectl extensions proposal](https://github.com/kubernetes/community/pull/122) +* [previous kubectl extensions discussions](https://github.com/kubernetes/kubernetes/pull/30086) +* [PoC implementation](https://github.com/kubernetes/kubernetes/pull/37499) (fully functional with a [sample plugin](https://github.com/fabianofranz/kubernetes/blob/fd83635b26f1e41b84fcc1c1a811c3e41b63576c/pkg/kubectl/plugins/examples/kubectl-aging) written in Ruby) +* [Helm plugins architecture](https://github.com/kubernetes/helm/blob/master/docs/plugins.md) + +