Update Documentation: include bash-completion@2

[todd-dsm]

The web and kubectl completion -h instructions for Installing and Setting Up kubectl need a slight tuneup. The homebrew instructions should reflect a few different options for Bash on macOS.

1. bash-completion is for Bash 3.2 (macOS default), and
2. bash-completion@2 is for Bash 4.1+ (upgraded GNU Bash)

I lost an hour of my life to this; I hope this helps others.

What happened: By following the homebrew install instructions on this page, then entering kubectl and tabbing, this is the output:

$ kubectl -bash: __ltrim_colon_completions: command not found
-bash: __ltrim_colon_completions: command not found

.gitignore           README.md            conformance-test.sh  ssl/                 
.vagrant/            Vagrantfile          kubeconfig           user-data          

What you expected to happen: By following the same path as above this should be the output:

kubectl 
annotate        certificate     cp              exec            options         rollout         uncordon
api-versions    cluster-info    create          explain         patch           run             version
apply           completion      delete          expose          port-forward    scale           
attach          config          describe        get             proxy           set             
auth            convert         drain           label           replace         taint           
autoscale       cordon          edit            logs            rolling-update  top             

Anything else we need to know: Currently the instructions assume the default Bash on a vanilla macOS install; while I understand this being most-likely scenario, the default version of Bash is shamefully old.

After reviewing to options in homebrew it appears there are 2:

1. bash-completion is for Bash 3.2 and
2. bash-completion@2 is for Bash 4.1+

brew info bash-completion
bash-completion: stable 1.3 (bottled)
Programmable completion for Bash 3.2
https://bash-completion.alioth.debian.org/
Conflicts with: bash-completion@2
Not installed
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/bash-completion.rb
==> Caveats
Add the following lines to your ~/.bash_profile:
  [ -f /usr/local/etc/bash_completion ] && . /usr/local/etc/bash_completion

brew info bash-completion@2
bash-completion@2: stable 2.5 (bottled), HEAD
Programmable completion for Bash 4.1+
https://github.com/scop/bash-completion
Conflicts with: bash-completion
/usr/local/Cellar/bash-completion@2/2.5 (640 files, 897.7KB) *
  Poured from bottle on 2017-04-22 at 13:31:25
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/bash-completion@2.rb
==> Dependencies
Required: bash ✔
==> Caveats
Add the following to your ~/.bash_profile:
  if [ -f /usr/local/share/bash-completion/bash_completion ]; then
    . /usr/local/share/bash-completion/bash_completion
  fi

The Solution

For those of us that cannot live without all the options, this is how we do:

Install:

brew install bash shellcheck dash bash-completion@2 kubectl

Configure Then the ~/.bashrc needs to be updated to reflect this changes:

declare sysBashrc='/etc/bashrc'
if [[ -f "$sysBashrc" ]]; then
    . "$sysBashrc"
fi
...
###############################################################################
###                                   Bash                                  ###
###############################################################################
export SHELL='/usr/local/bin/bash'
export BASH_VERSION="$(bash --version | head -1 | awk -F " " '{print $4}')"
source /usr/local/share/bash-completion/bash_completion
...
###############################################################################
###                                KUBERNETES                               ###
###############################################################################
source <(kubectl completion bash)
...

TEST

1. Open a new tab (the ~/.bashrc is sourced-in)
2. Enter kubectl and tab twice

We then get the expected result.

The requested details follow:

Kubernetes version (use kubectl version):

kubectl version
Client Version: version.Info{Major:"1", Minor:"6", GitVersion:"v1.6.1", GitCommit:"b0b7a323cc5a4a2019b2e9520c21c7830b7f708e", GitTreeState:"clean", BuildDate:"2017-04-03T23:37:53Z", GoVersion:"go1.8", Compiler:"gc", Platform:"darwin/amd64"}
Server Version: version.Info{Major:"1", Minor:"5", GitVersion:"v1.5.4+coreos.0", GitCommit:"97c11b097b1a2b194f1eddca8ce5468fcc83331c", GitTreeState:"clean", BuildDate:"2017-03-08T23:54:21Z", GoVersion:"go1.7.4", Compiler:"gc", Platform:"linux/amd64"}

Environment: personal/dev

• Cloud provider or hardware configuration: NA
• OS (e.g. from /etc/os-release): macOS Sierra
• Kernel (e.g. uname -a): Darwin hostname 16.5.0 Darwin Kernel Version 16.5.0: Fri Mar 3 16:52:33 PST 2017; root:xnu-3789.51.2~3/RELEASE_X86_64 x86_64 i386 MacBookPro11,3 Darwin
• Install tools: homebrew

[cblecker]

So were you running bash 3.2 or bash 4 prior to this? It looks like the instructions are for bash-completion which should be for the bash installed by default in macOS. /assign

[todd-dsm]

I always install the latest Bash, currently 4.4.12(1)-release. Apple's is too old and I'm not going live in their cave; most people won't - that's why homebrew is a huge project.

Correct, the instructions are for the stock version of Bash (presently 3.2.57(1)-release). My suggestion is to include instructions for both versions. Mostly to keep others from wasting the same time.

I've already done the testing so folding in the new details should be pretty straight-forward.

[cblecker]

@todd-dsm: I've opened https://github.com/kubernetes/kubernetes.github.io/pull/3737 to update the kubernetes documentation, and https://github.com/Homebrew/homebrew-core/issues/13552 to potentially update how homebrew works to make this clearer.

[cblecker]

Docs have been updated: https://kubernetes.io/docs/tasks/tools/install-kubectl/ /close