Install the Credentials Plugin

Install and configure the Konvoy Credentials Plugin.

The Konvoy credentials plugin makes it easy to use external identity providers with kubectl. When using the plugin, kubectl initiates an authentication session in your browser storing identity tokens locally. When a token expires, the plugin starts a new authentication session and refreshes the token.

Before you begin

You need certain software configurations and settings before you start this procedure. This procedure requires the following items and configurations:

  • A running Konvoy cluster

  • The IP address of your running cluster. (This address is represented in this topic as your-cluster-IP and is a placeholder for your cluster IP address. Insert your cluster IP address in these locations.)

NOTE: You can access this plugin, these instructions, and set variables used, at this location: https://your-cluster-IP/ops/landing. Select the Credentials Plugin instructions button.

Configure the Konvoy credentials plugin

The following procedures describe how to configure the Konvoy credentials plugin:

Download a kubectl configuration file

Download the plugin binary and a cluster generated kubectl configuration file. If you are using Kommander and add a new cluster, come back to this page to download an updated kubeconfig.

  1. Download a plugin binary and Kubectl configuration. Select the correct link for your platform:

    Operating System Plugin Binary and kubectl Location
    Mac OS/Darwin - https://your-cluster-IP/token/static/downloads/darwin/konvoy-async-auth_v0.1.3/konvoy-async-plugin
    - https://your-cluster-IP/token//plugin/kubeconfig
    Linux - https://your-cluster-IP/token/static/downloads/linux/konvoy-async-auth_v0.1.3/konvoy-async-plugin
    - https://your-cluster-IP/token//plugin/kubeconfig
    Windows - https://your-cluster-IP/token/static/downloads/windows/konvoy-async-auth_v0.1.3/konvoy-async-plugin.exe
    - https://your-cluster-IP/token//plugin/kubeconfig_windows
  2. Download both files to your computer. On Linux and MacOs, mark the plugin as an executable file. Enter the following command:

    chmod +x konvoy-async-plugin
    
  3. Copy the binary file to a location in your PATH environment variable. /usr/local/bin is a good location for the Linux and MacOS platforms.

Running kubectl

  1. Configure kubectl to use the plugin. Enter the following command:

    kubectl --kubeconfig </path/to/downloaded/config> get pods -A
    
  2. Set the KUBECONFIG environment variable to avoid typing --kubeconfig each time you run the command. Enter the following command:

    export KUBECONFIG=</path/to/downloaded/config>
    

Using Contexts

If this cluster is managing authentication for external clusters deployed by Kommander, you must set the correct kubectl context. The generated kubeconfig has contexts for each cluster managed by Kommander.

  1. List each context using the following command:

    kubectl --kubeconfig </path/to/downloaded/kubeconfig> config get-contexts
    
  2. To select a different context, use the following command:

    kubectl --kubeconfig </path/to/downloaded/kubeconfig> use-context context-name
    

For more information on using and managing kubeconfig files, refer to this documentation:

Manual configuration

These instructions configure your global kubeconfig, located at ${HOME}/.kube/config.

NOTE: The following commands can be pasted directly into a terminal.

Download and Install Konvoy credentials plugin

Use the command for your operating system to download and install the plugin.

OSX

curl --create-dirs https://your-cluster-IP/token/static/downloads/darwin/konvoy-async-auth_v0.1.3/konvoy-async-plugin \
      -o ${HOME}/.kube/konvoy/bin/konvoy-async-plugin && \
      chmod +x ${HOME}/.kube/konvoy/bin/konvoy-async-plugin

LINUX

curl --create-dirs https://<your-cluster-IP>/token/static/downloads/linux/konvoy-async-auth_v0.1.3/konvoy-async-plugin \
      -o ${HOME}/.kube/konvoy/bin/konvoy-async-plugin && \
      chmod +x ${HOME}/.kube/konvoy/bin/konvoy-async-plugin

Windows

Enter this command in your browser:

https://your-cluster-IP/token/static/downloads/windows/konvoy-async-auth_v0.1.3/konvoy-async-plugin.exe

Select cluster

This cluster handles authentication for multiple clusters using Kommander. Determine the cluster you want to configure. You can use these commands again to configure multiple clusters.

Create a cluster configuration

kubectl config set-cluster your-cluster-IP \
    --server=https://your-cluster-IP/konvoy/api-server

Create kubeconfig user profile

The default profile name is fine for most use cases. If you plan to authenticate with the same cluster, using multiple user accounts, you must create a profile for each user. Use your profile name in the following commands:

kubectl config set-credentials your-profile-name \
  --exec-command=konvoy/bin/konvoy-async-plugin \
  --exec-api-version=client.authentication.k8s.io/v1beta1 \
  --exec-arg="-auth-url=https://your-cluster-IP/token/" \
  --exec-arg="-kubeconfig-user=your-profile-name"

Create the context

kubectl config set-context default-profile-your-cluster-IP \
      --cluster=your-cluster-IP \
      --user=your-profile-name

Set the active context

kubectl config use-context your-profile-name.ksphere-platform.d2iq.cloud

Enter the following simple kubectl command:

    kubectl get pods -A

This opens a browser window and lets you authenticate. If you are using a remote terminal, a link displays. Copy and paste this link into a local browser window.