Jenkins Helm Charts

Upgrading to version 5.0.0 involves significant breaking changes to the configuration schema, specifically regarding image definitions and administrative credentials.

Image Configuration Changes

Direct image and tag keys have been removed in favor of structured objects. If you need to override images, use the new sub-keys:

• Controller Image: Replace controller.image, controller.tag, and controller.tagLabel with controller.image.registry, controller.image.repository, controller.image.tag, and controller.image.tagLabel. Also, move controller.imagePullPolicy to controller.image.pullPolicy.
• Sidecar (configAutoReload): Replace controller.sidecars.configAutoReload.image with controller.sidecars.configAutoReload.image.registry, controller.sidecars.configAutoReload.image.repository, controller.sidecars.configAutoReload.image.tag, and controller.sidecars.configAutoReload.image.tagLabel.
• Agent Image: Replace agent.image and agent.tag with agent.image.repository and agent.image.tag. The registry is still configurable via agent.jnlpregistry.
• Helmtest BATS: Split helmtest.bats.image into helmtest.bats.image.registry, helmtest.bats.image.repository, and helmtest.bats.image.tag.

Renamed Keys

• Admin Credentials: controller.adminUsername $\rightarrow$ controller.admin.username, controller.adminPassword $\rightarrow$ controller.admin.password, and controller.adminSecret $\rightarrow$ controller.admin.createSecret.
• Sidecars: controller.sidecars.other $\rightarrow$ controller.sidecars.additionalSidecarContainers.
• Agent Containers: agent.additionalContainers[*].image $\rightarrow$ agent.additionalContainers[*].image.repository and agent.additionalContainers[*].tag $\rightarrow$ agent.additionalContainers[*].image.tag.
• Additional Agents/Clouds: All image and tag keys under additionalAgents and additionalClouds have been moved under an image.repository and image.tag hierarchy.

Removed Features

• backup.* has been removed. Use external Kubernetes backup solutions.

# Example of new 5.0.0 image configuration
controller:
  image:
    registry: docker.io
    repository: jenkins/jenkins
    tag: lts
    pullPolicy: Always

Version 2.0.0 introduces two major changes: Jenkins Configuration as Code (JCasC) is now the default, and the container no longer runs as root.

Configuration as Code (JCasC)

Configuration is managed via the Jenkins Configuration as Code Plugin.

• Warning: Manual changes made via the Jenkins UI will likely be reset to the defaults defined in your Helm values.
• Migration: Export your current settings using Manage Jenkins $\rightarrow$ Configuration as Code $\rightarrow$ Download Configuration and use that as a starting point for your Helm values.

Non-Root Execution

Containers no longer run as root.

• Action Required: Ensure your Jenkins image supports the configured user/group ID (default is 1000:1000). You may need to manually update file permissions.

Migration Steps

1. Ensure your image contains user/group ID 1000 (e.g., jenkins/jenkins:lts).
2. Backup your persistent volume.
3. Ensure the configuration-as-code plugin is installed.
4. Export current settings via the plugin.
5. Prepare your values.yaml with JCasC settings.
6. Put Jenkins in Quiet Down mode (<JENKINS_URL>/quietDown).
7. Update file permissions inside the pod:

   kubectl exec -it <jenkins_pod> -c jenkins -- /bin/bash
   chown -R 1000:1000 /var/jenkins_home

8. Perform the Helm upgrade.

# Default values introduced in 2.0.0
controller:
  runAsUser: 1000
  fsGroup: 1000
  JCasC:
    enabled: true
    defaultConfig: true
  sidecars:
    configAutoReload:
      enabled: true

Upgrading to 3.0.0 involves major architectural and terminology shifts:

Requirements and Architecture

• Helm Version: You must use Helm 3 as the chart uses apiVersion: v2.
• Workload Type: Jenkins has transitioned from a Deployment to a StatefulSet.

Configuration Changes

• XML to JCasC: All XML configuration options have been removed. You must migrate to Jenkins Configuration as Code (JCasC).
• Security: You must check and adjust your securityRealm and authorizationStrategy to prevent your configured users and permissions from being overridden.

Terminology Mapping (Values Renaming)

Many values have been renamed from master to controller or slave to agent:

• master $\rightarrow$ controller
• master.useSecurity $\rightarrow$ controller.adminSecret
• master.slaveListenerPort $\rightarrow$ controller.agentListenerPort
• master.slaveHostPort $\rightarrow$ controller.agentListenerHostPort
• master.slaveKubernetesNamespace $\rightarrow$ agent.namespace
• master.slaveDefaultsProviderTemplate $\rightarrow$ agent.defaultsProviderTemplate
• master.slaveJenkinsUrl $\rightarrow$ agent.jenkinsUrl
• master.slaveJenkinsTunnel $\rightarrow$ agent.jenkinsTunnel
• master.slaveConnectTimeout $\rightarrow$ agent.kubernetesConnectTimeout
• master.slaveReadTimeout $\rightarrow$ agent.kubernetesReadTimeout
• master.slaveListenerServiceAnnotations $\rightarrow$ controller.agentListenerServiceAnnotations
• master.slaveListenerServiceType $\rightarrow$ controller.agentListenerServiceType
• master.slaveListenerLoadBalancerIP $\rightarrow$ controller.agentListenerLoadBalancerIP
• agent.slaveConnectTimeout $\rightarrow$ agent.connectTimeout
• master.imageTag $\rightarrow$ use controller.image and controller.tag
• slave.imageTag $\rightarrow$ use agent.image and agent.tag