Update docs

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
+- 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.
-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

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
+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:
 - 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
+- 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.