From a1402f8864f9904b3009ba40a12b55ec09cadbb3 Mon Sep 17 00:00:00 2001 From: Chris Kim Date: Tue, 2 Feb 2021 10:42:29 -0800 Subject: [PATCH] Docs update - user guide (#687) * Most of the changes for the user-guide section * Add follow up changes to user guide section --- site/content/docs/user-guide/configuration.md | 5 ++-- site/content/docs/user-guide/install.md | 2 +- site/content/docs/user-guide/list.md | 17 ++++++------- site/content/docs/user-guide/quickstart.md | 4 ++-- site/content/docs/user-guide/search.md | 2 +- site/content/docs/user-guide/setup/install.md | 24 +++++++++---------- .../docs/user-guide/setup/uninstall.md | 6 ++--- site/content/docs/user-guide/setup/updates.md | 8 +++---- site/content/docs/user-guide/upgrade.md | 6 ++--- .../docs/user-guide/using-custom-indexes.md | 17 +++++++------ 10 files changed, 45 insertions(+), 46 deletions(-) diff --git a/site/content/docs/user-guide/configuration.md b/site/content/docs/user-guide/configuration.md index 34cb43beb5..3d2a023b7e 100644 --- a/site/content/docs/user-guide/configuration.md +++ b/site/content/docs/user-guide/configuration.md @@ -9,7 +9,8 @@ weight: 900 ## Customize installation directory {#custom-install-dir} By default, Krew installs itself and plugins to `$HOME/.krew`. This means -Krew itself and the installed plugins will be visible only to your user. +Krew itself and the installed plugins will be visible only to the user who +installed it. To customize this installation path, set the `KREW_ROOT` environment variable while [installing Krew]({{< relref "setup/install.md" >}}). After Krew is @@ -32,7 +33,7 @@ pointing to the [krew-index][ki] repository. You can force Krew to use a different repository by setting `KREW_DEFAULT_INDEX_URI` before running the [installation instructions]({{}}) or after [removing the default index]({{}}). -`KREW_DEFAULT_INDEX_URI` should point to a git repository URI that uses a valid +`KREW_DEFAULT_INDEX_URI` must point to a git repository URI that uses a valid git remote protocol. To use a different default index, set the `KREW_DEFAULT_INDEX_URI` environment diff --git a/site/content/docs/user-guide/install.md b/site/content/docs/user-guide/install.md index 4de037a008..b63841b5f0 100644 --- a/site/content/docs/user-guide/install.md +++ b/site/content/docs/user-guide/install.md @@ -4,7 +4,7 @@ slug: installing-plugins weight: 400 --- -Plugins can be installed with `kubectl krew install` command: +Plugins can be installed with the `kubectl krew install` command: ```text {{}}kubectl krew install ca-cert diff --git a/site/content/docs/user-guide/list.md b/site/content/docs/user-guide/list.md index b5c937199c..d8abb83425 100644 --- a/site/content/docs/user-guide/list.md +++ b/site/content/docs/user-guide/list.md @@ -4,22 +4,22 @@ slug: list weight: 500 --- -You can list all installed `kubectl` plugins (including those not installed via -Krew) using: +To list all plugins installed via Krew, run: ```sh -{{}}kubectl plugin list +{{}}kubectl krew list ``` -To list all plugins installed via Krew, run: +You can list all installed `kubectl` plugins (including those not installed via +Krew) using: ```sh -{{}}kubectl krew list +{{}}kubectl plugin list ``` ### Backing up plugin list -When you pipe or redirect `kubectl krew list` command’s output to another file +When you pipe or redirect the `kubectl krew list` command’s output to another file or command, it will return a list of plugin names installed, e.g.: ```sh @@ -29,8 +29,9 @@ whoami tree ``` -You can then [install]({{}}) the list of plugins from a file -by feeding the file to the `install` command over standard input (stdin): +You can then [install]({{}}) the list of plugins from the file +(on another machine, for example) by feeding the file to the `install` command over +standard input (stdin): ```sh {{}}kubectl krew install < backup.txt diff --git a/site/content/docs/user-guide/quickstart.md b/site/content/docs/user-guide/quickstart.md index 5720c990f0..cc25e9b791 100644 --- a/site/content/docs/user-guide/quickstart.md +++ b/site/content/docs/user-guide/quickstart.md @@ -6,7 +6,7 @@ weight: 100 Krew helps you discover and install [`kubectl` plugins][kpl] on your machine. -There are [a lot of][list] `kubectl` plugins you can install and use to enhance +You can install and use [a wide variety of][list] `kubectl` plugins to enhance your Kubernetes experience. Let's get started: @@ -54,7 +54,7 @@ auth-proxy Authentication proxy to a pod or service {{}}kubectl krew uninstall access-matrix ``` -This is pretty much all you need to know as a user to use Krew. +This is practically all you need to know to start using Krew. [kpl]: https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/ [list]: {{< relref "plugins.md" >}} diff --git a/site/content/docs/user-guide/search.md b/site/content/docs/user-guide/search.md index 2e99d8be4a..da37106bd0 100644 --- a/site/content/docs/user-guide/search.md +++ b/site/content/docs/user-guide/search.md @@ -5,7 +5,7 @@ weight: 300 --- You can find a list of `kubectl` plugins distributed via Krew [here][list]. -However, you can achieve this using the command-line as well. +However, you can find plugins using the command line as well. ## Search available plugins diff --git a/site/content/docs/user-guide/setup/install.md b/site/content/docs/user-guide/setup/install.md index 5287832477..a4b9a037ee 100644 --- a/site/content/docs/user-guide/setup/install.md +++ b/site/content/docs/user-guide/setup/install.md @@ -7,7 +7,7 @@ weight: 200 Krew itself is a `kubectl` plugin that is installed and updated via Krew (yes, Krew self-hosts). -> ⚠️ **Warning:** krew is only compatible with `kubectl` v1.12 or higher. +> ⚠️ **Warning:** krew is only compatible with `kubectl` v1.12 or later. - **macOS/Linux**: [bash/zsh](#bash), [fish](#fish) - **[Windows](#windows)** @@ -17,7 +17,7 @@ Krew self-hosts). #### Bash or ZSH shells {#bash} 1. Make sure that `git` is installed. -1. Run this command in your terminal to download and install `krew`: +1. Run this command to download and install `krew`: ```sh ( @@ -29,7 +29,7 @@ Krew self-hosts). ) ``` -1. Add `$HOME/.krew/bin` directory to your PATH environment variable. To do +1. Add the `$HOME/.krew/bin` directory to your PATH environment variable. To do this, update your `.bashrc` or `.zshrc` file and append the following line: ```sh @@ -38,7 +38,7 @@ Krew self-hosts). and restart your shell. -1. Verify running `kubectl krew` works. +1. Run `kubectl krew` to check the installation. #### Fish shell {#fish} @@ -56,7 +56,7 @@ Krew self-hosts). end ``` -1. Add `$HOME/.krew/bin` directory to your PATH environment variable. To do +1. Add the `$HOME/.krew/bin` directory to your PATH environment variable. To do this, update your `config.fish` file and append the following line: ```fish @@ -65,30 +65,30 @@ Krew self-hosts). and restart your shell. -1. Verify running `kubectl krew` works. +1. Run `kubectl krew` to check the installation. ## Windows {#windows} -1. Make sure `git` is installed on your system. +1. Make sure `git` is installed. 1. Download `krew.exe` from the [Releases][releases] page to a directory. -1. Launch a command-line window (`cmd.exe`) with elevated privileges (since the installation requires use of symbolic links) and navigate to that directory. +1. Launch a command prompt (`cmd.exe`) with administrator privileges (since the installation requires use of symbolic links) and navigate to that directory. 1. Run the following command to install krew: ```sh krew install krew ``` -1. Add `%USERPROFILE%\.krew\bin` directory to your `PATH` environment variable +1. Add the `%USERPROFILE%\.krew\bin` directory to your `PATH` environment variable ([how?](https://java.com/en/download/help/path.xml)) 1. Launch a new command-line window. -1. Verify running `kubectl krew` works. +1. Run `kubectl krew` to check the installation. [releases]: https://github.com/kubernetes-sigs/krew/releases ## Other package managers -You can alternatively install it via some OS-package managers like Homebrew +You can alternatively install Krew via some OS-package managers like Homebrew (macOS). -However, we don't actively support that scenario at the moment. +However, that method is not actively supported at this time. diff --git a/site/content/docs/user-guide/setup/uninstall.md b/site/content/docs/user-guide/setup/uninstall.md index 17d06fa480..da51798a52 100644 --- a/site/content/docs/user-guide/setup/uninstall.md +++ b/site/content/docs/user-guide/setup/uninstall.md @@ -4,13 +4,13 @@ slug: uninstall weight: 200 --- -To remove Krew and plugins installed altogether, run this on your Linux/macOS machine: +To remove Krew and its associated plugins altogether, run this command on your Linux or macOS machine: ```sh {{}}rm -rf -- ~/.krew ``` -On Windows, remove directory: `%USERPROFILE%\.krew`. +On Windows, remove the `%USERPROFILE%\.krew` directory. > **Note:** If you installed Krew with another package manager (e.g. Homebrew), -> follow their installations in addition to instructions above. +> follow their instructions for uninstalling in addition to the instructions above. diff --git a/site/content/docs/user-guide/setup/updates.md b/site/content/docs/user-guide/setup/updates.md index 8151da884e..deeb71893a 100644 --- a/site/content/docs/user-guide/setup/updates.md +++ b/site/content/docs/user-guide/setup/updates.md @@ -4,14 +4,14 @@ slug: update weight: 300 --- -Krew will occasionally check if a new version is available to remind you to +Krew will occasionally check if a new version is available and remind you to upgrade to a newer version. -This is done by calling the GitHub API, and we do not collect any data from your -machine during this process. +This is done by calling the GitHub API, and the process does not collect any data from your +machine. If you want to disable the update checks, set the `KREW_NO_UPGRADE_CHECK` -environment variable. To permanently disable this, add the following to your +environment variable. To permanently disable this feature, add the following to your `~/.bashrc`, `~/.bash_profile`, or `~/.zshrc`: ```shell diff --git a/site/content/docs/user-guide/upgrade.md b/site/content/docs/user-guide/upgrade.md index ab6c1be44f..56bd895988 100644 --- a/site/content/docs/user-guide/upgrade.md +++ b/site/content/docs/user-guide/upgrade.md @@ -4,9 +4,7 @@ slug: upgrading-plugins weight: 600 --- -Plugins you are using might have newer versions available. - -If you want to upgrade all plugins to their latest versions, run: +To upgrade all plugins that you have installed to their latest versions, run: ```sh {{}}kubectl krew upgrade @@ -15,7 +13,7 @@ If you want to upgrade all plugins to their latest versions, run: Since Krew itself is a plugin also managed through Krew, running the upgrade command will also upgrade your `krew` setup to the latest version. -To upgrade only some plugins, you can explicitly specify their name: +To upgrade only certain plugins, you can explicitly specify their names: ```sh {{}}kubectl krew upgrade diff --git a/site/content/docs/user-guide/using-custom-indexes.md b/site/content/docs/user-guide/using-custom-indexes.md index 5e6203c107..b2eb48075e 100644 --- a/site/content/docs/user-guide/using-custom-indexes.md +++ b/site/content/docs/user-guide/using-custom-indexes.md @@ -4,7 +4,7 @@ slug: custom-indexes weight: 800 --- -Plugin indexes contain plugin manifests, which are documents that describe +Plugin indexes contain plugin manifests, which are documents that describe the installation procedure for a plugin. For discovery purposes, Krew comes with a `default` plugin index, plugins hosted in the [`krew-index` repository][ki]. @@ -25,7 +25,7 @@ The URI you use can be any [git remote](https://git-scm.com/docs/git-remote) ## Removing a custom index You can remove a custom plugin index by passing the name it was added with to -the remove command: +the `index remove` command: ```sh {{}}kubectl krew index remove foo @@ -33,7 +33,7 @@ the remove command: ## Listing indexes -To see what indexes you have added run the list command: +To see what indexes you have added run the `index list` command: ```sh {{}}kubectl krew index list @@ -78,18 +78,17 @@ Similarly: ``` -> **Caveat:** If two indexes offer a plugin with the same name, only one can +> **Note:** If two indexes each include a plugin with the same name, only one can > be installed at any time. ## The default index -When a plugin doesn't have an explicit `INDEX_NAME` prefix, it refers to a plugin -from the `default` index. These plugins have an implicit `default/` prepended to -them in Krew commands. The `INDEX_NAME` prefix is used to differentiate plugins -with the same name across different indexes. +When you don't include an explicit `INDEX_NAME` prefix in your Krew command, the +command will refer to a plugin from the default index. The `INDEX_NAME` prefix is +used to differentiate plugins with the same name across different indexes. Krew ships with [`krew-index`][ki] as the `default` index, but this can be -removed using the `kubectl krew index remove default` command. Once this is +removed using the `kubectl krew index remove default` command. Once it is removed, you can add another index with the name `default` and plugins from it will not require the `INDEX_NAME` prefix in commands.