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

Update README.md and initial version of docs

This commit is contained in:
antoniaklja 2019-01-04 17:00:00 +01:00
parent 732342a56c
commit 2a0ac25515
5 changed files with 197 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
README.md
View File

@ -1,33 +1,33 @@
# jenkins-operator # 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 ## TODO
![jenkins-operator-draft](jenkins-operator-draft.png)
Common: Common:
* simple API for generating Kubernetes events using one common format * simple API for generating Kubernetes events using one common format
* ~~VirtusLab docker registry~~ https://hub.docker.com/r/virtuslab/jenkins-operator * ~~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~~ * ~~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/): * documentation
* Installation
* Getting Started
* Authorization
* Plugins
* Seed jobs
* Backup and Restore
* How it works
* architecture
* CR definition
* K8s events
* Debugging
* Base and User configuration
* Contributing
* ~~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~~
@ -48,74 +48,7 @@ User configuration:
* trigger backup job before pod deletion using preStop k8s hooks * trigger backup job before pod deletion using preStop k8s hooks
* verify Jenkins configuration events * verify Jenkins configuration events
## Configuration (this section has to be moved to external docs) [installation]:doc/installation.md
[getting_started]:doc/getting-started.md
This section describes Jenkins configuration. [how_it_works]:doc/how-it-works.md
### 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`.
[developer_guide]:doc/developer-guide.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

6
doc/developer-guide.md
View File

@ -28,7 +28,7 @@ Build and run `jenkins-operator` locally:
make build && make docker-build && make minikube-run EXTRA_ARGS='--minikube --local' 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 ```bash
kubectl apply -f jenkins-operator/deploy/crds/virtuslab_v1alpha1_jenkins_cr.yaml 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 make e2e E2E_IMAGE=jenkins-operator
``` ```
See the project [README][jenkins-operator] for more details.
## Hacks ## Hacks
### `pkg/apis/virtuslab/v1alpha1/jenkins_types` has changed ### `pkg/apis/virtuslab/v1alpha1/jenkins_types` has changed
@ -68,7 +66,7 @@ make deepcopy-gen
```bash ```bash
minikube service jenkins-operator-example --url 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
``` ```

124
doc/getting-started.md Normal file
View File

@ -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

15
doc/how-it-works.md Normal file
View File

@ -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

34
doc/installation.md Normal file
View File

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