kube-ps1: Kubernetes prompt for bash and zsh

A script that lets you add the current Kubernetes context and namespaceconfigured on kubectl to your Bash/Zsh prompt strings (i.e. the $PS1).

Inspired by several tools used to simplify usage of kubectl.

Installing

MacOS

Homebrew package manager:

$ brew update
$ brew install kube-ps1

From Source

1. Clone this repository
2. Source the kube-ps1.sh in your ~/.zshrc or your ~/.bashrc

Arch Linux

AUR Package available at https://aur.archlinux.org/packages/kube-ps1/.

Zsh

source /path/to/kube-ps1.sh
PROMPT='$(kube_ps1)'$PROMPT

Bash

source /path/to/kube-ps1.sh
PS1='[\u@\h \W $(kube_ps1)]\$ '

Zsh Plugin Managers

Using zplugin

Update .zshrc with:

zplugin light jonmosco/kube-ps1
PROMPT='$(kube_ps1)'$PROMPT

Requirements

The default prompt assumes you have the kubectl command line utility installed.Official installation instructions and binaries are available:

Install and Set up kubectl

If using this with OpenShift, the oc tool needs installed. It can be obtainedfrom brew ports:

brew install openshift-cli

or the source can be downloaded:

OC Client Tools

Set the binary to oc with the following environment variable:

KUBE_PS1_BINARY=oc

If neither binary is available, the prompt will print the following:

(<symbol>|BINARY-N/A:N/A)

Helper utilities

There are several great tools that make using kubectl very enjoyable:

• kubectx and kubens are great forfast switching between clusters and namespaces.

Tmux port

I have begun porting kube-ps1 to tmux as a status line plugin. If you prefertmux, and like the functionality provided by kube-ps1, checkout thekube-tmux project

Prompt Structure

The default prompt layout is:

(<symbol>|<context>:<namespace>)

If the current-context is not set, kube-ps1 will return the following:

(<symbol>|N/A:N/A)

Enabling/Disabling

If you want to stop showing Kubernetes status on your prompt string temporarilyrun kubeoff. To disable the prompt for all shell sessions, run kubeoff -g.You can enable it again in the current shell by running kubeon, and globallywith kubeon -g.

kubeon     : turn on kube-ps1 status for this shell.  Takes precedence over
             global setting for current session
kubeon -g  : turn on kube-ps1 status globally
kubeoff    : turn off kube-ps1 status for this shell. Takes precedence over
             global setting for current session
kubeoff -g : turn off kube-ps1 status globally

Customization

The default settings can be overridden in ~/.bashrc or ~/.zshrc by settingthe following environment variables:

For terminals that do not support UTF-8, the symbol will be replaced with thestring k8s.

To disable a feature, set it to an empty string:

KUBE_PS1_SEPARATOR=''

Colors

The default colors are set with the following environment variables:

Blue was used for the default symbol to match the Kubernetes color as closelyas possible. Red was chosen as the context name to stand out, and cyan for thenamespace.

Set the variable to an empty string if you do not want color for eachprompt section:

KUBE_PS1_CTX_COLOR=''

Names are usable for the following colors:

black, red, green, yellow, blue, magenta, cyan

256 colors are available by specifying the numerical value as the variableargument.

Customize display of cluster name and namespace

You can change how the cluster name and namespace are displayed using theKUBE_PS1_CLUSTER_FUNCTION and KUBE_PS1_NAMESPACE_FUNCTION variablesrespectively.

For the following examples let's assume the following:

cluster name: sandbox.k8s.example.comnamespace: alpha

If you're using domain style cluster names, your prompt will get quite longvery quickly. Let's say you only want to display the first portion of thecluster name (sandbox), you could do that by adding the following:

function get_cluster_short() {
  echo "$1" | cut -d . -f1
}

KUBE_PS1_CLUSTER_FUNCTION=get_cluster_short

The same pattern can be followed to customize the display of the namespace.Let's say you would prefer the namespace to be displayed in all uppercase(ALPHA), here's one way you could do that:

function get_namespace_upper() {
    echo "$1" | tr '[:lower:]' '[:upper:]'
}

export KUBE_PS1_NAMESPACE_FUNCTION=get_namespace_upper

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.

Bug Reports and shell configuration

Due to the vast ways of customizing the shell, please try the prompt with aminimal configuration before submitting a bug report.

This can be done as follows for each shell before loading kube-ps1:

Bash:

bash --norc

Zsh:

zsh -f
or
zsh --no-rcs

Contributors

• Ahmet Alp Balkan
• Jared Yanovich