mirror of
https://github.com/vmware-tanzu/velero.git
synced 2026-01-09 06:33:22 +00:00
[GH-1505] add documentation regarding autocompletion for velero CLI (#2208)
* add documentation regarding autocompletion for velero CLI Signed-off-by: Carlos Panato <ctadeu@gmail.com>
This commit is contained in:
Carlos Tadeu Panato Junior
committed by
Carlisia Campos
Carlisia Campos
parent
fc3ec9ff2c
commit
82d6ad4ae3
@@ -51,8 +51,13 @@ Velero uses storage provider plugins to integrate with a variety of storage syst
|
||||
|
||||
_Note: if your object storage provider is different than your volume snapshot provider, follow the installation instructions for your object storage provider first, then return here and follow the instructions to [add your volume snapshot provider][4]._
|
||||
|
||||
## Command line Autocompletion
|
||||
|
||||
Please refer to [this part of the documentation][5].
|
||||
|
||||
[0]: supported-providers.md
|
||||
[1]: https://github.com/vmware-tanzu/velero/releases/latest
|
||||
[2]: on-premises.md
|
||||
[3]: overview-plugins.md
|
||||
[4]: customize-installation.md#install-an-additional-volume-snapshot-provider
|
||||
[5]: customize-installation.md#optional-velero-cli-configurations
|
||||
|
||||
@@ -11,6 +11,7 @@
|
||||
- [Install an additional volume snapshot provider](#install-an-additional-volume-snapshot-provider)
|
||||
- [Generate YAML only](#generate-yaml-only)
|
||||
- [Additional options](#additional-options)
|
||||
- [Optional Velero CLI configurations](#optional-velero-cli-configurations)
|
||||
|
||||
## Plugins
|
||||
|
||||
@@ -30,7 +31,7 @@ If you are using an alternate identity mechanism, such as kube2iam/kiam on AWS,
|
||||
|
||||
By default, `velero install` does not install Velero's [restic integration][3]. To enable it, specify the `--use-restic` flag.
|
||||
|
||||
If you've already run `velero install` without the `--use-restic` flag, you can run the same command again, including the `--use-restic` flag, to add the restic integration to your existing install.
|
||||
If you've already run `velero install` without the `--use-restic` flag, you can run the same command again, including the `--use-restic` flag, to add the restic integration to your existing install.
|
||||
|
||||
## Customize resource requests and limits
|
||||
|
||||
@@ -89,6 +90,148 @@ If you are installing Velero in Kubernetes 1.13.x or earlier, you need to use `k
|
||||
|
||||
Run `velero install --help` or see the [Helm chart documentation](https://github.com/helm/charts/tree/master/stable/velero) for the full set of installation options.
|
||||
|
||||
## Optional Velero CLI configurations
|
||||
|
||||
### Enabling shell autocompletion
|
||||
|
||||
**Velero CLI** provides autocompletion support for `Bash` and `Zsh`, which can save you a lot of typing.
|
||||
|
||||
Below are the procedures to set up autocompletion for `Bash` (including the difference between `Linux` and `macOS`) and `Zsh`.
|
||||
|
||||
## Bash on Linux
|
||||
|
||||
The **Velero CLI** completion script for `Bash` can be generated with the command `velero completion bash`. Sourcing the completion script in your shell enables velero autocompletion.
|
||||
|
||||
However, the completion script depends on [**bash-completion**](https://github.com/scop/bash-completion), which means that you have to install this software first (you can test if you have bash-completion already installed by running `type _init_completion`).
|
||||
|
||||
### Install bash-completion
|
||||
|
||||
`bash-completion` is provided by many package managers (see [here](https://github.com/scop/bash-completion#installation)). You can install it with `apt-get install bash-completion` or `yum install bash-completion`, etc.
|
||||
|
||||
The above commands create `/usr/share/bash-completion/bash_completion`, which is the main script of bash-completion. Depending on your package manager, you have to manually source this file in your `~/.bashrc` file.
|
||||
|
||||
To find out, reload your shell and run `type _init_completion`. If the command succeeds, you're already set, otherwise add the following to your `~/.bashrc` file:
|
||||
|
||||
```shell
|
||||
source /usr/share/bash-completion/bash_completion
|
||||
```
|
||||
|
||||
Reload your shell and verify that bash-completion is correctly installed by typing `type _init_completion`.
|
||||
|
||||
### Enable Velero CLI autocompletion for Bash on Linux
|
||||
|
||||
You now need to ensure that the **Velero CLI** completion script gets sourced in all your shell sessions. There are two ways in which you can do this:
|
||||
|
||||
- Source the completion script in your `~/.bashrc` file:
|
||||
|
||||
```shell
|
||||
echo 'source <(velero completion bash)' >>~/.bashrc
|
||||
```
|
||||
|
||||
- Add the completion script to the `/etc/bash_completion.d` directory:
|
||||
|
||||
```shell
|
||||
velero completion bash >/etc/bash_completion.d/velero
|
||||
```
|
||||
|
||||
- If you have an alias for velero, you can extend shell completion to work with that alias:
|
||||
|
||||
```shell
|
||||
echo 'alias v=velero' >>~/.bashrc
|
||||
echo 'complete -F __start_velero v' >>~/.bashrc
|
||||
```
|
||||
|
||||
> `bash-completion` sources all completion scripts in `/etc/bash_completion.d`.
|
||||
|
||||
Both approaches are equivalent. After reloading your shell, velero autocompletion should be working.
|
||||
|
||||
## Bash on macOS
|
||||
|
||||
The **Velero CLI** completion script for Bash can be generated with `velero completion bash`. Sourcing this script in your shell enables velero completion.
|
||||
|
||||
However, the velero completion script depends on [**bash-completion**](https://github.com/scop/bash-completion) which you thus have to previously install.
|
||||
|
||||
|
||||
> There are two versions of bash-completion, v1 and v2. V1 is for Bash 3.2 (which is the default on macOS), and v2 is for Bash 4.1+. The velero completion script **doesn't work** correctly with bash-completion v1 and Bash 3.2. It requires **bash-completion v2** and **Bash 4.1+**. Thus, to be able to correctly use velero completion on macOS, you have to install and use Bash 4.1+ ([*instructions*](https://itnext.io/upgrading-bash-on-macos-7138bd1066ba)). The following instructions assume that you use Bash 4.1+ (that is, any Bash version of 4.1 or newer).
|
||||
|
||||
|
||||
### Install bash-completion
|
||||
|
||||
> As mentioned, these instructions assume you use Bash 4.1+, which means you will install bash-completion v2 (in contrast to Bash 3.2 and bash-completion v1, in which case kubectl completion won't work).
|
||||
|
||||
You can test if you have bash-completion v2 already installed with `type _init_completion`. If not, you can install it with Homebrew:
|
||||
|
||||
```shell
|
||||
brew install bash-completion@2
|
||||
```
|
||||
|
||||
As stated in the output of this command, add the following to your `~/.bashrc` file:
|
||||
|
||||
```shell
|
||||
export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
|
||||
[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"
|
||||
```
|
||||
|
||||
Reload your shell and verify that bash-completion v2 is correctly installed with `type _init_completion`.
|
||||
|
||||
### Enable Velero CLI autocompletion for Bash on macOS
|
||||
|
||||
You now have to ensure that the velero completion script gets sourced in all your shell sessions. There are multiple ways to achieve this:
|
||||
|
||||
- Source the completion script in your `~/.bashrc` file:
|
||||
|
||||
```shell
|
||||
echo 'source <(velero completion bash)' >>~/.bashrc
|
||||
|
||||
```
|
||||
|
||||
- Add the completion script to the `/usr/local/etc/bash_completion.d` directory:
|
||||
|
||||
```shell
|
||||
velero completion bash >/usr/local/etc/bash_completion.d/velero
|
||||
```
|
||||
|
||||
- If you have an alias for velero, you can extend shell completion to work with that alias:
|
||||
|
||||
```shell
|
||||
echo 'alias v=velero' >>~/.bashrc
|
||||
echo 'complete -F __start_velero v' >>~/.bashrc
|
||||
```
|
||||
|
||||
- If you installed velero with Homebrew (as explained [above](#install-with-homebrew-on-macos)), then the velero completion script should already be in `/usr/local/etc/bash_completion.d/velero`. In that case, you don't need to do anything.
|
||||
|
||||
> The Homebrew installation of bash-completion v2 sources all the files in the `BASH_COMPLETION_COMPAT_DIR` directory, that's why the latter two methods work.
|
||||
|
||||
In any case, after reloading your shell, velero completion should be working.
|
||||
|
||||
|
||||
## Autocompletion on Zsh
|
||||
|
||||
The velero completion script for Zsh can be generated with the command `velero completion zsh`. Sourcing the completion script in your shell enables velero autocompletion.
|
||||
|
||||
To do so in all your shell sessions, add the following to your `~/.zshrc` file:
|
||||
|
||||
```shell
|
||||
source <(velero completion zsh)
|
||||
```
|
||||
|
||||
If you have an alias for kubectl, you can extend shell completion to work with that alias:
|
||||
|
||||
```shell
|
||||
echo 'alias v=velero' >>~/.zshrc
|
||||
echo 'complete -F __start_velero v' >>~/.zshrc
|
||||
```
|
||||
|
||||
After reloading your shell, kubectl autocompletion should be working.
|
||||
|
||||
If you get an error like `complete:13: command not found: compdef`, then add the following to the beginning of your `~/.zshrc` file:
|
||||
|
||||
```shell
|
||||
autoload -Uz compinit
|
||||
compinit
|
||||
```
|
||||
|
||||
|
||||
[1]: https://github.com/vmware-tanzu/velero/releases/latest
|
||||
[2]: namespace.md
|
||||
[3]: restic.md
|
||||
|
||||
@@ -51,8 +51,13 @@ Velero uses storage provider plugins to integrate with a variety of storage syst
|
||||
|
||||
_Note: if your object storage provider is different than your volume snapshot provider, follow the installation instructions for your object storage provider first, then return here and follow the instructions to [add your volume snapshot provider][4]._
|
||||
|
||||
## Command line Autocompletion
|
||||
|
||||
Please refer to [this part of the documentation][5].
|
||||
|
||||
[0]: supported-providers.md
|
||||
[1]: https://github.com/vmware-tanzu/velero/releases/latest
|
||||
[2]: on-premises.md
|
||||
[3]: overview-plugins.md
|
||||
[4]: customize-installation.md#install-an-additional-volume-snapshot-provider
|
||||
[5]: customize-installation.md#optional-velero-cli-configurations
|
||||
|
||||
@@ -11,6 +11,8 @@
|
||||
- [Install an additional volume snapshot provider](#install-an-additional-volume-snapshot-provider)
|
||||
- [Generate YAML only](#generate-yaml-only)
|
||||
- [Additional options](#additional-options)
|
||||
- [Optional Velero CLI configurations](#optional-velero-cli-configurations)
|
||||
|
||||
|
||||
## Plugins
|
||||
|
||||
@@ -89,6 +91,147 @@ If you are installing Velero in Kubernetes 1.13.x or earlier, you need to use `k
|
||||
|
||||
Run `velero install --help` or see the [Helm chart documentation](https://github.com/helm/charts/tree/master/stable/velero) for the full set of installation options.
|
||||
|
||||
## Optional Velero CLI configurations
|
||||
|
||||
### Enabling shell autocompletion
|
||||
|
||||
**Velero CLI** provides autocompletion support for `Bash` and `Zsh`, which can save you a lot of typing.
|
||||
|
||||
Below are the procedures to set up autocompletion for `Bash` (including the difference between `Linux` and `macOS`) and `Zsh`.
|
||||
|
||||
## Bash on Linux
|
||||
|
||||
The **Velero CLI** completion script for `Bash` can be generated with the command `velero completion bash`. Sourcing the completion script in your shell enables velero autocompletion.
|
||||
|
||||
However, the completion script depends on [**bash-completion**](https://github.com/scop/bash-completion), which means that you have to install this software first (you can test if you have bash-completion already installed by running `type _init_completion`).
|
||||
|
||||
### Install bash-completion
|
||||
|
||||
`bash-completion` is provided by many package managers (see [here](https://github.com/scop/bash-completion#installation)). You can install it with `apt-get install bash-completion` or `yum install bash-completion`, etc.
|
||||
|
||||
The above commands create `/usr/share/bash-completion/bash_completion`, which is the main script of bash-completion. Depending on your package manager, you have to manually source this file in your `~/.bashrc` file.
|
||||
|
||||
To find out, reload your shell and run `type _init_completion`. If the command succeeds, you're already set, otherwise add the following to your `~/.bashrc` file:
|
||||
|
||||
```shell
|
||||
source /usr/share/bash-completion/bash_completion
|
||||
```
|
||||
|
||||
Reload your shell and verify that bash-completion is correctly installed by typing `type _init_completion`.
|
||||
|
||||
### Enable Velero CLI autocompletion for Bash on Linux
|
||||
|
||||
You now need to ensure that the **Velero CLI** completion script gets sourced in all your shell sessions. There are two ways in which you can do this:
|
||||
|
||||
- Source the completion script in your `~/.bashrc` file:
|
||||
|
||||
```shell
|
||||
echo 'source <(velero completion bash)' >>~/.bashrc
|
||||
```
|
||||
|
||||
- Add the completion script to the `/etc/bash_completion.d` directory:
|
||||
|
||||
```shell
|
||||
velero completion bash >/etc/bash_completion.d/velero
|
||||
```
|
||||
|
||||
- If you have an alias for velero, you can extend shell completion to work with that alias:
|
||||
|
||||
```shell
|
||||
echo 'alias v=velero' >>~/.bashrc
|
||||
echo 'complete -F __start_velero v' >>~/.bashrc
|
||||
```
|
||||
|
||||
> `bash-completion` sources all completion scripts in `/etc/bash_completion.d`.
|
||||
|
||||
Both approaches are equivalent. After reloading your shell, velero autocompletion should be working.
|
||||
|
||||
## Bash on macOS
|
||||
|
||||
The **Velero CLI** completion script for Bash can be generated with `velero completion bash`. Sourcing this script in your shell enables velero completion.
|
||||
|
||||
However, the velero completion script depends on [**bash-completion**](https://github.com/scop/bash-completion) which you thus have to previously install.
|
||||
|
||||
|
||||
> There are two versions of bash-completion, v1 and v2. V1 is for Bash 3.2 (which is the default on macOS), and v2 is for Bash 4.1+. The velero completion script **doesn't work** correctly with bash-completion v1 and Bash 3.2. It requires **bash-completion v2** and **Bash 4.1+**. Thus, to be able to correctly use velero completion on macOS, you have to install and use Bash 4.1+ ([*instructions*](https://itnext.io/upgrading-bash-on-macos-7138bd1066ba)). The following instructions assume that you use Bash 4.1+ (that is, any Bash version of 4.1 or newer).
|
||||
|
||||
|
||||
### Install bash-completion
|
||||
|
||||
> As mentioned, these instructions assume you use Bash 4.1+, which means you will install bash-completion v2 (in contrast to Bash 3.2 and bash-completion v1, in which case kubectl completion won't work).
|
||||
|
||||
You can test if you have bash-completion v2 already installed with `type _init_completion`. If not, you can install it with Homebrew:
|
||||
|
||||
```shell
|
||||
brew install bash-completion@2
|
||||
```
|
||||
|
||||
As stated in the output of this command, add the following to your `~/.bashrc` file:
|
||||
|
||||
```shell
|
||||
export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
|
||||
[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"
|
||||
```
|
||||
|
||||
Reload your shell and verify that bash-completion v2 is correctly installed with `type _init_completion`.
|
||||
|
||||
### Enable Velero CLI autocompletion for Bash on macOS
|
||||
|
||||
You now have to ensure that the velero completion script gets sourced in all your shell sessions. There are multiple ways to achieve this:
|
||||
|
||||
- Source the completion script in your `~/.bashrc` file:
|
||||
|
||||
```shell
|
||||
echo 'source <(velero completion bash)' >>~/.bashrc
|
||||
|
||||
```
|
||||
|
||||
- Add the completion script to the `/usr/local/etc/bash_completion.d` directory:
|
||||
|
||||
```shell
|
||||
velero completion bash >/usr/local/etc/bash_completion.d/velero
|
||||
```
|
||||
|
||||
- If you have an alias for velero, you can extend shell completion to work with that alias:
|
||||
|
||||
```shell
|
||||
echo 'alias v=velero' >>~/.bashrc
|
||||
echo 'complete -F __start_velero v' >>~/.bashrc
|
||||
```
|
||||
|
||||
- If you installed velero with Homebrew (as explained [above](#install-with-homebrew-on-macos)), then the velero completion script should already be in `/usr/local/etc/bash_completion.d/velero`. In that case, you don't need to do anything.
|
||||
|
||||
> The Homebrew installation of bash-completion v2 sources all the files in the `BASH_COMPLETION_COMPAT_DIR` directory, that's why the latter two methods work.
|
||||
|
||||
In any case, after reloading your shell, velero completion should be working.
|
||||
|
||||
|
||||
## Autocompletion on Zsh
|
||||
|
||||
The velero completion script for Zsh can be generated with the command `velero completion zsh`. Sourcing the completion script in your shell enables velero autocompletion.
|
||||
|
||||
To do so in all your shell sessions, add the following to your `~/.zshrc` file:
|
||||
|
||||
```shell
|
||||
source <(velero completion zsh)
|
||||
```
|
||||
|
||||
If you have an alias for kubectl, you can extend shell completion to work with that alias:
|
||||
|
||||
```shell
|
||||
echo 'alias v=velero' >>~/.zshrc
|
||||
echo 'complete -F __start_velero v' >>~/.zshrc
|
||||
```
|
||||
|
||||
After reloading your shell, kubectl autocompletion should be working.
|
||||
|
||||
If you get an error like `complete:13: command not found: compdef`, then add the following to the beginning of your `~/.zshrc` file:
|
||||
|
||||
```shell
|
||||
autoload -Uz compinit
|
||||
compinit
|
||||
```
|
||||
|
||||
[0]: supported-providers.md
|
||||
[1]: https://github.com/vmware-tanzu/velero/releases/latest
|
||||
[2]: namespace.md
|
||||
|
||||
Reference in New Issue
Block a user