Installing the Operator

How to install Jenkins Operator

This document describes installation procedure for Jenkins Operator. All container images can be found at virtuslab/jenkins-operator Docker Hub repository.

Requirements

To run Jenkins Operator, you will need:

  • access to a Kubernetes cluster version 1.17+
  • kubectl version 1.17+

Listed below are the two ways to deploy Jenkins Operator.

Deploy Jenkins Operator using YAML’s

First, install Jenkins Custom Resource Definition:

kubectl apply -f https://raw.githubusercontent.com/jenkinsci/kubernetes-operator/master/config/crd/bases/jenkins.io_jenkins.yaml

Then, install the Operator and other required resources:

kubectl apply -f https://raw.githubusercontent.com/jenkinsci/kubernetes-operator/master/deploy/all-in-one-v1alpha2.yaml

Watch Jenkins Operator instance being created:

kubectl get pods -w

Now Jenkins Operator should be up and running in the default namespace. For deploying Jenkins, refer to Deploy Jenkins section.

Deploy Jenkins Operator using Helm Chart

Alternatively, you can also use Helm to install the Operator (and optionally, by default, Jenkins). It requires the Helm 3+ for deployment.

Create a namespace for the operator:

$ kubectl create namespace <your-namespace>

To install, you need only to type these commands:

$ helm repo add jenkins https://raw.githubusercontent.com/jenkinsci/kubernetes-operator/master/chart
$ helm install <name> jenkins/jenkins-operator -n <your-namespace>

To add custom labels and annotations, you can use values.yaml file or pass them into helm install command, e.g.:

$ helm install <name> jenkins/jenkins-operator -n <your-namespace> --set jenkins.labels.LabelKey=LabelValue,jenkins.annotations.AnnotationKey=AnnotationValue

You can further customize Jenkins using values.yaml:

Jenkins instance configuration

FieldDefault valueDescription
jenkins

operator is section for configuring operator deployment

enabledtrueEnabled can enable or disable the Jenkins instance. Set to false if you have configured CR already and/or you want to deploy an operator only.
apiVersionjenkins.io/v1alpha2Version of the CR manifest. The recommended and default value is jenkins.io/v1alpha2. More info
namejenkinsName of resource. The pod name will be jenkins-<name> (name will be set as suffix).
namespacedefaultNamespace the resources will be deployed to. It's not recommended to use default namespace. Create new namespace for jenkins (e.g. kubectl create -n jenkins)
labels{}Labels are injected into metadata labels field.
annotations{}Annotations are injected into metadata annotations field.
imagejenkins/jenkins:ltsImage is the name (and tag) of the Jenkins instance. It's recommended to use LTS (tag: "lts") version.
env[]Env contains jenkins container environment variables.
imagePullPolicyAlwaysDefines policy for pulling images
priorityClassName""PriorityClassName indicates the importance of a Pod relative to other Pods. More info
disableCSRFProtectionfalsedisableCSRFProtection can enable or disable operator built-in CSRF protection. Set it to true if you are using OpenShift Jenkins Plugin. More info
imagePullSecrets[]Used if you want to pull images from private repository More info
notifications[]Notifications is feature that notify user about Jenkins reconciliation status More info
basePlugins
- name: kubernetes
  version: "1.25.2"
- name: workflow-job
  version: "2.39"
- name: workflow-aggregator
  version: "2.6"
- name: git
  version: "4.2.2"
- name: job-dsl
  version: "1.77"
- name: configuration-as-code
  version: "1.38"
- name: kubernetes-credentials
        -provider
  version: "0.13"
Plugins installed and required by the operator shouldn't contain plugins defined by user You can change their versions here More info
plugins[]Plugins required by the user. You can define plugins here. More info Example:
plugins:
 - name: simple-theme-plugin
   version: 0.5.1
seedJobs[]Placeholder for jenkins seed jobs For seed job creation tutorial, check:
Prepare seed jobs
Configure seed jobs
Example:
seedJobs:
- id: jenkins-operator
  targets: "cicd/jobs/*.jenkins"
  description: "Jenkins Operator repository"
  repositoryBranch: master
  repositoryUrl:
  - https://github.com/jenkinsci/kubernetes-operator.git
resources
limits:
  cpu: 1500m
  memory: 3Gi
requests:
  cpu: 1
  memory: 500M
Resource limit/request for Jenkins More info
volumes
- name: backup
  persistentVolumeClaim:
    claimName: jenkins-backup
Volumes used by Jenkins By default, we are only using PVC volume for storing backups.
volumeMounts[]volumeMounts are mounts for Jenkins pod.
securityContextrunAsUser: 1000 fsGroup: 1000SecurityContext for pod.
servicenot implementedHttp Jenkins service. See https://jenkinsci.github.io/kubernetes-operator/docs/getting-started/latest/schema/#github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Service for details.
slaveServicenot implementedSlave Jenkins service. See https://jenkinsci.github.io/kubernetes-operator/docs/getting-started/latest/schema/#github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Service for details.
livenessProbe
livenessProbe:
  failureThreshold: 12
  httpGet:
    path: /login
    port: http
    scheme: HTTP
  initialDelaySeconds: 80
  periodSeconds: 10
  successThreshold: 1
  timeoutSeconds: 5
livenessProbe for Pod
readinessProbe
readinessProbe:
  failureThreshold: 3
  httpGet:
    path: /login
    port: http
    scheme: HTTP
  initialDelaySeconds: 30
  periodSeconds: 10
  successThreshold: 1
  timeoutSeconds: 1
readinessProbe for Pod
backup

Backup

Backup is section for configuring operator's backup feature By default backup feature is enabled and pre-configured This section simplifies the configuration described here: Configuring backup and restore For customization tips see Custom backup and restore
configuration

Configuration

Section where we can configure Jenkins instance. See Customizing Jenkins for details

Configuring operator deployment

FieldDefault valueDescription
operator

operator is section for configuring operator deployment

replicaCount
1Number of Replicas.
imagevirtuslab/jenkins-operator:v0.4.0Name (and tag) of the Jenkins Operator image.
imagePullPolicyIfNotPresentDefines policy for pulling images.
imagePullSecrets[]Used if you want to pull images from private repository.
nameOverride""nameOverride overrides the app name.
fullnameOverride""fullnameOverride overrides the deployment name
resources{}
nodeSelector{}
tolerations{}
affinity{}

Backup

(Appears on: JenkinsConfiguration)

Backup defines configuration of Jenkins backup.

FieldDefault valueDescription
enabledtrueEnabled is enable/disable switch for backup feature.
imagevirtuslab/jenkins-operator-backup-pvc:v0.0.8Image used by backup feature.
containerNamebackupBackup container name.
interval30Defines how often make backup in seconds.
makeBackupBeforePodDeletiontrueWhen enabled will make backup before pod deletion.
backupCommand/home/user/bin/backup.shBackup container command.
restoreCommand/home/user/bin/restore.shBackup restore command.
pvc

Persistent Volume Claim Kubernetes resource


enabledtrueEnable/disable switch for PVC
enabledtrueEnable/disable switch for PVC
size5GiSize of PVC
className""StorageClassName for PVC More info
env
- name: BACKUP_DIR
  value: /backup
- name: JENKINS_HOME
  value: /jenkins-home
- name: BACKUP_COUNT
  value: "3"
Contains container environment variables. PVC backup provider handles these variables:
BACKUP_DIR - path for storing backup files (default: "/backup")
JENKINS_HOME - path to jenkins home (default: "/jenkins-home")
BACKUP_COUNT - define how much recent backups will be kept
volumeMounts
- name: jenkins-home
  mountPath: /jenkins-home
- mountPath: /backup
  name: backup
Holds the mount points for volumes.

Configuration

(Appears on: Jenkins instance configuration)

FieldDefault valueDescription
configurationAsCode{}ConfigurationAsCode defines configuration of Jenkins customization via Configuration as Code Jenkins plugin. Example:
- configMapName: jenkins-casc
  content: {}
groovyScripts{}GroovyScripts defines configuration of Jenkins customization via groovy scripts. Example:
- configMapName: jenkins-gs
  content: {}
secretRefName“”secretRefName of existing secret (previously created).
secretData{}If secretRefName is empty, secretData creates new secret and fills with data provided in secretData.

Note on Operator’s nightly built images

If you wish to use the newest, not yet released version of the Operator, you can use one of nightly built snapshot images, however the maintainers of this project cannot guarantee their stability.

You can find nightly built images by heading to virtuslab/jenkins-operator Docker Hub repository and looking for images with tag in the form of {git-hash}, {git-hash} being the hash of master branch commit that you want to use snapshot of.

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
Last modified December 8, 2021