Change the default JNLP container image for kubernetes agents provisioning

Article ID:360030405571
Last Reviewed:2025-08-22()
3 minute readKnowledge base

Issue

  • I would like to modify the default jnlp container image used by pod templates

Environment

Explanation

By default, the Kubernetes plugin uses the jenkins/inbound-agent public image.

In CloudBees CI:

  • Prior to version 2.204.1.3, the Kubernetes plugin default is used across all managed controllers.

  • Since version 2.204.1.3, the default image is set to cloudbees/cloudbees-core-agent by default across all managed controllers.

However, enterprises might need to:

  • Use a Private Docker Registry

  • Use a different default JNLP image

In CloudBees CI on modern cloud platforms, there are different approaches to change the default jnlp container image for an instance:

  1. Specify the default image via a system property (Recommended)

  2. Define a default parent template (also known as Default Provider Template) to the Kubernetes Cloud(s)

Resolution

System Property Approach

The default jnlp container image can be set by adding the JVM system property -Dorg.csanchez.jenkins.plugins.kubernetes.pipeline.PodTemplateStepExecution.defaultImage=<fullImageNameAndTag> on startup. In fact, since version 2.204.1.3, CloudBees CI adds the system property -Dorg.csanchez.jenkins.plugins.kubernetes.pipeline.PodTemplateStepExecution.defaultImage=cloudbees/cloudbees-core-agent:<version> as a controller Global Java Options to enforce cloudbees/cloudbees-core-agent:<version> as the default jnlp container image to all managed controllers, and also provides a solution to change it.

With Helm

With Helm (2.387.2.3 and later)

In current CloudBees CI charts, configure the default agent jnlp image by using separate registry, repository, and tag attributes in the values.yaml file, for exmaple:

Agents:
  image:
    registry: my.registry.com
    repository: 'cloudbees/cloudbees-core-agent'
    tag: 2.516.2.28983
▼

With Helm prior to 2.387.2.3 (legacy)

In earlier CloudBees CI charts, configure the default agent jnlp image can be set via the .Agents.Image.dockerImage attribute, for example:

Agents:
  Image:
    # Change the following with full image name and tag such as `my.registry.com/cloudbees/cloudbees-core-agent:2.163.1.2`
    dockerImage: "<fullImageNameAndTag>"
▼

Upon an operations center restart, reprovision any existing managed controllers to apply the changes.

With Helm prior to 2.204.1.3

For versions prior to 2.204.1.3, add -Dorg.csanchez.jenkins.plugins.kubernetes.pipeline.PodTemplateStepExecution.defaultImage=<fullImageNameAndTag> as a value in Master.JavaOpts. Upon an operations center restart, reprovision any existing managed controllers to apply the changes.

With .yaml modifications

Add -Dorg.csanchez.jenkins.plugins.kubernetes.pipeline.PodTemplateStepExecution.defaultImage=<fullImageNameAndTag> to the MASTER_GLOBAL_JAVA_OPTIONS environment variable. Upon an operations center restart, reprovision any existing managed controllers to apply the changes.

Default Provider Template Approach

In a Kubernetes Cloud, there is an option called Defaults Provider Template Name which provides a way of using this template as a parent to all other pod templates for that cloud. This can be used to customize the default jnlp container (not only the image). For example:

modern-cloud-default-jnlp-image-default-provider.png

When defining a Defaults Provider Template Name in the kubernetes-shared-cloud on the operations center, most templates defined in the managed controllers will inherit this parent template.

However, there are considerations to this approach:

  • The Defaults Provider Template Name in the kubernetes-shared-cloud applies to all pod templates defined under Manage Jenkins  Kubernetes Pod Templates or inside pipelines for the cloud named "kubernetes". It does not apply to templates defined in a local controller Kubernetes cloud (i.e. a Kubernetes Cloud that is configured in the managed controller global configuration. Each cloud has its own Default Provider Template).

  • This approach relies on Pod Template inheritance that must be understood. Especially around how YAML merge works.

Due to those considerations, this is not the preferred approach. It may be a viable option in cases where a managed controller has different Kubernetes Clouds configured, and those clouds need different defaults for the jnlp container.

Further Notes

To disable the enforcement of the default jnlp container image in CloudBees CI on modern cloud platforms for current and legacy charts, the .Agents.Image.dockerImage and .Agents.image.* attributes may be left empty. With this configuration, the Kubernetes plugin’s defaults will be used:

Agents:
  image:
    registry:
    repository:
    tag:
▼

Upon an operations center restart, reprovision any existing managed controllers to apply the changes.

Tested products/plugins version

References