Skip to content

Latest commit

 

History

History
169 lines (143 loc) · 5.87 KB

hip-0008.md

File metadata and controls

169 lines (143 loc) · 5.87 KB
Raw
hip title authors created type status
0008
Add descriptions to custom completions
Marc Khouzam <marc.khouzam@montreal.ca>
2020-11-14
feature
accepted

Abstract

Provide (optional) descriptions for helm's custom completions.

The goal is to help users be more efficient by providing useful information when doing auto-completion.

Motivation

Helm currently supports auto-completion for the following shells: bash, zsh, fish. Both the zsh and fish shells support descriptions for completions.

For example, in the case of zsh:

$ helm s<TAB>
search  -- search for a keyword in charts
show    -- show information of a chart
status  -- display the status of the named release

The Cobra project, which is used by Helm to define its commands and flags, automatically provides completion descriptions when completing those commands and flags. Those descriptions are based on the usage information specified by Helm. However, custom completions that are provided by helm itself currently don't include any descriptions. For example, when completing helm status it is helm that provides the list of releases, but this list does not include descriptions.

$ helm status n<TAB>
nginx          nginx-ingress

Augmenting helm's custom completions with descriptions allows providing additional information to help users make their selection from the list of completions.

Rationale

The completions for some helm arguments do not always provide sufficient information for a user to know which value to choose. For instance, the name of a release is not always informative enough for the user to know which one to select. For example:

$ helm upgrade ngin<TAB>
nginx         nginx2

Clearly, in this case, the user needs to know the details of each release in advance as the difference between completion choices is not very helpful.

Specification

Here are proposed descriptions for the different types of custom completions:

  • chart names (for 'install', 'pull', 'show *', 'template', 'upgrade')
    • <chart description>
$ helm install myrelease bitnami/c<TAB>
bitnami/cassandra  -- Apache Cassandra is a free and open-source distributed database managemen
bitnami/common     -- A Library Helm Chart for grouping common logic between bitnami charts. Th
bitnami/consul     -- Highly available and distributed service discovery and key-value store de
bitnami/contour    -- Contour Ingress controller for Kubernetes

As the chart description will often be too long to fit on a single line, the shell will truncate the description to fit the shell's window. Note that each shell handles this case in its own way, where zsh truncates, while fish uses an ellipsis.

  • chart version (for '--version')
    • App: <app version>, Created: <date>
$ helm pull bitnami/nginx --version 7.1.<TAB>
7.1.0  -- App: 1.19.2, Created: September 24, 2020
7.1.1  -- App: 1.19.3, Created: September 29, 2020
7.1.2  -- App: 1.19.3, Created: October 2, 2020
  • kubernetes context (for '--kube-context')
    • <kube cluster name>
$ helm --kube-context d<TAB>
default  -- k3d-k3s-default
dev      -- development
  • helm environment variables (for 'env')
    • <value> (<description of variable>)
$ helm env HELM_RE<TAB>
HELM_REGISTRY_CONFIG    -- /me/Library/Preferences/helm/registry.json (Path to the registry configuration file)
HELM_REPOSITORY_CACHE   -- /me/Library/Caches/helm/repository (Path to the file containing cached repository indexes)
HELM_REPOSITORY_CONFIG  -- /me/Library/Preferences/helm/repositories.yaml (Path to the file containing repository names and URLs)
  • plugin names (for 'plugin uninstall', 'plugin update')
    • <plugin description>
$ helm plugin uninstall <TAB>
2to3        -- migrate and cleanup Helm v2 configuration and releases in-place to Helm v3
fullstatus  -- provide status of resources part of the release
  • release names (for 'get *', 'history', 'rollback', 'status', 'test', 'upgrade')
    • <chart name>-<chart version> -> <release status>
$ helm status <TAB>
mynginx        -- nginx-6.0.5 -> superseded
nginx-ingress  -- nginx-ingress-controller-5.4.4 -> deployed
  • release revisions (for 'rollback', '--revision')
    • App: <app version>, Chart: <chart name>-<chart version>
$ helm rollback nginx-ingress <TAB>
1  -- App: 0.34.1, Chart: nginx-ingress-controller-5.4.4
2  -- App: 0.40.2, Chart: nginx-ingress-controller-5.6.10
  • repo names (for 'repo remove' and completion of chart names)
    • <repo URL>
$ helm repo remove <TAB>
bitnami  -- https://charts.bitnami.com/bitnami
center   -- https://repo.chartcenter.io
stable   -- https://charts.helm.sh/stable
  • output formats (for '--output', '-o')
    • <format description>
$ helm status -o <TAB>
json   -- Output result in JSON format
table  -- Output result in human-readable format
yaml   -- Output result in YAML format

Note that descriptions can be turned off by the user when generating the shell completion script using the --no-descriptions flag.

Backwards compatibility

Not applicable to shell auto-completion. In fact, this allows us to implement some descriptions and still be able to modify them later if different ones are requested.

Security implications

None

How to teach this

The new descriptions will automatically appear when using auto-completion, so no special effort needs to be made to teach this new feature.

Reference implementation

A PR will be opened to implement the proposed specification for descriptions of custom completions.

Open issues

None.

It is worth clarifying that the bash shell does not support descriptions for auto-completion, so this feature will not apply to bash. That being said, there is a PR open on the Cobra project that adds descriptions for bash completions.