Agent availability and offline handling in Jenkins - Commands & Configuration

Introduction

Jenkins uses agents to run tasks. Sometimes agents go offline or become unavailable. Managing agent availability helps keep your builds running smoothly without interruptions.

When a build job is stuck because the assigned agent is offline.

When you want to check which agents are ready to run jobs.

When you need to bring an offline agent back online to continue work.

When you want to temporarily disable an agent for maintenance.

When you want Jenkins to automatically handle offline agents to avoid build failures.

Commands

This command starts a Jenkins agent by connecting it to the Jenkins master using the JNLP URL and secret key. It brings the agent online so it can run jobs.

Terminal

java -jar agent.jar -jnlpUrl http://localhost:8080/computer/my-agent/slave-agent.jnlp -secret 1234567890abcdef

Expected Output

[Jenkins agent] Connecting to http://localhost:8080/computer/my-agent/slave-agent.jnlp

[Jenkins agent] Connected

[Jenkins agent] Agent successfully connected and online

→

-jnlpUrl - Specifies the URL to connect the agent to the Jenkins master

→

-secret - Provides the secret key for secure authentication

This command disconnects the Jenkins agent from the master, making it go offline. Use this to safely take an agent offline for maintenance.

Terminal

java -jar agent.jar -disconnect

Expected Output

[Jenkins agent] Disconnecting from Jenkins master

[Jenkins agent] Agent disconnected and offline

This command toggles the offline status of the agent named 'my-agent' using Jenkins REST API. It can bring the agent online or offline remotely.

Terminal

curl -X POST http://localhost:8080/computer/my-agent/toggleOffline

Expected Output

No output (command runs silently)

→

-X POST - Sends a POST request to change the agent status

Starts the Jenkins agent with a specified working directory. This helps organize files and logs for the agent.

Terminal

java -jar agent.jar -jnlpUrl http://localhost:8080/computer/my-agent/slave-agent.jnlp -secret 1234567890abcdef -workDir "."

Expected Output

[Jenkins agent] Connecting to http://localhost:8080/computer/my-agent/slave-agent.jnlp

[Jenkins agent] Connected

[Jenkins agent] Agent successfully connected and online

→

-workDir - Sets the working directory for the agent files

Key Concept

If you remember nothing else from this pattern, remember: keeping Jenkins agents online and properly connected ensures your build jobs run without interruption.

Common Mistakes

Trying to run jobs on an agent that is offline.

The job will fail or stay queued because the agent is not available to execute it.

Check agent status and bring the agent online before running jobs.

Not providing the correct secret key when starting the agent.

The agent will fail to authenticate and stay disconnected.

Use the exact secret key from Jenkins agent configuration when starting the agent.

Forgetting to disconnect an agent properly before maintenance.

Jenkins may still try to send jobs to the agent, causing failures.

Use the disconnect command or Jenkins UI to take the agent offline safely.

Summary

Start Jenkins agents with the correct JNLP URL and secret to bring them online.

Use disconnect commands or Jenkins UI to take agents offline safely for maintenance.

Check agent status regularly to avoid build failures caused by offline agents.

Practice

1. What does it mean when a Jenkins agent is marked as offline?

easy

A. The agent is connected and ready to accept jobs.

B. The agent is not available to run any jobs.

C. The agent is running a job currently.

D. The agent is permanently deleted from Jenkins.

Solution

1. Step 1: Understand agent status meaning

   In Jenkins, an agent marked offline means it is not available to run jobs.

2. Step 2: Differentiate from other statuses

   Online agents are connected and ready; offline means unavailable temporarily or for maintenance.

3. Final Answer:

   The agent is not available to run any jobs. -> Option B

4. Quick Check:

   Offline agent = unavailable [OK]

Hint: Offline means agent can't run jobs now [OK]

Common Mistakes:

• Confusing offline with running a job
• Thinking offline means deleted
• Assuming offline means ready

2. Which of the following is the correct way to mark a Jenkins agent as offline using the Jenkins CLI?

easy

A. jenkins-cli offline-agent --name agent1

B. java -jar jenkins-cli.jar offline-agent agent1

C. java -jar jenkins-cli.jar offline-agent --agent agent1

D. java -jar jenkins-cli.jar disconnect-node agent1

Solution

1. Step 1: Recall Jenkins CLI command for offline

   The correct command to mark an agent offline is disconnect-node with the agent name as argument.

2. Step 2: Check syntax correctness

   Options A, B, and C use incorrect commands or flags; only java -jar jenkins-cli.jar disconnect-node agent1 uses the correct command and syntax.

3. Final Answer:

   java -jar jenkins-cli.jar disconnect-node agent1 -> Option D

4. Quick Check:

   disconnect-node command marks offline [OK]

Hint: Use 'disconnect-node' command with agent name [OK]

Common Mistakes:

• Using wrong command names like offline-agent
• Adding incorrect flags
• Confusing CLI syntax

3. Given this Jenkins pipeline snippet:

node('agent1') {
  echo "Agent status: ${env.NODE_NAME}"
}

If agent1 is offline, what will happen when this pipeline runs?

medium

A. The pipeline will fail immediately with an error.

B. The pipeline will run on the master node instead.

C. The pipeline will wait until agent1 comes online.

D. The pipeline will skip the node block and continue.

Solution

1. Step 1: Understand node block behavior

   The node('agent1') block waits for the specified agent to be available before running.

2. Step 2: Check what happens if agent is offline

   If agent1 is offline, Jenkins will wait until it comes online or timeout occurs.

3. Final Answer:

   The pipeline will wait until agent1 comes online. -> Option C

4. Quick Check:

   node waits for agent online [OK]

Hint: node waits for specified agent to be online [OK]

Common Mistakes:

• Assuming pipeline fails immediately
• Thinking it runs on master automatically
• Believing it skips the node block

4. You have a Jenkins agent that should be offline for maintenance, but jobs are still assigned to it. What is the most likely cause?

medium

A. The agent was not properly marked offline in Jenkins configuration.

B. The agent is offline but Jenkins is ignoring the status due to a plugin bug.

C. The agent was marked offline but the 'Accept tasks' option is still enabled.

D. The jobs are configured to run only on the master node.

Solution

1. Step 1: Check agent offline marking

   If jobs are still assigned, likely the agent was not properly marked offline in Jenkins UI or configuration.

2. Step 2: Eliminate other causes

   The agent was marked offline but the 'Accept tasks' option is still enabled. is incorrect because offline agents do not accept tasks; The agent is offline but Jenkins is ignoring the status due to a plugin bug. is rare; The jobs are configured to run only on the master node. is unrelated.

3. Final Answer:

   The agent was not properly marked offline in Jenkins configuration. -> Option A

4. Quick Check:

   Proper offline marking stops job assignment [OK]

Hint: Ensure agent is correctly marked offline in Jenkins UI [OK]

Common Mistakes:

• Assuming offline agent still accepts tasks
• Blaming plugins without checking config
• Confusing job node assignment

5. You want to create a Jenkins pipeline that automatically skips running on an agent if it is offline and instead runs on the master node. Which scripted pipeline snippet achieves this?

hard

A. if (Jenkins.instance.getNode('agent1').toComputer().isOnline()) {
node('agent1') { echo 'Running on agent1' }
} else {
node('master') { echo 'Running on master' }
}

B. node('agent1') {
if (agent1.isOnline()) {
echo 'Running on agent1'
} else {
node('master') { echo 'Running on master' }
}
}

C. try {
node('agent1') { echo 'Running on agent1' }
} catch (Exception e) {
node('master') { echo 'Running on master' }
}

D. node('agent1') {
echo 'Running on agent1'
}
node('master') {
echo 'Running on master'
}

Solution

1. Step 1: Check agent online status in pipeline

   if (Jenkins.instance.getNode('agent1').toComputer().isOnline()) { node('agent1') { echo 'Running on agent1' } } else { node('master') { echo 'Running on master' } } correctly checks if 'agent1' is online using Jenkins API before choosing node.

2. Step 2: Verify fallback to master node

   If agent1 is offline, if (Jenkins.instance.getNode('agent1').toComputer().isOnline()) { node('agent1') { echo 'Running on agent1' } } else { node('master') { echo 'Running on master' } } runs the job on 'master' node, matching the requirement.

3. Step 3: Analyze other options

   node('agent1') { if (agent1.isOnline()) { echo 'Running on agent1' } else { node('master') { echo 'Running on master' } } } uses invalid syntax; try { node('agent1') { echo 'Running on agent1' } } catch (Exception e) { node('master') { echo 'Running on master' } } relies on exception which is not best practice; node('agent1') { echo 'Running on agent1' } node('master') { echo 'Running on master' } runs both nodes unconditionally.

4. Final Answer:

   if (Jenkins.instance.getNode('agent1').toComputer().isOnline()) { node('agent1') { echo 'Running on agent1' } } else { node('master') { echo 'Running on master' } } -> Option A

5. Quick Check:

   Check agent online status before node selection [OK]

Hint: Check agent online status via Jenkins API before node [OK]

Common Mistakes:

• Using invalid syntax to check agent status
• Relying on exceptions to handle offline agents
• Running both nodes regardless of status