Installing the Operator

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

- 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:
 - name: simple-theme-plugin
   version: 0.5.1

seedJobs:
- id: jenkins-operator
  targets: "cicd/jobs/*.jenkins"
  description: "Jenkins Operator repository"
  repositoryBranch: master
  repositoryUrl:
  - https://github.com/jenkinsci/kubernetes-operator.git

limits:
  cpu: 1500m
  memory: 3Gi
requests:
  cpu: 1
  memory: 500M

- name: backup
  persistentVolumeClaim:
    claimName: jenkins-backup

livenessProbe:
  failureThreshold: 12
  httpGet:
    path: /login
    port: http
    scheme: HTTP
  initialDelaySeconds: 80
  periodSeconds: 10
  successThreshold: 1
  timeoutSeconds: 5

readinessProbe:
  failureThreshold: 3
  httpGet:
    path: /login
    port: http
    scheme: HTTP
  initialDelaySeconds: 30
  periodSeconds: 10
  successThreshold: 1
  timeoutSeconds: 1

Configuring operator deployment

Backup

(Appears on: JenkinsConfiguration)

Backup defines configuration of Jenkins backup.

- name: BACKUP_DIR
  value: /backup
- name: JENKINS_HOME
  value: /jenkins-home
- name: BACKUP_COUNT
  value: "3"

- name: jenkins-home
  mountPath: /jenkins-home
- mountPath: /backup
  name: backup

Configuration

(Appears on: Jenkins instance configuration)

- configMapName: jenkins-casc
  content: {}

- configMapName: jenkins-gs
  content: {}

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

Validating Webhook

Validating webhook can be used in order to increase the Operator’s capabilities to monitor security issues. It will look for security vulnerabilities in the base and requested plugins. It can be easily installed via Helm charts by setting webhook.enabled in values.yaml.

Note: The webhook takes some time to get up and running. It’s recommended to first deploy the Operator and later Jenkins Custom Resource by using toggles in values.yaml. For the installation with yaml manifests (without using Helm chart), first, install cert-manager:

kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.yaml

It takes some time to get cert-manager up and running. Then, install the webhook and other required resources:

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

Now, download the manifests for the operator and other resources from here and provide these additional fields in the Operator manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: jenkins-operator
  labels:
    control-plane: controller-manager
spec:
  selector:
    matchLabels:
      control-plane: controller-manager
  replicas: 1
  template:
    metadata:
      labels:
        control-plane: controller-manager
    spec:
      serviceAccountName: jenkins-operator
      securityContext:
        runAsUser: 65532
      containers:
      - command:
        - /manager
        args:
        - --leader-elect
        - --validate-security-warnings
        image: virtuslab/jenkins-operator:v0.7.0
        name: jenkins-operator
        imagePullPolicy: IfNotPresent
        securityContext:
          allowPrivilegeEscalation: false
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8081
          initialDelaySeconds: 15
          periodSeconds: 20
        readinessProbe:
          httpGet:
            path: /readyz
            port: 8081
          initialDelaySeconds: 5
          periodSeconds: 10
        resources:
          limits:
            cpu: 200m
            memory: 100Mi
          requests:
            cpu: 100m
            memory: 20Mi
        env:
          - name: WATCH_NAMESPACE
            valueFrom:
              fieldRef:
                fieldPath: metadata.namespace
        volumeMounts:
          - mountPath: /tmp/k8s-webhook-server/serving-certs
            name: webhook-certs
            readOnly: true
      volumes:
      - name: webhook-certs
        secret:
          defaultMode: 420
          secretName: jenkins-webhook-certificate
      terminationGracePeriodSeconds: 10

To enable security validation in the Jenkins Custom Resource, set

jenkins.ValidateSecurityWarnings=true