diff --git a/README.md b/README.md index 408bfdcb..50e9b7af 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ Some of the problems we want to solve: - security and hardening out of the box - orphaned jobs with no jnlp connection - make errors more visible for end users +- backup and restore for jobs history ## Documentation @@ -41,27 +42,13 @@ Feel free to file [issues](https://github.com/VirtusLab/jenkins-operator/issues) Common: * simple API for generating Kubernetes events using one common format -* ~~VirtusLab docker registry~~ https://hub.docker.com/r/virtuslab/jenkins-operator -* ~~decorate Jenkins API client and add more functions for handling jobs and builds e.g. Ensure, CreateOrUpdate~~ -* documentation -* ~~VirtusLab flavored Jenkins theme~~ * create Jenkins Jobs View for all jobs managed by the operator -* jenkins job for executing groovy scripts and configuration as code (from ConfigMap) +* code clean up and more tests Base configuration: -* ~~install configuration as a code Jenkins plugin~~ -* handle Jenkins restart when base configuration has changed -* ~~install~~ and configure Kubernetes plugin (in-progress) -* e2e pipelines using Kubernetes plugin -* Jenkins hardening, disable insecure options -* watch other Kubernetes resources by the fixed labels +* - User configuration: -* ~~user reconciliation loop with CR validation~~ -* ~~configure seed jobs and deploy keys~~ -* ~~e2e tests for seed jobs~~ -* mask private key build parameter using mask-plugin -* configure Jenkins authorization (via configuration as a code plugin or groovy scripts) * backup and restore for Jenkins jobs running as standalone job (AWS, GCP, Azure) * trigger backup job before pod deletion using preStop k8s hooks * verify Jenkins configuration events diff --git a/doc/getting-started.md b/doc/getting-started.md index 0c0cd8ac..9cd371bc 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -69,8 +69,83 @@ kubectl jenkins-operator-example 8080:8080 Jenkins operator uses [job-dsl][job-dsl] and [ssh-credentials][ssh-credentials] plugins for configuring seed jobs and deploy keys. +## Prepare job definitions and pipelines -It can be configured using `Jenkins.spec.seedJobs` section from custom resource manifest: +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 @@ -79,20 +154,38 @@ metadata: name: example spec: master: - image: jenkins/jenkins + image: jenkins/jenkins:lts seedJobs: - id: jenkins-operator targets: "cicd/jobs/*.jenkins" - description: "Jenkins Operator e2e tests repository" + description: "Jenkins Operator repository" repositoryBranch: master - repositoryUrl: git@github.com:VirtusLab/jenkins-operator-e2e.git + 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-e2e + key: jenkins-operator ``` -And corresponding Kubernetes Secret (in the same namespace) with private key: +And Kubernetes Secret: ``` apiVersion: v1 @@ -107,31 +200,15 @@ data: ... ``` -If your GitHub repository is public, you don't have to configure `privateKey` and create Kubernetes Secret: - -``` -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 -``` - -Jenkins operator will automatically configure and trigger Seed Job Pipeline for all entries from `Jenkins.spec.seedJobs`. +**jenkins-operator** will automatically discover and configure all seed jobs. ## Install Plugins ## Configure Authorization -## Configure Backup & Restore +## Configure Backup & Restore (work in progress) + +Not implemented yet. ## Debugging