Agent types (permanent, cloud) in Jenkins - Commands & Configuration

Introduction

Jenkins uses agents to run tasks. Permanent agents are always ready on your own machines. Cloud agents start when needed and stop after use, saving resources.

When you want a dedicated machine always ready to run Jenkins jobs without delay.

When you want to save costs by using cloud machines only during job execution.

When you need to run jobs on different operating systems or environments dynamically.

When you want to scale Jenkins capacity automatically based on workload.

When you want to isolate jobs to avoid interference by running them on separate cloud agents.

Config File - jenkins-agent-config.xml

jenkins-agent-config.xml

<slave>
  <name>permanent-agent-1</name>
  <description>Permanent agent on local server</description>
  <remoteFS>/home/jenkins</remoteFS>
  <numExecutors>2</numExecutors>
  <mode>NORMAL</mode>
  <retentionStrategy class="hudson.slaves.RetentionStrategy$Always"/>
  <launcher class="hudson.slaves.JNLPLauncher"/>
  <label>linux permanent</label>
</slave>

This XML configures a permanent Jenkins agent.

name: The agent's name.

remoteFS: The directory Jenkins uses on the agent machine.

numExecutors: How many jobs can run at once.

retentionStrategy: 'Always' means the agent stays connected all the time.

launcher: JNLPLauncher means the agent connects to Jenkins.

label: Used to assign jobs to this agent.

Commands

Starts the permanent agent by connecting it to the Jenkins master using the JNLP protocol and secret key.

Terminal

java -jar agent.jar -jnlpUrl http://jenkins.example.com/computer/permanent-agent-1/slave-agent.jnlp -secret 1234567890abcdef

Expected Output

[Jenkins agent] Connected

Agent permanent-agent-1 is online

→

-jnlpUrl - URL to connect the agent to Jenkins master

→

-secret - Secret key for secure connection

Installs the cloud agent plugin to enable dynamic cloud agents in Jenkins.

Terminal

jenkins-plugin-cli --plugins cloud-agent

Expected Output

Installing plugin: cloud-agent

Plugin cloud-agent installed successfully

Creates a cloud agent template node in Jenkins from an XML configuration file.

Terminal

jenkins-cli create-node cloud-agent-template < cloud-agent-template.xml

Expected Output

Node cloud-agent-template created

Lists all configured Jenkins nodes including permanent and cloud agents.

Terminal

jenkins-cli list-nodes

Expected Output

master

permanent-agent-1

cloud-agent-template

Key Concept

Permanent agents are always ready machines; cloud agents start and stop on demand to save resources.

Common Mistakes

Trying to use a permanent agent without starting its agent process.

The agent won't connect to Jenkins, so jobs assigned to it will not run.

Run the agent.jar command with correct URL and secret to connect the agent.

Not installing or configuring the cloud agent plugin before creating cloud agents.

Jenkins cannot create or manage cloud agents without the plugin.

Install the cloud agent plugin first using jenkins-plugin-cli.

Assigning jobs to cloud agents without a proper cloud agent template configured.

Jenkins cannot provision cloud agents dynamically, so jobs will fail to run.

Create and configure a cloud agent template node before assigning jobs.

Summary

Permanent agents run continuously on dedicated machines and connect to Jenkins using JNLP.

Cloud agents are created dynamically using templates and plugins to save resources.

Commands include starting agents, installing plugins, creating nodes, and listing nodes.