Jenkins Kubernetes Plugin: Dynamic Build Agents in Kubernetes Pods

What the Plugin Does and Who Needs It

The Jenkins Kubernetes plugin allocates a Kubernetes pod for every Jenkins build agent. The pod starts when Jenkins needs an agent, runs the build, and is stopped after the build completes. This lifecycle eliminates idle agent VMs and lets the cluster scheduler bin-pack build work onto available nodes.

The plugin injects four environment variables into the agent pod that the Jenkins agent JAR uses to connect back to the controller: `JENKINS_URL`, `JENKINS_SECRET`, `JENKINS_AGENT_NAME` and `JENKINS_NAME` (the last one is deprecated but kept for backward compatibility). Agents are launched as inbound agents, so the container reaches out to the Jenkins controller rather than the controller reaching into the pod.

It is not required to run the Jenkins controller inside Kubernetes. A controller on bare metal or a virtual machine can manage pods in a remote cluster, which is useful for organizations that have an existing Jenkins instance and want to move only the build workers onto Kubernetes.

Prerequisites and Initial Configuration

The plugin requires a running Kubernetes cluster at version 1.14 or later. OpenShift users need OpenShift Container Platform 4.x. A ServiceAccount with sufficient RBAC privileges must exist in the cluster before any pods can be scheduled; the repository provides an example at `src/main/kubernetes/service-account.yml`.

Configuration lives in the Jenkins UI under Manage Jenkins, then Manage Nodes and Clouds, then Configure Clouds. Adding a new cloud of type Kubernetes opens fields for the Kubernetes URL and the Jenkins URL. The plugin supports five credential types: username and password, a kubeconfig file as a secret file, a token as secret text (used for OpenShift), a Google Service Account private key for GKE, and an X.509 client certificate.

A Test Connection button validates that Jenkins can reach the cluster API server. The Pod Template section specifies the container image used to spin up agents. The Jenkins agent container defaults to the name `jnlp` for historical reasons, but the name can be overridden. The README advises against bundling the Jenkins agent JAR in the container image to avoid version drift; instead, use the Inject Jenkins agent in agent container checkbox so the controller pushes the correct JAR at startup.

Pipeline Integration: The podTemplate Step

The plugin adds two pipeline mechanisms. The first is a global pod template defined in the Jenkins UI, which assigns a label that freestyle or pipeline jobs can reference with `node('some-label')`. This is intended for migrating large existing job corpora to Kubernetes without rewriting every job definition.

The second and recommended approach for new jobs is the `podTemplate` pipeline step. It defines an ephemeral template scoped to a single pipeline block and is cleaned up immediately after the block exits. Reusable template definitions can be stored in YAML files and loaded inline, allowing teams to keep pod definitions in version control alongside the Jenkinsfile rather than in the Jenkins UI.

The `container` step switches the active container within the agent pod, letting different stages of the same build run in different images without spinning up additional pods. Multiple containers in one pod share the workspace volume, which avoids the overhead of passing artifacts between separate pods.

To install the plugin in a Jenkins controller image, the Dockerfile in the repository uses the `jenkins-plugin-cli` command:

RUN jenkins-plugin-cli --plugins kubernetes-client-api \
    kubernetes-credentials \
    docker-commons \
    cloudbees-folder \
    workflow-api \
    variant \
    durable-task \
    workflow-durable-task-step \
    metrics \
    caffeine-api
COPY target/kubernetes.hpi /usr/share/jenkins/ref/plugins/kubernetes.hpi

This shows the full plugin dependency chain needed alongside the main kubernetes.hpi file.

WebSocket, Garbage Collection and Security Considerations

By default, agent pods connect to the Jenkins controller over a TCP port. Enabling WebSocket changes the transport to HTTP or HTTPS, which is described in JEP-222. This matters when the Jenkins controller is behind a reverse proxy or an ingress resource that does not forward arbitrary TCP ports. The README notes that WebSocket is unnecessary when the controller and agents run in the same cluster, but can simplify setup for agents in an external cluster.

Agent pods can be left behind in exceptional cases, typically when the connection between the pod and the controller is lost before the build finishes. These orphan pods repeatedly attempt to reconnect. The plugin provides a garbage collection mechanism to delete them, but it is disabled by default because it generates extra load on the Kubernetes API server. Teams that run many parallel builds should evaluate whether to enable it.

For jobs that should only use a specific cloud configuration, the plugin supports folder-level restrictions. In the cloud's advanced configuration, checking `Restrict pipeline support to authorized folders` limits which jobs can request pods from that cloud. The job's folder configuration must then explicitly authorize the cloud.

Running on OpenShift and Google Container Engine

The README documents specific configurations for OpenShift and Google Container Engine. For OpenShift, the supported credential type is secret text using a token (xoxb style credentials are not involved here; OpenShift tokens are long-lived service account tokens or short-lived tokens depending on cluster configuration). For GKE, the credential type is a Google Service Account private key.

When Jenkins runs inside the same Kubernetes cluster, the defaults for Kubernetes URL and Jenkins URL work without modification. When the controller is external, both URLs must be set explicitly. The README also addresses self-signed HTTPS certificates on the Jenkins controller: if agents connect over WebSocket to a controller with a self-signed certificate, additional TLS configuration is needed on the agent side.

The Dockerfile in the repository shows how to build a Jenkins controller image with the plugin pre-installed using `jenkins-plugin-cli`. It also demonstrates the plugin dependency chain: kubernetes-client-api, kubernetes-credentials, docker-commons, workflow-api, durable-task, workflow-durable-task-step and caffeine-api are all listed as required plugins.

Limitations and When to Consider Alternatives

The plugin adds a layer of indirection between Jenkins and the build environment. Teams must understand Kubernetes RBAC, pod scheduling, resource requests and limits, and persistent volume claims to configure builds that need caching. The `maven-with-cache-pvc.yml` example in the repository shows how to use a PersistentVolumeClaim for a Maven local repository, but PVC provisioning is a Kubernetes-level concern that Jenkins pipeline authors must account for.

The plugin works with dynamic pod allocation only. It does not support running builds on pre-existing long-lived pods the way a static node pool would. If a build tool requires a warm JVM, a pre-fetched container image or other session state, the cold-start time of a new pod per build becomes a real cost.

GitHub Actions and GitLab CI both provide built-in container-per-job execution without a separate plugin or cluster configuration. Those platforms own the scheduler and the runner fleet, which reduces operational overhead. The Jenkins Kubernetes plugin is the right choice specifically when an organization already runs Jenkins and wants to offload agent scaling to an existing Kubernetes cluster, not when starting fresh.

Release Cadence, Maintenance and Licence

The plugin follows Jenkins' version numbering convention where version numbers encode the UTC date of the build. Recent releases include 4557.ve746270f672f on 2026-09-16, 4547.v52f3080db_8cd on 2026-08-13, and 4540.v612369217f87 on 2026-07-24. The last push to the repository was on 2026-09-24, indicating active maintenance.

The repository is licensed under Apache-2.0. It includes a CHANGELOG-archive.md for historical changes and uses a `.git-blame-ignore-revs` file to avoid blaming reformatting commits in `git blame` output, which suggests the codebase has had formatting passes applied. The build system uses Maven with a standard `pom.xml`; integration tests can be run locally using the included `kind.sh` script which sets up a local Kubernetes cluster via kind.

The plugin page on plugins.jenkins.io provides the canonical installation path for users who manage plugins through the Jenkins Update Center rather than manually.

Editorial conclusion

The Jenkins Kubernetes plugin is the standard path for teams running Jenkins on or near Kubernetes who want on-demand build agents rather than a pre-provisioned pool. It suits organizations that already operate a Kubernetes cluster and have existing Jenkins pipelines they want to migrate. Teams that have no Kubernetes cluster, or that are evaluating alternatives such as GitLab CI or GitHub Actions, will find those platforms offer native per-job container isolation without a separate plugin layer. Before adoption, verify that your ServiceAccount has the necessary RBAC permissions to create and delete pods, and confirm whether WebSocket is required for connectivity between the Jenkins controller and the cluster. The plugin's garbage collection mechanism is disabled by default; enable it if you expect agent pods to be left behind after connection failures.

Frequently asked questions

Official sources

1. jenkinsci/kubernetes-plugin on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases