Jenkins Kubernetes Plugin

Pod templates can inherit from existing templates using the inheritFrom field.

Inheritance Rules:

• Simple values (strings): The child template overrides the parent.
• Complex values (lists, maps): The child template merges with the parent. The yamlMergeStrategy in the child controls this behavior.
• Service account & Node selector: These are completely substituted by the child.
• Container templates & Volumes: If a child defines a container or volume with the same name as one in the parent, it inherits/overrides the parent's configuration. If the name is new, it is added.
• Image Pull Secrets: These are combined (all secrets from both parent and child are used).
• Multiple Inheritance: inheritFrom can accept multiple templates separated by spaces. They are processed in order, with later items overriding earlier ones. If a template is not found, it is ignored.

podTemplate(inheritFrom: 'mypod', containers: [
    containerTemplate(name: 'maven', image: 'maven:3.9.9-eclipse-temurin-21')
  ]) {
  node(POD_LABEL) {
    …
  }
}

The Kubernetes plugin allocates Jenkins agents within Kubernetes pods.

Core Concepts

• The Agent Container: Every pod contains at least one special container running the Jenkins agent. While it defaults to the name jnlp, you can specify a different name in the pod template.
• Sidecar Containers: You can run arbitrary processes in other containers within the same pod. In Pipeline jobs, you can execute commands in these specific containers using the container step.
• Label-based Allocation: When you define a Pod Template in the Jenkins UI, you assign it a label. When a job (Freestyle or Pipeline) requests a node with that specific label (e.g., node('some-label')), the Kubernetes Cloud automatically allocates a new pod to run that build.

Best Practice: While global pod templates are useful for migrating existing freestyle projects, new users should prefer using the podTemplate step within Pipelines for better control.

You can nest podTemplate blocks within each other to compose complex environments. This is particularly useful when creating reusable Pipeline Library functions.

Crucial Requirement: When nesting, you must use the label generated by the innermost podTemplate to call the node step. This ensures the agent runs on a pod that contains all the combined containers from the outer templates.

// Example of nesting templates in a Pipeline Library
package com.foo.utils

public void dockerTemplate(body) {
  def label = "worker-${UUID.randomUUID().toString()}"
  podTemplate(label: label,
        containers: [containerTemplate(name: 'docker', image: 'docker', command: 'cat', ttyEnabled: true)],
        volumes: [hostPathVolume(hostPath: '/var/run/docker.sock', mountPath: '/var/run/docker.sock')]) {
    body.call(label)
  }
}

public void mavenTemplate(body) {
  def label = "worker-${UUID.randomUUID().toString()}"
  podTemplate(label: label,
        containers: [containerTemplate(name: 'maven', image: 'maven', command: 'cat', ttyEnabled: true)],
        volumes: [secretVolume(secretName: 'maven-settings', mountPath: '/root/.m2'),
                  persistentVolumeClaim(claimName: 'maven-local-repo', mountPath: '/root/.m2nrepo')]) {
    body.call(label)
  }
}

return this

// --- Usage in a Pipeline ---

import com.foo.utils

slaveTemplates = new PodTemplates()

slaveTemplates.dockerTemplate {
  slaveTemplates.mavenTemplate { label ->
    node(label) {
      container('docker') {
        sh 'echo from docker'
      }
      container('maven') {
        sh 'echo from maven'
      }
     }
  }
}

You can define multiple containers within a single agent pod using the containers parameter in podTemplate. Containers in the same pod share resources like mount points, and each container's ports are accessible via localhost.

Note: The container directive for executing commands in specific containers is currently in ALPHA status and may have issues with concurrency and pipeline recovery.

def label = "mypod-${UUID.randomUUID().toString()}"
podTemplate(label: label, containers: [
    containerTemplate(name: 'maven', image: 'maven:3.3.9-jdk-8-alpine', ttyEnabled: true, command: 'cat'),
    containerTemplate(name: 'golang', image: 'golang:1.8.0', ttyEnabled: true, command: 'cat')
  ]) {

    node(label) {
        stage('Get a Maven project') {
            git 'https://github.com/jenkinsci/kubernetes-plugin.git'
            container('maven') {
                stage('Build a Maven project') {
                    sh 'mvn -B clean install'
                }
            }
        }

        stage('Get a Golang project') {
            git url: 'https://github.com/hashicorp/terraform.git'
            container('golang') {
                stage('Build a Go project') {
                    sh """
                    mkdir -p /go/src/github.com/hashicorp
                    ln -s `pwd` /go/src/github.com/hashicorp/terraform
                    cd /go/src/github.com/hashicorp/terraform && make core-dev
                    """
                }
            }
        }

    }
}