kubectl-shturval-plugin

About the plugin

The Shturval platform includes kubectl-shturval-plugin, which lets you access clusters from the command line.

kubectl-shturval-plugin works only with the internal authentication provider.

kubectl-shturval-plugin:

  • authenticates to the platform;
  • loads kubeconfig for one cluster or all clusters available to the user;
  • can save connection parameters in kubectl-shturval-plugin.yaml so you do not have to enter them on every login.

After kubeconfig is loaded, use kubectl to work with the cluster.

Supported scenarios

ScenarioWhat is usedWhen to use
With config from GUIkubectl-shturval-plugin.yaml, downloaded from the GUIGUI is available and you prefer not to enter parameters manually
With config from CLIkubectl-shturval-plugin.yaml generated by kubectl shturval login genconfigGUI is unavailable, but connection parameters are known
Without configkubectl shturval login with parametersOne-time login without saving a YAML file

What is kubectl-shturval-plugin.yaml

kubectl-shturval-plugin.yaml is a configuration file with platform connection parameters. You can obtain it in two ways:

  1. Generate it in the CLI with kubectl shturval login genconfig;
  2. Download it from the platform GUI.

If values are already stored in this file, kubectl shturval login can reuse them. Parameters passed on the command line take precedence over values in the YAML file and do not overwrite it.

If the platform runs in a closed environment, use your mirror address for kubectl-shturval instead of the public link.

Installation and commands

Before you begin, place kubectl-shturval-plugin in the same directory as kubectl. After installation, the plugin is available as the kubectl shturval ... subcommand.

Step 1: Find where kubectl is located

    Find the kubectl executable:

    which kubectl

    Find kubectl.exe:

    Get-ChildItem -Path C:\\ \"kubectl.exe\" -Recurse -Force -ErrorAction SilentlyContinue

    Step 2: Place the plugin in the same directory as kubectl

    If the downloaded file has a different name, rename it to kubectl-shturval (Linux) or kubectl-shturval.exe (Windows) when moving it.

      Copy the file to the directory next to kubectl and make it executable:

      sudo cp ENTER-PATH-TO-DOWNLOADED-kubectl-shturval-version ENTER-DIRECTORY-WHERE-kubectl-shturval-IS-LOCATED && sudo chmod +x ENTER-DIRECTORY-WHERE-kubectl-shturval-IS-LOCATED

      Copy kubectl-shturval.exe to the directory where kubectl.exe is located:

      cp ENTER-PATH-TO-DOWNLOADED-kubectl-shturval.exe ENTER-DIRECTORY-WHERE-kubectl.exe-IS-LOCATED

      Step 3. Verify that the file is next to kubectl

        Verify that kubectl-shturval is in the directory:

        ls ENTER-DIRECTORY-WHERE-kubectl-IS-LOCATED | grep kubectl-shturval

        Verify that kubectl-shturval.exe is in the directory:

        Test-Path -PathType Leaf -Path 'ENTER-DIRECTORY-WHERE-kubectl.exe-IS-LOCATED\\kubectl-shturval.exe'

        Basic commands

        CommandDescriptionWhen to use
        kubectl shturval loginAuthenticates to the platform and loads kubeconfig for one or more accessible clustersWhen you need immediate cluster access
        kubectl shturval login genconfigGenerates kubectl-shturval-plugin.yaml with connection parametersTo save connection settings for reuse

        Command help

        To view built-in help, run:

        kubectl shturval login -h

          Usage scenario with config from GUI

          Use this scenario if you have GUI access and want to use kubectl-shturval-plugin without manually entering connection parameters in the console.

          Files you can download from the GUI

          ScenarioWhere to downloadResult after kubectl shturval login with the config file
          One clusterIn a specific cluster’s interfaceclustername.conf in the working directory with kubeconfig for one cluster
          All accessible clustersOn the platform home pageall-clusters.conf in the working directory with kubeconfigs for accessible clusters

          General procedure

          1. Download kubectl-shturval-plugin.yaml from the GUI.
          2. Place the file in the user’s home directory. Linux examples use /root.
          3. Run kubectl shturval login.
          4. Use the resulting kubeconfig directly or move it to ~/.kube/config.

          If you do not pass a password on the command line, you will be prompted interactively.

          Access to one cluster

          1. In the cluster GUI, click the arrow to the right of your username.
          2. Select Download config for kubectl-shturval-plugin.
          3. Wait for the file to download (see the screenshot below).
          Download config for kubectl-shturval-plugin from the cluster GUI

          Download config menu next to the username in the cluster GUI Save dialog for kubectl-shturval-plugin.yaml

          Example configuration file 

          auth-url: shturval.clustername.ip-XX-XX-XX-XX.shturval.link
client-id: backend
client-secret: qz86fkqkb
cacert: |
  -----BEGIN CERTIFICATE-----
  MIIC+TCCAoCgAwIBAgINAKaLeSkAAAAAUNCR+TAKBggqhkjOPQQDAzCBvzELMAkG
  A1UEBhMCVVMxFjAUBgNpFQUWw==
  -----END CERTIFICATE-----  
username: username
cluster-name: clustername
kubeConfig: clustername.conf
server-url: shturval.clustername.ip-XX-XX-XX-XX.shturval.link

          In this scenario, the plugin loads the cluster kubeconfig into the directory where commands are executed and saves it with a name that matches the cluster.

          Next steps

          1. Open a command-line session and place the configuration file in the user’s home directory (for Linux, /root).
          2. Run the command to load the cluster kubeconfig. You will be prompted for your account password. After the command completes, kubeconfig is saved in the working directory with a name that matches the cluster.
          3. Move the cluster kubeconfig to ~/.kube and rename the file to config.
          mv ENTER-PATH-TO-DOWNLOADED-kubectl-shturval-plugin.yaml USER-HOME-DIRECTORY/kubectl-shturval-plugin.yaml
kubectl shturval login
mv ENTER-PATH-TO-clustername.conf ~/.kube/config

          After this, use kubectl to work with the cluster.

          Access to all user-accessible clusters

          1. On the platform home page, click the arrow to the right of your username.
          2. Select Download config kubectl-shturval-plugin for all clusters.
          3. Wait for kubectl-shturval-plugin.yaml to download (see the screenshot below).
          Download kubectl-shturval-plugin config for all clusters from the platform GUI

          Download config for all clusters from the platform home page Save dialog for kubectl-shturval-plugin.yaml for all clusters

          Example configuration file 

          auth-url: shturval.clustername.ip-XX-XX-XX-XX.shturval.link
client-id: backend
client-secret: qz86fkqkb
cacert: |
  -----BEGIN CERTIFICATE-----
  MIIC+TCCAoCgAwIBAgINAKaLeSkAAAAAUNCR+TAKBggqhkjOPQQDAzCBvzELMAkG
  A1UEBhMCVVMxFjAUBgNpFQUWw==
  -----END CERTIFICATE-----  
username: username
kubeConfig: all-clusters.conf
server-url: shturval.clustername.ip-XX-XX-XX-XX.shturval.link

          Kubeconfigs for accessible clusters are loaded into the all-clusters.conf file in the working directory.

          Next steps

          1. Open a command-line session and place the configuration file in the user’s home directory (for Linux, /root).
          2. Run the command to load cluster kubeconfigs. You will be prompted for your account password.
          3. Move the kubeconfigs to ~/.kube and rename the file to config.
          mv ENTER-PATH-TO-DOWNLOADED-kubectl-shturval-plugin.yaml USER-HOME-DIRECTORY/kubectl-shturval-plugin.yaml
kubectl shturval login
mv ENTER-PATH-TO-all-clusters.conf ~/.kube/config

          See Typical access errors if you cannot access the cluster or clusters.

          Usage scenario with config from CLI

          Use this scenario if the GUI is unavailable but connection parameters are known and you want to store them in kubectl-shturval-plugin.yaml for reuse.

          Parameters

          ParameterWhen neededDescription
          -s, --server-urlUsually requiredshturval-backend server URL
          -u, --usernameUsually requiredUsername for connecting to shturval-backend
          -p, --passwordOptionalPassword for connecting to shturval-backend. If the password contains special characters ($, <, >, *, &, ?, /, ), escape them with single quotes. For example, --password='my$Password?'
          --client-secretRequired for authenticationClient secret for the external authentication service
          --client-idOptionalClient ID for the external authentication service. Default: backend
          --auth-urlOptionalAuthentication server URL
          --cacertOptionalRoot trusted certificate contents
          --cacert-fileOptionalPath to the root trusted certificate
          -n, --cluster-nameOptionalCluster name to get kubeconfig for one cluster. Omit to get kubeconfigs for all accessible clusters
          --config-pathOptionalPath to the kubectl-shturval-plugin.yaml file. Default on Linux: /root
          -i, --insecureOptionalSkip TLS connection verification
          -k, --kubeconfigOptionalPath for downloaded kubeconfigs. Default on Linux: /root/.kube/config
          --ttlOptionalToken lifetime. Default: 24h

          Get client-secret from the backend key of the backend-* secret in the shturval-backend namespace of the management cluster. If you do not have access to this secret, request the backend key value from your platform administrator.

          General workflow

          1. Generate kubectl-shturval-plugin.yaml with kubectl shturval login genconfig.
          2. Verify the file contents.
          3. Run kubectl shturval login to get kubeconfig.
          4. Use the downloaded kubeconfig with kubectl.

          Step 1: Generate the configuration file

          Minimal example 

          kubectl shturval login genconfig --username=ENTER-USERNAME-FOR-CONNECTION --server-url=ENTER-shturval-backend-SERVER-URL --insecure=true --client-secret=ENTER-AUTH-SERVICE-CLIENT-SECRET

          The kubectl-shturval-plugin.yaml file is created in the user’s home directory. Linux examples use /root.

          Save the file to a different directory and skip TLS verification 

          kubectl shturval login genconfig --username=ENTER-USERNAME-FOR-CONNECTION --password='ENTER-USER-PASSWORD' --server-url=ENTER-shturval-backend-SERVER-URL --insecure=true --client-secret=ENTER-AUTH-SERVICE-CLIENT-SECRET --config-path=ENTER-PATH-TO-CONFIG-FILE

          Step 2: Verify that the file was created 

          cat ENTER-PATH-TO-kubectl-shturval-plugin.yaml

          Step 3: Sign in and download kubeconfig

          When the configuration file is ready, run:

          kubectl shturval login

          Override parameters for a single run

          Parameters passed to kubectl shturval login take precedence over the same values in kubectl-shturval-plugin.yaml. The configuration file itself is not overwritten.

          For example, you can sign in with a different account:

          kubectl shturval login --username=ENTER-USERNAME-FOR-CONNECTION --password='ENTER-USER-PASSWORD'

          Output

          • if one cluster is specified in the configuration, kubeconfig for that cluster is loaded;
          • if cluster-name is not specified, kubeconfigs for all accessible clusters are loaded;
          • you can set the final kubeconfig path with --kubeconfig.

          See Typical access errors if you cannot access the cluster or clusters.

          Usage scenario without config

          Use this scenario for direct login with kubectl shturval login without saving kubectl-shturval-plugin.yaml.

          Prerequisites

          • server-url for shturval-backend;
          • username and password;
          • client-secret for the authentication service;
          • if needed, cluster-name, authentication service parameters, and TLS settings.

          --client-secret is the value of the backend key in the backend-* secret in the shturval-backend namespace of the management cluster. If you do not have access to the secret, request the value from the platform administrator.

          kubectl shturval login parameters

          ParameterRequiredDescription
          --auth-url [string]NoAuthentication server URL
          --cacert [string]NoRoot trusted certificate contents
          --cacert-file [string]NoPath to the root trusted certificate
          --client-id [string]NoClient ID for the authentication service. Default: backend
          --client-secret [string]YesClient secret for the authentication service
          -n, --cluster-name [string]NoName of one cluster. If omitted, kubeconfigs for all accessible clusters are loaded
          --config-path [string]NoPath to kubectl-shturval-plugin.yaml, if used
          -i, --insecureNoSkip TLS connection verification
          -k, --kubeconfig [string]NoPath where kubeconfig will be saved. Default on Linux: /root/.kube/config
          -p, --password [string]NoUser password. If the password contains special characters ($, <, >, *, &, ?, /, ), use single quotes. For example, --password='my$Password?'
          -s, --server-url [string]Yesshturval-backend server URL
          --ttl [string]NoToken lifetime. Default: 24 hours
          -u, --username [string]YesUsername for connecting to shturval-backend
          -v, --versionNologin command version

          If you do not pass --password, you will be prompted interactively.

          Interactive password prompt when running kubectl shturval login

          Password prompt when logging in via kubectl shturval login

          Minimal scenario

          To access all available clusters without TLS verification, start with this command:

          kubectl shturval login --username=ENTER-USERNAME-FOR-CONNECTION --server-url=ENTER-shturval-backend-SERVER-URL --insecure=true --client-secret=ENTER-AUTH-SERVICE-CLIENT-SECRET

          Examples

          All accessible clusters with TLS verification (root certificate specified) 

          kubectl shturval login --username=ENTER-USERNAME-FOR-CONNECTION --password='ENTER-USER-PASSWORD' --server-url=ENTER-shturval-backend-SERVER-URL --client-secret=ENTER-AUTH-SERVICE-CLIENT-SECRET --cacert=-----BEGIN CERTIFICATE-----Base64 content-----END CERTIFICATE-----

          All accessible clusters with TLS verification disabled (root certificate from file) 

          kubectl shturval login --username=ENTER-USERNAME-FOR-CONNECTION --password='ENTER-USER-PASSWORD' --server-url=ENTER-shturval-backend-SERVER-URL --client-secret=ENTER-AUTH-SERVICE-CLIENT-SECRET --cacert-file=ENTER-PATH-TO-ROOT-CA-CERTIFICATE

          All accessible clusters with a custom kubeconfig output path 

          kubectl shturval login --username=ENTER-USERNAME-FOR-CONNECTION --password='ENTER-USER-PASSWORD' --server-url=ENTER-shturval-backend-SERVER-URL --insecure=true --client-secret=ENTER-AUTH-SERVICE-CLIENT-SECRET --kubeconfig=ENTER-PATH-TO-SAVE-kubeconfig

          One cluster with required authentication parameters and TLS verification disabled 

          kubectl shturval login --username=ENTER-USERNAME-FOR-CONNECTION --password='ENTER-USER-PASSWORD' --server-url=ENTER-shturval-backend-SERVER-URL --client-secret=ENTER-AUTH-SERVICE-CLIENT-SECRET --cluster-name=myclustername --insecure=true

          One cluster with required authentication parameters and TLS verification enabled 

          kubectl shturval login --username=ENTER-USERNAME-FOR-CONNECTION --password='ENTER-USER-PASSWORD' --server-url=ENTER-shturval-backend-SERVER-URL --client-secret=ENTER-AUTH-SERVICE-CLIENT-SECRET --cluster-name=ENTER-CLUSTER-NAME --cacert-file=ENTER-PATH-TO-ROOT-CA-CERTIFICATE

          See Typical access errors if you cannot access the cluster or clusters.

          ← Getting cluster kubeconfig
          Release 2.15.0 →