diff --git a/keps/NEXT_KEP_NUMBER b/keps/NEXT_KEP_NUMBER index 8351c19397f..60d3b2f4a4c 100644 --- a/keps/NEXT_KEP_NUMBER +++ b/keps/NEXT_KEP_NUMBER @@ -1 +1 @@ -14 +15 diff --git a/keps/sig-cli/0014-krew.md b/keps/sig-cli/0014-krew.md new file mode 100644 index 00000000000..25c8f07c797 --- /dev/null +++ b/keps/sig-cli/0014-krew.md @@ -0,0 +1,237 @@ +--- +kep-number: 14 +title: Krew +authors: + - "@lbb" +owning-sig: sig-cli +participating-sigs: + - sig-cli +reviewers: + - TBD + - "@pwittroc" +approvers: + - "@pwittroc" +editor: lbb +creation-date: 2018-07-03 +last-updated: yyyy-mm-dd +status: provisional +see-also: + - n/a +replaces: + - n/a +superseded-by: + - n/a +--- + +# Krew + +## Table of Contents +* [Krew](#krew) + * [Table of Contents](#table-of-contents) + * [Summary](#summary) + * [Motivation](#motivation) + * [Discoverability](#discoverability) + * [Cross-platform Packaging](#cross-platform-packaging) + * [Lifecycle management](#lifecycle-management) + * [Goals](#goals) + * [Non-Goals](#non-goals) + * [Proposal](#proposal) + * [Capabilities](#capabilities) + * [Scenarios (standalone only)](#scenarios-standalone-only) + * [Scenarios](#scenarios) + * [UX and CLI Flow](#ux-and-cli-flow) + * [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints-optional) + * [Risks](#risks) + * [Graduation Criteria](#graduation-criteria) + * [Implementation History](#implementation-history) + * [Drawbacks](#drawbacks) + +## Summary + +krew is a package manager for the kubectl plugin system. krew introduces a way +to handle kubectl plugin management and discovery. + +## Motivation + +The kubectl plugin system allows users to extend kubectl by placing extension +executables in a plugin directory. This allows new subcommands and subcommand +trees to be added in the kubectl CLI interface under `kubectl plugin `. +This has the following user friction: + +* Users need to manually download and manage plugins to ~/.kube/plugins and + keep them up to date +* Users need to be aware of the installation requirements and instructions of + each plugin + +Currently, there are no unified distribution methods for kubectl plugins. +This has several disadvantages: + +### Discoverability + +Available kubectl plugins are not easily discoverable and searchable. + +### Cross-platform Packaging + +Plugins need to be packaged separately different OS and distros. +Often, plugin maintainers do not do this. + +### Lifecycle management + +Often installation is done through manually downloading a zip and placing +it under ~/.kube/plugins. This is an unpleasant experience to the user +especially when it comes to updating the plugins, +or when a user deletes ~/.kube. + +--- + +Those disadvantages will lead to slow the adoption rate of kubectl plugins. +krew will be a plugin manager able to solve all of the named issues. + +### Goals + + +* Install, uninstall and update plugins +* Discovery of plugins +* Giving developers a platform to contribute their plugins to +* Build repository platform for contributors (i.e brew formulas approach) +* Allow multiple plugin index sources +* (only for standalone) Self hosting: krew installation doesn't require a + package manager: it can upgrade itself + +### Non-Goals + +* Dependency management of libraries +* Plugins are user facing programs, they should not depend on each other. + They have environment requirements like curl or git. + Krew is not responsible to cover external dependency, + program and environment setup like apt, + brew or dnf. The user will be informed to take action. +* Complete integration with various download sources like “hg://” or “samba://” +* kubectl version compatibility management + + +## Proposal + +#### Capabilities + +Note: This proposal has already been implemented in +`github.com/GoogleContainerTools/krew` as a proof of concept. +The goal is to move it into kubectl. + +Define a new meta config format called plugin manifest +(stored in the index under: .yaml) + + +### Scenarios (standalone only) + +* User wants to install krew. They can run one `curl` command to install the + plugin manager, the plugin manager should then be able to function properly. + +### Scenarios + +* User wants to install and update a plugin. + They use the search to discover plugins `kubectl plugin search foo`. + Every plugin displays a short description of its purpose. + They find the right plugin and install it with the install command. + Using the update command them can update all installed plugins to it + latest version. +* User moves to a new machine and wants to reinstall all their plugins. + They can copy the declarative plugin list. This file contains all plugins that + were requested by the user to be installed. They have to copy it to the new + installation and run an update. There will be a command for exporting and + importing depots. +* Developer wants to make his plugin discoverable by others. + They provide a link to the whole plugin as a compressed file under a public + URL. (Github provides any commit/tag as .tar.gz automatically.) + Afterwards the developer creates a PR against the index repository with a new + meta description file. This file contains the download url, download hash, + plugin version and description and tags. Meta descriptions are used by the + plugin manager to discover and manage plugins. +* Developer wants to update their plugin and make those changes public. + They create a new PR against the index repository updating their plugin meta + description file. + +### UX and CLI Flow + +```text +# Update and fetch plugin index. +$ kubectl plugin update + +# Search for plugins +$ kubectl plugin search servicecat +service-catalog Consume services in Kubernetes using the Open S... available +service-cat-viewer Show ASCII cat picture for every Service format... installed +service-catalog-gke A helper utility for discovering GKE services l... available + +$ kubectl plugin info service-cat-viewer +DESCRIPTION: Show ASCII cat picture for every Service formatet ISO-11801 +URL: https://github.com/oscar-kitty/viewer.git + +CAVEATS: +This plugin needs the following programs: +* fzf +* jq + +For a better user experience: + export $TERM=vt220 + +# Install the plugin. +$ kubectl plugin install service-cat-viewer +Installation (1/1): service-cat-viewer +Downloading https://github.com/oscar-kitty/viewer.git +Progress: 100% +Done! + +Plugin Caveats: + This plugin needs the following programs: + * fzf + * jq + + For a better user experience: + export $TERM=vt220 + +# Update all plugins and index +$ kubectl plugin upgrade + +# Update specific plugins +$ kubectl plugin upgrade foo bar + +# uninstall plugin +$ kubectl plugin remove aws-cat-viewer + +# Store the list of installed plugins +$ kubectl plugin list > deposit.txt + +# On a new machine load the plugin list +$ kubectl plugin install < deposit.txt +... [Plugin installation output] ... +``` + +### Implementation Details/Notes/Constraints + +krew has already been implemented in the `github.com/GoogleContainerTools/krew` +repo, and should be moved to a separate repo for the sub project. +krew was initially developed as its own cli, however once it has matured, +it should be published as a subcommand of kubectl or as a statically linked +plugin. It should also be more tightly integrated with apply. + +### Risks +The index repository needs some form of governance to prevent malicious plugins. + +## Graduation Criteria +* Dogfood krew by either: + * moving one or more of the cncf clis to it (i.e helm) + * getting user feedback from one or more mid or large application deployments + using krew. +* Publish krew as a subcommand of kubectl. + + +## Implementation History +krew was implemented in the `github.com/GoogleContainerTools/krew` repo before +subprojects became a first class thing in Kubernetes. The code has been fully +implemented, but it must be moved to a proper location. + +## Drawbacks + +Implementing krew and growing the ecosystem can hold back the git-style plugin +approach.