Standardise the CI agent tools image for Docker and RKE2 Jenkins agents¶

Status¶

Accepted

1. Context¶

HybridOps pipelines need a repeatable worker toolchain across both of the agent surfaces used by Jenkins:

a Docker-based bootstrap agent on the control node
the preferred steady-state agents running on RKE2

Without a standard agent image, the build surface drifts:

tools appear in one agent type but not another
versions diverge across Docker and Kubernetes workers
troubleshooting becomes slower because failures are tied to image variance

The platform needs one versioned worker image that can be promoted across both execution environments.

2. Decision¶

HybridOps standardises on a single CI agent tools image for Jenkins agents.

That image:

is versioned and promoted deliberately
is used by Docker bootstrap agents and RKE2 pod agents
contains the baseline toolchain required by HybridOps delivery workflows
is treated as part of the platform release surface rather than ad hoc local worker setup

The Jenkins controller does not become the place where build tools accumulate. Tooling belongs in agent images.

3. Rationale¶

3.1 One worker contract across two execution surfaces¶

The Docker bootstrap agent and the RKE2 agents exist for different lifecycle stages, but they should behave the same from the pipeline point of view.

3.2 Better repeatability¶

A pinned image version gives:

clearer promotion and rollback
cleaner debugging
fewer environment-specific pipeline surprises

3.3 Cleaner controller posture¶

Keeping tools in the agent image rather than on the controller host reduces drift and keeps the controller focused on coordination.

4. Consequences¶

Positive¶

Docker and RKE2 Jenkins agents share one expected toolchain
image changes become auditable and versioned
pipeline authors can target one baseline instead of many local variants

Trade-offs¶

the agent image becomes a maintained platform artifact
image updates must be tested before rollout
urgent tooling additions need release discipline rather than host-local edits

5. Implementation notes¶

The CI agent tools image should carry the tools required by the supported pipeline set, such as:

container client tooling
infrastructure delivery tooling
automation and validation tooling

Exact package selection can evolve, but the decision does not: Jenkins agents should consume a standard image instead of assembling their toolchain ad hoc at runtime.

6. Validation¶

This decision is considered implemented when:

Docker bootstrap agents and RKE2 agents use the same published image lineage
supported Jenkins runbooks and HOWTOs reference that image consistently
platform pipelines execute successfully on the standard image without relying on controller-local tools

7. References¶

Maintainer: HybridOps
License: MIT-0 for code, CC BY 4.0 for documentation unless otherwise stated.