GitHub issues

What is kconnect?

kconnect is a CLI utility that can be used to discover and securely access Kubernetes clusters across multiple operating environments.

Based on the authentication mechanism chosen the CLI will discover Kubernetes clusters you are allowed to access in a target hosting environment (i.e. EKS, AKS, Rancher) and generate a kubeconfig for a chosen cluster.

Currently supported platforms: EKS, AKS, Rancher

Features

Authenticate using SAML, Azure Active Directory, AWS IAM, Rancher Token
Discover clusters in EKS, AKS and Rancher
Generate a kubeconfig for a cluster
Query history of connected servers
Regenerate the kubeconfig from your history by using an id or an alias
Import defaults values for your company

Documentation

For installation, getting started and other documentation head over to the projects documentation site or look in the /docs directory.

Contributions

Contributions are very welcome. Please read the contributing guide or see the docs.

Acknowledgements

For the SAML identity provider we rely heavily on the saml2aws project by Versent. For the Azure AD provider we have taken inspiration from the Microsoft Authentication Library for Go and have directly used their wstrust package (see pkg/azure/wstrust).

Thanks to both these projects for making the implementation easier.

Installation

NOTE: kconnect requires kubectl for k8s cluster cli interaction.

NOTE: kconnect requires aws-iam-authenticator for authentication to AWS EKS clusters.

NOTE: kconnect requires kubelogin for non-interactive authentication to Azure AKS clusters.

NOTE: kconnect requires az cli for interactive authentication to Azure AKS clusters.

NOTE:> For specific tested and pinned versions, use the install-kconnect.sh script or the with-deps docker image

kubectl plugin

To install as a kubectl plugin:

kubectl krew index add fidelity https://github.com/fidelity/krew-index.git
kubectl krew install fidelity/connect

You can then run like so:

kubectl connect use eks

Mac

To install on OSX you can use homebrew:

brew install fidelity/tap/kconnect

Alternatively you can download a binary from the latest release.

Linux

To install on Linux you can use homebrew:

brew install fidelity/tap/kconnect

Alternatively, the latest release contains .deb, .rpm and binaries for Linux.

We are working on publishing as a snap.

Windows

The latest release contains a binary for Windows.

We have an open issue to support chocolatey in the future.

Docker

You can also use kconnect via Docker by using the images we publish to Docker Hub:

docker pull docker.io/kconnectcli/kconnect:latest
docker run -it --rm -v ~/.kconnect:/.kconnect kconnect:latest use eks --idp-protocol saml

Install script

You can install kconnect, along with kubectl, helm and aws-iam-authenticator by running:

curl -fsSL -o install-kconnect.sh https://raw.githubusercontent.com/fidelity/kconnect/main/scripts/install-kconnect.sh
chmod 700 install-kconnect.sh
./install-kconnect.sh

This works on Linux, macOS and Windows (using GitBash terminal)

Getting started

Once you have installed kconnect you can see a list of the commands available by running:

kconnect help

NOTE: kconnect requires:

aws-iam-authenticator to authenticate to AWS EKS clusters.
kubelogin to authenticate to Azure AKS clusters.

The general workflow for using kconnect is the following:

kconnect configure - import configuration that contains defaults for your organisation - 1 time
kconnect use - connect to a cluster for the first time - only the first time
kconnect to - use to reconnect to a cluster that you have already connected to - most used command day-to-day

Creating and importing configuration

Before using kconnect to connect to a Kubernetes cluster you may want to import an identity provider configuration with your (or your organisations) defaults so that you don’t have to supply all connection settings each time you connect to a new cluster.

You will need to create a configuration file (see example here). The configuration file can be imported from a local file or remote location via HTTP/HTTPS (and from stdin).

Each new user in your organization can then import the default configurations in this file using the kconnect configure command with the -f flag:

kconnect configure -f https://raw.githubusercontent.com/fidelity/kconnect/main/examples/config.yaml

Once the user has created their local configuration file, they should be able to display their configuration settings.

kconnect configure

First time connection to a cluster

When discovering and connecting to a cluster for the first time you can do the following:

kconnect use eks --idp-protocol saml

This will guide you interactively setting the flags and selecting a cluster. It also gives you the option to set an easy-to-remember alias.

NOTE: only saml is supported at present for IdP.

Reconnecting to a cluster

If you’ve previously connected to a cluster you can reconnect to it using the alias (if you set one):

kconnect to dev-bu-1

Or using the history id (which can be found by using kconnect ls):

kconnect to 01EM615GB2YX3C6WZ9MCWBDWBF

Setting Flags

Flags can be replaced with environment variables by following the format UPPERCASED_SNAKE_CASE and appending to the KCONNECT_ prefix.

For example --username can be set as KCONNECT_USERNAME; or --idp-protocol as KCONNECT_IDP_PROTOCOL.

kconnect

The Kubernetes Connection Manager CLI

Synopsis

The kconnect tool uses a pre-configured Identity Provider to log in to one or more managed Kubernetes cluster providers, discovers the list of clusters visible to your authenticated user and options, and generates a kubectl configutation context for the selected cluster.

Most kubectl contexts include an authentication token which kubectl sends to Kubernetes with each request rather than a username and password to establish your identity. Authentication tokens typically expire after some time. The user must then to log in again to the managed Kubernetes service provider and regenerate the kubectl context for that cluster connection in order to refresh the access token.

The kconnect tool makes this much easier by automating the login and kubectl context regeneration process, and by allowing the user to repeat previously successful connections.

Each time kconnect creates a new connection context, the kconnect tool saves the information for that connection in the user’s connection history list. The user can then display their connection history entries and reconnect to any entry by its unique ID (or by a user-friendly alias) to refresh an expired access token for that cluster.

kconnect [flags]

Examples


  # Display a help screen with kconnect commands.
  kconnect help

  # Configure the default identity provider and connection profile for your user.
  #
  # Use this command to set up kconnect the first time you use it on a new system.
  #
  kconnect config -f FILE_OR_URL

  # Create a kubectl confirguration context for an AWS EKS cluster.
  #
  # Use this command the first time you connect to a new cluster or a new context.
  #
  kconnect use eks

  # Display connection history entries.
  #
  kconnect ls

  # Add an alias to a connection history entry.
  #
  kconnect alias add --id 012EX456834AFXR0F2NZT68RPKD --alias MYALIAS

  # Reconnect and refresh the token for an aliased connection history entry.
  #
  # Use this to reconnect to a provider and refresh an expired access token.
  #
  kconnect to MYALIAS

  # Display connection history entry aliases.
  #
  kconnect alias ls

Options

      --config string      Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
  -h, --help               help for kconnect
      --no-input           Explicitly disable interactivity when running in a terminal
      --no-version-check   If set to true kconnect will not check for a newer version
  -v, --verbosity int      Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

kconnect alias

Query and manipulate connection history entry aliases.

Synopsis

An alias is a user-friendly name for a connection history entry, otherwise referred to by its entry ID.

The alias command and sub-commands allow you to query and manipulate aliases for connection history entries.

kconnect alias [flags]

Examples


  # Add an alias to an existing connection history entry
  kconnect alias add --id 123456 --alias appdev

  # List available connection history entry aliases
  kconnect alias ls

  # Remove an alias from a connection history entry
  kconnect alias remove --alias appdev

Options

  -h, --help                      help for alias
      --history-location string   Location of where the history is stored. (default "$HOME/.kconnect/history.yaml")

Options inherited from parent commands

      --config string      Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --no-input           Explicitly disable interactivity when running in a terminal
      --no-version-check   If set to true kconnect will not check for a newer version
  -v, --verbosity int      Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

kconnect alias add

Add an alias to a connection history entry

Synopsis

Adds a user-friendly alias to a connection history entry.

The user can then reconnect and refresh the access token for that cluster using the alias instead of the connection history entry’s unique ID.

kconnect alias add [flags]

Examples


  # Add an alias to a connection history entry
  kconnect alias add --id 01EMEM5DB60TMX7D8SS2JCX3MT --alias dev-bu-1

  # Connect to a cluster using the alias
  kconnect to dev-bu-1

  # List available aliases
  kconnect alias ls

  # List available history entries - includes aliases
  kconnect ls

Options

      --alias string   Alias name for a history entry
  -h, --help           help for add
      --id string      Id for a history entry

Options inherited from parent commands

      --config string             Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --history-location string   Location of where the history is stored. (default "$HOME/.kconnect/history.yaml")
      --no-input                  Explicitly disable interactivity when running in a terminal
      --no-version-check          If set to true kconnect will not check for a newer version
  -v, --verbosity int             Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

kconnect alias ls

List all the aliases currently defined

Synopsis

List all the aliases currently defined for connection history entries in the user’s connection history.

An alias is a user-friendly name for a connection history entry.

kconnect alias ls [flags]

Examples


  # Display all the aliases as a table
  kconnect alias ls

  # Display all connection history entry aliases as a table
  kconnect alias ls

  # Display all connection history entry aliases as json
  kconnect alias ls --output json

  # Connect to a cluster using a connection history entry alias
  kconnect to ${alias}

  # List all connection history entries as a table - includes aliases
  kconnect ls

Options

  -h, --help            help for ls
      --output string   Output format for the results (default "table")

Options inherited from parent commands

      --config string             Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --history-location string   Location of where the history is stored. (default "$HOME/.kconnect/history.yaml")
      --no-input                  Explicitly disable interactivity when running in a terminal
      --no-version-check          If set to true kconnect will not check for a newer version
  -v, --verbosity int             Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

kconnect alias remove

Remove connection history entry aliases.

Synopsis

Remove an alias from a single connection history entry by the entry ID or the alias.

Set the --all flag on this command to remove all connection history aliases from the user’s connection history.

kconnect alias remove [flags]

Examples


  # Remove an alias using the alias name
  kconnect alias remove --alias dev-bu-1

  # Remove an alias using a histiry entry id
  kconnect alias remove --id 01EMEM5DB60TMX7D8SS2JCX3MT

  # Remove all aliases
  kconnect alias remove --all

  # List available aliases
  kconnect alias ls

  # Query your connection history - includes aliases
  kconnect ls

Options

      --alias string   Alias name for a history entry
      --all            Remove all aliases from the histiry entries
  -h, --help           help for remove
      --id string      Id for a history entry

Options inherited from parent commands

      --config string             Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --history-location string   Location of where the history is stored. (default "$HOME/.kconnect/history.yaml")
      --no-input                  Explicitly disable interactivity when running in a terminal
      --no-version-check          If set to true kconnect will not check for a newer version
  -v, --verbosity int             Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

kconnect config

Set and view your kconnect configuration.

Synopsis

The configure command creates kconnect configuration files and displays previously-defined configurations in a user-friendly display format.

If run with no flags, the command displays the configurations stored in the current user’s $HOME/.kconnect/config.yaml file.

The configure command can create a set of default configurations for a new system or a new user via the -f flag and a local filename or remote URL.

The user typically only needs to use this command the first time they use kconnect.

kconnect config [flags]

Examples


  # Display user's current configurations
  kconnect config

  # Display the user's configurations as json
  kconnect config --output json

  # Set the user's configurations from a local file
  kconnect config -f ./defaults.yaml

  # Set the user's configurations from a remote location via HTTP
  kconnect config -f https://mycompany.com/config.yaml

  # Set the user's configurations from stdin
  cat ./config.yaml | kconnect config -f -

Options

  -f, --file string       File or remote location to use to set the default configuration
  -h, --help              help for config
      --output string     Controls the output format for the result. (default "yaml")
      --password string   The password used for authentication
      --username string   The username used for authentication

Options inherited from parent commands

      --config string      Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --no-input           Explicitly disable interactivity when running in a terminal
      --no-version-check   If set to true kconnect will not check for a newer version
  -v, --verbosity int      Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

kconnect ls

Query the user’s connection history

Synopsis

Query and display the user’s connection history entries, including entry IDs and aliases.

Each time kconnect creates a new kubectl context to connect to a Kubernetes cluster, it saves the settings for the new connection as an entry in the user’s connection history. The user can then reconnect using those same settings later via the connection history entry’s ID or alias.

kconnect ls [flags]

Examples


  # Display all connection history entries as a table
  kconnect ls

  # Display all connection history entries as YAML
  kconnect ls --output yaml

  # Display a specific connection history entry by entry id
  kconnect ls --filter id=01EM615GB2YX3C6WZ9MCWBDWBF

  # Display a specific connection history entry by its alias
  kconnect ls --filter alias=mydev

  # Display all connection history entries that have "dev" in its alias
  kconnect ls --filter alias=*dev*

  # Display all connection history entries for the EKS managed cluster provider
  kconnect ls --filter cluster-provider=eks

  # Display all connection history entries for entries with namespace kube-system
  kconnect ls --filter namespace=kube-system

  # Reconnect using the connection history entry alias
  kconnect to mydev

Options

      --filter string             filter to apply to import. Can specify multiple filters by using commas, and supports wilcards (*)
  -h, --help                      help for ls
      --history-location string   Location of where the history is stored. (default "$HOME/.kconnect/history.yaml")
  -k, --kubeconfig string         Location of the kubeconfig to use. (default "$HOME/.kube/config")
      --max-history int           Sets the maximum number of history items to keep (default 100)
      --no-history                If set to true then no history entry will be written
  -o, --output string             Output format for the results (default "table")

Options inherited from parent commands

      --config string      Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --no-input           Explicitly disable interactivity when running in a terminal
      --no-version-check   If set to true kconnect will not check for a newer version
  -v, --verbosity int      Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

kconnect to

Reconnect to a connection history entry.

Synopsis

Reconnect to a cluster in the connection history by its entry ID or alias.

The kconnect tool creates an entry in the user’s connection history with all the connection settings each time it generates a new kubectl configuration context for a Kubernetes cluster. The user can then reconnect to the same cluster and refresh their access token or regenerate the kubectl configuration context using the connection history entry’s ID or alias.

The to command also accepts - or LAST as proxy references to the most recent connection history entry, or LAST~N for the Nth previous entry.

Although kconnect does not save the user’s password in the connection history, the user can avoid having to enter their password interactively by setting the KCONNECT_PASSWORD environment variable or the --password command-line flag. Otherwise kconnect will promot the user to enter their password.

kconnect to [historyid/alias/-/LAST/LAST~N] [flags]

Examples


  # Reconnect based on an alias - aliases can be found using kconnect ls
  kconnect to uat-bu1

  # Reconnect based on an history id - history id can be found using kconnect ls
  kconnect to 01EM615GB2YX3C6WZ9MCWBDWBF

  # Reconnect interactively from history list
  kconnect to

  # Reconnect to current cluster (this is useful for renewing credentials)
  kconnect to -
  OR
  kconnect to LAST

  # Reconnect to cluster used before current one
  kconnect to LAST~1

  # Reconnect based on an alias supplying a password
  kconnect to uat-bu1 --password supersecret

  # Reconnect based on an alias supplying a password via env var
  KCONNECT_PASSWORD=supersecret kconnect to uat-bu2

Options

  -h, --help                      help for to
      --history-location string   Location of where the history is stored. (default "$HOME/.kconnect/history.yaml")
  -k, --kubeconfig string         Location of the kubeconfig to use. (default "$HOME/.kube/config")
      --password string           Password to use
      --set-current               Sets the current context in the kubeconfig to the selected cluster (default true)

Options inherited from parent commands

      --config string      Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --no-input           Explicitly disable interactivity when running in a terminal
      --no-version-check   If set to true kconnect will not check for a newer version
  -v, --verbosity int      Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

kconnect use

Connect to a Kubernetes cluster provider and cluster.

Synopsis

Connect to a managed Kubernetes cluster provider via the configured identity provider, prompting the user to enter or choose connection settings appropriate to the provider and a target cluster once connected.

The kconnect tool generates a kubectl configuration context with a fresh access token to connect to the chosen cluster and adds a connection history entry to store the chosen connection settings. If given an alias name, kconnect will add a user-friendly alias to the new connection history entry.

The user can then reconnect to the provider with the settings stored in the connection history entry using the kconnect to command and the connection history entry ID or alias. When the user reconnects using a connection history entry, kconnect regenerates the kubectl configuration context and refreshes their access token.

The use command requires a target provider name as its first parameter. If no value is supplied for --idp-protocol the first supported protocol for the specified cluster provider.

Note: interactive mode is not supported in windows git-bash application currently.
Note: kconnect use eks requires aws-iam-authenticator. aws-iam-authenticator
Note: kconnect use aks requires kubelogin and azure cli. kubelogin azure-cli
Note: kconnect use oidc requires kube-oidc-login and rename to kubectl-oidc_login. kube-oidc-login

kconnect use [flags]

Examples


  # Connect to EKS and choose an available EKS cluster.
  kconnect use eks

  # Connect to an EKS cluster and create an alias for its connection history entry.
  kconnect use eks --alias mycluster

  # Reconnect to a cluster by its connection history entry alias.
  kconnect to mycluster

  # Display the user's connection history as a table.
  kconnect ls

Options

  -h, --help   help for use

Options inherited from parent commands

      --config string      Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --no-input           Explicitly disable interactivity when running in a terminal
      --no-version-check   If set to true kconnect will not check for a newer version
  -v, --verbosity int      Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

kconnect use aks

Connect to the aks cluster provider and choose a cluster.

Synopsis

Connect to aks via the configured identify provider, prompting the user to enter or choose connection settings and a target cluster once connected.

Note: kconnect use aks requires kubelogin and azure cli. kubelogin azure-cli

kconnect use aks [flags]

Examples

  # Discover AKS clusters using Azure AD
  kconnect use aks --idp-protocol aad

  # Discover AKS clusters using file based credentials
  export AZURE_TENANT_ID="123455"
  export AZURE_CLIENT_ID="76849"
  export AZURE_CLIENT_SECRET="supersecret"
  kconnect use aks --idp-protocol az-env

  # Reconnect to a cluster by its connection history entry alias.
  kconnect to mycluster

  # Display the user's connection history as a table.
  kconnect ls

Options

      --admin                      Generate admin user kubeconfig
  -a, --alias string               Friendly name to give to give the connection
      --azure-env string           The Azure environment the clusters are in. Possible values: public,china,usgov,stack (default "public")
  -c, --cluster-id string          Id of the cluster to use.
      --cluster-name string        The name of the AKS cluster
  -h, --help                       help for aks
      --history-location string    Location of where the history is stored. (default "$HOME/.kconnect/history.yaml")
      --idp-protocol string        The idp protocol to use (e.g. saml, aad). See flags additional flags for the protocol.
  -k, --kubeconfig string          Location of the kubeconfig to use. (default "$HOME/.kube/config")
      --login-type string          The login method to use when connecting to the AKS cluster as a non-admin. Possible values: devicecode,spn,ropc,msi,azurecli (default "devicecode")
      --max-history int            Sets the maximum number of history items to keep (default 100)
  -n, --namespace string           Sets namespace for context in kubeconfig
      --no-history                 If set to true then no history entry will be written
      --password string            The password to use for authentication
  -r, --resource-group string      The Azure resource group to use
      --server-fqdn-type string    Connect to AKS cluster via Public/Private FQDN (default "public")
      --set-current                Sets the current context in the kubeconfig to the selected cluster (default true)
      --subscription-id string     The Azure subscription to use (specified by ID)
      --subscription-name string   The Azure subscription to use (specified by name)
      --username string            The username used for authentication

Options inherited from parent commands

      --config string      Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --no-input           Explicitly disable interactivity when running in a terminal
      --no-version-check   If set to true kconnect will not check for a newer version
  -v, --verbosity int      Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

IDP Protocol Options

AAD Options

Use --idp-protocol=aad

      --aad-host string       The AAD host to use (default "login.microsoftonline.com")
      --client-id string      The azure ad client id (default "04b07795-8ddb-461a-bbee-02f9e1bf7b46")
      --idp-protocol string   The idp protocol to use (e.g. saml). Each protocol has its own flags.
      --password string       The password to use for authentication
  -t, --tenant-id string      The azure tenant id
      --username string       The username used for authentication

AZ-ENV Options

Use --idp-protocol=az-env

      --use-file   Use file based authorization

kconnect use eks

Connect to the eks cluster provider and choose a cluster.

Synopsis

Connect to eks via the configured identify provider, prompting the user to enter or choose connection settings and a target cluster once connected.

Note: kconnect use eks requires aws-iam-authenticator. aws-iam-authenticator

kconnect use eks [flags]

Examples


  # Discover EKS clusters using SAML
  kconnect use eks --idp-protocol saml

  # Discover EKS clusters using SAML with a specific role
  kconnect use eks --idp-protocol saml --role-arn arn:aws:iam::000000000000:role/KubernetesAdmin

  # Discover an EKS cluster and add an alias to its connection history entry
  kconnect use eks --alias mycluster
  
  # Reconnect to a cluster by its connection history entry alias.
  kconnect to mycluster

  # Display the user's connection history as a table.
  kconnect ls

Options

  -a, --alias string                         Friendly name to give to give the connection
      --assume-role-arn string               ARN of the AWS role to be assumed
      --aws-shared-credentials-file string   Location to store AWS credentials file
  -c, --cluster-id string                    Id of the cluster to use.
  -h, --help                                 help for eks
      --history-location string              Location of where the history is stored. (default "$HOME/.kconnect/history.yaml")
      --idp-protocol string                  The idp protocol to use (e.g. saml, aad). See flags additional flags for the protocol.
  -k, --kubeconfig string                    Location of the kubeconfig to use. (default "$HOME/.kube/config")
      --max-history int                      Sets the maximum number of history items to keep (default 100)
  -n, --namespace string                     Sets namespace for context in kubeconfig
      --no-history                           If set to true then no history entry will be written
      --partition string                     AWS partition to use (default "aws")
      --password string                      The password to use for authentication
      --region string                        AWS region to connect to
      --region-filter string                 A regex filter to apply to the AWS regions list, e.g. '^us-|^eu-' will only show US and eu regions
      --role-arn string                      ARN of the AWS role to be logged in with
      --role-filter string                   A filter to apply to the roles list, e.g. 'EKS' will only show roles that contain EKS in the name
      --set-current                          Sets the current context in the kubeconfig to the selected cluster (default true)
      --username string                      The username used for authentication

Options inherited from parent commands

      --config string      Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --no-input           Explicitly disable interactivity when running in a terminal
      --no-version-check   If set to true kconnect will not check for a newer version
  -v, --verbosity int      Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

IDP Protocol Options

AWS-IAM Options

Use --idp-protocol=aws-iam

      --access-key string      AWS access key to use
      --partition string       AWS partition to use (default "aws")
      --profile string         AWS profile to use
      --region string          AWS region to connect to
      --secret-key string      AWS secret key to use
      --session-token string   AWS session token to use

SAML Options

Use --idp-protocol=saml

      --idp-endpoint string   identity provider endpoint provided by your IT team
      --idp-provider string   the name of the idp provider
      --partition string      AWS partition to use (default "aws")
      --region string         AWS region to connect to

kconnect use rancher

Connect to the rancher cluster provider and choose a cluster.

Synopsis

Connect to rancher via the configured identify provider, prompting the user to enter or choose connection settings and a target cluster once connected.

kconnect use rancher [flags]

Examples

  # Discover Rancher clusters using Active Directory
	kconnect use rancher --idp-protocol rancher-ad

	# Discover clusters via Rancher using a API key
	kconnect use rancher --idp-protocol static-token --token ABCDEF
  
  # Reconnect to a cluster by its connection history entry alias.
  kconnect to mycluster

  # Display the user's connection history as a table.
  kconnect ls

Options

  -a, --alias string              Friendly name to give to give the connection
      --api-endpoint string       The Rancher API endpoint
  -c, --cluster-id string         Id of the cluster to use.
      --cluster-name string       The Rancher user friendly cluster name
  -h, --help                      help for rancher
      --history-location string   Location of where the history is stored. (default "$HOME/.kconnect/history.yaml")
      --idp-protocol string       The idp protocol to use (e.g. saml, aad). See flags additional flags for the protocol.
  -k, --kubeconfig string         Location of the kubeconfig to use. (default "$HOME/.kube/config")
      --max-history int           Sets the maximum number of history items to keep (default 100)
  -n, --namespace string          Sets namespace for context in kubeconfig
      --no-history                If set to true then no history entry will be written
      --password string           The password to use for authentication
      --set-current               Sets the current context in the kubeconfig to the selected cluster (default true)
      --username string           The username used for authentication

Options inherited from parent commands

      --config string      Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --no-input           Explicitly disable interactivity when running in a terminal
      --no-version-check   If set to true kconnect will not check for a newer version
  -v, --verbosity int      Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

IDP Protocol Options

STATIC-TOKEN Options

Use --idp-protocol=static-token

      --idp-protocol string   The idp protocol to use (e.g. saml). Each protocol has its own flags.
      --token string          the token to use for authentication

RANCHER-AD Options

Use --idp-protocol=rancher-ad

      --api-endpoint string   The Rancher API endpoint
      --idp-protocol string   The idp protocol to use (e.g. saml). Each protocol has its own flags.
      --password string       The password to use for authentication
      --username string       The username used for authentication

kconnect use oidc

Connect to the oidc cluster provider and choose a cluster.

Synopsis

Connect to oidc via the configured identify provider, prompting the user to enter or choose connection settings and a target cluster once connected.

Note: kconnect use oidc requires kube-oidc-login and rename to kubectl-oidc_login. kube-oidc-login

kconnect use oidc [flags]

Examples


  # Setup cluster for oidc protocol using default config file
  kconnect use oidc

  # Setup cluster for oidc protocol using config url
  kconnect use oidc --config-url https://localhost:8080

  # Setup cluster and add an alias to its connection history entry
  kconnect use oidc --alias mycluster
  
  # Reconnect to a cluster by its connection history entry alias.
  kconnect to mycluster

  # Display the user's connection history as a table.
  kconnect ls

Options

  -a, --alias string                Friendly name to give to give the connection
      --ca-cert string              ca cert for configuration url
      --cluster-auth string         cluster auth data
  -c, --cluster-id string           Id of the cluster to use.
      --cluster-url string          cluster api server endpoint
      --config-url string           configuration endpoint
  -h, --help                        help for oidc
      --history-location string     Location of where the history is stored. (default "$HOME/.kconnect/history.yaml")
      --idp-protocol string         The idp protocol to use (e.g. saml, aad). See flags additional flags for the protocol.
  -k, --kubeconfig string           Location of the kubeconfig to use. (default "$HOME/.kube/config")
      --max-history int             Sets the maximum number of history items to keep (default 100)
  -n, --namespace string            Sets namespace for context in kubeconfig
      --no-history                  If set to true then no history entry will be written
      --oidc-client-id string       oidc client id
      --oidc-client-secret string   oidc client secret
      --oidc-server string          oidc server url
      --oidc-use-pkce string        if use pkce
      --password string             The password to use for authentication
      --set-current                 Sets the current context in the kubeconfig to the selected cluster (default true)
      --skip-oidc-ssl string        flag to skip ssl for calling oidc server
      --skip-ssl string             flag to skip ssl for calling config url
      --username string             The username used for authentication

Options inherited from parent commands

      --config string      Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --no-input           Explicitly disable interactivity when running in a terminal
      --no-version-check   If set to true kconnect will not check for a newer version
  -v, --verbosity int      Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

IDP Protocol Options

OIDC Options

Use --idp-protocol=oidc

      --ca-cert string              ca cert for configuration url
      --cluster-auth string         cluster auth data
      --cluster-url string          cluster api server endpoint
      --config-url string           configuration endpoint
      --oidc-client-id string       oidc client id
      --oidc-client-secret string   oidc client secret
      --oidc-server string          oidc server url
      --oidc-use-pkce string        if use pkce
      --skip-oidc-ssl string        flag to skip ssl for calling oidc server
      --skip-ssl string             flag to skip ssl for calling config url

kconnect version

Display version & build information

Synopsis

Display version & build information

kconnect version [flags]

Options

  -h, --help   help for version

Options inherited from parent commands

      --config string      Configuration file for application wide defaults. (default "$HOME/.kconnect/config.yaml")
      --no-input           Explicitly disable interactivity when running in a terminal
      --no-version-check   If set to true kconnect will not check for a newer version
  -v, --verbosity int      Sets the logging verbosity. Greater than 0 is debug and greater than 9 is trace.

Releasing kconnect

The release of kconnect is done using goreleaser which is orchestrated using Githib Actions.

Process

The following steps are required to do a release:

Merge any PRs into the main branch that contain features, bug fixes and other changes that you want to include in the release.
We use Semver 2.0 for the release numbering. You will need to decide what the next release number will be based on the changes and whether it will be a “pre-release”:
- Normal release: it will follow the MAJOR.MINOR.PATCH format, for example 0.3.0
- Pre-release: it will follow the MAJOR.MINOR.PATCH-rc.RCNUMBER format, for example 0.3.0-rc.1
Locally on your machine get the latest main branch code:

git checkout main
git pull

Tag the main branch with the release number previously determined:

git tag -a 0.3.0 -m "0.3.0"

Push the new tag to GitHub:

git push origin 0.3.0

Go to GitHub and check on the goreleaser action. This action is what does the actual release.
Once the goreleaser action completes go to the releases on GitHub and check the release is available.
Click Edit next to the release and tidy up the Changelog entries. If there are any breaking changes then a new markdown section should be added to the top that documents this.
Locally on your machine, run this command:

sudo docker run -v /path/to/repo/.krew.yaml:/tmp/template-file.yaml rajatjindal/krew-release-bot:v0.0.38 krew-release-bot template --tag 0.3.0 --template-file /tmp/template-file.yaml

Take the output of this command (excluding logging output). Update this file https://github.com/fidelity/krew-index/blob/main/plugins/connect.yaml with the output you just obtained (note: these manual steps will be automated in future)

Implementation

We use goreleaser to do the majority of the build, packaging and release. The .goreleaser.yml configuration file drives this.

The goreleaser GitHub Action that kicks off goreleaser on tagging the main branch is located here.

There is an additional GitHub workflow that is used to publish the docs to GitHub pages and that is located here.

Thank you for considering to contribute to kconnect 🎉👍

This document will provide help on how to go about this. You can contribute in the following ways:

Reporting bugs
Disclosing security concerns responsibly
Suggesting features
Contributing code

All contributions and project spaces are subject to our Code of Conduct.

Reporting Bugs

Reporting bugs is an essential part in making kconnect better for its end users.

Please open an issue unless you are making a significant security disclosure. A new Bug Report can be raised here.

When raising bugs please include as much information as possible including steps about how to reproduce the problem and what you expect the behavior to be.

How to disclose security concerns responsibly

Please follow the instructions in our security policy (also visible in the Security tab on the project’s repo).

Suggesting features

If there is a feature that you would like in kconnect then please let us know about it.

Features are also suggested using GitHub Issues. A new Feature enhancement request can be raised here.

Include as much information as possible, understanding the problem that the feature is trying to solve will really help us in understanding the benefit.

Contributing Code

Code contributions to kconnect are very welcome as long as you follow a few rules:

Your contribution must be received under the project’s open source license.
You must have permission to make the contribution. We strongly recommend including a Signed-off-by line to indicate your adherence to the Developer Certificate of Origin.
All code contributions must be made via PR, and all checks must pass before merging.

If you need a pointer on where to start you can look at the good first issue and help wanted issues:

good first issue - small changes that are suitable for a beginner
help wanted - more involved changes

You can also choose your own issue to work on from this list of available issues.

When choosing an issue to work on its preferable that you choose a issue that is planned for the next milestone and that has a higher priority....but this is just a nice to have and any contribution would be considered and welcomed.

Getting started

Install Go >= 1.17
Fork the kconnect repo
Create a branch for your change:

git checkout -b <feature-name>

Make the change, including any additional tests
Run the tests:

make test

Check for linting errors:

make lint

Build and manually test kconnect locally:

make build

Commit and push your branch. We follow Conventional Commits for the commits and PRs.
Create a pull request. If the PR is a work in progress ensure that that PR is created as a draft.
Check that the PR checks pass

Once a PR has been created it will be reviewed by one of the maintainers of kconnect.

Getting help

If you have other questions about this project, please open an issue. To reach the Fidelity OSPO directly, please email opensource@fmr.com.

kconnect - The Kubernetes Connection Manager CLI