Runbook – Bootstrap Jenkins Docker Agent on Control Node¶

Intent¶

Purpose: Provide the Docker-based inbound agent used during bootstrap before RKE2 agents are available.
Owner: Platform Operations
Trigger: Bootstrap window, RKE2 unavailable, or controlled fallback.
Impact: Adds an execution surface and may increase host risk if the Docker socket is mounted into the agent.
Severity: P2
Pre-reqs: Jenkins controller is healthy, Docker Engine is healthy, the standard agent image is available, and the agent node exists in Jenkins.
Rollback: Stop and remove the agent container, then disable the node in Jenkins through JCasC or another approved path.

Context¶

This runbook covers the transition period where the controller is online but the steady-state RKE2 agent surface is not yet ready.

Jenkins controller is online on the control node.
Primary agents (RKE2 pod agents) are not yet available.
A labelled agent (example: ctrl-docker) is required to run early pipelines.

For long-term operation, prefer RKE2 agents.

Preconditions and safety checks¶

1) Confirm controller health:

docker ps --format "table {{.Names}}    {{.Status}}" | egrep "jenkins-controller|NAME"
curl -sS -o /dev/null -w "HTTP=%{http_code}
" http://localhost:8080/login

2) Confirm Docker network exists (or will be created):

docker network ls | awk '{print $2}' | grep -x "jenkins" || true

3) Decide operating mode:

Recommended (public/hardened): node is defined via controller JCasC; this runbook only runs the agent container and uses a provided secret (Vault/AKV).
Bootstrap convenience: role-managed node creation via Script Console (may be disabled in hardened Jenkins).

Steps¶

1) Ensure the Jenkins node exists

Preferred path: define node via controller JCasC (for example 30-nodes-docker.yaml) so no UI click-ops are required.

Validate the node is present:

TOKEN="$(sudo sh -c 'tr -d "\n" </opt/jenkins/.secrets/admin_api_token')"
curl -g -sS -u "admin:${TOKEN}"   "http://localhost:8080/computer/api/json?tree=computer[displayName,offline]"   | head -c 800 && echo

Expected result

ctrl-docker exists in the computer list (offline may be true until the container connects).

2) Obtain the inbound secret

If you are running in hardened mode, supply jenkins_agents_docker_agent_secret from your secret store.

If you are operating with explicit admin access, you may retrieve it from JNLP:

curl -sS -u "admin:${TOKEN}"   "http://localhost:8080/computer/ctrl-docker/slave-agent.jnlp"   | head -n 40

Expected result

JNLP includes an <argument> token (the secret) and the agent name.

3) Run the agent container (or apply the role)

Apply your playbook that runs hybridops.app.jenkins_agents_docker, or run the equivalent container manually.

Manual (example):

docker rm -f jenkins-agent-ctrl-docker 2>/dev/null || true

docker run -d --name jenkins-agent-ctrl-docker   --network jenkins   -e JENKINS_URL="http://jenkins-controller:8080/"   -e JENKINS_AGENT_NAME="ctrl-docker"   -e JENKINS_SECRET="<INBOUND_SECRET>"   -e AGENT_WORKDIR="/home/jenkins/agent"   -v /var/run/docker.sock:/var/run/docker.sock   hybridops/ci-agent-tools:0.1.0

Expected result

Container stays up (not restarting).
Logs show Connected.

4) Verify node online and schedule a labelled pipeline

docker logs --tail 120 jenkins-agent-ctrl-docker
curl -g -sS -u "admin:${TOKEN}"   "http://localhost:8080/computer/api/json?tree=computer[displayName,offline]"   | head -c 800 && echo

Expected result

Agent logs show successful connection.
Jenkins API shows ctrl-docker with offline:false.

Verification¶

Success criteria:

Agent container is running (Up) and not restarting.
Jenkins shows the node online.
A test pipeline can schedule to agent { label 'ctrl-docker' }.

Post-actions and clean-up¶

Disable Docker socket mounting if not required for the next phase.
Transition pipelines to RKE2 agents once available.
Rotate inbound secrets if you suspect exposure.

References¶

License: MIT-0 for code, CC-BY-4.0 for documentation