From 2a0ac25515bf17e468824598a70d5599341dbb7b Mon Sep 17 00:00:00 2001 From: antoniaklja Date: Fri, 4 Jan 2019 17:00:00 +0100 Subject: [PATCH] Update README.md and initial version of docs --- README.md | 111 ++++++++---------------------------- doc/developer-guide.md | 6 +- doc/getting-started.md | 124 +++++++++++++++++++++++++++++++++++++++++ doc/how-it-works.md | 15 +++++ doc/installation.md | 34 +++++++++++ 5 files changed, 197 insertions(+), 93 deletions(-) create mode 100644 doc/getting-started.md create mode 100644 doc/how-it-works.md create mode 100644 doc/installation.md diff --git a/README.md b/README.md index 964c4875..db83b474 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,33 @@ # jenkins-operator -Kubernetes native Jenkins operator. +Kubernetes native Jenkins operator which manages Jenkins on Kubernetes. +It was built with immutability and declarative configuration as code in mind. -## Developer guide +It provides out of the box: +- Seed Jobs and DSL Pipelines as code +- Kubernetes plugin +- Configuration as Code plugin +- Secure and Hardened Jenkins instance +- Basic Authentication -Can be found [here][developer_guide]. +## Documentation + +1. [Installation][installation] +2. [Getting Started][getting_started] +3. [How it works][how_it_works] +4. [Developer Guide][developer_guide] + +## Contribution + +Feel free to file [issues](https://github.com/VirtusLab/jenkins-operator/issues) or [pull requests](https://github.com/VirtusLab/jenkins-operator/pulls). ## TODO -![jenkins-operator-draft](jenkins-operator-draft.png) - 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 [github pages with Hugo](https://gohugo.io/): - * Installation - * Getting Started - * Authorization - * Plugins - * Seed jobs - * Backup and Restore - * How it works - * architecture - * CR definition - * K8s events - * Debugging - * Base and User configuration - * Contributing +* documentation * ~~VirtusLab flavored Jenkins theme~~ * create Jenkins Jobs View for all jobs managed by the operator * ~~jenkins job for executing groovy scripts~~ @@ -48,74 +48,7 @@ User configuration: * trigger backup job before pod deletion using preStop k8s hooks * verify Jenkins configuration events -## Configuration (this section has to be moved to external docs) - -This section describes Jenkins configuration. - -### Seed Jobs - -Jenkins operator uses [job-dsl][job-dsl] and [ssh-credentials][ssh-credentials] plugins for configuring seed jobs -and deploy keys. - - -It can be configured using `Jenkins.spec.seedJobs` section from custom resource manifest: - -``` -apiVersion: virtuslab.com/v1alpha1 -kind: Jenkins -metadata: - name: example -spec: - master: - image: jenkins/jenkins - seedJobs: - - id: jenkins-operator - targets: "cicd/jobs/*.jenkins" - description: "Jenkins Operator e2e tests repository" - repositoryBranch: master - repositoryUrl: git@github.com:VirtusLab/jenkins-operator-e2e.git - privateKey: - secretKeyRef: - name: deploy-keys - key: jenkins-operator-e2e -``` - -And corresponding Kubernetes Secret (in the same namespace) with private key: - -``` -apiVersion: v1 -kind: Secret -metadata: - name: deploy-keys -data: - jenkins-operator-e2e: | - -----BEGIN RSA PRIVATE KEY----- - MIIJKAIBAAKCAgEAxxDpleJjMCN5nusfW/AtBAZhx8UVVlhhhIKXvQ+dFODQIdzO - oDXybs1zVHWOj31zqbbJnsfsVZ9Uf3p9k6xpJ3WFY9b85WasqTDN1xmSd6swD4N8 - ... -``` - -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`. - - +[installation]:doc/installation.md +[getting_started]:doc/getting-started.md +[how_it_works]:doc/how-it-works.md [developer_guide]:doc/developer-guide.md -[job-dsl]:https://github.com/jenkinsci/job-dsl-plugin -[ssh-credentials]:https://github.com/jenkinsci/ssh-credentials-plugin \ No newline at end of file diff --git a/doc/developer-guide.md b/doc/developer-guide.md index e867d9bb..37876831 100644 --- a/doc/developer-guide.md +++ b/doc/developer-guide.md @@ -28,7 +28,7 @@ Build and run `jenkins-operator` locally: make build && make docker-build && make minikube-run EXTRA_ARGS='--minikube --local' ``` -Once `minikube` and `jenkins-operator` are up and running, apply CR file: +Once `minikube` and `jenkins-operator` are up and running, apply Jenkins custom resource: ```bash kubectl apply -f jenkins-operator/deploy/crds/virtuslab_v1alpha1_jenkins_cr.yaml @@ -52,8 +52,6 @@ make docker-build-e2e make e2e E2E_IMAGE=jenkins-operator ``` -See the project [README][jenkins-operator] for more details. - ## Hacks ### `pkg/apis/virtuslab/v1alpha1/jenkins_types` has changed @@ -68,7 +66,7 @@ make deepcopy-gen ```bash minikube service jenkins-operator-example --url -kubectl get secret jenkins-operator-credentials-example -o yaml +kubectl get secret jenkins-operator-credentials-example -o 'jsonpath={.data.password}' | base64 -d ``` diff --git a/doc/getting-started.md b/doc/getting-started.md new file mode 100644 index 00000000..ca3e980b --- /dev/null +++ b/doc/getting-started.md @@ -0,0 +1,124 @@ +# Getting Started + +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 + +// TODO install operator etc. + +## Deploy Jenkins + +Once jenkins-operator is up and running let's deploy actual Jenkins instance. +Let's use example below: + +```bash +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 +``` + +Create Jenkins Custom Resource: + +```bash +kubectl create -f deploy/crds/virtuslab_v1alpha1_jenkins_cr.yaml +``` + +Watch Jenkins instance being created: + +```bash +kubectl get pods -w +``` + +Connect to Jenkins: + +// TODO (antoniaklja) + +## Configure Seed Jobs and Pipelines + +Jenkins operator uses [job-dsl][job-dsl] and [ssh-credentials][ssh-credentials] plugins for configuring seed jobs +and deploy keys. + + +It can be configured using `Jenkins.spec.seedJobs` section from custom resource manifest: + +``` +apiVersion: virtuslab.com/v1alpha1 +kind: Jenkins +metadata: + name: example +spec: + master: + image: jenkins/jenkins + seedJobs: + - id: jenkins-operator + targets: "cicd/jobs/*.jenkins" + description: "Jenkins Operator e2e tests repository" + repositoryBranch: master + repositoryUrl: git@github.com:VirtusLab/jenkins-operator-e2e.git + privateKey: + secretKeyRef: + name: deploy-keys + key: jenkins-operator-e2e +``` + +And corresponding Kubernetes Secret (in the same namespace) with private key: + +``` +apiVersion: v1 +kind: Secret +metadata: + name: deploy-keys +data: + jenkins-operator-e2e: | + -----BEGIN RSA PRIVATE KEY----- + MIIJKAIBAAKCAgEAxxDpleJjMCN5nusfW/AtBAZhx8UVVlhhhIKXvQ+dFODQIdzO + oDXybs1zVHWOj31zqbbJnsfsVZ9Uf3p9k6xpJ3WFY9b85WasqTDN1xmSd6swD4N8 + ... +``` + +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`. + +[job-dsl]:https://github.com/jenkinsci/job-dsl-plugin +[ssh-credentials]:https://github.com/jenkinsci/ssh-credentials-plugin + +## Install Plugins + +## Configure Authorization + +## Configure Backup & Restore + +## Debugging \ No newline at end of file diff --git a/doc/how-it-works.md b/doc/how-it-works.md new file mode 100644 index 00000000..79362d79 --- /dev/null +++ b/doc/how-it-works.md @@ -0,0 +1,15 @@ +# How it works + +This document describes a high level overview how jenkins-operator works. + +## Architecture and design + +![jenkins-operator-draft](../jenkins-operator-draft.png) + +## Base configuration + +## Jobs managed by jenkins-operator + +## Backup and Restore + +## Operator Status diff --git a/doc/installation.md b/doc/installation.md new file mode 100644 index 00000000..ff3d65e9 --- /dev/null +++ b/doc/installation.md @@ -0,0 +1,34 @@ +# Installation + +This document describes installation procedure for jenkins-operator. + +## Requirements + +To run jenkins-operator, you will need: +- running Kubernetes cluster +- kubectl +- optionally Kubernetes namespace for jenkins-operator + +## Configure Custom Resource Definition + +Install Jenkins Custom Resource Definition: + +```bash +kubectl create -f deploy/crds/virtuslab_v1alpha1_jenkins_crd.yaml +``` + +## Deploy jenkins-operator + +Deploy jenkins-operator with RBAC (it may take some time): + +```bash +kubectl create -f deploy/service_account.yaml +kubectl create -f deploy/role.yaml +kubectl create -f deploy/role_binding.yaml +kubectl create -f deploy/operator.yaml +``` + +Now jenkins-operator should be up and running within `default` namespace. + + +