Installing the Operator

Requirements

• A Kubernetes cluster and permission to create the operator’s CRD and RBAC resources.
• kubectl configured for that cluster, using a version compatible with its API server.
• Helm 3 if installing the chart.

See the release notes and release CI when evaluating your cluster version.

Install using Helm

Add the chart repository and install chart version 0.9.0:

helm repo add jenkins https://raw.githubusercontent.com/jenkinsci/kubernetes-operator/master/chart
helm repo update
helm install jenkins-operator jenkins/jenkins-operator \
  --version 0.9.0 --namespace jenkins --create-namespace \
  --set jenkins.namespace=jenkins

By default, this installs both the operator and a Jenkins instance. To install only the operator, add --set jenkins.enabled=false, then follow Deploying Jenkins.

Chart 0.9.0 uses these defaults:

The chart version, operator version, Jenkins version, and backup version are independent. Use a custom values file with -f values.yaml to override settings. See the 0.9.0 chart reference for supported values, including jenkins.lifecycle, jenkins.terminationGracePeriodSeconds, jenkins.skipPlugins, and operator.watchNamespace.

For example, to add Jenkins labels and annotations:

helm install jenkins-operator jenkins/jenkins-operator \
  --version 0.9.0 --namespace jenkins --create-namespace \
  --set jenkins.namespace=jenkins \
  --set jenkins.labels.LabelKey=LabelValue \
  --set jenkins.annotations.AnnotationKey=AnnotationValue

Install using release manifests

Install the CRD, then the operator and its RBAC resources:

kubectl apply -f https://raw.githubusercontent.com/jenkinsci/kubernetes-operator/v0.9.0/config/crd/bases/jenkins.io_jenkins.yaml
kubectl apply -f https://raw.githubusercontent.com/jenkinsci/kubernetes-operator/v0.9.0/deploy/all-in-one-v1alpha2.yaml
kubectl rollout status deployment/jenkins-operator --namespace default

This installs the operator in default; it does not create a Jenkins instance. Continue with Deploying Jenkins. For separate operator and Jenkins namespaces, see the separate namespaces guide.

Upgrade an existing installation

Back up Jenkins data and save your custom values before upgrading. Review the release notes and backup storage requirements.

Helm does not upgrade CRDs from a chart’s crds/ directory. Apply the release CRD before upgrading the chart, using your existing release name, namespace, and custom values:

kubectl apply -f https://raw.githubusercontent.com/jenkinsci/kubernetes-operator/v0.9.0/config/crd/bases/jenkins.io_jenkins.yaml
helm repo update
helm upgrade jenkins-operator jenkins/jenkins-operator \
  --version 0.9.0 --namespace jenkins -f values.yaml

Check the rendered values before applying them, particularly custom images, probes, backup settings, and any use of the new skipPlugins option. The CR API remains jenkins.io/v1alpha2.

Validating webhook

The webhook can reject Jenkins resources whose configured base or additional plugin versions match security warnings from Jenkins Update Center metadata. This validation is opt-in: enable both the operator’s webhook and spec.validateSecurityWarnings on the Jenkins resource.

The webhook requires cert-manager for its serving certificate. If cert-manager is already installed, install the operator first with Jenkins creation disabled:

helm upgrade --install jenkins-operator jenkins/jenkins-operator \
  --version 0.9.0 --namespace jenkins --create-namespace \
  --set jenkins.enabled=false --set webhook.enabled=true

If cert-manager is not installed, the chart can install its bundled cert-manager dependency and CRDs with --set cert-manager.enabled=true. Check that dependency’s compatibility with your cluster. Wait for cert-manager and the operator’s serving certificate before creating a Jenkins resource.

For a Helm-managed Jenkins instance, set jenkins.enabled=true and jenkins.validateSecurityWarnings=true in your values file once the webhook is ready. For a resource managed separately, set:

spec:
  validateSecurityWarnings: true

The operator needs access to https://updates.jenkins.io/update-center.actual.json to fetch warning metadata. Validation rejects a resource if that metadata has not yet been fetched. See Security for the validation behavior and other hardening settings.

Development snapshots

Nightly images are published to the operator repository with a short Git commit hash as their tag. These are development snapshots, not the stable 0.9.0 image. Use the master manifests only when intentionally testing unreleased changes.

Note on restricted Jenkins controller pod volumeMounts

Current design of the Operator puts an emphasis on creating a full GitOps flow of work for Jenkins users. One of the key points of this design is maintaining an immutable state of Jenkins.

One of the prerequisites of this is an ephemeral Jenkins home directory. To achieve that, Operator mounts emptyDir Volume (jenkins-home) as Jenkins home directory. It is not possible to overwrite volumeMount and specify any other Volume for Jenkins home directory, as attempting to do so will result in Operator error.

jenkins-home is not the only Jenkins controller pod volumeMount that is non-configurable and managed by Operator, below is the full list of those volumeMounts:

• jenkins-home
• scripts
• init-configuration
• operator-credentials