The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

Kubernetes plugin

container: Run build steps in a container

Selects a container of the agent pod so that all shell steps are executed in that container.
  • name : String
  • shell : String (optional)

    Specifies a shell which will run inside the container and process requests from Jenkins to run executables, set environment variables, and similar infrastructure.

    This does not affect the shell used to run user code, such as sh steps. To run your scripts with a specific shell on Linux, use an interpreter line:

    sh '''#!/bin/bash
    for x in {0..9}; do echo x; done
    '''

    or just use a subprocess and an externally versioned script:

    sh 'bash ci.sh'

    On Windows, choose between the bat or powershell steps.

    For a pod running on Linux, defaults to sh, which should be in $PATH; for a pod running on Windows, defaults to cmd, which should be in %Path%. Should not generally be overridden.

podTemplate: Define a podTemplate to use in the kubernetes plugin

Defines a Kubernetes pod template that can be used to create nodes.

Example:

podTemplate(...) {
    node(POD_LABEL) {
        // some steps
    }
}
  • activeDeadlineSeconds : int (optional)
  • annotations (optional)
      Array / List of Nested Object
    • key : String
      The annotation key.
    • value : String
      The annotation value.
  • cloud : String (optional)
    The Kubernetes cloud to use to schedule the pod.
    If unset, the first available Kubernetes cloud will be used.
  • containers (optional)
      Array / List of Nested Object
    • name : String
      The name for the container to be run. One container is automatically created with the name jnlp, and runs the Jenkins agent. In order to replace the default agent image, the container with the agent must be named jnlp.
    • image : String
      Container image (repository, name, and tag) for a Jenkins inbound agent. Connection details will be passed as environment variables as per documentation.
    • alwaysPullImage : boolean (optional)
      If ticked, the latest version of the image will be pulled every time it is used. See Images - Kubernetes for the default Kubernetes behaviour.
    • args : String (optional)

      Arguments to pass to the command.

      ${computer.jnlpmac} and ${computer.name} are replaced with the agent secret and name respectively.

      For Windows containers the args Start-Sleep 999999 are reasonable choices to go with powershell.

    • command : String (optional)

      Override the image entrypoint with a different one.

      For Windows containers powershell is a good default.

    • envVars (optional)
      The environment variables to pass to the container.
        Array / List of Nested Choice of Objects
      • containerEnvVar
        • key : String
          The environment variable key.
        • value : String
          The environment variable value.
      • envVar
        • key : String
          The environment variable key.
        • value : String
          The environment variable value.
      • podEnvVar
        • key : String
          The environment variable key.
        • value : String
          The environment variable value.
      • secretEnvVar
        • key : String
          The environment variable key.
        • secretName : String
          Name of secret to lookup from Kubernetes.
        • secretKey : String
          Key of secret to lookup from Kubernetes.
        • optional : boolean
          Whether this secret is optional.
    • livenessProbe (optional)
        Nested Object
      • execArgs : String
        Command executed by the liveness probe.
      • timeoutSeconds : int
        Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1.
      • initialDelaySeconds : int
        Number of seconds after the container has started before liveness or readiness probes are initiated. Defaults to 0 seconds. Minimum value is 0.
      • failureThreshold : int

        When a Pod starts and the probe fails, Kubernetes will try failureThreshold times before giving up.
        Giving up in case of liveness probe means restarting the container.
        In case of readiness probe the Pod will be marked Unready. Defaults to 3. Minimum value is 1.

      • periodSeconds : int

        How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1.

      • successThreshold : int
        Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness. Minimum value is 1.
    • ports (optional)
        Array / List of Nested Object
      • name : String (optional)
        The name of the port
      • containerPort : int (optional)
        Port to expose into the pod
      • hostPort : int (optional)
        Port to expose onto the host
    • privileged : boolean (optional)
      Flag to mark the container as privileged.
    • resourceLimitCpu : String (optional)
      Kubernetes Resources Limit of CPU This value can be set to control the CPU resource limit passed when creating the Jenkins agent Docker container in Kubernetes. Unlike a resource request, this is the upper limit of resources used by your Jenkins Agent container. When left blank, the defaults of your Kubernetes cluster will be used. For more info, see the Kubernetes docs. e.g. `500m`.
    • resourceLimitEphemeralStorage : String (optional)
    • resourceLimitMemory : String (optional)
      Kubernetes Resources Limit of Memory This value can be set to control the memory resource limit passed when creating the Jenkins agent Docker container in Kubernetes. Unlike a resource request, this is the upper limit of resources used by your Jenkins Agent container. When left blank, the defaults of your Kubernetes cluster will be used. For more info, see the Kubernetes docs. e.g. `250Mi`.
    • resourceRequestCpu : String (optional)
      Kubernetes Resources Request of CPU This value can be set to control the CPU resources requested when creating the Jenkins agent Docker container in Kubernetes. When left blank, the defaults of your Kubernetes cluster will be used. For more info, see the Kubernetes docs. e.g. `500m`.
    • resourceRequestEphemeralStorage : String (optional)
    • resourceRequestMemory : String (optional)
      Kubernetes Resources Request of Memory This value can be set to control the memory resources requested when creating the Jenkins agent Docker container in Kubernetes. When left blank, the defaults of your Kubernetes cluster will be used. For more info, see the Kubernetes docs. e.g. `250Mi`.
    • runAsGroup : String (optional)
      Specify the gid to run as.
    • runAsUser : String (optional)
      Specify the uid to run as.
    • shell : String (optional)
    • ttyEnabled : boolean (optional)
      Whether this container should allocate a TTY for itself.
    • workingDir : String (optional)
      Path to the root of the workspace from the view point of this container, such as /home/jenkins/agent.
  • envVars (optional)
      Array / List of Nested Choice of Objects
    • containerEnvVar
      • key : String
        The environment variable key.
      • value : String
        The environment variable value.
    • envVar
      • key : String
        The environment variable key.
      • value : String
        The environment variable value.
    • podEnvVar
      • key : String
        The environment variable key.
      • value : String
        The environment variable value.
    • secretEnvVar
      • key : String
        The environment variable key.
      • secretName : String
        Name of secret to lookup from Kubernetes.
      • secretKey : String
        Key of secret to lookup from Kubernetes.
      • optional : boolean
        Whether this secret is optional.
  • hostNetwork : boolean (optional)
  • idleMinutes : int (optional)
  • imagePullSecrets : Array / List of String (optional)
    • inheritFrom : String (optional)
    • instanceCap : int (optional)
    • label : String (optional)
      Jenkins node label to bind. If left blank, one will be generated for you, and inside the step it will be bound to the variable POD_LABEL so you can use this as the argument to the node step.
      Example:
              podTemplate(...) {
                  node(POD_LABEL) {
                      // some steps
                  }
              }
          
    • name : String (optional)
    • namespace : String (optional)
    • nodeSelector : String (optional)
    • nodeUsageMode : String (optional)
    • podRetention (optional)
        Nested Choice of Objects
      • always
        • default
          • never
            • onFailure
            • runAsGroup : String (optional)
            • runAsUser : String (optional)
            • schedulerName : String (optional)
            • serviceAccount : String (optional)
            • showRawYaml : boolean (optional)
            • slaveConnectTimeout : int (optional)
            • supplementalGroups : String (optional)
            • volumes (optional)
                Array / List of Nested Choice of Objects
              • configMapVolume
                • mountPath : String
                  Path to mount this volume inside the pod.
                • configMapName : String
                  The name of the Kubernetes Config Map to mount into the pod.
                • optional : boolean
                  Whether this configmap needs to exist.
                • subPath : String (optional)
                  SubPath to mount this volume inside the pod.
              • dynamicPVC
                • accessModes : String (optional)
                  A PersistentVolume can be mounted on a host in any way supported by the resource provider. Providers will have different capabilities and each PV’s access modes are set to the specific modes supported by that particular volume. For example, NFS can support multiple read/write clients, but a specific NFS PV might be exported on the server as read-only. Each PV gets its own set of access modes describing that specific PV’s capabilities. Defaults to ReadWriteOnce.
                • mountPath : String (optional)
                  Path to mount this volume inside the pod.
                • requestsSize : String (optional)
                  Claims, like pods, can request specific quantities of a resource. In this case, the request is for storage. The same resource model applies to both volumes and claims. Defaults to 10Gi.
                • storageClassName : String (optional)
                  A StorageClass provides a way for administrators to describe the “classes” of storage they offer. Different classes might map to quality-of-service levels, or to backup policies, or to arbitrary policies determined by the cluster administrators. Kubernetes itself is unopinionated about what classes represent. This concept is sometimes called “profiles” in other storage systems.
              • emptyDirVolume
                • mountPath : String
                  Path to mount this volume inside the pod.
                • memory : boolean
                  Flag for in-memory volume.
              • genericEphemeralVolume
                • accessModes : String (optional)
                  A PersistentVolume can be mounted on a host in any way supported by the resource provider. Providers will have different capabilities and each PV’s access modes are set to the specific modes supported by that particular volume. For example, NFS can support multiple read/write clients, but a specific NFS PV might be exported on the server as read-only. Each PV gets its own set of access modes describing that specific PV’s capabilities. Defaults to ReadWriteOnce.
                • mountPath : String (optional)
                  Path to mount this volume inside the pod.
                • requestsSize : String (optional)
                  Claims, like pods, can request specific quantities of a resource. In this case, the request is for storage. The same resource model applies to both volumes and claims. Defaults to 10Gi.
                • storageClassName : String (optional)
                  A StorageClass provides a way for administrators to describe the “classes” of storage they offer. Different classes might map to quality-of-service levels, or to backup policies, or to arbitrary policies determined by the cluster administrators. Kubernetes itself is unopinionated about what classes represent. This concept is sometimes called “profiles” in other storage systems.
              • hostPathVolume
                • hostPath : String
                  File or directory on the host node's filesystem to mount into the pod.
                • mountPath : String
                  Path to mount this volume inside the pod.
                • readOnly : boolean
                  Flag for read-only mount, set hostPath mount to readOnly is considered best-practice.
              • nfsVolume
                • serverAddress : String
                  NFS Server Address.
                • serverPath : String
                  NFS Server Path.
                • readOnly : boolean
                • mountPath : String
                  Path to mount this volume inside the pod.
              • persistentVolumeClaim
                • mountPath : String
                  Path to mount this volume inside the pod.
                • claimName : String
                  The claim name.
                • readOnly : boolean
                  Flag for read-only volume.
              • secretVolume
                • mountPath : String
                  Path to mount this volume inside the pod.
                • secretName : String
                  The name of the Kubernetes Secret to mount into the pod.
                • defaultMode : String
                  The file permissions for the secret volume. Does not support Octal notation.
                • optional : boolean
                  Whether the secret needs to exist.
            • workingDir : String (optional)
            • workspaceVolume (optional)
                Nested Choice of Objects
              • dynamicPVC
                • accessModes : String (optional)
                  A PersistentVolume can be mounted on a host in any way supported by the resource provider. Providers will have different capabilities and each PV’s access modes are set to the specific modes supported by that particular volume. For example, NFS can support multiple read/write clients, but a specific NFS PV might be exported on the server as read-only. Each PV gets its own set of access modes describing that specific PV’s capabilities. Defaults to ReadWriteOnce.
                • requestsSize : String (optional)
                  Claims, like pods, can request specific quantities of a resource. In this case, the request is for storage. The same resource model applies to both volumes and claims. Defaults to 10Gi.
                • storageClassName : String (optional)
                  A StorageClass provides a way for administrators to describe the “classes” of storage they offer. Different classes might map to quality-of-service levels, or to backup policies, or to arbitrary policies determined by the cluster administrators. Kubernetes itself is unopinionated about what classes represent. This concept is sometimes called “profiles” in other storage systems.
              • emptyDirWorkspaceVolume
                • memory : boolean
                  Flag for in-memory volume.
              • genericEphemeralVolume
                • accessModes : String (optional)
                  A PersistentVolume can be mounted on a host in any way supported by the resource provider. Providers will have different capabilities and each PV’s access modes are set to the specific modes supported by that particular volume. For example, NFS can support multiple read/write clients, but a specific NFS PV might be exported on the server as read-only. Each PV gets its own set of access modes describing that specific PV’s capabilities. Defaults to ReadWriteOnce.
                • requestsSize : String (optional)
                  Claims, like pods, can request specific quantities of a resource. In this case, the request is for storage. The same resource model applies to both volumes and claims. Defaults to 10Gi.
                • storageClassName : String (optional)
                  A StorageClass provides a way for administrators to describe the “classes” of storage they offer. Different classes might map to quality-of-service levels, or to backup policies, or to arbitrary policies determined by the cluster administrators. Kubernetes itself is unopinionated about what classes represent. This concept is sometimes called “profiles” in other storage systems.
              • hostPathWorkspaceVolume
                • hostPath : String
                  File or directory on the host node's filesystem to mount into the pod.
              • nfsWorkspaceVolume
                • serverAddress : String
                  NFS Server Address.
                • serverPath : String
                  NFS Server Path.
                • readOnly : boolean
              • persistentVolumeClaimWorkspaceVolume
                • claimName : String
                  The claim name.
                • readOnly : boolean
                  Flag for read-only volume.
            • yaml : String (optional)
            • yamlMergeStrategy (optional)
                Nested Choice of Objects
              • merge
                • override

                kubeconfig: Setup Kubernetes CLI (kubectl)

                Configure Kubernetes client (kubectl) so it can be used in the build to run Kubernetes commands
                • serverUrl : String
                  URL of the Kubernetes API endpoint. If not set the connection options will be autoconfigured from service account or kube config file.
                • credentialsId : String
                • caCertificate : String
                  The base64 encoded certificate of the certificate authority (CA). It is used to verify the server certificate.

                  Leaving this field empty will skip the certificate verification.

                containerLog: Get container log from Kubernetes

                • name : String
                  Name of the container, as specified in containerTemplate.
                • limitBytes : int (optional)
                  If set, the number of bytes to read from the server before terminating the log output. This may not display a complete final line of logging, and may return slightly more or slightly less than the specified limit.
                • returnLog : boolean (optional)
                  Return the container log. If not checked, the log will be printed to the build log.
                • sinceSeconds : int (optional)
                  A relative time in seconds before the current time from which to show logs. If this value precedes the time a pod was started, only logs since the pod start will be returned. If this value is in the future, no logs will be returned.
                • tailingLines : int (optional)
                  If set, the number of lines from the end of the log to show. If not specified, log is shown from the creation of the container or limited by "sinceSeconds".

                Was this page helpful?

                Please submit your feedback about this page through this quick form.

                Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

                    


                See existing feedback here.