Customizing Jenkins

How to customize Jenkins

How to customize Jenkins

Jenkins can be customized with plugins. Plugin’s configuration is applied as groovy scripts or the configuration as code plugin. Any plugin working for Jenkins can be installed by the Jenkins Operator.

Pre-installed plugins:

  • configuration-as-code:2147.v8a_8d38668c72
  • git:5.11.0
  • job-dsl:3732.v9a_c49a_61a_313
  • kubernetes:4560.vc25b_83890c34
  • kubernetes-credentials-provider:1.324.v5271cd145cb_1
  • workflow-aggregator:608.v67378e9d3db_1

Rest of the plugins can be found in plugins repository.

Install plugins

Edit Custom Resource under spec.master.plugins:

apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
  name: example
spec:
  master:
   plugins:
   - name: simple-theme-plugin
     version: "0.7"

Under spec.master.basePlugins you can find plugins for a valid Jenkins Operator:

apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
  name: example
spec:
  master:
    basePlugins:
    - name: configuration-as-code
      version: "2147.v8a_8d38668c72"
    - name: git
      version: "5.11.0"
    - name: job-dsl
      version: "3732.v9a_c49a_61a_313"
    - name: kubernetes
      version: "4560.vc25b_83890c34"
    - name: kubernetes-credentials-provider
      version: "1.324.v5271cd145cb_1"
    - name: workflow-aggregator
      version: "608.v67378e9d3db_1"

You can change their versions.

The Jenkins Operator will then automatically install plugins after the Jenkins master pod restart.

Apply plugin’s config

By using a ConfigMap you can create your own Jenkins customized configuration. Then you must reference the ConfigMap in the Jenkins pod customization file in spec.groovyScripts or spec.configurationAsCode

Create a ConfigMap with specific name (eg. jenkins-operator-user-configuration). Then, modify the Jenkins manifest:

apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
  name: example
spec:
  configurationAsCode:
    configurations:
    - name: jenkins-operator-user-configuration
  groovyScripts:
    configurations:
    - name: jenkins-operator-user-configuration

Here is an example of jenkins-operator-user-configuration:

apiVersion: v1
kind: ConfigMap
metadata:
  name: jenkins-operator-user-configuration
data:
  1-configure-theme.groovy: |
    import jenkins.*
    import jenkins.model.*
    import hudson.*
    import hudson.model.*
    import org.jenkinsci.plugins.simpletheme.ThemeElement
    import org.jenkinsci.plugins.simpletheme.CssTextThemeElement
    import org.jenkinsci.plugins.simpletheme.CssUrlThemeElement

    Jenkins jenkins = Jenkins.getInstance()

    def decorator = Jenkins.instance.getDescriptorByType(org.codefirst.SimpleThemeDecorator.class)

    List<ThemeElement> configElements = new ArrayList<>();
    configElements.add(new CssTextThemeElement("DEFAULT"));
    configElements.add(new CssUrlThemeElement("https://cdn.rawgit.com/afonsof/jenkins-material-theme/gh-pages/dist/material-light-green.css"));
    decorator.setElements(configElements);
    decorator.save();

    jenkins.save()
  1-system-message.yaml: |
    jenkins:
      systemMessage: "Configuration as Code integration works!!!"
  • *.groovy is Groovy script configuration
  • *.yaml is configuration as code

If you want to correct your configuration you can edit it while the Jenkins Operator is running. Jenkins will reconcile and apply the new configuration.

How to use secrets from a Groovy scripts

If you configured spec.groovyScripts.secret.name, then this secret is available to use from map Groovy scripts. The secrets are loaded to secrets map.

Create a secret with for example the name jenkins-conf-secrets.

kind: Secret
apiVersion: v1
type: Opaque
metadata:
  name: jenkins-conf-secrets
  namespace: default
data:
  SYSTEM_MESSAGE: SGVsbG8gd29ybGQ=

Then modify the Jenkins pod manifest by changing spec.groovyScripts.secret.name to jenkins-conf-secrets.

apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
  name: example
spec:
  configurationAsCode:
    configurations:
    - name: jenkins-operator-user-configuration
    secret:
      name: jenkins-conf-secrets
  groovyScripts:
    configurations:
    - name: jenkins-operator-user-configuration
    secret:
      name: jenkins-conf-secrets

Now you can test that the secret is mounted by applying this ConfigMap for Groovy script:

apiVersion: v1
kind: ConfigMap
metadata:
  name: jenkins-operator-user-configuration
data:
  1-system-message.groovy: |
    import jenkins.*
    import jenkins.model.*
    import hudson.*
    import hudson.model.*
    Jenkins jenkins = Jenkins.getInstance()

    jenkins.setSystemMessage(secrets["SYSTEM_MESSAGE"])
    jenkins.save()

Or by applying this configuration as code:

apiVersion: v1
kind: ConfigMap
metadata:
  name: jenkins-operator-user-configuration
data:
  1-system-message.yaml: |
    jenkins:
      systemMessage: ${SYSTEM_MESSAGE}

After this, you should see the Hello world system message from the Jenkins homepage.

Usage statistics

Set spec.master.disableUsageStatistics: true (Helm: jenkins.disableUsageStatistics: true) to disable Jenkins usage statistics. The default leaves the Jenkins setting unchanged.

Seed agent scheduling

The seed agent accepts only jobs targeting seed-job-agent by default, including existing agents after upgrade. Set spec.seedJobRestrictJobsToLabel: false (Helm: jenkins.seedJobRestrictJobsToLabel: false) to allow unlabeled jobs.

Jenkins home storage

Jenkins home uses emptyDir by default. See why Jenkins home is disposable. To use a Pod-owned ephemeral PVC:

spec:
  master:
    homeVolume:
      ephemeral:
        storageClassName: fast
        accessModes: [ReadWriteOnce]
        resources:
          requests:
            storage: 20Gi

Select one source: ephemeral or emptyDir (optional medium and sizeLimit). Omit storageClassName for the cluster default; "" requests no StorageClass. Helm uses jenkins.homeVolume.

Changing home storage replaces the Pod without migrating data. Existing backup and restore settings still apply.

Externally managed pod fields

Built-in cloud identity rules

spec.reconciliation.ignoreWellKnownInjections defaults to true. It prevents the following injected fields from triggering pod recreation. Set it to false to disable these rules.

IntegrationExact env namesVolume names
AWS IRSAAWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE, AWS_REGION, AWS_DEFAULT_REGION, AWS_STS_REGIONAL_ENDPOINTSaws-iam-token
EKS Pod IdentityAWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_CONTAINER_AUTHORIZATION_TOKEN_FILEeks-pod-identity-token
Azure Workload IdentityAZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_AUTHORITY_HOST, AZURE_FEDERATED_TOKEN_FILEazure-identity-token, or prefix azure-workload-identity-reserved-
Google ADCGOOGLE_APPLICATION_CREDENTIALSAdd your injector’s volume name manually

Matching volume mounts are also ignored. Matching names explicitly declared in your CR are ignored too: changing AWS_REGION, for example, will not recreate the pod. Disable the switch and use manual rules if you need narrower control.

Cloud identity configuration is still required; see AKS for Azure. Native GKE identity needs no ignore rules. No label or annotation keys are included in the built-in list.

Manual rules

Add rules for other externally managed fields. They work with or without the built-in rules:

spec:
  reconciliation:
    ignore:
      annotations: [identity.example.com/managed]
      labels: [identity.example.com/managed]
      env: [EXTERNAL_TOKEN_FILE]
      volumes: [external-identity-token]
      volumeNamePrefixes: [custom-token-]

Names and keys are exact and case-sensitive. Volume prefixes are literal, non-empty strings, not globs; volume rules also ignore mounts by volume name. Env rules cover value and valueFrom in regular containers, but not envFrom or init containers. Rules apply to both desired and actual fields during comparison only.

Extra pod labels and annotations are already tolerated. Use manual metadata rules when another controller changes or removes keys declared in spec.master. ServiceAccount annotations remain managed separately.

Other restart checks remain active, including failures, credentials, operator upgrades and changes to retained fields. Unrecognized sidecars and probe rewrites are not covered. The experimental Deployment path does not use these rules.

Helm uses the same settings under jenkins.reconciliation.

Istio and Linkerd regular/native sidecars and their known injected volumes are covered by the same switch; exact component names. Mesh rules preserve user-declared containers and volumes. Istio requires this Pod annotation to keep application probes unchanged:

spec:
  master:
    annotations:
      sidecar.istio.io/rewriteAppHTTPProbers: "false"

Full strict-mTLS compatibility is not supported: mesh policy must permit direct kubelet probes and operator-to-Jenkins traffic. Linkerd does not use the Istio annotation. See Istio health checks.

Kubernetes volume defaults

For ConfigMap, Secret, Projected and DownwardAPI volumes, omitted defaultMode compares equal to Kubernetes’ default 0644 (420), independently of ignore rules. Different permissions or volume sources still trigger reconciliation.