Add docs for 0.3.0 version to the website

This commit is contained in:
Tomasz Sęk 2019-12-20 15:03:04 +01:00
parent b6e10574e9
commit d7a706c4aa
No known key found for this signature in database
GPG Key ID: DC356D23F6A644D0
20 changed files with 3254 additions and 42 deletions

View File

@ -1,14 +1,14 @@
---
title: "Latest (v0.2.x)"
linkTitle: "Latest (v0.2.x)"
title: "Latest (v0.3.x)"
linkTitle: "Latest (v0.3.x)"
weight: 10
date: 2019-08-05
date: 2019-12-20
description: >
How to work with jenkins-operator latest version
---
{{% pageinfo %}}
This document describes a getting started guide for **Jenkins Operator** `v0.2.x` and an additional configuration.
This document describes a getting started guide for **Jenkins Operator** `v0.3.x` and an additional configuration.
{{% /pageinfo %}}
## First Steps

View File

@ -2,7 +2,7 @@
title: "AKS"
linkTitle: "AKS"
weight: 10
date: 2019-08-05
date: 2019-12-20
description: >
Additional configuration for Azure Kubernetes Service
---

View File

@ -2,7 +2,7 @@
title: "Configuration"
linkTitle: "Configuration"
weight: 2
date: 2019-08-05
date: 2019-12-20
description: >
How to configure Jenkins with Operator
---

View File

@ -2,7 +2,7 @@
title: "Configure backup and restore"
linkTitle: "Configure backup and restore"
weight: 10
date: 2019-08-05
date: 2019-12-20
description: >
Prevent loss of job history
---

View File

@ -2,7 +2,7 @@
title: "Custom Backup and Restore Providers"
linkTitle: "Custom Backup and Restore Providers"
weight: 10
date: 2019-08-05
date: 2019-12-20
description: >
Custom backup and restore provider
---

View File

@ -2,7 +2,7 @@
title: "Customization"
linkTitle: "Customization"
weight: 3
date: 2019-08-05
date: 2019-12-20
description: >
How to customize Jenkins
---

View File

@ -2,7 +2,7 @@
title: "Deploy Jenkins"
linkTitle: "Deploy Jenkins"
weight: 1
date: 2019-08-05
date: 2019-12-20
description: >
Deploy production ready Jenkins Operator manifest
---

View File

@ -2,7 +2,7 @@
title: "Diagnostics"
linkTitle: "Diagnostics"
weight: 40
date: 2019-08-05
date: 2019-12-20
description: >
How to deal with Jenkins Operator problems
---

View File

@ -0,0 +1,114 @@
---
title: "Notifications"
linkTitle: "Notifications"
weight: 10
date: 2019-12-20
description: >
How to setup operator notifications.
---
## Slack
Please follow [this](https://api.slack.com/incoming-webhooks) instructions to get web hook URL.
Create web hook secret with name `jenkins-operator-notification-data`. Contains key `url` with provided web hook URL.
```bash
$ kubectl create secret generic jenkins-operator-notification-data --from-literal=url=<webhook_url>
```
Example configuration for Slack:
```
kind: Jenkins
spec:
master:
notifications:
- loggingLevel: info
verbose: true
name: <name>
slack:
webHookURLSecretKeySelector:
secret:
name: <secret_name>
key: <key>
```
## Microsoft Teams
Please follow [this](https://docs.microsoft.com/en-gb/outlook/actionable-messages/send-via-connectors) instructions to get web hook URL.
Example configuration for Microsoft Teams:
```
kind: Jenkins
spec:
master:
notifications:
- loggingLevel: info
verbose: true
name: <name>
teams:
webHookURLSecretKeySelector:
secret:
name: <secret_name>
key: <key>
```
## Mailgun
Example configuration for Mailgun:
```
kind: Jenkins
spec:
master:
notifications:
- loggingLevel: info
verbose: true
name: <name>
mailgun:
domain: <domain>
apiKeySecretKeySelector:
secret:
name: <secret_name>
key: <key>
recipient: <your_email>
from: <mailgun_email>
```
## Debug options
As you see there is two debugging options:
* `loggingLevel` (warning/info) - Set level of messages to send.
* `verbose` - Print stacktrace and additional error messages
## Multiple providers
You can use multiple providers to send notification to another communication channels at the same time.
For example you will send notifications to Slack and Teams.
```
kind: Jenkins
spec:
master:
notifications:
- loggingLevel: info
verbose: true
name: nslack
slack:
webHookURLSecretKeySelector:
secret:
name: <secret_name>
key: <key>
- loggingLevel: info
verbose: true
name: nteams
teams:
webHookURLSecretKeySelector:
secret:
name: <secret_name>
key: <key>
```

View File

@ -2,7 +2,7 @@
title: "Schema"
linkTitle: "Schema"
weight: 40
date: 2019-08-05
date: 2019-12-20
description: >
API Schema definitions for Jenkins CRD
---
@ -19,7 +19,7 @@ This document contains API scheme for `jenkins-operator` Custom Resource Definit
</ul>
<h2 id="jenkins.io">jenkins.io</h2>
<p>
<p>Package v1alpha2 contains the API Schema definitions for the jenkins.io v1alpha2 API group</p>
<p>Package v1alpha2 contains API Schema definitions for the jenkins.io v1alpha2 API group</p>
</p>
Resource Types:
<ul><li>
@ -108,12 +108,26 @@ Every single change here requires a pod restart.</p>
</td>
<td>
<em>(Optional)</em>
<p>SeedJobs defines a list of Jenkins Seed Job configurations
<p>SeedJobs defines list of Jenkins Seed Job configurations
More info: <a href="https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-seed-jobs-and-pipelines">https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-seed-jobs-and-pipelines</a></p>
</td>
</tr>
<tr>
<td>
<code>notifications</code></br>
<em>
<a href="#github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Notification">
[][]github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Notification
</a>
</em>
</td>
<td>
<p>Notifications defines list of a services which are used to inform about Jenkins status
Can be used to integrate chat services like Slack, Microsoft Teams or Mailgun</p>
</td>
</tr>
<tr>
<td>
<code>service</code></br>
<em>
<a href="#github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Service">
@ -123,7 +137,7 @@ Service
</td>
<td>
<em>(Optional)</em>
<p>Service is the Kubernetes service of the Jenkins master HTTP pod
<p>Service is Kubernetes service of Jenkins master HTTP pod
Defaults to :
port: 8080
type: ClusterIP</p>
@ -140,7 +154,7 @@ Service
</td>
<td>
<em>(Optional)</em>
<p>Service is the Kubernetes service of the Jenkins slave pods
<p>Service is Kubernetes service of Jenkins slave pods
Defaults to :
port: 50000
type: ClusterIP</p>
@ -157,7 +171,7 @@ Backup
</td>
<td>
<em>(Optional)</em>
<p>Backup defines the configuration of a Jenkins backup
<p>Backup defines configuration of Jenkins backup
More info: <a href="https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-backup-and-restore">https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-backup-and-restore</a></p>
</td>
</tr>
@ -172,7 +186,7 @@ Restore
</td>
<td>
<em>(Optional)</em>
<p>Backup defines the configuration of a Jenkins backup restore
<p>Backup defines configuration of Jenkins backup restore
More info: <a href="https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-backup-and-restore">https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-backup-and-restore</a></p>
</td>
</tr>
@ -187,7 +201,7 @@ GroovyScripts
</td>
<td>
<em>(Optional)</em>
<p>GroovyScripts defines the configuration of Jenkins customization via groovy scripts</p>
<p>GroovyScripts defines configuration of Jenkins customization via groovy scripts</p>
</td>
</tr>
<tr>
@ -201,7 +215,7 @@ ConfigurationAsCode
</td>
<td>
<em>(Optional)</em>
<p>ConfigurationAsCode defines the configuration of Jenkins customization via the Configuration as Code Jenkins plugin</p>
<p>ConfigurationAsCode defines configuration of Jenkins customization via Configuration as Code Jenkins plugin</p>
</td>
</tr>
</table>
@ -292,7 +306,7 @@ string
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.JenkinsSpec">JenkinsSpec</a>)
</p>
<p>
<p>Backup defines the configuration of a Jenkins backup</p>
<p>Backup defines configuration of Jenkins backup</p>
</p>
<table>
<thead>
@ -323,7 +337,7 @@ Handler
</em>
</td>
<td>
<p>Action defines the action which performs the backup in the backup container sidecar</p>
<p>Action defines action which performs backup in backup container sidecar</p>
</td>
</tr>
<tr>
@ -334,7 +348,7 @@ uint64
</em>
</td>
<td>
<p>Interval tells you how often the backup is made in seconds
<p>Interval tells how often make backup in seconds
Defaults to 30.</p>
</td>
</tr>
@ -346,7 +360,7 @@ bool
</em>
</td>
<td>
<p>MakeBackupBeforePodDeletion tells the operator to make a backup before Jenkins master pod deletion</p>
<p>MakeBackupBeforePodDeletion tells operator to make backup before Jenkins master pod deletion</p>
</td>
</tr>
</tbody>
@ -358,7 +372,7 @@ bool
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.Customization">Customization</a>)
</p>
<p>
<p>ConfigMapRef is the reference to Kubernetes ConfigMap</p>
<p>ConfigMapRef is reference to Kubernetes ConfigMap</p>
</p>
<table>
<thead>
@ -387,7 +401,7 @@ string
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.JenkinsSpec">JenkinsSpec</a>)
</p>
<p>
<p>ConfigurationAsCode defines configuration of Jenkins customization via the Configuration as Code Jenkins plugin</p>
<p>ConfigurationAsCode defines configuration of Jenkins customization via Configuration as Code Jenkins plugin</p>
</p>
<table>
<thead>
@ -418,7 +432,7 @@ Customization
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.JenkinsMaster">JenkinsMaster</a>)
</p>
<p>
<p>Container defines the Kubernetes container attributes</p>
<p>Container defines Kubernetes container attributes</p>
</p>
<table>
<thead>
@ -773,7 +787,7 @@ Kubernetes core/v1.ExecAction
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.SeedJob">SeedJob</a>)
</p>
<p>
<p>JenkinsCredentialType defines the type of Jenkins credential used in the seed job mechanism</p>
<p>JenkinsCredentialType defines type of Jenkins credential used to seed job mechanism</p>
</p>
<h3 id="github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.JenkinsMaster">JenkinsMaster
</h3>
@ -795,7 +809,7 @@ every single change requires a Jenkins master pod restart</p>
<tbody>
<tr>
<td>
<code>masterAnnotations</code></br>
<code>annotations</code></br>
<em>
map[string]string
</em>
@ -810,6 +824,22 @@ More info: <a href="http://kubernetes.io/docs/user-guide/annotations">http://kub
</tr>
<tr>
<td>
<code>masterAnnotations</code></br>
<em>
map[string]string
</em>
</td>
<td>
<em>(Optional)</em>
<p>Annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: <a href="http://kubernetes.io/docs/user-guide/annotations">http://kubernetes.io/docs/user-guide/annotations</a>
Deprecated: will be removed in the future, please use Annotations(annotations)</p>
</td>
</tr>
<tr>
<td>
<code>nodeSelector</code></br>
<em>
map[string]string
@ -963,6 +993,17 @@ version: 0.12.1</p>
<p>Plugins contains plugins required by user</p>
</td>
</tr>
<tr>
<td>
<code>disableCSRFProtection</code></br>
<em>
bool
</em>
</td>
<td>
<p>DisableCSRFProtection allows you to toggle CSRF Protection on Jenkins</p>
</td>
</tr>
</tbody>
</table>
<h3 id="github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.JenkinsSpec">JenkinsSpec
@ -1013,6 +1054,20 @@ More info: <a href="https://github.com/jenkinsci/kubernetes-operator/blob/master
</tr>
<tr>
<td>
<code>notifications</code></br>
<em>
<a href="#github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Notification">
[][]github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Notification
</a>
</em>
</td>
<td>
<p>Notifications defines list of a services which are used to inform about Jenkins status
Can be used to integrate chat services like Slack, Microsoft Teams or Mailgun</p>
</td>
</tr>
<tr>
<td>
<code>service</code></br>
<em>
<a href="#github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Service">
@ -1233,7 +1288,7 @@ string
</td>
<td>
<em>(Optional)</em>
<p>UserAndPasswordHash is a SHA256 hash made from the username and password</p>
<p>UserAndPasswordHash is a SHA256 hash made from user and password</p>
</td>
</tr>
<tr>
@ -1245,7 +1300,7 @@ string
</td>
<td>
<em>(Optional)</em>
<p>CreatedSeedJobs contains list of seed job ids already created in Jenkins</p>
<p>CreatedSeedJobs contains list of seed job id already created in Jenkins</p>
</td>
</tr>
<tr>
@ -1360,6 +1415,10 @@ SecretKeySelector
<h3 id="github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Notification">Notification
</h3>
<p>
(<em>Appears on:</em>
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.JenkinsSpec">JenkinsSpec</a>)
</p>
<p>
<p>Notification is a service configuration used to send notifications about Jenkins status</p>
</p>
<table>
@ -1372,10 +1431,10 @@ SecretKeySelector
<tbody>
<tr>
<td>
<code>loggingLevel</code></br>
<code>level</code></br>
<em>
<a href="#github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.NotificationLogLevel">
NotificationLogLevel
<a href="#github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.NotificationLevel">
NotificationLevel
</a>
</em>
</td>
@ -1438,16 +1497,28 @@ github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Mailgun
<td>
</td>
</tr>
<tr>
<td>
<code>smtp</code></br>
<em>
<a href="#github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.SMTP">
github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.SMTP
</a>
</em>
</td>
<td>
</td>
</tr>
</tbody>
</table>
<h3 id="github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.NotificationLogLevel">NotificationLogLevel
<h3 id="github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.NotificationLevel">NotificationLevel
(<code>string</code> alias)</p></h3>
<p>
(<em>Appears on:</em>
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.Notification">Notification</a>)
</p>
<p>
<p>NotificationLogLevel defines logging level of Notification</p>
<p>NotificationLevel defines the level of a Notification</p>
</p>
<h3 id="github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Plugin">Plugin
</h3>
@ -1545,12 +1616,106 @@ uint64
</tr>
</tbody>
</table>
<h3 id="github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.SMTP">SMTP
</h3>
<p>
(<em>Appears on:</em>
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.Notification">Notification</a>)
</p>
<p>
<p>SMTP is handler for sending emails via this protocol</p>
</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>usernameSecretKeySelector</code></br>
<em>
<a href="#github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.SecretKeySelector">
SecretKeySelector
</a>
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>passwordSecretKeySelector</code></br>
<em>
<a href="#github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.SecretKeySelector">
SecretKeySelector
</a>
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>port</code></br>
<em>
int
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>server</code></br>
<em>
string
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>tlsInsecureSkipVerify</code></br>
<em>
bool
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>from</code></br>
<em>
string
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>to</code></br>
<em>
string
</em>
</td>
<td>
</td>
</tr>
</tbody>
</table>
<h3 id="github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.SecretKeySelector">SecretKeySelector
</h3>
<p>
(<em>Appears on:</em>
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.Mailgun">Mailgun</a>,
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.MicrosoftTeams">MicrosoftTeams</a>,
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.SMTP">SMTP</a>,
<a href="#github.com%2fjenkinsci%2fkubernetes-operator%2fpkg%2fapis%2fjenkins%2fv1alpha2.Slack">Slack</a>)
</p>
<p>
@ -1679,7 +1844,7 @@ string
</em>
</td>
<td>
<p>Targets is the repository path where the seed job definitions are</p>
<p>Targets is the repository path where are seed job definitions</p>
</td>
</tr>
<tr>
@ -1690,7 +1855,7 @@ string
</em>
</td>
<td>
<p>RepositoryBranch is the repository branch where the seed job definitions are</p>
<p>RepositoryBranch is the repository branch where are seed job definitions</p>
</td>
</tr>
<tr>
@ -1887,7 +2052,7 @@ int32
</em>
</td>
<td>
<p>The port that is exposed by this service.
<p>The port that are exposed by this service.
More info: <a href="https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies">https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies</a></p>
</td>
</tr>
@ -1902,7 +2067,7 @@ int32
<em>(Optional)</em>
<p>The port on each node on which this service is exposed when type=NodePort or LoadBalancer.
Usually assigned by the system. If specified, it will be allocated to the service
if unused, or else creation of the service will fail.
if unused or else creation of the service will fail.
Default is to auto-allocate a port if the ServiceType of this Service requires one.
More info: <a href="https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport">https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport</a></p>
</td>
@ -1917,7 +2082,7 @@ More info: <a href="https://kubernetes.io/docs/concepts/services-networking/serv
<td>
<em>(Optional)</em>
<p>If specified and supported by the platform, this will restrict traffic through the cloud-provider
the load-balancer will be restricted to the specified client IPs. This field will be ignored if the
load-balancer will be restricted to the specified client IPs. This field will be ignored if the
cloud-provider does not support the feature.&rdquo;
More info: <a href="https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/">https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/</a></p>
</td>
@ -1975,5 +2140,5 @@ SecretKeySelector
<hr/>
<p><em>
Generated with <code>gen-crd-api-reference-docs</code>
on git commit <code>f4c4235</code>.
on git commit <code>b6e1057</code>.
</em></p>

View File

@ -0,0 +1,18 @@
---
title: "Latest (v0.2.x)"
linkTitle: "Latest (v0.2.x)"
weight: 10
date: 2019-08-05
description: >
How to work with jenkins-operator latest version
---
{{% pageinfo %}}
This document describes a getting started guide for **Jenkins Operator** `v0.2.x` and an additional configuration.
{{% /pageinfo %}}
## First Steps
Prepare your Kubernetes cluster and set up your `kubectl` access.
Once you have running Kubernetes cluster you can focus on installing **Jenkins Operator** according to the [Installation](/kubernetes-operator/docs/installation/) guide.

View File

@ -0,0 +1,24 @@
---
title: "AKS"
linkTitle: "AKS"
weight: 10
date: 2019-08-05
description: >
Additional configuration for Azure Kubernetes Service
---
Azure AKS managed Kubernetes service adds to every pod the following environment variables:
```yaml
- name: KUBERNETES_PORT_443_TCP_ADDR
value:
- name: KUBERNETES_PORT
value: tcp://
- name: KUBERNETES_PORT_443_TCP
value: tcp://
- name: KUBERNETES_SERVICE_HOST
value:
```
The operator is aware of it and omits these environment variables when checking if a Jenkins pod environment has been changed. It prevents the
restart of a Jenkins pod over and over again.

View File

@ -0,0 +1,325 @@
---
title: "Configuration"
linkTitle: "Configuration"
weight: 2
date: 2019-08-05
description: >
How to configure Jenkins with Operator
---
## Configure Seed Jobs and Pipelines
Jenkins operator uses [job-dsl][job-dsl] and [kubernetes-credentials-provider][kubernetes-credentials-provider] plugins for configuring jobs
and deploy keys.
## Prepare job definitions and pipelines
First you have to prepare pipelines and job definition in your GitHub repository using the following structure:
```
cicd/
├── jobs
│   └── build.jenkins
└── pipelines
└── build.jenkins
```
**`cicd/jobs/build.jenkins`** is a job definition:
```
#!/usr/bin/env groovy
pipelineJob('build-jenkins-operator') {
displayName('Build jenkins-operator')
definition {
cpsScm {
scm {
git {
remote {
url('https://github.com/jenkinsci/kubernetes-operator.git')
credentials('jenkins-operator')
}
branches('*/master')
}
}
scriptPath('cicd/pipelines/build.jenkins')
}
}
}
```
**`cicd/pipelines/build.jenkins`** is an actual Jenkins pipeline:
```
#!/usr/bin/env groovy
def label = "build-jenkins-operator-${UUID.randomUUID().toString()}"
def home = "/home/jenkins"
def workspace = "${home}/workspace/build-jenkins-operator"
def workdir = "${workspace}/src/github.com/jenkinsci/kubernetes-operator/"
podTemplate(label: label,
containers: [
containerTemplate(name: 'jnlp', image: 'jenkins/jnlp-slave:alpine'),
containerTemplate(name: 'go', image: 'golang:1-alpine', command: 'cat', ttyEnabled: true),
],
envVars: [
envVar(key: 'GOPATH', value: workspace),
],
) {
node(label) {
dir(workdir) {
stage('Init') {
timeout(time: 3, unit: 'MINUTES') {
checkout scm
}
container('go') {
sh 'apk --no-cache --update add make git gcc libc-dev'
}
}
stage('Dep') {
container('go') {
sh 'make dep'
}
}
stage('Test') {
container('go') {
sh 'make test'
}
}
stage('Build') {
container('go') {
sh 'make build'
}
}
}
}
}
```
## Configure Seed Jobs
Jenkins Seed Jobs are configured using `Jenkins.spec.seedJobs` section from your custom resource manifest:
```
apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
name: example
spec:
seedJobs:
- id: jenkins-operator
targets: "cicd/jobs/*.jenkins"
description: "Jenkins Operator repository"
repositoryBranch: master
repositoryUrl: https://github.com/jenkinsci/kubernetes-operator.git
```
**Jenkins Operator** will automatically discover and configure all the seed jobs.
You can verify if deploy keys were successfully configured in the Jenkins **Credentials** tab.
![jenkins](/kubernetes-operator/img/jenkins-credentials.png)
You can verify if your pipelines were successfully configured in the Jenkins Seed Job console output.
![jenkins](/kubernetes-operator/img/jenkins-seed.png)
If your GitHub repository is **private** you have to configure SSH or username/password authentication.
### SSH authentication
#### Generate SSH Keys
There are two methods of SSH private key generation:
```bash
$ openssl genrsa -out <filename> 2048
```
or
```bash
$ ssh-keygen -t rsa -b 2048
$ ssh-keygen -p -f <filename> -m pem
```
Then copy content from generated file.
#### Public key
If you want to upload your public key to your Git server you need to extract it.
If key was generated by `openssl` then you need to type this to extract public key:
```bash
$ openssl rsa -in <filename> -pubout > <filename>.pub
```
If key was generated by `ssh-keygen` the public key content is located in <filename>.pub and there is no need to extract public key
#### Configure SSH authentication
Configure a seed job like this:
```
apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
name: example
spec:
seedJobs:
- id: jenkins-operator-ssh
credentialType: basicSSHUserPrivateKey
credentialID: k8s-ssh
targets: "cicd/jobs/*.jenkins"
description: "Jenkins Operator repository"
repositoryBranch: master
repositoryUrl: git@github.com:jenkinsci/kubernetes-operator.git
```
and create a Kubernetes Secret (name of secret should be the same from `credentialID` field):
```
apiVersion: v1
kind: Secret
metadata:
name: k8s-ssh
stringData:
privateKey: |
-----BEGIN RSA PRIVATE KEY-----
MIIJKAIBAAKCAgEAxxDpleJjMCN5nusfW/AtBAZhx8UVVlhhhIKXvQ+dFODQIdzO
oDXybs1zVHWOj31zqbbJnsfsVZ9Uf3p9k6xpJ3WFY9b85WasqTDN1xmSd6swD4N8
...
username: github_user_name
```
### Username & password authentication
Configure the seed job like:
```
apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
name: example
spec:
seedJobs:
- id: jenkins-operator-user-pass
credentialType: usernamePassword
credentialID: k8s-user-pass
targets: "cicd/jobs/*.jenkins"
description: "Jenkins Operator repository"
repositoryBranch: master
repositoryUrl: https://github.com/jenkinsci/kubernetes-operator.git
```
and create a Kubernetes Secret (name of secret should be the same from `credentialID` field):
```
apiVersion: v1
kind: Secret
metadata:
name: k8s-user-pass
stringData:
username: github_user_name
password: password_or_token
```
## HTTP Proxy for downloading plugins
To use forwarding proxy with an operator to download plugins you need to add the following environment variable to Jenkins Custom Resource (CR), e.g.:
```yaml
spec:
master:
containers:
- name: jenkins-master
env:
- name: CURL_OPTIONS
value: -L -x <proxy_url>
```
In `CURL_OPTIONS` var you can set additional arguments to `curl` command.
## Pulling Docker images from private repositories
To pull a Docker Image from private repository you can use `imagePullSecrets`.
Please follow the instructions on [creating a secret with a docker config](https://kubernetes.io/docs/concepts/containers/images/?origin_team=T42NTAGHM#creating-a-secret-with-a-docker-config).
### Docker Hub Configuration
To use Docker Hub additional steps are required.
Edit the previously created secret:
```bash
kubectl -n <namespace> edit secret <name>
```
The `.dockerconfigjson` key's value needs to be replaced with a modified version.
After modifications, it needs to be encoded as a Base64 value before setting the `.dockerconfigjson` key.
Example config file to modify and use:
```
{
"auths":{
"https://index.docker.io/v1/":{
"username":"user",
"password":"password",
"email":"yourdockeremail@gmail.com",
"auth":"base64 of string user:password"
},
"auth.docker.io":{
"username":"user",
"password":"password",
"email":"yourdockeremail@gmail.com",
"auth":"base64 of string user:password"
},
"registry.docker.io":{
"username":"user",
"password":"password",
"email":"yourdockeremail@gmail.com",
"auth":"base64 of string user:password"
},
"docker.io":{
"username":"user",
"password":"password",
"email":"yourdockeremail@gmail.com",
"auth":"base64 of string user:password"
},
"https://registry-1.docker.io/v2/": {
"username":"user",
"password":"password",
"email":"yourdockeremail@gmail.com",
"auth":"base64 of string user:password"
},
"registry-1.docker.io/v2/": {
"username":"user",
"password":"password",
"email":"yourdockeremail@gmail.com",
"auth":"base64 of string user:password"
},
"registry-1.docker.io": {
"username":"user",
"password":"password",
"email":"yourdockeremail@gmail.com",
"auth":"base64 of string user:password"
},
"https://registry-1.docker.io": {
"username":"user",
"password":"password",
"email":"yourdockeremail@gmail.com",
"auth":"base64 of string user:password"
}
}
}
```
[job-dsl]:https://github.com/jenkinsci/job-dsl-plugin
[kubernetes-credentials-provider]:https://jenkinsci.github.io/kubernetes-credentials-provider-plugin/

View File

@ -0,0 +1,86 @@
---
title: "Configure backup and restore"
linkTitle: "Configure backup and restore"
weight: 10
date: 2019-08-05
description: >
Prevent loss of job history
---
Backup and restore is done by a container sidecar.
### PVC
#### Create PVC
Save to the file named pvc.yaml:
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: <pvc_name>
namespace: <namespace>
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 500Gi
```
Run the following command:
```bash
$ kubectl -n <namespace> create -f pvc.yaml
```
#### Configure Jenkins CR
```yaml
apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
name: <cr_name>
namespace: <namespace>
spec:
master:
securityContext:
runAsUser: 1000
fsGroup: 1000
containers:
- name: jenkins-master
image: jenkins/jenkins:lts
- name: backup # container responsible for the backup and restore
env:
- name: BACKUP_DIR
value: /backup
- name: JENKINS_HOME
value: /jenkins-home
- name: BACKUP_COUNT
value: "3" # keep only the 2 most recent backups
image: virtuslab/jenkins-operator-backup-pvc:v0.0.7 # look at backup/pvc directory
imagePullPolicy: IfNotPresent
volumeMounts:
- mountPath: /jenkins-home # Jenkins home volume
name: jenkins-home
- mountPath: /backup # backup volume
name: backup
volumes:
- name: backup # PVC volume where backups will be stored
persistentVolumeClaim:
claimName: <pvc_name>
backup:
containerName: backup # container name is responsible for backup
action:
exec:
command:
- /home/user/bin/backup.sh # this command is invoked on "backup" container to make backup, for example /home/user/bin/backup.sh <backup_number>, <backup_number> is passed by operator
interval: 30 # how often make backup in seconds
makeBackupBeforePodDeletion: true # make a backup before pod deletion
restore:
containerName: backup # container name is responsible for restore backup
action:
exec:
command:
- /home/user/bin/restore.sh # this command is invoked on "backup" container to make restore backup, for example /home/user/bin/restore.sh <backup_number>, <backup_number> is passed by operator
#recoveryOnce: <backup_number> # if want to restore specific backup configure this field and then Jenkins will be restarted and desired backup will be restored
```

View File

@ -0,0 +1,184 @@
---
title: "Custom Backup and Restore Providers"
linkTitle: "Custom Backup and Restore Providers"
weight: 10
date: 2019-08-05
description: >
Custom backup and restore provider
---
With enough effort one can create a custom backup and restore provider
for the Jenkins Operator.
## Requirements
Two commands (e.g. scripts) are required:
- a backup command, e.g. `backup.sh` that takes one argument, a **backup number**
- a restore command, e.g. `backup.sh` that takes one argument, a **backup number**
Both scripts need to return an exit code of `0` on success and `1` or greater for failure.
One of those scripts (or the entry point of the container) needs to be responsible
for backup cleanup or rotation if required, or an external system.
## How it works
The mechanism relies on basic Kubernetes and UNIX functionalities.
The backup (and restore) container runs as a sidecar in the same
Kubernetes pod as the Jenkins master.
Name of the backup and restore containers can be set as necessary using
`spec.backup.containerName` and `spec.restore.containerName`.
In most cases it will be the same container, but we allow for less common use cases.
The operator will call a backup or restore commands inside a sidecar container when necessary:
- backup command (defined in `spec.backup.action.exec.command`)
will be called every `N` seconds configurable in: `spec.backup.interval`
and on pod shutdown (if enabled in `spec.backup.makeBackupBeforePodDeletion`)
with an integer representing the current backup number as first and only argument
- restore command (defined in `spec.restore.action.exec.command`)
will be called at Jenkins startup
with an integer representing the backup number to restore as first and only argument
(can be overridden using `spec.restore.recoveryOnce`)
## Example AWS S3 backup using the CLI
This example shows abbreviated version of a simple AWS S3 backup implementation
using: `aws-cli`, `bash` and `kube2iam`.
In addition to your normal `Jenkins` `CustomResource` some additional settings
for backup and restore are required, e.g.:
```yaml
kind: Jenkins
apiVersion: jenkins.io/v1alpha1
metadata:
name: example
namespace: jenkins
spec:
master:
masterAnnotations:
iam.amazonaws.com/role: "my-example-backup-role" # tell kube2iam where the AWS IAM role is
containers:
- name: jenkins-master
...
- name: backup # container responsible for backup and restore
image: quay.io/virtuslab/aws-cli:1.16.263-2
workingDir: /home/user/bin/
command: # our container entry point
- sleep
- infinity
env:
- name: BACKUP_BUCKET
value: my-example-bucket # the S3 bucket name to use
- name: BACKUP_PATH
value: my-backup-path # the S3 bucket path prefix to use
- name: JENKINS_HOME
value: /jenkins-home # the path to mount jenkins home dir in the backup container
volumeMounts:
- mountPath: /jenkins-home # Jenkins home volume
name: jenkins-home
- mountPath: /home/user/bin/backup.sh
name: backup-scripts
subPath: backup.sh
readOnly: true
- mountPath: /home/user/bin/restore.sh
name: backup-scripts
subPath: restore.sh
readOnly: true
volumes:
- name: backup-scripts
configMap:
defaultMode: 0754
name: jenkins-operator-backup-s3
securityContext: # make sure both containers use the same UID and GUID
runAsUser: 1000
fsGroup: 1000
...
backup:
containerName: backup # container name responsible for backup
interval: 3600 # how often make a backup in seconds
makeBackupBeforePodDeletion: true # trigger backup just before deleting the pod
action:
exec:
command:
# this command is invoked on "backup" container to create a backup,
# <backup_number> is passed by operator,
# for example /home/user/bin/backup.sh <backup_number>
- /home/user/bin/backup.sh
restore:
containerName: backup # container name is responsible for restore backup
action:
exec:
command:
# this command is invoked on "backup" container to restore a backup,
# <backup_number> is passed by operator
# for example /home/user/bin/restore.sh <backup_number>
- /home/user/bin/restore.sh
# recoveryOnce: <backup_number> # if want to restore specific backup configure this field and then Jenkins will be restarted and desired backup will be restored
```
The actual backup and restore scripts will be provided in a `ConfigMap`:
```yaml
kind: ConfigMap
apiVersion: v1
metadata:
name: jenkins-operator-backup-s3
namespace: jenkins
labels:
app: jenkins-operator
data:
backup.sh: |-
#!/bin/bash -xeu
[[ ! $# -eq 1 ]] && echo "Usage: $0 backup_number" && exit 1;
[[ -z "${BACKUP_BUCKET}" ]] && echo "Required 'BACKUP_BUCKET' env not set" && exit 1;
[[ -z "${BACKUP_PATH}" ]] && echo "Required 'BACKUP_PATH' env not set" && exit 1;
[[ -z "${JENKINS_HOME}" ]] && echo "Required 'JENKINS_HOME' env not set" && exit 1;
backup_number=$1
echo "Running backup #${backup_number}"
BACKUP_TMP_DIR=$(mktemp -d)
tar -C ${JENKINS_HOME} -czf "${BACKUP_TMP_DIR}/${backup_number}.tar.gz" --exclude jobs/*/workspace* -c jobs && \
aws s3 cp ${BACKUP_TMP_DIR}/${backup_number}.tar.gz s3://${BACKUP_BUCKET}/${BACKUP_PATH}/${backup_number}.tar.gz
echo Done
restore.sh: |-
#!/bin/bash -xeu
[[ ! $# -eq 1 ]] && echo "Usage: $0 backup_number" && exit 1
[[ -z "${BACKUP_BUCKET}" ]] && echo "Required 'BACKUP_BUCKET' env not set" && exit 1;
[[ -z "${BACKUP_PATH}" ]] && echo "Required 'BACKUP_PATH' env not set" && exit 1;
[[ -z "${JENKINS_HOME}" ]] && echo "Required 'JENKINS_HOME' env not set" && exit 1;
backup_number=$1
echo "Running restore #${backup_number}"
BACKUP_TMP_DIR=$(mktemp -d)
aws s3 cp s3://${BACKUP_BUCKET}/${BACKUP_PATH}/${backup_number}.tar.gz ${BACKUP_TMP_DIR}/${backup_number}.tar.gz
tar -C ${JENKINS_HOME} -zxf "${BACKUP_TMP_DIR}/${backup_number}.tar.gz"
echo Done
```
In our example we will use S3 bucket lifecycle policy to keep
the number of backups under control, e.g. Cloud Formation fragment:
```yaml
Type: AWS::S3::Bucket
Properties:
BucketName: my-example-bucket
...
LifecycleConfiguration:
Rules:
- Id: BackupCleanup
Status: Enabled
Prefix: my-backup-path
ExpirationInDays: 7
NoncurrentVersionExpirationInDays: 14
AbortIncompleteMultipartUpload:
DaysAfterInitiation: 3
```

View File

@ -0,0 +1,186 @@
---
title: "Customization"
linkTitle: "Customization"
weight: 3
date: 2019-08-05
description: >
How to customize Jenkins
---
Jenkins can be customized using groovy scripts or the [configuration as code plugin](https://github.com/jenkinsci/configuration-as-code-plugin).
By using a [ConfigMap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) you can create your own **Jenkins** customized configuration.
Then you must reference the **`ConfigMap`** in the **Jenkins** pod customization file in `spec.groovyScripts` or `spec.configurationAsCode`
For example create a **`ConfigMap`** with name `jenkins-operator-user-configuration`. Then, modify the **Jenkins** manifest to look like this:
```yaml
apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
name: example
spec:
configurationAsCode:
configurations:
- name: jenkins-operator-user-configuration
groovyScripts:
configurations:
- name: jenkins-operator-user-configuration
```
Here is an example of `jenkins-operator-user-configuration`:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: jenkins-operator-user-configuration
data:
1-configure-theme.groovy: |
import jenkins.*
import jenkins.model.*
import hudson.*
import hudson.model.*
import org.jenkinsci.plugins.simpletheme.ThemeElement
import org.jenkinsci.plugins.simpletheme.CssTextThemeElement
import org.jenkinsci.plugins.simpletheme.CssUrlThemeElement
Jenkins jenkins = Jenkins.getInstance()
def decorator = Jenkins.instance.getDescriptorByType(org.codefirst.SimpleThemeDecorator.class)
List<ThemeElement> configElements = new ArrayList<>();
configElements.add(new CssTextThemeElement("DEFAULT"));
configElements.add(new CssUrlThemeElement("https://cdn.rawgit.com/afonsof/jenkins-material-theme/gh-pages/dist/material-light-green.css"));
decorator.setElements(configElements);
decorator.save();
jenkins.save()
1-system-message.yaml: |
jenkins:
systemMessage: "Configuration as Code integration works!!!"
```
* `*.groovy` is Groovy script configuration
* `*.yaml is` configuration as code
If you want to correct your configuration you can edit it while the **Jenkins Operator** is running.
Jenkins will reconcile and apply the new configuration.
### Using secrets from a Groovy script
If you configured `spec.groovyScripts.secret.name`, then this secret is available to use from map Groovy scripts.
The secrets are loaded to `secrets` map.
Create a [secret](https://kubernetes.io/docs/concepts/configuration/secret/) with for example the name `jenkins-conf-secrets`.
```yaml
kind: Secret
apiVersion: v1
type: Opaque
metadata:
name: jenkins-conf-secrets
namespace: default
data:
SYSTEM_MESSAGE: SGVsbG8gd29ybGQ=
```
Then modify the **Jenkins** pod manifest by changing `spec.groovyScripts.secret.name` to `jenkins-conf-secrets`.
```yaml
apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
name: example
spec:
configurationAsCode:
configurations:
- name: jenkins-operator-user-configuration
secret:
name: jenkins-conf-secrets
groovyScripts:
configurations:
- name: jenkins-operator-user-configuration
secret:
name: jenkins-conf-secrets
```
Now you can test that the secret is mounted by applying this `ConfigMap` for Groovy script:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: jenkins-operator-user-configuration
data:
1-system-message.groovy: |
import jenkins.*
import jenkins.model.*
import hudson.*
import hudson.model.*
Jenkins jenkins = Jenkins.getInstance()
jenkins.setSystemMessage(secrets["SYSTEM_MESSAGE"])
jenkins.save()
```
Or by applying this configuration as code:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: jenkins-operator-user-configuration
data:
1-system-message.yaml: |
jenkins:
systemMessage: ${SYSTEM_MESSAGE}
```
After this, you should see the `Hello world` system message from the **Jenkins** homepage.
## Install Plugins
Edit Custom Resource under `spec.master.plugins`:
```
apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
name: example
spec:
master:
plugins:
- name: simple-theme-plugin
version: 0.5.1
```
Under `spec.master.basePlugins` you can find plugins for a valid **Jenkins Operator**:
```yaml
apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
name: example
spec:
master:
basePlugins:
- name: kubernetes
version: 1.18.3
- name: workflow-job
version: "2.34"
- name: workflow-aggregator
version: "2.6"
- name: git
version: 3.12.0
- name: job-dsl
version: "1.76"
- name: configuration-as-code
version: "1.29"
- name: configuration-as-code-support
version: "1.19"
- name: kubernetes-credentials-provider
version: 0.12.1
```
You can change their versions.
The **Jenkins Operator** will then automatically install plugins after the Jenkins master pod restarts.

View File

@ -0,0 +1,89 @@
---
title: "Deploy Jenkins"
linkTitle: "Deploy Jenkins"
weight: 1
date: 2019-08-05
description: >
Deploy production ready Jenkins Operator manifest
---
Once Jenkins Operator is up and running let's deploy actual Jenkins instance.
Create manifest e.g. **`jenkins_instance.yaml`** with following data and save it on drive.
```bash
apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
name: example
spec:
master:
containers:
- name: jenkins-master
image: jenkins/jenkins:lts
imagePullPolicy: Always
livenessProbe:
failureThreshold: 12
httpGet:
path: /login
port: http
scheme: HTTP
initialDelaySeconds: 80
periodSeconds: 10
successThreshold: 1
timeoutSeconds: 5
readinessProbe:
failureThreshold: 3
httpGet:
path: /login
port: http
scheme: HTTP
initialDelaySeconds: 30
periodSeconds: 10
successThreshold: 1
timeoutSeconds: 1
resources:
limits:
cpu: 1500m
memory: 3Gi
requests:
cpu: "1"
memory: 500Mi
seedJobs:
- id: jenkins-operator
targets: "cicd/jobs/*.jenkins"
description: "Jenkins Operator repository"
repositoryBranch: master
repositoryUrl: https://github.com/jenkinsci/kubernetes-operator.git
```
Deploy a Jenkins to Kubernetes:
```bash
kubectl create -f jenkins_instance.yaml
```
Watch the Jenkins instance being created:
```bash
kubectl get pods -w
```
Get the Jenkins credentials:
```bash
kubectl get secret jenkins-operator-credentials-<cr_name> -o 'jsonpath={.data.user}' | base64 -d
kubectl get secret jenkins-operator-credentials-<cr_name> -o 'jsonpath={.data.password}' | base64 -d
```
Connect to the Jenkins instance (minikube):
```bash
minikube service jenkins-operator-http-<cr_name> --url
```
Connect to the Jenkins instance (actual Kubernetes cluster):
```bash
kubectl port-forward jenkins-<cr_name> 8080:8080
```
Then open browser with address `http://localhost:8080`.
![jenkins](/img/jenkins.png)

View File

@ -0,0 +1,42 @@
---
title: "Diagnostics"
linkTitle: "Diagnostics"
weight: 40
date: 2019-08-05
description: >
How to deal with Jenkins Operator problems
---
Turn on debug in **Jenkins Operator** deployment:
```bash
sed -i 's|\(args:\).*|\1\ ["--debug"\]|' deploy/operator.yaml
kubectl apply -f deploy/operator.yaml
```
Watch Kubernetes events:
```bash
kubectl get events --sort-by='{.lastTimestamp}'
```
Verify Jenkins master logs:
```bash
kubectl logs -f jenkins-<cr_name>
```
Verify the `jenkins-operator` logs:
```bash
kubectl logs deployment/jenkins-operator
```
## Troubleshooting
Delete the Jenkins master pod and wait for the new one to come up:
```bash
kubectl delete pod jenkins-<cr_name>
```

File diff suppressed because it is too large Load Diff