Runbook – Bootstrap Jenkins Docker Agent on Control Node (ctrl-01)¶

Purpose: Provide a Docker-based inbound agent on ctrl-01 for bootstrap execution before RKE2 agents exist.
Owner: Platform Operations
Trigger: Bootstrap window, RKE2 unavailable, or controlled fallback.
Impact: Adds an execution surface; may increase host risk if Docker socket is mounted.
Severity: P2
Pre-reqs: Jenkins controller is healthy, Docker Engine is healthy, agent image available, agent node exists in Jenkins.
Rollback strategy: Stop/remove the agent container; disable the node in Jenkins (via JCasC or approved process).

Context¶

This runbook supports the transition period where:

Jenkins controller is online on ctrl-01.
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¶

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