kubernetes-sigs/krew

📦 Find and install kubectl plugins

Krew

Krew is the package manager for kubectl plugins.

What does Krew do?

Krew is a tool that makes it easy to use kubectl plugins. Krew helps you discover plugins, install and manage them on your machine. It is similar to tools like apt, dnf or brew. Today, over 200 kubectl plugins are available on Krew.

• For kubectl users: Krew helps you find, install and manage kubectl plugins in a consistent way.
• For plugin developers: Krew helps you package and distribute your plugins on multiple platforms and makes them discoverable.

Documentation

Visit the Krew documentation to find Installation instructions, User Guide and Developer Guide.

You can follow the Quickstart to get started with Krew.

Contributor Documentation

• Releasing Krew: how to release new version of Krew.
• Plugin Lifecycle: how Krew installs/upgrades plugins and itself. (Not necessarily up-to-date, but it can give a good idea about how Krew works under the covers.)
• Krew Architecture: architectural decisions behind designing initial versions of Krew. (Not up-to-date.)
• Krew Logo: our logo and branding assets.

Visit ./docs for all documentation.

Roadmap

Please check out the Issue Tracker to see the plan of record for new features and changes.

Community

Bug reports

• If you have a problem with the Krew itself, please file an issue in this repository.
• If you're having a problem with a particular plugin's installation or upgrades, file an issue at krew-index repository.
• If you're having an issue with an installed plugin, file an issue for the repository the plugin's source code is hosted at.

Communication channels

• Slack: #krew or #sig-cli
• Mailing List
• Kubernetes Community site

Contributing

Interested in contributing to Krew? Please refer to our Contributing Guidelines for more details.

Code of Conduct

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.

krew's Issues

cmd: some command errors are printing usage string

$ kubectl plugin upgrade ca-cert
Updated index
Error: failed to upgrade plugin "ca-cert", err: can't upgrade, the newest version is already installed
Usage:
  krew upgrade [flags]

Flags:
  -h, --help   help for upgrade

F0815 12:26:42.423219   57730 root.go:49] failed to upgrade plugin "ca-cert", err: can't upgrade, the newest version is already installed
error: exit status 255

pkg/installation: Proposed refactor

Current problems with methods called via Install():

• they take way too many arguments
  • very hard to refactor
  • super hard to test
• calls stack too deep, hard to reason about the call stack without writing it on a paper.

I'm proposing Install() method should be a linear call pipeline and we should separate installation "steps" to individual methods that:

• take less arguments
• are testable
• preferably don't call other methods with non-tested logic.

Current process

(call stack TOO DEEP, signatures too long/complex/untestable)

func Install(p environment.Paths, plugin index.Plugin, forceHEAD bool, forceDownloadFile string) error {
    - findInstalledPluginVersion(p.InstallPath(), p.BinPath(), plugin.Name)
    - getDownloadTarget(plugin, forceHEAD)
    - install(plugin.Name, version, uri, bin, p, fos, forceDownloadFile)--|

    func install(plugin, version, uri, bin string, p environment.Paths, fos []index.FileOperation, forceDownloadFile string) error
        - downloadAndMove(version, uri, fos, filepath.Join(p.DownloadPath(), plugin), p.PluginInstallPath(plugin), forceDownloadFile)
        - createOrUpdateLink(p.BinPath(), filepath.Join(dst, filepath.FromSlash(bin)), plugin)

        func downloadAndMove(version, uri string, fos []index.FileOperation, downloadPath, installPath, forceDownloadFile string) (dst string, err error)
        - pseudo initializeFetcher(forceDownloadFile, version, uri, downloadPath)
        - moveToInstallDir(downloadPath, installPath, version, fos)

            func moveToInstallDir(download, pluginDir, version string, fos []index.FileOperation) (string, error)
                - moveAllFiles(download, tempdir, fos); err != nil
                - moveOrCopyDir(tempdir, installPath)

New process

(linear, minimal responsibility, testable)

func Install(){
    1. Does it exist (<- paths, plugin.Name)
    2. Find a matching platform (<- Plugin, os,arch)
    3. Determine which version (=url) to install (<- Platform, forceHEAD)
    4. Initialize a fetcher (<- url, forceHEAD, forceDownloadFile)
    5. Fetch archive file (fetcher.Do) (<-fetcher)
    6. Save archive file to a temp file (<-io.Reader, tmpFile)
    7. Determine Unarchiver (<-tmpFile.Name)
    7. Extract archive file to download dir (<-tmpFile, tmpDir unarchiver)
    8. Do fileOps from=download_dir to=temp_dir <(download_dir, temp_dir, fos)
    9. Move/Copy from=temp_dir to=install_dir <(download_dir, install_dir)
    10. Create/Update link (<-paths, plugin.Name)
}

index: Validate platform selectors aren't overlapping

We need index.Validate() code to check if there are overlapping platform selectors.

For example, a manifest shouldn't be allowed to have a platform spec with os in [darwin,linux] and another with {os:darwin,arch:amd64} selector. (Because darwin/amd64 matches both.)

We currently don't validate this. It's more of a static check/linting for plugin developers. Also if we have overlapping selectors, it's currently unclear which one we'd pick (probably the first one depending on the order, which isn't good).

Vendor krew's own manifest file (krew.yaml) for iteration

We should bring krew.yaml to this repository and put it in the release .zip file.

• This could help offline/self-contained installation of krew (#67)
• We will have a versioned krew.yaml along with krew itself.
  • On a new release, we can just copy it to krew-index.
• Allows us to iterate on krew.yaml multiple times during the dev phase (between two releases).

Proposal: make spec.platforms[].files optional

If no files field specified, we may consider assuming:

files
- from: '*'
  to: '.'

then developers can just point to the entrypoint within the extracted archive through bin: field.

This already started to become a common pattern in several plugins.

(macOS) .DS_Store picked up as a plugin name

$ kubectl krew list -v=10
F1007 14:45:13.892817    4431 root.go:50] failed to find all installed versions, 
err failed to get plugin version, err: the plugin name ".DS_Store" is not allowed

This probably happened because I launched the index directory in macOS Finder.app once.

Move to k8s.io/cli-runtime

https://github.com/kubernetes/cli-runtime

Since krew is already a plugin today, using cli-runtime can help us standardize some cmdline flags (esp. useful for list cmd probably). (I don't know what else we'd get out of it right away.)

/cc @juanvallejo

archive checksums aren't consistent

If I run hack/make-all.sh twice, I get different checksums. e.g.

krew.tar.gz checksum: 86fff449a95637432c28592b530077a449fe578acc296aacbcc9a7e71ef83126
krew.zip checksum: 08aa780dc8cc702c553fb622f334b8439b537c8679309680feb5b2d462b3b2ed

and

krew.tar.gz checksum: 0233e2af055875784db833083d56fc235e09a085f2bcc1624598ab03a8bf43cd
krew.zip checksum: 8bb9df9aef534442c9d7f5b05c3112ae7cf20f4b5ec54b28c1e5c60b11f47482

Binaries between two runs are identical, but for some reason, archives are changing.

Use plugin description in search command

kubectl plugin search certificate is not bringing up ca-cert which has the word in its description.

/priority P2
/priority backlog

Add cloudbuild{,-release}.yaml to upload builds/releases to GCS

• Create GCS bucket in a long-haul project gs://krew
• Create a builder env to run hack/build-cross-releases.sh
• Write cloudbuild{,-release}.yaml to build & push the builds/releases.
• Configure GCB triggers
• Write a RELEASING.md explaining how releases are made.

Remove: Zip-inflation

Zip inflation currently tried to get rid of the first folder in a zip archive.

This behavior is inconsistent, it should be removed before we have to move many plugins.
See: #9

[kubectl-1.12] Allow dash in plugin names

Any krew plugin named like a-b-c today is symlinked as kubectl-a-b-c.

This causes plugin to be invokable only through kubectl a b c and loses the dashes in the original name.

Per kubectl/#540, the new design allows underscores (_) to be treated as - at invocation-time. This means, if a symlink is linked as kubectl-a_b_c, it can be invoked as kubectl a-b-c as desired (and equivalent of pre-1.12 behavior).

Proposed solution

Just replace dashes (-) with underscores _. This way we don't have to replace plugin identifiers in manifest filenames or name: fields.

This way krew can hide this implementation detail behind the covers and not expose it to both plugin devs and plugin users.

Will submit a PR shortly.

Support more download formats than zip

For a lot of Go projects, binary releases are either available directly or in a .tar.gz format. With how many k8s related projects are written in Go, it seems like it would make sense to add support for those formats. As an example, I'm using goreleaser to release rbac-lookup. That defaults to .tar.gz formats for Mac and Linux releases. Even just supporting downloading binaries directly without trying to unzip them would likely be helpful (and very straightforward). I'm happy to do some work in this direction if this is a feature if there's interest.

build-cross-releases produces cgo-dependent binary

A binary compiled with build-cross-releases on glibc doesn't work on Alpine.

Needs cgo disabling and cross-compilation flags.

Document symlinking and underscoring

We should explain:

• the new bin path introduced (in architecture guide?)
• we do symlinking (in architecture guide?, possibly dev guide?)
• we automatically convert -s in plugin names to _ (dev guide?)

Add version (commit info) to krew version command

It should be easy to tell which tag/commit that it's built from using kubectl plugin krew version. Currently only shows the sha256 of the krew plugin itself.

Implement a plugin audit command

Background:

We are currently not linting or verifying submissions for the krew index. We should provide a lint tool that is equal to the homebrew audit command.

User Story:

$ krew audit --source=./foo.yaml
Check Name Convention: OK
Validate Manifest: OK
Check Install: OK
Test Install and Uninstall with labels(os=linux,arch=amd64): SKIP
All Checks passed

$ krew audit foo
....

Usage for Developers and CI

The plugin developer can invoke the command locally. In the CI we can call the command for all updated plugin files like:

for name in $(git diff --name-only HEAD~1 HEAD | grep -o "^plugins/.*.yaml"); do
  krew audit "$name"
done

The CI executes this command for different platforms to test the installation.

The audit command should check for:

• Manifest
• Naming conventions
• Installation & Removal

fixes https://github.com/GoogleContainerTools/krew-index/issues/15

deduplicate tty detection

cmd/krew/cmd/list.go
42:			if !(isatty.IsTerminal(os.Stdout.Fd()) || isatty.IsCygwinTerminal(os.Stdout.Fd())) {

cmd/krew/cmd/install.go
47:			if (len(pluginNames) != 0 || *manifest != "") && !(isatty.IsTerminal(os.Stdin.Fd()) || isatty.IsCygwinTerminal(os.Stdin.Fd())) {
51:			if len(pluginNames) == 0 && *manifest == "" && !(isatty.IsTerminal(os.Stdin.Fd()) || isatty.IsCygwinTerminal(os.Stdin.Fd())) {

Remove directory indirection from krew.zip

Right now krew.zip has the following structure

unzip -l out/krew.zip
drwxr-xr-x  3.0 unx        0 b- stor 18-Oct-10 23:17 out/bin/
-rwxr-xr-x  3.0 unx 11682304 b- defN 18-Oct-10 23:17 out/bin/krew-windows_amd64.exe
-rwxr-xr-x  3.0 unx 11716104 b- defN 18-Oct-10 23:17 out/bin/krew-darwin_amd64
-rwxr-xr-x  3.0 unx 10214825 b- defN 18-Oct-10 23:17 out/bin/krew-linux_arm
-rwxr-xr-x  3.0 unx 11828176 b- defN 18-Oct-10 23:17 out/bin/krew-linux_amd64

The out/ prefix in the .zip yaml is unnecessary. I'm even thinking bin/ is redundant, too.

We can keep bin/ in case we add other stuff to the release someday, but I think it doesn't matter that much.

Fixing this would

• make copy operations in hack/krew.yaml shorter
• make installation instructions look shorter/cleaner

/cc @lbb; wdyt?

Uninstall travis releases in favor of gcb

After #88 is merged, delete deploy script in travis CI as GCB will upload the release binaries.

That said, we need to set correctly with the pre-calculated GCS URLs so (1) the Release message on GitHub (2) README links to the correct binary URLs.

krew install (without args) ensures index

Running

krew install

without providing any args (because user wants to just see the help/usage) takes long time, because it ensures the index.

Use file signatures to detect archive types

We currently rely on .zip and .tar.gz extension of downloaded files to choose extraction algorithm. File magic numbers can help here better and make it possible to use plugin archives without explicit file extension.

Can't figure out failure

I am not sure what failure I am experiencing with this plugin. Errors seem to be concatenated against each other.
https://github.com/jasonrichardsmith/krew-index/blob/initial-submission/plugins/rbac-view.yaml

$ kubectl krew install --manifest=rbac-view.yaml
Installing plugin: rbac-view
W1019 10:03:04.251654   14926 install.go:132] failed to install plugin "rbac-view": failed to dowload and move during installation: failed to download and verify file: failed to create file "/tmp/krew-downloads/rbac-view/bin/linux/rbac-view": open /tmp/krew-downloads/rbac-view/bin/linux/rbac-view: no such file or directory
F1019 10:03:04.251778   14926 root.go:52] failed to install some plugins: [rbac-view]

krew search shouldn't output header when no plugins found

When plugins not found, krew search outputs only header.

$ kubectl plugin search hoge
NAME DESCRIPTION STATUS

I think it is better that the command doesn't output anything when no plugins found.

Install failures are not printed

Instead it just says it failed and moves onto the next download (we probably don't need this behavior).

In case of sha256 verifications, even the logs don't print any errors.

ci flaky: go get gometalinter failing to fetch

Example:
https://travis-ci.org/GoogleContainerTools/krew/builds/427308224 (I think I just destroyed it by clicking Rebuild).

Error message:

$ go get gopkg.in/alecthomas/gometalinter.v2
package gopkg.in/alecthomas/gometalinter.v2: unrecognized import path "gopkg.in/alecthomas/gometalinter.v2" (parse https://gopkg.in/alecthomas/gometalinter.v2?go-get=1: no go-import meta tags ())
The command "go get gopkg.in/alecthomas/gometalinter.v2" failed and exited with 1 during .

Proposal: deprecate "head" field

Given now --manifest and --archive can be provided to krew install command to ease installing plugins locally for development, head: no longer provides a good value:

• it makes plugin versioning and upgrade model harder to reason about
• homebrew also recently deprecated head field
• provides no real value at this point

Proposal: support custom index repositories

Krew should support customizable index repositories.

This would allow users to distribute plugins without requiring them to make a pull request to the centralized index repo like "krew-index".

Similarly, this would allow vendors to distribute their plugins that are too specific or one-off to be in the centralized index repo.

Work here is probably:

• Determine/propose a user experience journey
• Propose a design
• Implement CLI commands to tap/untap into other index repos
• Refactor update/upgrade paths to keep taps in mind
• Write user/developer documentation on working with custom repos.

@lbb has showed interest to work on this.

bash completion naming conflicts with kubectl

Is there a way to prevent the bash completion naming conflicts?
After krew installation, when kubectl is tab-completed, instead of the name being output and a space (useful), I'm given no space and another tab gives the options:

$ kubectl
kubectl              kubectl-krew         kubectl-view_secret

This is on macos with bash 5.0.0, I haven't checked on Linux.
Thanks

krew -h prints only glog help

$ kubectl krew -h
Usage of /Users/ahmetb/.krew/bin/kubectl-krew:
  -alsologtostderr
    	log to standard error as well as files
  -log_backtrace_at value
    	when logging hits line file:N, emit a stack trace
  -log_dir string
    	If non-empty, write log files in this directory
  -logtostderr
    	log to standard error instead of files
  -stderrthreshold value
    	logs at or above this threshold go to stderr
  -v value
    	log level for V logs
  -vmodule value
    	comma-separated list of pattern=N settings for file-filtered logging

Migrate to pkg/errors

We should migrate to http://github.com/pkg/errors sometime. We have a lot of error message consistencies such as:

• something bad happened, err: %v
• something bad happened, err=%+v
• something bad happened: %v

This would involve:

1. Standardize wrapping errors.
2. Format errors with %+v where appropriate to print the stack trace.

Handle "krew remove krew"

Krew by design can't remove itself. We need to handle the case that someone wants to remove krew itself.

$ krew remove krew
krew can't remove krew. Please run:
    rm -r <krew-path>

$ echo $?
1

Krew installation error due to missing plugin.yaml

I'm trying to install krew following the instructions at https://github.com/GoogleContainerTools/krew. Unfortunately it fails with the error message "failed to install plugin "krew", err: the resulting plugin dir has to contain a plugin.yaml file".

My computer is running Linux with Fedora Core 28. Uname output:
Linux AARN20440W10B1 4.17.9-200.fc28.x86_64 #1 SMP Mon Jul 23 21:41:29 UTC 2018 x86_64 x86_64 x86_64 GNU/Linux

Here is detailed log when I run it from the temp directory:

$ ./krew-linux -v 9 install krew
I0730 09:56:51.947909   30818 root.go:101] Ensure creating dir: "/home/andreas/.kube/plugins/krew"
I0730 09:56:51.948225   30818 root.go:101] Ensure creating dir: "/tmp/krew"
I0730 09:56:51.948297   30818 root.go:101] Ensure creating dir: "/home/andreas/.kube/plugins/krew/store"
I0730 09:56:51.949300   30818 git.go:62] Going to run git pull --ff-only -v
From https://github.com/GoogleContainerTools/krew-index
 = [up to date]      master     -> origin/master
Already up to date.
Updated index
I0730 09:56:52.535801   30818 scanner.go:73] Reading plugin "krew"
Will install plugin: krew
I0730 09:56:52.538575   30818 install.go:105] Installing plugin: krew
I0730 09:56:52.538602   30818 install.go:64] Looking for installed versions
I0730 09:56:52.538633   30818 util.go:58] Searching for installed versions of krew in "/home/andreas/.kube/plugins/krew/store"
I0730 09:56:52.538795   30818 install.go:73] Finding download target for plugin krew
I0730 09:56:52.538822   30818 util.go:40] Matching platform for labels(arch=amd64,os=linux)
I0730 09:56:52.538956   30818 util.go:47] Found matching platform with index (1)
I0730 09:56:52.538989   30818 util.go:119] Matching plugin version is 437272f4f52b6d114f87b366cc3d069f54ab7451dc530c9b6517139fc150f908
I0730 09:56:52.539014   30818 install.go:41] Creating download dir "/tmp/krew/krew"
I0730 09:56:52.539211   30818 install.go:51] Getting sha256 (437272f4f52b6d114f87b366cc3d069f54ab7451dc530c9b6517139fc150f908) signed version
I0730 09:56:52.539241   30818 downloader.go:32] Fetching "https://storage.googleapis.com/krew-test/krew-437272f4f52b6d114f87b366cc3d069f54ab7451dc530c9b6517139fc150f908.zip"
I0730 09:56:52.983511   30818 downloader.go:39] Reading download data into memory
I0730 09:56:55.014619   30818 downloader.go:44] Read 13917853 bytes of download data into memory
I0730 09:56:55.014784   30818 downloader.go:52] Extracting download zip to "/tmp/krew/krew"
I0730 09:56:55.572781   30818 move.go:151] Creating plugin dir "/home/andreas/.kube/plugins/krew/store/krew"
I0730 09:56:55.572859   30818 move.go:157] Creating temp plugin move operations dir "/tmp/krew-temp-move716057421"
I0730 09:56:55.572872   30818 move.go:122] Finding move targets from "/tmp/krew/krew" to "/tmp/krew-temp-move716057421" with file operation={build/unix/plugin.yaml plugin.yaml}
I0730 09:56:55.572890   30818 move.go:44] Trying to move single file directly from=%q to=%q with file operation=%+v /tmp/krew/krew /tmp/krew-temp-move716057421 {build/unix/plugin.yaml plugin.yaml}
I0730 09:56:55.572911   30818 move.go:52] Wasn't a single file, proceeding with Glob move
I0730 09:56:55.572920   30818 move.go:122] Finding move targets from "/tmp/krew/krew" to "/tmp/krew-temp-move716057421" with file operation={build/krew-linux krew}
I0730 09:56:55.572927   30818 move.go:44] Trying to move single file directly from=%q to=%q with file operation=%+v /tmp/krew/krew /tmp/krew-temp-move716057421 {build/krew-linux krew}
I0730 09:56:55.572934   30818 move.go:52] Wasn't a single file, proceeding with Glob move
I0730 09:56:55.572942   30818 move.go:122] Finding move targets from "/tmp/krew/krew" to "/tmp/krew-temp-move716057421" with file operation={build/unix/commands/* commands}
I0730 09:56:55.572948   30818 move.go:44] Trying to move single file directly from=%q to=%q with file operation=%+v /tmp/krew/krew /tmp/krew-temp-move716057421 {build/unix/commands/* commands}
I0730 09:56:55.572957   30818 move.go:52] Wasn't a single file, proceeding with Glob move
I0730 09:56:55.572968   30818 move.go:167] Checking for plugin descriptor in new plugin dir
I0730 09:56:55.572974   30818 util.go:81] Checking path "/tmp/krew-temp-move716057421" for plugin descriptors
W0730 09:56:55.577480   30818 install.go:112] failed to install plugin "krew", err: the resulting plugin dir has to contain a plugin.yaml file
Error: failed to install some plugins: [krew]
Usage:
  krew install [flags]

Flags:
      --HEAD            Force HEAD if versioned and HEAD installs are possible.
  -h, --help            help for install
      --source string   (Development-only) specify plugin manifest directly.

Global Flags:
      --alsologtostderr                  log to standard error as well as files
      --log_backtrace_at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
      --log_dir string                   If non-empty, write log files in this directory
      --logtostderr                      log to standard error instead of files (default true)
      --stderrthreshold severity         logs at or above this threshold go to stderr (default 2)
  -v, --v Level                          log level for V logs (default 9)
      --vmodule moduleSpec               comma-separated list of pattern=N settings for file-filtered logging

F0730 09:56:55.578205   30818 root.go:49] failed to install some plugins: [krew]

krew info's error message isn't friendly when plugin doesn't exist

When plugin doesn't exist, krew info outputs error message as follows:

$ kubectl plugin info hoge
F0728 16:15:27.943022    8904 info.go:40] failed to read the plugin file, err: failed to open index file, err: open /Users/ksuda/.kube/plugins/krew/index/plugins/hoge.yaml: no such file or directory
error: exit status 255

Personally, I feel the above message is not user friendly.

I expect error message as follows:

$ kubectl plugin info hoge
Error: plugin "hoge" not found

Compilation requires native modules and gcc

Compilation on alpine (per #84) requires:

• gcc
• netdb.h (musl-dev)

Also shasum -a 256 isn't packaged.

Executing kubectl-krew directly is broken

(valid after #42 is merged)

$ kubectl-krew
F0924 19:35:45.867271   43700 root.go:65] failed to find current krew version, err: failed to resolve path, err: failed to stat the currently executed path, err: lstat kubectl-krew: no such file or directory

but kubectl krew works.

Verbose logs

kubectl-krew -v=10
I0924 19:36:04.659937   43717 root.go:93] Ensure creating dir: "/Users/ahmetb/.krew"
I0924 19:36:04.660571   43717 root.go:93] Ensure creating dir: "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew"
I0924 19:36:04.660603   43717 root.go:93] Ensure creating dir: "/Users/ahmetb/.krew/store"
I0924 19:36:04.660622   43717 root.go:93] Ensure creating dir: "/Users/ahmetb/.krew/bin"
F0924 19:36:04.660670   43717 root.go:65] failed to find current krew version, err: failed to resolve path, err: failed to stat the currently executed path, err: lstat kubectl-krew: no such file or directory

Not sure why krew needs to find itself through current directory. It's now at $HOME/.krew/bin/kubectl-krew.

Make it possible to override OS/arch used for installation

It should be possible to force installation of another platform from any other platform. i.e. I should be able to install windows/arm from darwin/amd64.

This would be needed to write a program that validates installation recipes (url, bin, files...) of all platforms listed in a manifest.

hack:CI/CD tooling to verify manifests

We should have a way of doing some sanity checks on the plugin files to prevent:

• the entire index from breaking due to bad yaml
• bad links/sha (at the time of merging the PR)

Perhaps we can find the changed yaml files and do krew install --source=$f to verify installation.

Question on bin files without .exe suffix

If a plugin's windows platform spec specifies something like bin: foo, we:

1. copy the executable to plugin's installation dir as foo
2. but we symlink it as kubectl-foo.exe on windows.

I am not at all sure that kubectl-foo.exe which points to foo (that has no .exe extension) can be executed. Can someone verify if this works or not?

Depending on that, (1) we need to make sure if a platform spec matches windows, its bin must end with ".exe" (2) we need to update existing plugin specs in krew-index.

Support direct binary (non-archive) downloads

I've been thinking about this for a while.

Especially with kubectl 1.12 plugin model, it's inevitable people will have Go repositories on Github with static binary releases (without ZIPs).

I've so far heard from at least one plugin dev that goreleaser doesn't support creating .zip, so they need to change their release model to accommodate krew distribution.

Strawman design:

We can have 3 modes, like:

archive downloads: download: archive: https://.../foo.zip sha256: [...]

file downloads: download: file: https://.../kubectl-foo_linux_amd64 sha256: [...]

head: download: head: [...]

Thoughts? There's time to do this during for krew 0.2.

cc: @lbb

Provide .tar.gz release artifact

In addition to .zip (which is good for windows) we should also have .tar.gz for krew releases.

This would unburden the mac and linux users from installing unzip tool, which is not really standard, whereas tar is.

BUG: Fatal error with wrong --archive type

When using --archive we assume the filetype of the index URL.
This will lead to a decoding error when the --archive type mismatches with the type specified in the uri:.

./bin/krew-darwin_amd64 install --archive ./krew.zip --manifest krew.yaml -v 6
I1014 21:40:35.421829    9181 install.go:132] --manifest specified, not ensuring plugin index
I1014 21:40:35.423021    9181 install.go:101] Will install plugin: krew
Installing plugin: krew
I1014 21:40:35.423051    9181 install.go:74] Looking for installed versions
I1014 21:40:35.423066    9181 util.go:77] Searching for installed versions of krew in "/Users/lbb/.krew/bin"
I1014 21:40:35.423113    9181 install.go:83] Finding download target for plugin krew
I1014 21:40:35.423123    9181 util.go:36] Using os=darwin arch=amd64
I1014 21:40:35.423129    9181 util.go:59] Matching platform for labels(arch=amd64,os=darwin)
I1014 21:40:35.423179    9181 util.go:66] Found matching platform with index (0)
I1014 21:40:35.423186    9181 util.go:129] Matching plugin version is 170f15a0f363bf1d35896b5963495e70e215caa41ebfb7244351c42c6ab06222
I1014 21:40:35.423196    9181 install.go:46] Creating download dir "/var/folders/b6/3hk_x4nx08z2qb9ph8_zcxgh0000gn/T/krew-downloads/krew"
I1014 21:40:35.423865    9181 install.go:61] Getting sha256 (170f15a0f363bf1d35896b5963495e70e215caa41ebfb7244351c42c6ab06222) signed version
I1014 21:40:35.423888    9181 downloader.go:36] Fetching "https://github.com/GoogleContainerTools/krew/releases/download/v0.1.0-alpha.1-56-g1727d93/krew.tar.gz"
I1014 21:40:35.423936    9181 downloader.go:43] Reading download data into memory
I1014 21:40:35.507490    9181 downloader.go:48] Read 14405237 bytes of download data into memory
W1014 21:40:35.507655    9181 install.go:114] failed to install plugin "krew"
F1014 21:40:35.507691    9181 root.go:50] failed to install some plugins: [krew]
github.com/GoogleContainerTools/krew/cmd/krew/cmd.init.1.func1
	/Users/lbb/go/src/github.com/GoogleContainerTools/krew/cmd/krew/cmd/install.go:124
github.com/GoogleContainerTools/krew/vendor/github.com/spf13/cobra.(*Command).execute
	/Users/lbb/go/src/github.com/GoogleContainerTools/krew/vendor/github.com/spf13/cobra/command.go:762
github.com/GoogleContainerTools/krew/vendor/github.com/spf13/cobra.(*Command).ExecuteC
	/Users/lbb/go/src/github.com/GoogleContainerTools/krew/vendor/github.com/spf13/cobra/command.go:852
github.com/GoogleContainerTools/krew/vendor/github.com/spf13/cobra.(*Command).Execute
	/Users/lbb/go/src/github.com/GoogleContainerTools/krew/vendor/github.com/spf13/cobra/command.go:800
github.com/GoogleContainerTools/krew/cmd/krew/cmd.Execute
	/Users/lbb/go/src/github.com/GoogleContainerTools/krew/cmd/krew/cmd/root.go:48
main.main
	/Users/lbb/go/src/github.com/GoogleContainerTools/krew/cmd/krew/main.go:23
runtime.main
	/Users/lbb/homebrew/Cellar/go/1.11.1/libexec/src/runtime/proc.go:201
runtime.goexit
	/Users/lbb/homebrew/Cellar/go/1.11.1/libexec/src/runtime/asm_amd64.s:1333

plugin install is broken in master: rename fails "file exists"

I added bin: ca-cert.sh to existing ca-cert.yaml and ran:

kubectl krew install --source ~/.krew/index/plugins/ca-cert.yaml -v=10

I0925 10:43:18.446458   77773 git.go:62] Going to run git pull --ff-only -v
From https://github.com/GoogleContainerTools/krew-index
 = [up to date]      master     -> origin/master
Already up to date.
Updated index
Will install plugin: ca-cert
I0925 10:43:18.943571   77773 install.go:105] Installing plugin: ca-cert
I0925 10:43:18.943610   77773 install.go:69] Looking for installed versions
I0925 10:43:18.943639   77773 util.go:61] Searching for installed versions of ca-cert in "/Users/ahmetb/.krew/bin"
I0925 10:43:18.943675   77773 install.go:78] Finding download target for plugin ca-cert
I0925 10:43:18.943689   77773 util.go:43] Matching platform for labels(arch=amd64,os=darwin)
I0925 10:43:18.943792   77773 util.go:50] Found matching platform with index (0)
I0925 10:43:18.943817   77773 util.go:113] Matching plugin version is 8be8ed348d02285abc46bbf7a4cc83da0ee9d54dc2c5bf86a7b64947811b843c
I0925 10:43:18.943827   77773 install.go:46] Creating download dir "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew/ca-cert"
I0925 10:43:18.944054   77773 install.go:56] Getting sha256 (8be8ed348d02285abc46bbf7a4cc83da0ee9d54dc2c5bf86a7b64947811b843c) signed version
I0925 10:43:18.944087   77773 downloader.go:32] Fetching "https://github.com/ahmetb/kubectl-extras/archive/c403c5714a4442b8314e5a86b0ff63f7a815f83f.zip"
I0925 10:43:19.750567   77773 downloader.go:39] Reading download data into memory
I0925 10:43:19.818536   77773 downloader.go:44] Read 19613 bytes of download data into memory
I0925 10:43:19.818588   77773 downloader.go:52] Extracting download zip to "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew/ca-cert"
I0925 10:43:19.829590   77773 move.go:155] Creating plugin dir "/Users/ahmetb/.krew/store/ca-cert"
I0925 10:43:19.829832   77773 move.go:161] Creating temp plugin move operations dir "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew-temp-move184368352"
I0925 10:43:19.829850   77773 move.go:126] Finding move targets from "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew/ca-cert" to "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew-temp-move184368352" with file operation=index.FileOperation{From:"/*/ca-cert/*", To:"."}
I0925 10:43:19.829898   77773 move.go:44] Trying to move single file directly from="/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew/ca-cert" to="/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew-temp-move184368352" with file operation=index.FileOperation{From:"/*/ca-cert/*", To:"."}
I0925 10:43:19.830031   77773 move.go:52] Wasn't a single file, proceeding with Glob move
I0925 10:43:19.830323   77773 move.go:76] Move operations are complete
I0925 10:43:19.830338   77773 move.go:133] Move file from "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew/ca-cert/kubectl-extras-c403c5714a4442b8314e5a86b0ff63f7a815f83f/ca-cert/ca-cert.bash" to "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew-temp-move184368352/ca-cert.bash"
I0925 10:43:19.830543   77773 move.go:133] Move file from "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew/ca-cert/kubectl-extras-c403c5714a4442b8314e5a86b0ff63f7a815f83f/ca-cert/plugin.yaml" to "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew-temp-move184368352/plugin.yaml"
I0925 10:43:19.830729   77773 move.go:172] Move "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew-temp-move184368352" to "/Users/ahmetb/.krew/store/ca-cert/8be8ed348d02285abc46bbf7a4cc83da0ee9d54dc2c5bf86a7b64947811b843c"
W0925 10:43:19.836107   77773 install.go:112] failed to install plugin "ca-cert", err: failed to dowload and move during installation, err: could not rename file from "/var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew-temp-move184368352" to "/Users/ahmetb/.krew/store/ca-cert/8be8ed348d02285abc46bbf7a4cc83da0ee9d54dc2c5bf86a7b64947811b843c", err: rename /var/folders/76/5g_jbgjn6xg_jkwcm2n_m52r00dl55/T/krew-temp-move184368352 /Users/ahmetb/.krew/store/ca-cert/8be8ed348d02285abc46bbf7a4cc83da0ee9d54dc2c5bf86a7b64947811b843c: file exists
F0925 10:43:19.836154   77773 root.go:48] failed to install some plugins: [ca-cert]

Allow configuration of krew base path ($HOME/.krew)

#49 adds a hardcoded krew base path to $HOME/.krew.

It should be possible to override this path for reasons like:

1. user doesn't want to install binaries in $HOME (maybe they can do /usr/local/krew)
2. user/maintainer wants to check out a command on a fresh krew base path like mktemp -d or /tmp/some-test without causing any disturbance to their main krew installation.

A very simple way to do this appears to be environment variable, such as:

KREW_BASE="$(mktemp -d)" kubectl krew install foo
KREW_BASE="$HOME/work-profile/krew" krew install foo

[🔥WIP🔥] Migrating to kubectl v1.12 new plugin model (BREAKING CHANGES), krew v0.2 release.

Context:

• Kubernetes 1.12 implements git-style plugins (executables prefixed kubectl-* placed in PATH).

• Krew does not support this model (predates it), but we saw this coming during the design phase.

• This change will still break krew heavily.

• Now that kubernetes 1.12.0-beta.1 release is available, we need to make krew work with the new kubectl plugin model.

Plan

• Determine which krew version will fully support the "new plugin model": (v0.2)
• Provide breaking change notices
  • Release a patch version for krew, adding a warning to every major cmd (#40)
  • Update README about krew version being incompatible (#36)
• Plugin manifest updates
  • Add a field to platforms[] indicating which file(s) should be symlinked (#35)
    • allow naming the symlink from plugin name e.g: mtail→kubectl-mtail) (#42)
  • (Possibly) Disable unknown field checking in manifest YAML (and validate in "audit" cmd) to allow graceful addition of this field (but I think breaking everyone in this case is ok due to low user count)
  • (Possibly) Error out for manifests in v1alpha1. (#72)
• Krew mechanics
  • Determine a binary symlink path (like ~/.krew/bin) (#49)
  • Modify installation/upgrade to take symlinks into account. (#42)
  • Manually test upgrading krew.
  • Detect kubectl version (refuse to run if <v1.12) (#41)
• Index updates
  • Backport and test all krew-index with the new bin path. (kubernetes-sigs/krew-index#24)
• Documentation
  • Add note: "krew only works with kubectl-1.12 and above" (remove breaking change notice)
  • Have users add krew symlink path to $PATH
    • Update install script and user guide (show how to update PATH)
    • Mention this in krew meta-plugin CAVEATS section (#114)
  • Update developer guide with changes to kubectl-1.12 plugin model (#100)
  • Update developer guide with changes to krew (bin dir, symlinks etc) (#62)
  • Update user guide with nrew instructions (#93)
• Upstream issues
  • kubectl-1.12 doesn't allow dashes in plugin names (forces user to invoke by separating words into args) kubernetes/kubectl#540 not sure what we can do about this. #59
• Release
  • Update krew README installation instructions
  • Update krew, downgrade kubectl 1.12 warning to a notice.
  • Update krew.yaml to add linux/arm platform (was in #48) (#80)
  • Fix krew.yaml with new binary names introduced (was in #48) (#80)
  • Locally test.
  • Set up GCB triggers
  • Uninstall Travis CI trigger (#95, #89)
  • Tag release
  • Test GCS URLs

I'm probably missing a few but will update the list above continuously.

cc: @lbb

Automating github releases from git tag messages

List of issues encountered while releasing v0.2.0 with the scripts we have:

1. -m to git tag needs a header: e.g.krew ${TAG} + an empty line, then the actual message.
2. I still have to click "Draft new release" after pushing the annotated tag. This is unexpected.
   
3. The message is rendered as plaintext (without creating the release):
   
4. If I click "Draft new release", no fields are filled automatically (github bug probably smh):
   
5. If I leave fields empty and create a "Release", it shows the message as plaintext (no Markdown):
   

cmd: error printed twice

Similar to #27, another common problem people have with spf13/cobra for sure...

Document Style Guide/Enforcement for the index repo

The centralized krew-index repo started to get many pull requests. So far the #1 issue is:

1. What constitutes a plugin that can be in the central index?
2. Why a plugin name is OK or NOT OK in the central index?

I suggest we explain GOOD/BAD names by recommending people with example suggestions in a Style Guide that improves over time.

cc: @lbb.

% characters in CAVEATS are printed as %(missing!)

Add link to KEP and intention to donate this to kubectl

README could use a Roadmap section outlining this.