Docs: General fixes and improvements (#662)
* Restore security docs (non-versioned), fix troubleshooting section * Fix links in security page, add prerequisites to deploying jenkins * Minor fixes in troubleshooting section * Fix order of main sections * Remove tools guide from developer guide * Fix order of Getting Started guide parts
This commit is contained in:
Szymon Fugas
GitHub
parent
266c2aa50d
commit
273eab0a69
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: "Developer Guide"
|
||||
linkTitle: "Developer Guide"
|
||||
weight: 4
|
||||
weight: 5
|
||||
date: 2021-10-01
|
||||
description: >
|
||||
Jenkins Operator for developers
|
||||
|
|
@ -16,7 +16,7 @@ This document explains how to setup your development environment.
|
|||
- [operator_sdk][operator_sdk] version 1.3.0
|
||||
- [git][git_tool]
|
||||
- [go][go_tool] version 1.15.6
|
||||
- [goimports, golint, checkmake and staticcheck][install_dev_tools]
|
||||
- goimports, golint, checkmake and staticcheck
|
||||
- [minikube][minikube] version 1.21.0 (preferred Hypervisor - [virtualbox][virtualbox]) (automatically downloaded)
|
||||
- [docker][docker_tool] version 17.03+
|
||||
|
||||
|
|
@ -326,4 +326,3 @@ It uses [cert-manager](https://cert-manager.io/) as an external dependency.
|
|||
[kubectl_tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/
|
||||
[minikube]:https://kubernetes.io/docs/tasks/tools/install-minikube/
|
||||
[virtualbox]:https://www.virtualbox.org/wiki/Downloads
|
||||
[install_dev_tools]:https://jenkinsci.github.io/kubernetes-operator/docs/developer-guide/tools/
|
||||
|
|
|
|||
|
|
@ -1,57 +0,0 @@
|
|||
---
|
||||
title: "Tools"
|
||||
linkTitle: "Tools"
|
||||
weight: 30
|
||||
date: 2019-08-05
|
||||
description: >
|
||||
Required tools for building and running Jenkins Operator
|
||||
---
|
||||
|
||||
{{% pageinfo %}}
|
||||
This document explains how to install the Go tools used by the development process.
|
||||
{{% /pageinfo %}}
|
||||
|
||||
## Configure environment variables
|
||||
|
||||
```bash
|
||||
export GOPATH=/home/go # example value
|
||||
export GOROOT=/usr/lib/go-1.12 # example value
|
||||
export PATH=$GOPATH/bin:$PATH
|
||||
```
|
||||
|
||||
## goimports
|
||||
|
||||
```
|
||||
go get golang.org/x/tools/cmd/goimports
|
||||
cd $GOPATH/src/golang.org/x/tools/cmd/goimports
|
||||
go build
|
||||
go install
|
||||
```
|
||||
|
||||
## golint
|
||||
|
||||
```
|
||||
go get -u golang.org/x/lint/golint
|
||||
cd $GOPATH/src/golang.org/x/lint/golint
|
||||
go build
|
||||
go install
|
||||
```
|
||||
|
||||
## checkmake
|
||||
```
|
||||
go get github.com/mrtazz/checkmake
|
||||
cd $GOPATH/src/github.com/mrtazz/checkmake
|
||||
go build
|
||||
go install
|
||||
```
|
||||
|
||||
## staticcheck
|
||||
|
||||
```
|
||||
mkdir -p $GOPATH/src/github.com/dominikh/
|
||||
cd $GOPATH/src/github.com/dominikh/
|
||||
git clone https://github.com/dominikh/go-tools.git
|
||||
cd $GOPATH/src/github.com/dominikh/go-tools/staticcheck
|
||||
go build
|
||||
go install
|
||||
```
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: "AKS"
|
||||
linkTitle: "AKS"
|
||||
weight: 9
|
||||
weight: 8
|
||||
date: 2021-08-19
|
||||
description: >
|
||||
Additional configuration for Azure Kubernetes Service
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: "Custom backup and restore providers"
|
||||
linkTitle: "Custom backup and restore providers"
|
||||
weight: 6
|
||||
weight: 7
|
||||
date: 2021-08-19
|
||||
description: >
|
||||
Custom backup and restore provider
|
||||
|
|
|
|||
|
|
@ -7,6 +7,18 @@ description: >
|
|||
Deploy production ready Jenkins manifest
|
||||
---
|
||||
|
||||
{{% pageinfo %}}
|
||||
This document describes the procedure for deploying Jenkins.
|
||||
{{% /pageinfo %}}
|
||||
|
||||
|
||||
## Prerequisites
|
||||
The Operator needs to have been deployed beforehand. The procedure for deploying Jenkins described here doesn't apply to
|
||||
installation of Operator via Helm chart unless `jenkins.enabled` was set to false.
|
||||
That’s because by default, installation via Helm chart also covers deploying Jenkins.
|
||||
|
||||
|
||||
## Deploying Jenkins instance
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,114 +0,0 @@
|
|||
---
|
||||
title: "Notifications"
|
||||
linkTitle: "Notifications"
|
||||
weight: 7
|
||||
date: 2021-08-19
|
||||
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:
|
||||
|
||||
```yaml
|
||||
kind: Jenkins
|
||||
spec:
|
||||
master:
|
||||
notifications:
|
||||
- level: 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:
|
||||
|
||||
```yaml
|
||||
kind: Jenkins
|
||||
spec:
|
||||
master:
|
||||
notifications:
|
||||
- level: info
|
||||
verbose: true
|
||||
name: <name>
|
||||
teams:
|
||||
webHookURLSecretKeySelector:
|
||||
secret:
|
||||
name: <secret_name>
|
||||
key: <key>
|
||||
```
|
||||
|
||||
## Mailgun
|
||||
|
||||
Example configuration for Mailgun:
|
||||
|
||||
```yaml
|
||||
kind: Jenkins
|
||||
spec:
|
||||
master:
|
||||
notifications:
|
||||
- level: 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:
|
||||
|
||||
* `level` (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.
|
||||
|
||||
```yaml
|
||||
kind: Jenkins
|
||||
spec:
|
||||
master:
|
||||
notifications:
|
||||
- level: info
|
||||
verbose: true
|
||||
name: nslack
|
||||
slack:
|
||||
webHookURLSecretKeySelector:
|
||||
secret:
|
||||
name: <secret_name>
|
||||
key: <key>
|
||||
- level: info
|
||||
verbose: true
|
||||
name: nteams
|
||||
teams:
|
||||
webHookURLSecretKeySelector:
|
||||
secret:
|
||||
name: <secret_name>
|
||||
key: <key>
|
||||
```
|
||||
|
|
@ -1,63 +1,13 @@
|
|||
---
|
||||
title: "Security"
|
||||
linkTitle: "Security"
|
||||
weight: 8
|
||||
title: "Separate namespaces for Jenkins and Operator"
|
||||
linkTitle: "Separate namespaces for Jenkins and Operator"
|
||||
weight: 6
|
||||
date: 2021-08-20
|
||||
description: >
|
||||
Jenkins security and hardening out of the box
|
||||
How to install Jenkins and Jenkins Operator in separate namespaces
|
||||
---
|
||||
|
||||
By default **Jenkins Operator** performs an initial security hardening of Jenkins instance
|
||||
via groovy scripts to prevent any security gaps.
|
||||
|
||||
## Jenkins Access Control
|
||||
|
||||
Currently **Jenkins Operator** generates a username and random password and stores them in a Kubernetes Secret.
|
||||
However any other authorization mechanisms are possible and can be done via groovy scripts or configuration as code plugin.
|
||||
For more information take a look at [getting-started#jenkins-customization](/kubernetes-operator/docs/getting-started/latest/customizing-jenkins/).
|
||||
|
||||
Any change to Security Realm or Authorization requires that user called `jenkins-operator` must have admin rights
|
||||
because **Jenkins Operator** calls Jenkins API.
|
||||
|
||||
## Jenkins Hardening
|
||||
|
||||
The list below describes all the default security setting configured by the **Jenkins Operator**:
|
||||
|
||||
- basic settings - use `Mode.EXCLUSIVE` - Jobs must specify that they want to run on master node
|
||||
- enable CSRF - Cross Site Request Forgery Protection is enabled
|
||||
- disable usage stats - Jenkins usage stats submitting is disabled
|
||||
- enable master access control - Slave to Master Access Control is enabled
|
||||
- disable old JNLP protocols - `JNLP3-connect`, `JNLP2-connect` and `JNLP-connect` are disabled
|
||||
- disable CLI - CLI access of `/cli` URL is disabled
|
||||
- configure kubernetes-plugin - secure configuration for Kubernetes plugin
|
||||
|
||||
If you would like to dig a little bit into the code, take a look [here](https://github.com/jenkinsci/kubernetes-operator/blob/master/pkg/configuration/base/resources/base_configuration_configmap.go).
|
||||
|
||||
## Jenkins API
|
||||
|
||||
The **Jenkins Operator** generates and configures Basic Authentication token for Jenkins Go client
|
||||
and stores it in a Kubernetes Secret.
|
||||
|
||||
## Kubernetes
|
||||
|
||||
Kubernetes API permissions are limited by the following roles:
|
||||
|
||||
- [jenkins-operator role](https://github.com/jenkinsci/kubernetes-operator/blob/v0.6.0/deploy/all-in-one-v1alpha2.yaml)
|
||||
- [Jenkins Master role](https://github.com/jenkinsci/kubernetes-operator/blob/v0.6.0/pkg/configuration/base/resources/rbac.go)
|
||||
|
||||
Since **Jenkins Operator** must be able to grant permission for its deployed Jenkins masters
|
||||
to spawn pods (the `Jenkins Master role` above),
|
||||
the operator itself requires permission to create RBAC resources (the `jenkins-operator role` above).
|
||||
|
||||
Deployed this way, any subject which may create a Pod (including a Jenkins job) may
|
||||
assume the `jenkins-operator` role by using its' ServiceAccount, create RBAC rules, and thus escape its granted permissions.
|
||||
Any namespace to which the `jenkins-operator` is deployed must be considered to implicitly grant all
|
||||
possible permissions to any subject which can create a Pod in that namespace.
|
||||
|
||||
To mitigate this issue **Jenkins Operator** should be deployed in one namespace, and the Jenkins CR should be created in a separate namespace.
|
||||
Section below contains instructions on how to do it.
|
||||
|
||||
## Setup Jenkins Operator and Jenkins in separate namespaces
|
||||
## Create namespaces
|
||||
|
||||
You need to create two namespaces, for example we'll call them **jenkins** for Jenkins and **jenkins-operator** for Jenkins Operator.
|
||||
```bash
|
||||
|
|
@ -65,6 +15,8 @@ $ kubectl create ns jenkins-operator
|
|||
$ kubectl create ns jenkins
|
||||
```
|
||||
|
||||
## Create necessary resources in Jenkins Operator namespace
|
||||
|
||||
Next, you need to install resources necessary for the Operator to work in the `jenkins-operator` namespace. To do that,
|
||||
copy the manifest you see below to `jenkins-operator-rbac.yaml`file.
|
||||
|
||||
|
|
@ -299,7 +251,7 @@ kubectl apply -n jenkins-operator -f jenkins-operator-rbac.yaml
|
|||
```
|
||||
|
||||
There's only one thing left to install in `jenkins-operator` namespace, and that is the Operator itself. The manifest
|
||||
below contains the Operator as defined in all-in-one manifest found in [Installating the Operator](/kubernetes-operator/docs/getting-started/latest/installing-the-operator/)
|
||||
below contains the Operator as defined in all-in-one manifest found in [Installing the Operator](/kubernetes-operator/docs/getting-started/latest/installing-the-operator/)
|
||||
page, the only difference is that the one here sets `WATCH_NAMESPACE` to the `jenkins` namespace we created.
|
||||
|
||||
Copy its content to `jenkins-operator.yaml` file.
|
||||
|
|
@ -369,7 +321,9 @@ You have installed the Operator in `jenkins-operator` namespace, watching for Je
|
|||
there are two things left to do: creating necessary Role and RoleBinding for the Operator in `jenkins` namespace, and
|
||||
deploying actual Jenkins instance there.
|
||||
|
||||
Below you can find manifest with RBAC that need to be created in `jenkins` namespace. Copy its content to `jenkins-ns-rbac.yaml` file.
|
||||
## Create necessary resources in Jenkins namespace
|
||||
|
||||
Below you can find manifest with RBAC that needs to be created in `jenkins` namespace. Copy its content to `jenkins-ns-rbac.yaml` file.
|
||||
|
||||
```yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
|
|
@ -625,7 +579,3 @@ kubectl apply -n jenkins -f jenkins-instance.yaml
|
|||
|
||||
With this, you have just set up Jenkins Operator and Jenkins in separate namespaces. Now the Operator will run in
|
||||
its own namespace (`jenkins-operator`), watch for CRs in `jenkins` namespace, and deploy Jenkins there.
|
||||
|
||||
## Report a Security Vulnerability
|
||||
|
||||
If you find a vulnerability or any misconfiguration in Jenkins, please report it in the [issues](https://github.com/jenkinsci/kubernetes-operator/issues).
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
title: "Security"
|
||||
linkTitle: "Security"
|
||||
weight: 3
|
||||
date: 2019-08-05
|
||||
description: >
|
||||
Jenkins security and hardening out of the box
|
||||
---
|
||||
|
||||
By default **Jenkins Operator** performs an initial security hardening of Jenkins instance
|
||||
via groovy scripts to prevent any security gaps.
|
||||
|
||||
## Jenkins Access Control
|
||||
|
||||
Currently **Jenkins Operator** generates a username and random password and stores them in a Kubernetes Secret.
|
||||
However any other authorization mechanisms are possible and can be done via groovy scripts or configuration as code plugin.
|
||||
For more information take a look at the section on [customizing Jenkins](/kubernetes-operator/docs/getting-started/latest/customizing-jenkins/).
|
||||
|
||||
Any change to Security Realm or Authorization requires that user called `jenkins-operator` must have admin rights
|
||||
because **Jenkins Operator** calls Jenkins API.
|
||||
|
||||
## Jenkins Hardening
|
||||
|
||||
The list below describes all the default security setting configured by the **Jenkins Operator**:
|
||||
|
||||
- basic settings - use `Mode.EXCLUSIVE` - Jobs must specify that they want to run on master node
|
||||
- enable CSRF - Cross Site Request Forgery Protection is enabled
|
||||
- disable usage stats - Jenkins usage stats submitting is disabled
|
||||
- enable master access control - Slave to Master Access Control is enabled
|
||||
- disable old JNLP protocols - `JNLP3-connect`, `JNLP2-connect` and `JNLP-connect` are disabled
|
||||
- disable CLI - CLI access of `/cli` URL is disabled
|
||||
- configure kubernetes-plugin - secure configuration for Kubernetes plugin
|
||||
|
||||
If you would like to dig a little bit into the code, take a look [here][base-configuration].
|
||||
|
||||
## Jenkins API
|
||||
|
||||
The **Jenkins Operator** generates and configures Basic Authentication token for Jenkins Go client
|
||||
and stores it in a Kubernetes Secret.
|
||||
|
||||
## Kubernetes
|
||||
|
||||
Kubernetes API permissions are limited by the following roles:
|
||||
|
||||
- [jenkins-operator role][jenkins-operator-role]
|
||||
- [Jenkins Controller (Master) role][jenkins-controller-role]
|
||||
|
||||
Since **Jenkins Operator** must be able to grant permission for its deployed Jenkins masters
|
||||
to spawn pods (the `Jenkins Master role` above),
|
||||
the operator itself requires permission to create RBAC resources (the `jenkins-operator role` above).
|
||||
|
||||
Deployed this way, any subject which may create a Pod (including a Jenkins job) may
|
||||
assume the `jenkins-operator` role by using its' ServiceAccount, create RBAC rules, and thus escape its granted permissions.
|
||||
Any namespace to which the `jenkins-operator` is deployed must be considered to implicitly grant all
|
||||
possible permissions to any subject which can create a Pod in that namespace.
|
||||
|
||||
To mitigate this issue, **Jenkins Operator** should be deployed in one namespace, and the Jenkins CR should be created in
|
||||
a separate namespace. For instructions on how to deploy Jenkins Operator and Jenkins in separate namespaces, head over
|
||||
to the [Separate namespaces](/kubernetes-operator/docs/getting-started/latest/separate-namespaces) section of Getting Started
|
||||
guide.
|
||||
|
||||
|
||||
## Report a Security Vulnerability
|
||||
|
||||
If you find a vulnerability or any misconfiguration in Jenkins, please report it in the [issues](https://github.com/jenkinsci/kubernetes-operator/issues).
|
||||
|
||||
[jenkins-operator-role]:https://github.com/jenkinsci/kubernetes-operator/blob/v0.6.0/deploy/all-in-one-v1alpha2.yaml
|
||||
[jenkins-controller-role]:https://github.com/jenkinsci/kubernetes-operator/blob/v0.6.0/pkg/configuration/base/resources/rbac.go
|
||||
[base-configuration]:https://github.com/jenkinsci/kubernetes-operator/blob/master/pkg/configuration/base/resources/base_configuration_configmap.go
|
||||
[issues]:https://github.com/jenkinsci/kubernetes-operator/issues
|
||||
|
|
@ -1,10 +1,10 @@
|
|||
---
|
||||
title: "Troubleshooting"
|
||||
linkTitle: "Troubleshooting"
|
||||
weight: 3
|
||||
weight: 4
|
||||
date: 2021-08-19
|
||||
description: >
|
||||
Jenkins security and hardening out of the box
|
||||
Troubleshooting Jenkins Operator
|
||||
---
|
||||
|
||||
This document helps you to state the reason for an error in the Jenkins Operator, which is the first step in solving it.
|
||||
|
|
@ -15,7 +15,7 @@ Jenkins Operator can provide some useful logs. To get them, run:
|
|||
$ kubectl logs <controller-manager-pod-name> -f
|
||||
```
|
||||
|
||||
In the logs look for WARNING, ERROR and SEVERE keywords.
|
||||
In the logs look for `WARNING`, `ERROR` and `SEVERE` keywords.
|
||||
|
||||
## Jenkins logs
|
||||
|
||||
|
|
@ -55,5 +55,5 @@ $ kubectl delete pod <jenkins-pod>
|
|||
```
|
||||
|
||||
## Operator debug mode
|
||||
If you need to access additional logs from the Operator, you can run it in debug mode. To do that, add ``"--debug""``
|
||||
If you need to access additional logs from the Operator, you can run it in debug mode. To do that, add ``"--debug"``
|
||||
argument to jenkins-operator container args in your Operator deployment.
|
||||
Loading…
Reference in New Issue