docs: update README.md

jakuboskera · May 3, 2022 · abed0b4 · abed0b4
1 parent 4cfae02
commit abed0b4
Showing 1 changed file with 245 additions and 72 deletions.
diff --git a/README.md b/README.md
@@ -1,101 +1,264 @@
-# `kubectx` with support of `tkgi login`
+# `kubectx` with support of tkgi login
 
 This repository is fork of [ahmetb/kubectx](https://github.com/ahmetb/kubectx).
 
-There is added funcionallity of `tkgi login` for TKGI clusters.
+There is added funcionallity of tkgi login for TKGI clusters.
 So before switching to target context, tkgi login is done first.
 
-## Purpose of `tkgi-kubectx` ?
+## 📖 TOC
+- [`kubectx` with support of tkgi login](#kubectx-with-support-of-tkgi-login)
+  - [📖 TOC](#-toc)
+  - [🤔 Purpose of `tkgi-kubectx` ?](#-purpose-of-tkgi-kubectx-)
+  - [🚀 Usage](#-usage)
+    - [⚠️ Prerequisities](#️-prerequisities)
+      - [Check if Kubernetes context exists in kubeconfig](#check-if-kubernetes-context-exists-in-kubeconfig)
+      - [Installed tkgi CLI binary](#installed-tkgi-cli-binary)
+    - [Create configuration files for `tkgi-kubectx`](#create-configuration-files-for-tkgi-kubectx)
+      - [`~/.kube/tkgi-kubectx/config.yaml`](#kubetkgi-kubectxconfigyaml)
+      - [`~/.kube/tkgi-kubectx/credentials.yaml`](#kubetkgi-kubectxcredentialsyaml)
+    - [Test functionality](#test-functionality)
+  - [🎉 Example](#-example)
+  - [🛠 Installation](#-installation)
+    - [Homebrew (macOS and Linux)](#homebrew-macos-and-linux)
+    - [Scoop (Windows)](#scoop-windows)
+    - [From release](#from-release)
+  - [ℹ️ Tips](#ℹ️-tips)
+    - [macOS or Linux](#macos-or-linux)
+    - [Windows](#windows)
+
+## 🤔 Purpose of `tkgi-kubectx` ?
 
 Original **kubectx** can just switch between contexts (clusters). But if user
 works with TKGI clusters, he needs to first login to destination cluster before
 switching a context.
 
-From that reason, funcionallity of `tkgi login` was added to **kubectx** and was it
+From that reason, funcionallity of tkgi login was added to **kubectx** and was it
 named as **tkgi-kubectx**.
 
 It works almost the same as original **kubectx**. So you can utilize all the features
 what original **kubectx** has, see more in original repository
 [ahmetb/kubectx](https://github.com/ahmetb/kubectx).
 
-## How to use a `tkgi-kubectx`
+## 🚀 Usage
 
-Usage `tkgi-kubectx` is really almost the same as original `kubectx`.
-Hovewer if you create files `~/.kube/tkgi-kubectx/config.yaml` and `~/.kube/tkgi-kubectx/credentials.yaml`,
-`tkgi-kubectx` will start using login feature automatically.
+### ⚠️ Prerequisities
 
-### Prerequisities
+1. Created a Kubernetes context in your kubeconfig for a which tkgi login will be performed
+1. Installed `tkgi` CLI binary
 
-1. installed [tkgi](https://docs.pivotal.io/tkgi/1-13/installing-cli.html)
-1. created a file `~/.kube/tkgi-kubectx/config.yaml` - contains clusters name, TGKI API URL for that cluster and username
-1. created a file `~/.kube/tkgi-kubectx/credentials.yaml` - contains username, password and flag if user is cluster admin or not
+#### Check if Kubernetes context exists in kubeconfig
 
-#### Create config and credentials files
+To utilize kubectx with tkgi login feature you need to have already
+created Kubernetes context in your kubeconfig for given cluster.
 
-1. Create a folder `tkgi-kubectx` in `~/.kube`
+You can check if you have a context already created by
 
-    ```bash
-    mkdir -p ~/.kube/tkgi-kubectx
-    ```
+```bash
+kubectl config get-contexts
+```
+
+If in the output of previous command is not listed a context for given
+cluster, you have to do a manual login to the cluster first to create the
+context in your kubeconfig.
 
-1. Create a file `~/.kube/tkgi-kubectx/config.yaml`
+If in the output is listed a context for given cluster, you are ok
+and you can skip to next [section](#installed-tkgi-cli-binary).
+
+There are two types of manual logins to TKGI clusters:
+
+1. **cluster admin login** - if you are cluster admin
 
     ```bash
-    touch ~/.kube/tkgi-kubectx/config.yaml
+    tkgi login -a <TKGI API> -u <username> -k # -k if cert is self-signed
     ```
 
-1. Add content to the file
-
-    ```yaml
-    # ~/.kube/tkgi-kubectx/config.yaml
-
-    clusters:
-      # name of the cluster for a which tkgi login will be performed, the name is
-      # usually same as name of the context
-    - name: <cluster1>
-      # this username must be in ~/.kube/tkgi-kubectx/credentials.yaml
-      creds: <username>
-      # TKGI API URL where you normally login
-      tkgiApi: https://<tkgi api url>
-      # add how many clusters you want, the schema is same as for first cluster
-    - name: <clusterN>
-      creds: <username>
-      tkgiApi: https://<tkgi api url>
-    ...
+    ```bash
+    tkgi get-credentials <cluster>
     ```
 
-1. Create a file `~/.kube/tkgi-kubectx/credentials.yaml`
+1. **non cluster admin login**  if you are not cluster admin
 
     ```bash
-    touch ~/.kube/tkgi-kubectx/credentials.yaml
+    tkgi get-kubeconfig <cluster> -a <TKGI API> -u <username> -k # -k if cert is self-signed
     ```
 
-1. Add content to the file
-
-    ```yaml
-    # ~/.kube/tkgi-kubectx/credentials.yaml
-
-    credentials:
-      # username specified in ~/.kube/tkgi-kubectx/config.yaml
-    - username: <username>
-      # plaintext password for <username>
-      password: <password>
-      # either true or false, because login commands are different
-      # if user is cluster admin or not
-      clusterAdmin: true
-      # add how many users you want, the schema is same as for first username
-    - username: <another username>
-      password: <password>
-      clusterAdmin: false
-    ...
-    ```
+#### Installed tkgi CLI binary
+
+Because `tkgi-kubectx` uses tkgi CLI binary under the hood, you have to have
+installed tkgi CLI binary.
+
+You can check it by:
+
+```bash
+tkgi --version
+```
+
+If you don't have installed tkgi CLI binary, you can install from [HERE](https://docs.pivotal.io/tkgi/1-13/installing-cli.html).
+
+### Create configuration files for `tkgi-kubectx`
+
+If you met the listed prerequisities above, you can now configure `tkgi-kubectx`.
+
+`tkgi-kubectx` needs for its function two files, these files must be created in specified location:
+
+1. `~/.kube/tkgi-kubectx/config.yaml`
+1. `~/.kube/tkgi-kubectx/credentials.yaml`
+
+#### `~/.kube/tkgi-kubectx/config.yaml`
+
+This file contains Kubernetes contexts, TKGI API and credentials reference.
+
+```yaml
+# ~/.kube/tkgi-kubectx/config.yaml
+
+# contains list of clusters
+clusters:
+  # name of the cluster for a which tkgi login will be performed, the name is
+  # usually same as name of the context
+- name: <cluster1>
+  # reference to username from ~/.kube/tkgi-kubectx/credentials.yaml
+  creds: <username>
+  # TKGI API URL for given cluster
+  tkgiApi: https://<TKGI API>
+- name: <clusterN>
+  creds: <username>
+  tkgiApi: https://<TKGI API>
+...
+```
+
+#### `~/.kube/tkgi-kubectx/credentials.yaml`
+
+This file contains list of credentials which are then used for login.
+
+⚠️ Password is stored as plaintext, for this reason configuration was
+split into two files.
+
+```yaml
+# ~/.kube/tkgi-kubectx/credentials.yaml
+
+# contains list of credentials
+credentials:
+  # username specified in ~/.kube/tkgi-kubectx/config.yaml
+- username: <username>
+  # plaintext password for <username>
+  password: <password>
+  # either true or false, because login commands are different
+  # if user is cluster admin or not
+  clusterAdmin: true
+  # add how many users you want, the schema is same as for first username
+- username: <another username>
+  password: <password>
+  clusterAdmin: false
+...
+```
+
+### Test functionality
+
+Now you should have everything configured and tkgi login will be performed
+everytime before switching to context if this context is in `config.yaml`.
+
+See example usage below.
+
+## 🎉 Example
+
+Let's say we have three clusters:
+
+1. prod-cluster,
+1. test-cluster,
+1. dev-cluster.
+
+For prod-cluster and test-cluster we need to perform tkgi login everytime
+before switching to one of that contexts. For dev-cluster we don't need a tkgi login.
+For prod-cluster and test-cluster we will use different credentials.
+
+Check if we have these contexts in our kubeconfig.
+
+```bash
+$ kubectl config get-contexts
+dev-cluster
+prod-cluster
+test-cluster
+```
+
+Check if we have installed tkgi CLI binary
+
+```bash
+$ tkgi --version
 
-1. From now on everytime you switch context to different context and that context is configured
-   in  `~/.kube/tkgi-kubectx/config.yaml`, it will first login to target context (cluster).
-   Also when target context is using same TKGI API URI as previous contecxt, login is skipped,
-   as it is not needed and it is faster way to switch.
+TKGI CLI version: 1.13.0-build.212
+```
+
+In our `credentials.yaml` we have specified two credentials:
+
+```yaml
+# ~/.kube/tkgi-kubectx/credentials.yaml
+
+credentials:
+- username: lhofstadter
+  password: ILoveSheldon
+  clusterAdmin: true
+- username: rkoothrappali
+  password: iDontSpeakToGirls
+  clusterAdmin: false
+```
+
+In our `config.yaml` we have specified two clusters and for each cluster
+different credentials:
+
+```yaml
+# ~/.kube/tkgi-kubectx/config.yaml
+
+clusters:
+- name: prod-cluster
+  creds: lhofstadter
+  tkgiApi: https://prod-tkgi.example.com
+- name: test-cluster
+  creds: rkoothrappali
+  tkgiApi: https://test-tkgi.example.com
+```
+
+Switch to prod-cluster
+
+```bash
+$ tkgi-kubectx prod-cluster
+Login first before switching context to "prod-cluster"...
+
+API Endpoint: https://prod-tkgi.example.com
+User: lhofstadter
+Login successful.
+
+
+Fetching credentials for cluster prod-cluster.
+PKS_USER_PASSWORD is set. Reading password from PKS_USER_PASSWORD
+Context set for cluster prod-cluster.
+
+You can now switch between clusters by using:
+$kubectl config use-context <cluster-name>
+
+✔ Switched to context "prod-cluster".
+```
+
+Switch to test-cluster
+
+```bash
+$ tkgi-kubectx test-cluster
+Login first before switching context to "test-cluster"...
+
+Fetching kubeconfig for cluster test-cluster and user rkoothrappali.
+You can now use the kubeconfig for user rkoothrappali:
+$kubectl config use-context test-cluster
+
+✔ Switched to context "test-cluster".
+```
+
+Switch to dev-cluster
 
-## Installation
+```bash
+$ tkgi-kubectx dev-cluster
+✔ Switched to context "dev-cluster".
+```
+
+## 🛠 Installation
 
 ### Homebrew (macOS and Linux)
 
@@ -122,18 +285,28 @@ If you don't use any package managers mentioned above, you can install `tkgi-kub
 1. Untar or unzip the file
 1. Move binary `tkgi-kubectx` to your `PATH`
 
-## Tips
+## ℹ️ Tips
 
-Name `tkgi-kubectx` is relatively long name for a command so you can create an alias for it
+Name `tkgi-kubectx` is relatively long for a command so you can create an alias for it
 
-### MacOS or Linux
+### macOS or Linux
 
-```bash
-echo "alias kx=tkgi-kubectx" >> ~/.bashrc # or ~/.zshrc if you use ZSH
-```
+1. bash
+
+    ```bash
+    echo "alias kx=tkgi-kubectx" >> ~/.bashrc
+    ```
+
+1. zsh
+
+    ```bash
+    echo "alias kx=tkgi-kubectx" >> ~/.zshrc
+    ```
 
 ### Windows
 
-```pwsh
-Set-Alias -Name kx -Value tkgi-kubectx
-```
+1. PowerShell
+
+    ```pwsh
+    Set-Alias -Name kx -Value tkgi-kubectx
+    ```