public_git
/
kubernetes-operator
mirror of https://github.com/jenkinsci/kubernetes-operator.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Update docs

This commit is contained in:
antoniaklja 2019-01-08 21:44:17 +01:00
parent ef7cd96cb3
commit a6a85bcbf0
2 changed files with 28 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
README.md
View File

@ -1,24 +1,27 @@
# Jenkins Operator # Jenkins Operator
Kubernetes native Jenkins operator which manages Jenkins on Kubernetes. ## What's Jenkins Operator?
Jenkins operator it's a Kubernetes native operator which fully manages Jenkins on Kubernetes.
It was built with immutability and declarative configuration as code in mind. It was built with immutability and declarative configuration as code in mind.
It provides out of the box: It provides out of the box:
- preconfigured Kubernetes plugin - integration with Kubernetes
- Seed Jobs and DSL Pipelines as code - pipelines as code
- integration with Configuration as Code plugin - extensibility via groovy scripts or configuration as code plugin
- secure and hardened Jenkins instance - security and hardening
- basic authentication with username and password
## Problem statement and goals
The main reason why we decided to write the **jenkins-operator** is the fact that we faced a lot of problems with standard Jenkins deployment. The main reason why we decided to write the **jenkins-operator** is the fact that we faced a lot of problems with standard Jenkins deployment.
Also, we heavily use Jenkins on large production Kubernetes clusters in a multi-tenant environment. We want to make Jenkins more robust, suitable for dynamic and multi-tenant environments.
Some of the problems we want to solve: Some of the problems we want to solve:
- volumes handling (AWS EBS volume attach/detach issue) - volumes handling (AWS EBS volume attach/detach issue when using PVC)
- installing plugins with incompatible versions or security vulnerabilities - installing plugins with incompatible versions or security vulnerabilities
- declarative configuration as code - better configuration as code
- lack of end to end tests - lack of end to end tests
- make Jenkins more suitable for dynamic environment and handle graceful shutdown properly - handle graceful shutdown properly
- security and hardening out of the box - security and hardening out of the box
- orphaned jobs with no jnlp connection - orphaned jobs with no jnlp connection
- make errors more visible for end users - make errors more visible for end users
@ -43,7 +46,7 @@ Common:
* documentation * documentation
* ~~VirtusLab flavored Jenkins theme~~ * ~~VirtusLab flavored Jenkins theme~~
* create Jenkins Jobs View for all jobs managed by the operator * create Jenkins Jobs View for all jobs managed by the operator
* ~~jenkins job for executing groovy scripts~~ * jenkins job for executing groovy scripts and configuration as code (from ConfigMap)
Base configuration: Base configuration:
* ~~install configuration as a code Jenkins plugin~~ * ~~install configuration as a code Jenkins plugin~~
@ -51,11 +54,13 @@ Base configuration:
* ~~install~~ and configure Kubernetes plugin (in-progress) * ~~install~~ and configure Kubernetes plugin (in-progress)
* e2e pipelines using Kubernetes plugin * e2e pipelines using Kubernetes plugin
* Jenkins hardening, disable insecure options * Jenkins hardening, disable insecure options
* watch other Kubernetes resources by the fixed labels
User configuration: User configuration:
* ~~user reconciliation loop with CR validation~~ * ~~user reconciliation loop with CR validation~~
* ~~configure seed jobs and deploy keys~~ * ~~configure seed jobs and deploy keys~~
* ~~e2e tests for seed jobs~~ * ~~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) * 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) * backup and restore for Jenkins jobs running as standalone job (AWS, GCP, Azure)
* trigger backup job before pod deletion using preStop k8s hooks * trigger backup job before pod deletion using preStop k8s hooks

18
doc/how-it-works.md
View File

@ -5,6 +5,7 @@ This document describes a high level overview how **jenkins-operator** works.
1. [Architecture and design](#architecture-and-design) 1. [Architecture and design](#architecture-and-design)
2. [Operator State](#operator-state) 2. [Operator State](#operator-state)
3. [System Jenkins Jobs](#system-jenkins-jobs) 3. [System Jenkins Jobs](#system-jenkins-jobs)
3. [Jenkins Docker Images](#jenkins-docker-images)
## Architecture and design ## Architecture and design
@ -14,13 +15,13 @@ The **jenkins-operator** design incorporates the following concepts:
![reconcile](../reconcile.png) ![reconcile](../reconcile.png)
Base reconciliation loop takes care of reconciling base Jenkins configuration, which consists of: **Base** reconciliation loop takes care of reconciling base Jenkins configuration, which consists of:
- Ensure Manifests - monitors any changes in manifests - Ensure Manifests - monitors any changes in manifests
- Ensure Jenkins Pod - creates and verifies status of Jenkins master Pod - Ensure Jenkins Pod - creates and verifies status of Jenkins master Pod
- Ensure Jenkins Configuration - configures Jenkins instance including hardening, initial configuration for plugins, etc. - Ensure Jenkins Configuration - configures Jenkins instance including hardening, initial configuration for plugins, etc.
- Ensure Jenkins API token - generates Jenkins API token and initialized Jenkins client - Ensure Jenkins API token - generates Jenkins API token and initialized Jenkins client
User reconciliation loop takes care of reconciling user provided configuration, which consists of: **User** reconciliation loop takes care of reconciling user provided configuration, which consists of:
- Ensure Restore Job - creates Restore job and ensures that restore has been successfully performed - Ensure Restore Job - creates Restore job and ensures that restore has been successfully performed
- Ensure Seed Jobs - creates Seed Jobs and ensures that all of them have been successfully executed - Ensure Seed Jobs - creates Seed Jobs and ensures that all of them have been successfully executed
- Ensure User Configuration - executed user provided configuration, like groovy scripts, configuration as code or plugins - Ensure User Configuration - executed user provided configuration, like groovy scripts, configuration as code or plugins
@ -35,12 +36,17 @@ It helps to maintain or recover desired state even after operator or Jenkins res
## System Jenkins Jobs ## System Jenkins Jobs
The operator or Jenkins instance can be restarted at any time and any operation should not block the reconciliation loop so we implemented The operator or Jenkins instance can be restarted at any time and any operation should not block the reconciliation loop.
custom jobs API for executing system jobs (seed jobs, groovy scripts, etc.) according to the operator lifecycle. Taking this into account we implemented custom jobs API for executing system jobs (seed jobs, groovy scripts, etc.) according to the operator lifecycle.
Main assumptions are: Main assumptions are:
- do not block reconciliation loop - do not block reconciliation loop
- fire job, requeue reconciliation loop and verify status next time - fire job, requeue reconciliation loop and verify job status next time
- handle retries if case of failure - handle retries if case of failure
- handle build expiration (deadline) - handle build expiration (deadline)
- keep state in the custom resource status - keep state in the custom resource status section
## Jenkins Docker Images
**jenkins-operator** is fully compatible with **jenkins:lts** docker image and does not introduce and hidden changes there.
In case of need docker image can be easily changed in custom resource manifest as long as it supports standard Jenkins file system structure.