Agent Directive and Execution Environments
You'll learn: How to control exactly where and in what environment each part of your Jenkins pipeline runs using the agent directive.
What Is the Agent Directive?
In Jenkins pipelines, the agent directive tells Jenkins where to execute your pipeline code. Think of it like assigning tasks to specific workers: some tasks need a chef's kitchen, others need a carpenter's workshop. Similarly, some build steps need Docker, others need specific operating systems or tools.
The agent directive can appear at the pipeline level (applies to all stages) or stage level (overrides for specific stages).
Common Agent Types
Any Available Agent
agent any
Runs on any available Jenkins agent—no preferences.
Agent Labels
agent { label 'linux' }
Targets agents with specific labels (tags you assign in Jenkins configuration). Perfect for OS-specific builds or machines with particular software.
Docker Containers
agent {
docker { image 'node:18' }
}
Spins up a Docker container from the specified image and runs your pipeline steps inside it. This ensures a consistent, isolated environment every time.
Kubernetes Pods
agent {
kubernetes {
yaml '''
spec:
containers:
- name: maven
image: maven:3.8.1
'''
}
}
Creates a temporary Kubernetes pod with specific containers for your build—ideal for cloud-native workflows.
Why This Matters
Different stages often need different tools. Your test stage might need Node.js, while deployment needs kubectl. The agent directive lets you right-size each execution environment without installing everything everywhere.
Key Takeaway: The agent directive controls where and in what environment your pipeline stages execute, enabling you to use agent labels for specific machines, Docker images for isolated containers, or Kubernetes pods for cloud-native builds.