Kubernetes CLI Plugin

Allows you to configure kubectl to interact with Kubernetes clusters from within your jobs. Any tool built on top of kubectl can then be used from your pipelines to perform deployments, e.g. Shopify/krane or Helm.

Initially extracted and rewritten from the Kubernetes Plugin.

// Example when used in a pipeline
node {
  stage('Apply Kubernetes files') {
    withKubeConfig([credentialsId: 'user1', serverUrl: 'https://api.k8s.my-company.com']) {
      sh 'kubectl apply -f my-kubernetes-directory'
    }
  }
}

Prerequisites

• A jenkins installation running version 2.401.1 or higher (with jdk11 or jdk17).
• An executor with kubectl installed (tested against v1.22 to v1.29 included).
• A Kubernetes cluster.

How it works

The plugin generates a kubeconfig file based on the parameters that were provided in the build. This file is stored in a temporary file inside the build workspace and the exact path can be found in the KUBECONFIG environment variable. kubectl automatically picks up the path from this environment variable. Once the build is finished (or the pipeline block is exited), the temporary kubeconfig file is automatically removed.

Supported Credentials

The following types of credentials are supported and can be used to authenticate against Kubernetes clusters:

• Token, as secrets (see Plain Credentials plugin)
• Plain KubeConfig files (see Plain Credentials plugin)
• Username and Password (see Credentials plugin)
• Certificates (see Credentials plugin)
• OpenShift OAuth tokens, as secrets (see Kubernetes Credentials plugin)

If the Jenkins Agent is running within a Pod (e.g. by using the Kubernetes Plugin), you can fallback to the Pod's ServiceAccount by not setting any credentials.

Quick Usage Quide

The parameters have a slightly different effect depending if a plain KubeConfig file is provided.

Parameters (without KubeConfig File)

Parameters (with KubeConfig File)

The plugin writes the plain KubeConfig file and doesn't change any other field if only credentialsId is filled. The recommended way to use a single KubeConfig file with multiples clusters, users, and default namespaces is to configure a Context for each of them, and use the contextName parameter to switch between them (see Kubernetes documentation).

Parameters (when running inside a Pod)

Using Environment Variables

The parameters serverUrl, clusterName , namespace and contextName can contain environment variables and are interpolated before writing the configuration file to disk.

Using the Plugin in a Pipeline

The kubernetes-cli plugin provides the function withKubeConfig() for Jenkins Pipeline support. You can go to the Snippet Generator page under the Pipeline Syntax section in Jenkins, select withKubeConfig: Setup Kubernetes CLI from the Sample Step dropdown, and it will provide you configuration interface for the plugin. After filling the entries and click Generate Pipeline Script button, you will get the sample scripts which can be used in your Pipeline definition.

Example:

node {
  stage('List pods') {
    withKubeConfig([credentialsId: '<credential-id>',
                    caCertificate: '<ca-certificate>',
                    serverUrl: '<api-server-address>',
                    contextName: '<context-name>',
                    clusterName: '<cluster-name>',
                    namespace: '<namespace>'
                    ]) {
      sh 'kubectl get pods'
    }
  }
}

Usage with multiple Credentials

If you need to use more than one credential at the same time, you can use withKubeCredentials. It takes an array of the parameters as described for withKubeConfig, e.g.:

node {
  stage('Dump merged config') {
    withKubeCredentials([
        [credentialsId: '<credential-id-1>', serverUrl: '<api-server-address>'],
        [credentialsId: '<credential-id-2>', contextName: '<context-name>']
    ]) {
      sh 'kubectl config view'
    }
  }
}

The merging is done by kubectl itself, refer to its documentation for details. When providing more than one credential is provided no context will be set by default.

Usage when running inside a Pod

If you're running your pipelines within Kubernetes Pods, you could use those Pod's ServiceAccount instead of providing dedicated credentials. To do so, don't specify any credentialsId when calling withKubeConfig().

podTemplate(inheritFrom: 'default')
{
    node(POD_LABEL){
      stage('List Configmaps') {
        withKubeConfig([namespace: "this-other-namespace"]) {
          sh 'kubectl get configmap'
        }
  }
    }
}

Note: You may also want to call podTemplate() with a dedicated ServiceAccount that has the permissions required by your pipeline.

Using the Plugin from the Web Interface

1. Within the Jenkins dashboard, select a Job and then select "Configure"
2. Scroll down to the "Build Environment" section
3. Select "Configure Kubernetes CLI (kubectl) with multiple credentials"
4. In the "Credential" dropdown, select the credentials to authenticate on the cluster or the kubeconfig stored in Jenkins.
5. Repeat 4 as necessary

Generating Kubernetes Credentials

The following example describes how you could use the token of a ServiceAccount to access the Kubernetes cluster from Jenkins. The result depends of course on the permissions you have.

# Create a ServiceAccount named `jenkins-robot` in a given namespace.
$ kubectl -n <namespace> create serviceaccount jenkins-robot

# The next line gives `jenkins-robot` administator permissions for this namespace.
# * You can make it an admin over all namespaces by creating a `ClusterRoleBinding` instead of a `RoleBinding`.
# * You can also give it different permissions by binding it to a different `(Cluster)Role`.
$ kubectl -n <namespace> create rolebinding jenkins-robot-binding --clusterrole=cluster-admin --serviceaccount=<namespace>:jenkins-robot

# Get the name of the token that was automatically generated for the ServiceAccount `jenkins-robot`.
$ kubectl -n <namespace> get serviceaccount jenkins-robot -o go-template --template='{{range .secrets}}{{.name}}{{"\n"}}{{end}}'
jenkins-robot-token-d6d8z

# Retrieve the token and decode it using base64.
$ kubectl -n <namespace> get secrets jenkins-robot-token-d6d8z -o go-template --template '{{index .data "token"}}' | base64 -d
eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2V[...]

On Jenkins, navigate in the folder you want to add the token in, or go on the main page. Then click on the "Credentials" item in the left menu and find or create the "Domain" you want. Finally, paste your token into a Secret text credential. The ID is the credentialsId you need to use in the plugin configuration.

Development

Building and testing

To build the extension, run:

mvn clean package

and upload target/kubernetes-cli.hpi to your Jenkins installation.

To run the tests:

mvn clean test

Performing a Release

mvn release:prepare release:perform