kubernetes-operator/doc/getting-started.md

Getting Started

This document describes a getting started guide for jenkins-operator and an additional configuration.

1. First Steps
2. Deploy Jenkins
3. Configure Seed Jobs and Pipelines
4. Install Plugins
5. Configure Authorization
6. Configure Backup & Restore
7. Debugging

First Steps

Prepare your Kubernetes cluster and set up access. Once you have running Kubernetes cluster you can focus on installing jenkins-operator according to the Installation guide.

Deploy Jenkins

Once jenkins-operator is up and running let's deploy actual Jenkins instance. Let's use example below:

apiVersion: virtuslab.com/v1alpha1
kind: Jenkins
metadata:
  name: example
spec:
  master:
   image: jenkins/jenkins
  seedJobs:
  - id: jenkins-operator-e2e
    targets: "cicd/jobs/*.jenkins"
    description: "Jenkins Operator e2e tests repository"
    repositoryBranch: master
    repositoryUrl: https://github.com/VirtusLab/jenkins-operator-e2e.git

Watch Jenkins instance being created:

kubectl get pods -w

Get Jenkins credentials:

kubectl get secret jenkins-operator-credentials-example -o 'jsonpath={.data.password}' | base64 -d

Connect to Jenkins (minikube):

minikube service jenkins-operator-example --url

Connect to Jenkins (actual Kubernetes cluster):

kubectl describe svc jenkins-operator-example
kubectl jenkins-operator-example 8080:8080

Configure Seed Jobs and Pipelines

Jenkins operator uses job-dsl and ssh-credentials plugins for configuring seed jobs and deploy keys.

Prepare job definitions and pipelines

First you have to prepare pipelines and job definition in your GitHub repository using the following structure:

cicd/
├── jobs
│   └── build.jenkins
└── pipelines
    └── build.jenkins

cicd/jobs/build.jenkins it's a job definition:

#!/usr/bin/env groovy

pipelineJob('build-jenkins-operator') {
    displayName('Build jenkins-operator')

    definition {
        cpsScm {
            scm {
                git {
                    remote {
                        url('https://github.com/VirtusLab/jenkins-operator.git')
                        credentials('jenkins-operator')
                    }
                    branches('*/master')
                }
            }
            scriptPath('cicd/pipelines/build.jenkins')
        }
    }
}

cicd/jobs/build.jenkins it's an actual Jenkins pipeline:

#!/usr/bin/env groovy

def label = "build-jenkins-operator-${UUID.randomUUID().toString()}"
def home = "/home/jenkins"
def workspace = "${home}/workspace/build-jenkins-operator"
def workdir = "${workspace}/src/github.com/VirtusLab/jenkins-operator/"

podTemplate(label: label,
        containers: [
                containerTemplate(name: 'jnlp', image: 'jenkins/jnlp-slave:alpine'),
                containerTemplate(name: 'go', image: 'golang:1-alpine', command: 'cat', ttyEnabled: true),
        ]) {

    node(label) {
        dir(workdir) {
            stage('Init') {
                timeout(time: 3, unit: 'MINUTES') {
                    checkout scm
                }
                container('go') {
                    sh 'apk --no-cache --update add make git gcc libc-dev'
                }
            }

            stage('Build') {
                container('go') {
                    sh 'make build'
                }
            }
        }
    }
}

Configure Seed Jobs

Jenkins Seed Jobs are configured using Jenkins.spec.seedJobs section from your custom resource manifest:

apiVersion: virtuslab.com/v1alpha1
kind: Jenkins
metadata:
  name: example
spec:
  master:
   image: jenkins/jenkins:lts
  seedJobs:
  - id: jenkins-operator
    targets: "cicd/jobs/*.jenkins"
    description: "Jenkins Operator repository"
    repositoryBranch: master
    repositoryUrl: https://github.com/VirtusLab/jenkins-operator.git

If your GitHub repository is private you have to configure corresponding privateKey and Kubernetes Secret:

apiVersion: virtuslab.com/v1alpha1
kind: Jenkins
metadata:
  name: example
spec:
  master:
   image: jenkins/jenkins:lts
  seedJobs:
  - id: jenkins-operator
    targets: "cicd/jobs/*.jenkins"
    description: "Jenkins Operator repository"
    repositoryBranch: master
    repositoryUrl: git@github.com:VirtusLab/jenkins-operator.git
    privateKey:
      secretKeyRef:
        name: deploy-keys
        key: jenkins-operator

And Kubernetes Secret:

apiVersion: v1
kind: Secret
metadata:
  name: deploy-keys
data:
  jenkins-operator-e2e: |
    -----BEGIN RSA PRIVATE KEY-----
    MIIJKAIBAAKCAgEAxxDpleJjMCN5nusfW/AtBAZhx8UVVlhhhIKXvQ+dFODQIdzO
    oDXybs1zVHWOj31zqbbJnsfsVZ9Uf3p9k6xpJ3WFY9b85WasqTDN1xmSd6swD4N8
    ...

jenkins-operator will automatically discover and configure all seed jobs.

You can verify if deploy keys were successfully configured in Jenkins Credentials tab.

Install Plugins

Configure Authorization

Configure Backup & Restore (work in progress)

Not implemented yet.

Debugging