diff --git a/README.md b/README.md index 52bc27b9..408bfdcb 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,27 @@ # 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 provides out of the box: -- preconfigured Kubernetes plugin -- Seed Jobs and DSL Pipelines as code -- integration with Configuration as Code plugin -- secure and hardened Jenkins instance -- basic authentication with username and password +- integration with Kubernetes +- pipelines as code +- extensibility via groovy scripts or configuration as code plugin +- security and hardening + +## 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. -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: -- 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 -- declarative configuration as code +- better configuration as code - 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 - orphaned jobs with no jnlp connection - make errors more visible for end users @@ -43,7 +46,7 @@ Common: * documentation * ~~VirtusLab flavored Jenkins theme~~ * 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: * ~~install configuration as a code Jenkins plugin~~ @@ -51,11 +54,13 @@ Base configuration: * ~~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 diff --git a/doc/how-it-works.md b/doc/how-it-works.md index 8a7e343f..401e7590 100644 --- a/doc/how-it-works.md +++ b/doc/how-it-works.md @@ -5,6 +5,7 @@ This document describes a high level overview how **jenkins-operator** works. 1. [Architecture and design](#architecture-and-design) 2. [Operator State](#operator-state) 3. [System Jenkins Jobs](#system-jenkins-jobs) +3. [Jenkins Docker Images](#jenkins-docker-images) ## Architecture and design @@ -14,13 +15,13 @@ The **jenkins-operator** design incorporates the following concepts: ![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 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 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 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 @@ -35,12 +36,17 @@ It helps to maintain or recover desired state even after operator or Jenkins res ## 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 -custom jobs API for executing system jobs (seed jobs, groovy scripts, etc.) according to the operator lifecycle. +The operator or Jenkins instance can be restarted at any time and any operation should not block the reconciliation loop. +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: - 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 build expiration (deadline) -- keep state in the custom resource status \ No newline at end of file +- 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.