diff --git a/README.md b/README.md index 4715d071..18f01ee8 100644 --- 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 -u -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: - # this username must be in ~/.kube/tkgi-kubectx/credentials.yaml - creds: - # TKGI API URL where you normally login - tkgiApi: https:// - # add how many clusters you want, the schema is same as for first cluster - - name: - creds: - tkgiApi: https:// - ... + ```bash + tkgi get-credentials ``` -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 -a -u -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: - # plaintext password for - 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: - 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: + # reference to username from ~/.kube/tkgi-kubectx/credentials.yaml + creds: + # TKGI API URL for given cluster + tkgiApi: https:// +- name: + creds: + tkgiApi: https:// +... +``` + +#### `~/.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: + # plaintext password for + 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: + 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 + +✔ 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 -``` \ No newline at end of file +1. PowerShell + + ```pwsh + Set-Alias -Name kx -Value tkgi-kubectx + ```