Adapt docs for kubectl completion on macOS (#14636)

content/en/docs/tasks/tools/install-kubectl.md

@@ -355,50 +355,63 @@ Both approaches are equivalent. After reloading your shell, kubectl autocompleti
 
 {{% tab name="Bash on macOS" %}}
 
-{{< warning>}}
-macOS includes Bash 3.2 by default. The kubectl completion script requires Bash 4.1+ and doesn't work with Bash 3.2. A possible way around this is to install a newer version of Bash on macOS (see instructions [here](https://itnext.io/upgrading-bash-on-macos-7138bd1066ba)). The below instructions only work if you are using Bash 4.1+.
-{{< /warning >}}
 
 ### Introduction
 
-The kubectl completion script for Bash can be generated with the command `kubectl completion bash`. Sourcing the completion script in your shell enables kubectl autocompletion.
+The kubectl completion script for Bash can be generated with `kubectl completion bash`. Sourcing this script in your shell enables kubectl completion.
+
+However, the kubectl completion script depends on [**bash-completion**](https://github.com/scop/bash-completion) which you thus have to previously install.
+
+{{< warning>}}
+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 kubectl 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 kubectl 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).
+{{< /warning >}}
 
-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
 
-You can install bash-completion with Homebrew:
+{{< note >}}
+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).
+{{< /note >}}
+
+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
+brew install bash-completion@2
 ```
 
-As stated in the output of `brew install` ("Caveats" section), add the following lines to your `~/.bashrc` or `~/.bash_profile` file:
+As stated in the output of this command, add the following to your `~/.bashrc` file:
 
 ```shell
-[ -f /usr/local/etc/bash_completion ] && . /usr/local/etc/bash_completion
+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.
+Reload your shell and verify that bash-completion v2 is correctly installed with `type _init_completion`.
 
 ### Enable kubectl autocompletion
 
-If you installed kubectl with Homebrew (as explained [here](#install-with-homebrew-on-macos)), then the completion script was automatically installed to `/usr/local/etc/bash_completion.d/kubectl`. In that case, you don't need to do anything.
+You now have to ensure that the kubectl completion script gets sourced in all your shell sessions. There are multiple ways to achieve this:
 
-If you didn't install through Homebrew you now need to ensure that the kubectl completion script gets sourced in all your shell sessions as follows:
+- Source the completion script in your `~/.bashrc` file:
 
-- Add the completion script to `/usr/local/etc/bash_completion.d`:
+    ```shell
+    echo 'source <(kubectl completion bash)' >>~/.bashrc
+
+    ```
+
+- Add the completion script to the `/usr/local/etc/bash_completion.d` directory:
 
     ```shell
     kubectl completion bash >/usr/local/etc/bash_completion.d/kubectl
     ```
 
+- If you installed kubectl with Homebrew (as explained [above](#install-with-homebrew-on-macos)), then the kubectl completion script should already be in `/usr/local/etc/bash_completion.d/kubectl`. In that case, you don't need to do anything.
 
 {{< note >}}
-bash-completion (if installed with Homebrew) sources all the completion scripts in the directory.
+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.
 {{< /note >}}
 
-After reloading your shell, kubectl autocompletion should be working.
+In any case, after reloading your shell, kubectl completion should be working.
 {{% /tab %}}
 
 {{% tab name="Zsh" %}}