Source: Dev.to

0) What “create” vs “enable” means

Create agent – define a node in the Jenkins UI (name, labels, workspace).

Enable agent – start the agent process so it connects and becomes Online.

---

A) Create a local agent on your Mac (Controller on localhost)

Step 1 – Create agent workspace folder (Terminal)

mkdir -p ~/jenkins-agent

Step 2 – Create the node in Jenkins (UI)

1. Open Jenkins: http://localhost:9090
2. Manage Jenkins → Nodes and Clouds → New Node
3. Name: mac-agent
4. Type: Permanent Agent → Create

Step 3 – Configure the node (UI)

Click Save.

---

B) Enable (bring Online) the agent – Recommended method (WebSocket)

Step 4 – Download agent.jar (Terminal)

cd ~/jenkins-agent
curl -o agent.jar http://localhost:9090/jnlpJars/agent.jar

Step 5 – Start the agent (Terminal)

Run the agent (keep this terminal open):

java -jar agent.jar \
  -url http://localhost:9090 \
  -secret  \
  -name mac-agent \
  -webSocket \
  -workDir "/Users/aisalkyn/jenkins-agent"

Where to get “:
Nodes → mac-agent → Jenkins shows the exact command and secret.

Step 6 – Confirm it’s Online (UI)

Manage Jenkins → Nodes and Clouds – you should see mac-agent = green / Online.

---

C) Run a job on the agent (proof)

Step 7 – Pipeline using label mac

pipeline {
  agent { label 'mac' }

  stages {
    stage('Proof') {
      steps {
        sh 'hostname'
        sh 'whoami'
        sh 'pwd'
      }
    }
  }
}

Expected: workspace path includes

/Users/aisalkyn/jenkins-agent/workspace/...

---

D) Common problems (fast fixes)

Agent stays Offline

Cause: Node was created but the agent process wasn’t started.
Fix: Run the WebSocket command from Step 5.

“Invalid or corrupt jarfile agent.jar”

Cause: agent.jar was downloaded via a tunnel/redirect.
Fix: Re‑download directly:

curl -o agent.jar http://localhost:9090/jnlpJars/agent.jar

Jenkins won’t start (Java version)

Jenkins supports Java 17/21. Start Jenkins with Java 21 explicitly:

/opt/homebrew/opt/openjdk@21/bin/java -jar /opt/homebrew/opt/jenkins-lts/libexec/jenkins.war \
  --httpPort=9090 --httpListenAddress=127.0.0.1

Pipeline stuck “Still waiting to schedule task”

Cause: Label mismatch or agent offline.
Fix: Ensure the node has label mac and the agent is Online.

---

E) What to say in interviews (1 sentence)

“I create agents under Nodes, assign labels, and connect them using WebSocket so builds run on workers without opening inbound TCP ports.”

---

LAB: Jenkins Agents — Scheduling, Labels, Parallelism, and Scaling

This lab uses the agent you already created (mac-agent) and teaches:

• how Jenkins schedules work
• why agents matter
• when you need more agents

---

LAB 1 — Prove the build runs on the agent (baseline)

Goal

Verify that jobs do not run on the controller, but on mac-agent.

Jenkinsfile (Job 1)

pipeline {
  agent { label 'mac' }

  stages {
    stage('Where am I running?') {
      steps {
        sh 'echo "Node name: $NODE_NAME"'
        sh 'hostname'
        sh 'whoami'
        sh 'pwd'
      }
    }
  }
}

Expected result

• NODE_NAME = mac-agent
• Workspace path:

/Users/aisalkyn/jenkins-agent/workspace/...

DevOps takeaway: Agent labels decide where code runs.

---

LAB 2 — What happens if the agent is offline?

Goal

Understand why jobs get stuck.

Steps

1. Stop the agent process (Ctrl+C in the terminal).
2. Click Build Now on the job.

Result

Job remains in Build Queue with message:

Still waiting to schedule task
mac-agent is offline

DevOps takeaway: Jenkins does not start agents automatically; they must be alive for jobs to run.

---

LAB 3 — Controller vs Agent (anti‑pattern demo)

Goal

Show why running on the controller is a bad practice.

Jenkinsfile (Job 2)

pipeline {
  agent any

  stages {
    stage('Controller test') {
      steps {
        sh 'echo "Running on $NODE_NAME"'
      }
    }
  }
}

Result

Runs on the Built‑In Node (the controller).

Explain to students: The controller should not:

• build Docker images
• run Terraform
• execute heavy tests

DevOps rule: agent any is dangerous in production.

---

LAB 4 — Labels control scheduling (important)

Goal

Show how labels select agents.

Step

Change the label in the Jenkinsfile to something that does not exist:

agent { label 'linux' }

Result

• Job is stuck in the queue (no matching agent).

Fix

Revert to a valid label:

agent { label 'mac' }

---

End of cleaned markdown.

DevOps Takeaway

Label mismatch = no execution.

---

LAB 5 — Parallel builds with a single agent

Goal

Show executor limitation.

Jenkinsfile (Job 3)

pipeline {
  agent { label 'mac' }

  stages {
    stage('Parallel test') {
      parallel {
        stage('Task A') {
          steps {
            sh 'sleep 20'
          }
        }
        stage('Task B') {
          steps {
            sh 'sleep 20'
          }
        }
      }
    }
  }
}

Result

• One stage runs.
• The other waits.

Why?
mac-agent has 1 executor.

---

LAB 6 — Increase executors vs. add agents

Option A — Increase executors

In mac‑agent configuration set Executors: 2.
Re‑run the job → both stages run in parallel.

Option B — Add another agent

Create mac-agent-2 with 1 executor.

DevOps Rule

---

LAB 7 — Simulate real DevOps workloads

Jenkinsfile

pipeline {
  agent { label 'mac' }

  stages {
    stage('Build') {
      steps {
        sh 'echo "Building..."'
        sh 'sleep 10'
      }
    }

    stage('Test') {
      steps {
        sh 'echo "Testing..."'
        sh 'sleep 10'
      }
    }

    stage('Package') {
      steps {
        sh 'echo "Packaging..."'
        sh 'sleep 10'
      }
    }
  }
}

Explain

In real CI:

• build → test → scan → package
• All steps are executed by agents, not the controller.

---

Do you NEED more agents?

Short answer

• Right now: NO
• In real DevOps: YES

When ONE agent is enough

• Learning Jenkins
• Demos
• Small team
• Sequential pipelines

You are here now ✅

When you MUST add more agents

1. Parallel pipelines

   • Multiple developers pushing code
   • CI jobs pile up

2. Different tools

   • One agent for Docker
   • One for Terraform
   • One for security scans

3. Different OS

   • Linux agent
   • Windows agent
   • macOS agent

4. Security isolation

   • Production‑deploy agent ≠ build agent

Real‑world DevOps setup (typical)

---

Interview‑ready conclusion (memorize)

“I start with one agent for learning, but in real DevOps we use multiple, often ephemeral agents to handle parallel builds, isolation, security, and different environments.”