Kubernetes agents in Jenkins - Commands & Configuration

Introduction

Kubernetes agents in Jenkins let you run your build jobs inside Kubernetes pods. This helps you use containers to isolate builds and scale your build environment automatically.

When you want to run Jenkins build jobs in isolated containers to avoid conflicts.

When you need to scale Jenkins build capacity up or down automatically based on demand.

When you want to use Kubernetes to manage the lifecycle of Jenkins build agents.

When you want to run different build environments for different projects without manual setup.

When you want to reduce resource waste by creating agents only when needed.

Config File - kubernetes-agent.yaml

kubernetes-agent.yaml

apiVersion: v1
kind: Pod
metadata:
  labels:
    jenkins-agent: "true"
spec:
  containers:
  - name: jnlp
    image: jenkins/inbound-agent:4.10-4
    args: ['$(JENKINS_SECRET)', '$(JENKINS_NAME)']
    env:
    - name: JENKINS_URL
      value: "http://jenkins.example.com"
  restartPolicy: Never

This YAML defines a Kubernetes pod for a Jenkins agent.

• apiVersion, kind: Define this as a pod resource.
• metadata.labels: Labels help Jenkins identify this pod as an agent.
• spec.containers: Defines the container running the Jenkins inbound agent.
• args: Passes Jenkins secret and agent name for secure connection.
• env: Sets the Jenkins server URL for the agent to connect.
• restartPolicy: Never restart the pod automatically after completion.

Commands

This command creates the Kubernetes pod that will act as a Jenkins agent. It tells Kubernetes to start the pod defined in the YAML file.

Terminal

kubectl apply -f kubernetes-agent.yaml

Expected Output

pod/kubernetes-agent created

This command lists all pods labeled as Jenkins agents to check if the agent pod is running.

Terminal

kubectl get pods -l jenkins-agent=true

Expected Output

NAME               READY   STATUS    RESTARTS   AGE

kubernetes-agent   1/1     Running   0          10s

→

-l - Filter pods by label

This command shows the logs of the Jenkins agent pod to verify it connected successfully to the Jenkins server.

Terminal

kubectl logs pod/kubernetes-agent

Expected Output

INFO: Connected to Jenkins at http://jenkins.example.com

INFO: Agent started

Key Concept

If you remember nothing else from this pattern, remember: Kubernetes agents let Jenkins run builds inside pods that start and stop automatically, giving you isolated and scalable build environments.

Common Mistakes

Not setting the correct JENKINS_URL environment variable in the pod spec.

The agent cannot connect to the Jenkins server without the correct URL, so builds will fail to start.

Always set JENKINS_URL to your Jenkins server's full URL in the pod environment variables.

Forgetting to label the pod with 'jenkins-agent=true'.

Jenkins uses this label to find agent pods; without it, Jenkins won't recognize the pod as an agent.

Add the label 'jenkins-agent: true' under metadata.labels in the pod YAML.

Using a restartPolicy other than 'Never' for the agent pod.

If the pod restarts automatically, it can cause duplicate agents or resource waste.

Set restartPolicy to 'Never' so pods stop after the build completes.

Summary

Create a Kubernetes pod YAML that defines the Jenkins agent container and connection details.

Apply the YAML with kubectl to start the agent pod in the cluster.

Verify the pod is running and check logs to confirm the agent connected to Jenkins.