Checkpoint Lab — SSH, Inbound, WebSocket, Windows, and Ephemeral Agents: Connectivity, Remoting, and Agent Lifecycle

1. Scenario

You maintain a Jenkins controller behind HTTPS. General CI workers are agent-initiated because the controller cannot initiate connections into the worker network. Build evidence must survive worker replacement. Your task is to create one disposable WebSocket worker, run a build, force a disconnect, recover once, then replace the worker identity entirely.

2. Baseline and assumptions

• Jenkins 2.568.3 LTS; controller Java 21.
• Agent JVM: Java 21.
• Built-in node executors: 0.
• Primary node: ch18-ws-a, label ch18-remote, one executor.
• Reviewed container option: jenkins/inbound-agent:3391.va_37fa_a_305d6d-2-jdk21; record architecture-specific digest if used.
• Manual-JAR option: agent.jar downloaded from this controller.
• No proprietary repository, production credential or external deployment target.

3. Preflight evidence

Record:

• controller core and Java versions;
• node name, labels, executor count, launcher and remote root;
• agent Java version and Remoting/image identity;
• Jenkins URL hostname and whether WebSocket traverses a proxy;
• source repository URL + exact commit SHA for the synthetic Jenkinsfile;
• build job full name and expected artifact name;

Record only the inbound credential reference/handling method, never the secret.

4. Predict two state changes before acting

1. Disconnect prediction: when ch18-ws-a is terminated, Jenkins will mark the node offline; one new job requiring ch18-remote will wait rather than run on the built-in node.
2. Recreation prediction: after replacing the worker with ch18-ws-b, the old workspace disappears, but build A’s Jenkins record and archived evidence remain addressable by the original build number/source SHA.

5. Checkpoint Pipeline

pipeline {
  agent { label 'ch18-remote' }
  options { timestamps(); timeout(time: 5, unit: 'MINUTES') }
  stages {
    stage('Capture') {
      steps {
        sh '''
          set -eu
          mkdir -p out
          {
            echo "job=$JOB_NAME"
            echo "build=$BUILD_NUMBER"
            echo "node=$NODE_NAME"
            echo "labels=$NODE_LABELS"
            echo "workspace=$WORKSPACE"
            echo "source=${GIT_COMMIT:-synthetic-no-scm}"
            id
            java -version 2>&1 | head -n 3
          } | tee out/agent-evidence.txt
          sha256sum out/agent-evidence.txt | tee out/agent-evidence.sha256
        '''
        archiveArtifacts artifacts: 'out/*', fingerprint: true
      }
    }
    stage('Safe wait for disconnect drill') {
      steps { sleep time: 90, unit: 'SECONDS' }
    }
    stage('Post-wait identity') {
      steps {
        sh 'printf "node=%s workspace=%s\\n" "$NODE_NAME" "$WORKSPACE"'
      }
    }
  }
}

If your Pipeline is SCM-backed, record the exact commit SHA. If it is not, state that limitation explicitly rather than inventing a source identity.

6. Connect ch18-ws-a

Use either the controller’s agent.jar or the pinned official inbound image. Supply the secret through a protected file or runtime secret mechanism, not source control or a build parameter. Confirm the node shows online and capture a redacted connection log including Remoting version and Java/work-dir evidence.

7. Run build A and preserve baseline evidence

Trigger the Pipeline. During the safe wait, preserve build number/URL, node/workspace, source SHA, archive digest and agent connection state. This is the baseline that must remain attributable after the worker disappears.

8. Force the disconnect

During the 90-second wait, stop the disposable process/container for ch18-ws-a. Capture the first disconnect evidence before taking further action:

• agent log ending/channel close;
• node offline state/cause;
• build A stage/result at that moment;
• one additional queued build B and its why text.

Do not assume build A must resume or must fail; record the actual step behavior.

9. Recover once, safely

Restart ch18-ws-a once using the same valid configured identity. Capture the reconnection event and final build A state. If build A does not resume, preserve the error and do not hide it with repeated retries. Run one short new build only if needed to prove the node is healthy.

10. Destroy/recreate the agent identity

1. Stop ch18-ws-a permanently.
2. Preserve evidence from its remote root, then remove the disposable root.
3. Create node ch18-ws-b with label ch18-remote and a new remote root.
4. Connect using its new inbound material.
5. Run build C using the same reviewed Jenkinsfile/source revision.
6. Verify build C records ch18-ws-b and its new workspace while build A remains unchanged.

11. Verification checklist

• Built-in node remained at zero executors throughout.
• Agent Java is supported and Remoting/image identity is recorded.
• Build A remains linked to its original build number, source revision and archived SHA-256 evidence.
• Queued build B never silently ran on the controller.
• Replacement build C ran on ch18-ws-b with a different workspace/root.
• Old ch18-ws-a workspace/root was removed after evidence capture.
• No inbound secret, SSH key or API token appears in console output or archived files.
• Disconnect/reconnect/replacement timestamps and actual build outcomes are recorded without rewriting history.

12. Required evidence packet

• baseline.md: Jenkins/Java versions, built-in executors, launcher and proxy assumptions.
• agent-a.md: node labels, remote root, Java, Remoting/image tag+digest and redacted connection evidence.
• build-a.json or reviewed metadata: build number/URL/cause/source/node/result.
• agent-evidence.txt + SHA-256 digest from build A.
• disconnect.md: timestamp, first agent/controller evidence, actual stage/result.
• queue-b.json: reviewed queue item ID/reason while the agent is offline.
• reconnect.md: single recovery attempt and outcome.
• agent-b.md: new node identity, Java/Remoting/image evidence and new workspace root.
• build-c.json: replacement build attribution.
• teardown.md: old/new worker root cleanup and credential-reference retirement; no secret values.
• assumptions-limitations.md: local simulation boundaries and any missing Windows/SSH direct run.

13. Cleanup and rollback

1. Stop replacement agent process/container.
2. Remove disposable work directories after reviewed evidence is saved.
3. Retire/delete disposable nodes and their inbound material.
4. Remove lab-only SSH keys/known-host entries if an SSH variant was used.
5. Remove lab-only API credentials.
6. Keep only non-secret evidence needed for learning.

14. What Chapter 18 adds to the production operating model

You can now explain an agent connection as a chain of independently verifiable state: controller node configuration selects a launcher; bootstrap identity authenticates the intended peer; transport crosses firewall/proxy/SSH boundaries; Remoting creates the channel; a supported Java process exposes executors/workspaces under an OS identity; and teardown must remove transient worker state without erasing retained build/source evidence.

Chapter 19 builds on this lifecycle model by placing build steps inside Docker environments and examining Docker Pipeline, sidecars, registries and image workflows.

Knowledge check

Answer before revealing the explanation.

Official references and version notes

• Jenkins LTS changelog and Java support policy — lab baseline Jenkins 2.568.3 LTS; Jenkins system components, including agents, require Java 21 or 25 on this baseline.
• Using Jenkins agents and Managing Nodes — distributed execution, node configuration, Windows agent examples, and lifecycle concepts.
• Jenkins Remoting and Launching inbound agents — obtain agent.jar from the controller; inbound command, -webSocket, work directory, and direct TCP guidance.
• SSH Build Agents plugin — baseline 3.1097.v868116049892; SSH launch requires verified server identity and least-privilege agent credentials.
• Official Jenkins inbound-agent images — reviewed lab image line jenkins/inbound-agent:3391.va_37fa_a_305d6d-2-jdk21. Pin a reviewed tag/digest for repeatable labs rather than using latest.
• Controller Isolation — keep the built-in node at zero executors and do not use controller-local builds as a connectivity workaround.
• Installing Jenkins — standalone Jenkins uses the supported Jetty/Winstone stack; WebSocket-agent support depends on a compatible servlet/proxy path.