stow/oh-my-zsh/.oh-my-zsh/plugins/kube-ps1/README.md

   1 kube-ps1: Kubernetes prompt for bash and zsh
   2 ============================================
   3
   4 A script that lets you add the current Kubernetes context and namespace
   5 configured on `kubectl` to your Bash/Zsh prompt strings (i.e. the `$PS1`).
   6
   7 Inspired by several tools used to simplify usage of `kubectl`.
   8
   9 ## Installing
  10
  11 ### MacOS
  12
  13 Homebrew package manager:
  14
  15 ```
  16 $ brew update
  17 $ brew install kube-ps1
  18 ```
  19 ### From Source
  20
  21 1. Clone this repository
  22 2. Source the kube-ps1.sh in your `~/.zshrc` or your `~/.bashrc`
  23
  24 ### Arch Linux
  25 AUR Package available at [https://aur.archlinux.org/packages/kube-ps1/](https://aur.archlinux.org/packages/kube-ps1/).
  26
  27 #### Zsh
  28 ```sh
  29 source /path/to/kube-ps1.sh
  30 PROMPT='$(kube_ps1)'$PROMPT
  31 ```
  32 #### Bash
  33 ```sh
  34 source /path/to/kube-ps1.sh
  35 PS1='[\u@\h \W $(kube_ps1)]\$ '
  36 ```
  37
  38 ### Zsh Plugin Managers
  39
  40 #### Using [zplugin](https://github.com/zdharma/zplugin)
  41
  42 Update `.zshrc` with:
  43 ```sh
  44 zplugin light jonmosco/kube-ps1
  45 PROMPT='$(kube_ps1)'$PROMPT
  46 ```
  47
  48 ## Requirements
  49
  50 The default prompt assumes you have the `kubectl` command line utility installed.
  51 Official installation instructions and binaries are available:
  52
  53 [Install and Set up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
  54
  55 If using this with OpenShift, the `oc` tool needs installed.  It can be obtained
  56 from brew ports:
  57
  58 ```
  59 brew install openshift-cli
  60 ```
  61 or the source can be downloaded:
  62
  63 [OC Client Tools](https://www.openshift.org/download.html)
  64
  65 Set the binary to `oc` with the following environment variable:
  66
  67 ```
  68 KUBE_PS1_BINARY=oc
  69 ```
  70
  71 If neither binary is available, the prompt will print the following:
  72
  73 ```
  74 (<symbol>|BINARY-N/A:N/A)
  75 ```
  76
  77 ## Helper utilities
  78
  79 There are several great tools that make using kubectl very enjoyable:
  80
  81 - [`kubectx` and `kubens`](https://github.com/ahmetb/kubectx) are great for
  82 fast switching between clusters and namespaces.
  83
  84 ## Tmux port
  85
  86 I have begun porting kube-ps1 to tmux as a status line plugin.  If you prefer
  87 tmux, and like the functionality provided by kube-ps1, checkout the
  88 [kube-tmux](https://github.com/jonmosco/kube-tmux) project
  89
  90 ## Prompt Structure
  91
  92 The default prompt layout is:
  93
  94 ```
  95 (<symbol>|<context>:<namespace>)
  96 ```
  97
  98 If the current-context is not set, kube-ps1 will return the following:
  99
 100 ```
 101 (<symbol>|N/A:N/A)
 102 ```
 103
 104 ## Enabling/Disabling
 105
 106 If you want to stop showing Kubernetes status on your prompt string temporarily
 107 run `kubeoff`. To disable the prompt for all shell sessions, run `kubeoff -g`.
 108 You can enable it again in the current shell by running `kubeon`, and globally
 109 with `kubeon -g`.
 110
 111 ```
 112 kubeon     : turn on kube-ps1 status for this shell.  Takes precedence over
 113              global setting for current session
 114 kubeon -g  : turn on kube-ps1 status globally
 115 kubeoff    : turn off kube-ps1 status for this shell. Takes precedence over
 116              global setting for current session
 117 kubeoff -g : turn off kube-ps1 status globally
 118 ```
 119
 120 ## Customization
 121
 122 The default settings can be overridden in `~/.bashrc` or `~/.zshrc` by setting
 123 the following environment variables:
 124
 125 | Variable | Default | Meaning |
 126 | :------- | :-----: | ------- |
 127 | `KUBE_PS1_BINARY` | `kubectl` | Default Kubernetes binary |
 128 | `KUBE_PS1_NS_ENABLE` | `true` | Display the namespace. If set to `false`, this will also disable `KUBE_PS1_DIVIDER` |
 129 | `KUBE_PS1_PREFIX` | `(` | Prompt opening character  |
 130 | `KUBE_PS1_SYMBOL_ENABLE` | `true ` | Display the prompt Symbol. If set to `false`, this will also disable `KUBE_PS1_SEPARATOR` |
 131 | `KUBE_PS1_SYMBOL_PADDING` | `false` | Adds a space (padding) after the symbol to prevent clobbering prompt characters |
 132 | `KUBE_PS1_SYMBOL_DEFAULT` | `⎈ ` | Default prompt symbol. Unicode `\u2388` |
 133 | `KUBE_PS1_SYMBOL_USE_IMG` | `false` | ☸️  ,  Unicode `\u2638` as the prompt symbol |
 134 | `KUBE_PS1_SEPARATOR` | &#124; | Separator between symbol and context name |
 135 | `KUBE_PS1_DIVIDER` | `:` | Separator between context and namespace |
 136 | `KUBE_PS1_SUFFIX` | `)` | Prompt closing character |
 137 | `KUBE_PS1_CLUSTER_FUNCTION` | No default, must be user supplied | Function to customize how cluster is displayed |
 138 | `KUBE_PS1_NAMESPACE_FUNCTION` | No default, must be user supplied | Function to customize how namespace is displayed |
 139
 140 For terminals that do not support UTF-8, the symbol will be replaced with the
 141 string `k8s`.
 142
 143 To disable a feature, set it to an empty string:
 144
 145 ```
 146 KUBE_PS1_SEPARATOR=''
 147 ```
 148
 149 ## Colors
 150
 151 The default colors are set with the following environment variables:
 152
 153 | Variable | Default | Meaning |
 154 | :------- | :-----: | ------- |
 155 | `KUBE_PS1_PREFIX_COLOR` | `null` | Set default color of the prompt prefix |
 156 | `KUBE_PS1_SYMBOL_COLOR` | `blue` | Set default color of the Kubernetes symbol |
 157 | `KUBE_PS1_CTX_COLOR` | `red` | Set default color of the context |
 158 | `KUBE_PS1_SUFFIX_COLOR` | `null` | Set default color of the prompt suffix |
 159 | `KUBE_PS1_NS_COLOR` | `cyan` | Set default color of the namespace |
 160 | `KUBE_PS1_BG_COLOR` | `null` | Set default color of the prompt background |
 161
 162 Blue was used for the default symbol to match the Kubernetes color as closely
 163 as possible. Red was chosen as the context name to stand out, and cyan for the
 164 namespace.
 165
 166 Set the variable to an empty string if you do not want color for each
 167 prompt section:
 168
 169 ```
 170 KUBE_PS1_CTX_COLOR=''
 171 ```
 172
 173 Names are usable for the following colors:
 174
 175 ```
 176 black, red, green, yellow, blue, magenta, cyan
 177 ```
 178
 179 256 colors are available by specifying the numerical value as the variable
 180 argument.
 181
 182 ## Customize display of cluster name and namespace
 183
 184 You can change how the cluster name and namespace are displayed using the
 185 `KUBE_PS1_CLUSTER_FUNCTION` and `KUBE_PS1_NAMESPACE_FUNCTION` variables
 186 respectively.
 187
 188 For the following examples let's assume the following:
 189
 190 cluster name: `sandbox.k8s.example.com`
 191 namespace: `alpha`
 192
 193 If you're using domain style cluster names, your prompt will get quite long
 194 very quickly. Let's say you only want to display the first portion of the
 195 cluster name (`sandbox`), you could do that by adding the following:
 196
 197 ```sh
 198 function get_cluster_short() {
 199   echo "$1" | cut -d . -f1
 200 }
 201
 202 KUBE_PS1_CLUSTER_FUNCTION=get_cluster_short
 203 ```
 204
 205 The same pattern can be followed to customize the display of the namespace.
 206 Let's say you would prefer the namespace to be displayed in all uppercase
 207 (`ALPHA`), here's one way you could do that:
 208
 209 ```sh
 210 function get_namespace_upper() {
 211     echo "$1" | tr '[:lower:]' '[:upper:]'
 212 }
 213
 214 export KUBE_PS1_NAMESPACE_FUNCTION=get_namespace_upper
 215 ```
 216
 217 In both cases, the variable is set to the name of the function, and you must have defined the function in your shell configuration before kube_ps1 is called. The function must accept a single parameter and echo out the final value.
 218
 219 ### Bug Reports and shell configuration
 220
 221 Due to the vast ways of customizing the shell, please try the prompt with a
 222 minimal configuration before submitting a bug report.
 223
 224 This can be done as follows for each shell before loading kube-ps1:
 225
 226 Bash:
 227 ```bash
 228 bash --norc
 229 ```
 230
 231 Zsh:
 232 ```bash
 233 zsh -f
 234 or
 235 zsh --no-rcs
 236 ```
 237
 238 ## Contributors
 239
 240 * [Ahmet Alp Balkan](https://github.com/ahmetb)
 241 * Jared Yanovich