How to Use Kubernetes as Jenkins Agent for Scalable Builds

To use Kubernetes as an agent in Jenkins, install the Kubernetes plugin in Jenkins and configure a Kubernetes cloud with your cluster details. Then define pod templates that specify containers and resources for Jenkins agents, allowing Jenkins to dynamically create agents as Kubernetes pods for running jobs.

Syntax

The main steps to use Kubernetes as Jenkins agent involve configuring Jenkins with Kubernetes plugin and defining pod templates.

• Kubernetes Cloud Configuration: Connect Jenkins to your Kubernetes cluster by providing the API URL and credentials.
• Pod Template: Define the pod specification including containers, images, and resource limits.
• Agent Usage: Jenkins dynamically launches pods as agents to run build jobs.

groovy

kubernetes {
  cloudName('k8s')
  serverUrl('https://<k8s-api-server>')
  credentialsId('k8s-credentials')
  podTemplate {
    label('jenkins-agent')
    containers {
      containerTemplate {
        name('jnlp')
        image('jenkins/inbound-agent:latest')
        args('${computer.jnlpmac} ${computer.name}')
      }
    }
  }
}

Example

This example shows how to configure Jenkins to use Kubernetes as an agent by setting up a Kubernetes cloud and a pod template with a single container running the Jenkins inbound agent.

groovy

pipeline {
  agent {
    kubernetes {
      label 'k8s-agent'
      defaultContainer 'jnlp'
      yaml '''
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: jnlp
    image: jenkins/inbound-agent:latest
    args: ['$(JENKINS_SECRET)', '$(JENKINS_NAME)']
'''
    }
  }
  stages {
    stage('Build') {
      steps {
        container('jnlp') {
          sh 'echo Hello from Kubernetes Jenkins Agent'
        }
      }
    }
  }
}

Output

Hello from Kubernetes Jenkins Agent

Common Pitfalls

• Missing or incorrect Kubernetes credentials: Jenkins cannot connect to the cluster without proper API access.
• Pod template misconfiguration: Wrong container image or missing args can cause agent pods to fail starting.
• Resource limits not set: Can cause pods to be evicted or starved in busy clusters.
• Network policies blocking communication: Jenkins master must reach agent pods and vice versa.

groovy

/* Wrong pod template example (missing args) */
podTemplate {
  containers {
    containerTemplate {
      name('jnlp')
      image('jenkins/inbound-agent:latest')
      // Missing args causes agent to fail
    }
  }
}

/* Correct pod template example */
podTemplate {
  containers {
    containerTemplate {
      name('jnlp')
      image('jenkins/inbound-agent:latest')
      args('${computer.jnlpmac} ${computer.name}')
    }
  }
}

Quick Reference

Tips for using Kubernetes as Jenkins agent:

• Always install and configure the Kubernetes plugin in Jenkins.
• Use jenkins/inbound-agent image for the agent container.
• Define pod templates with proper args to connect agents.
• Set resource requests and limits to avoid pod eviction.
• Ensure Jenkins master can communicate with Kubernetes API and pods.

Key Takeaways

Install the Kubernetes plugin in Jenkins to enable Kubernetes agent support.

Configure Kubernetes cloud with API URL and credentials in Jenkins settings.

Define pod templates specifying containers and connection args for agents.

Jenkins dynamically creates Kubernetes pods as agents to run jobs.

Check credentials, pod specs, and network access to avoid common errors.