From 273eab0a6994670fcd6e10fc228ee4a2bfa9f90b Mon Sep 17 00:00:00 2001 From: Szymon Fugas Date: Wed, 6 Oct 2021 16:02:29 +0200 Subject: [PATCH] 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 --- .../content/en/docs/Developer Guide/_index.md | 5 +- .../content/en/docs/Developer Guide/tools.md | 57 --------- .../en/docs/Getting Started/latest/aks.md | 2 +- .../latest/custom-backup-and-restore.md | 2 +- .../latest/deploying-jenkins.md | 12 ++ .../Getting Started/latest/notifications.md | 114 ------------------ .../{security.md => separate-namespaces.md} | 72 ++--------- website/content/en/docs/Security/_index.md | 70 +++++++++++ .../content/en/docs/Troubleshooting/_index.md | 8 +- 9 files changed, 101 insertions(+), 241 deletions(-) delete mode 100644 website/content/en/docs/Developer Guide/tools.md delete mode 100644 website/content/en/docs/Getting Started/latest/notifications.md rename website/content/en/docs/Getting Started/latest/{security.md => separate-namespaces.md} (74%) create mode 100644 website/content/en/docs/Security/_index.md diff --git a/website/content/en/docs/Developer Guide/_index.md b/website/content/en/docs/Developer Guide/_index.md index d3a2caf8..4157a8c8 100644 --- a/website/content/en/docs/Developer Guide/_index.md +++ b/website/content/en/docs/Developer Guide/_index.md @@ -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/ diff --git a/website/content/en/docs/Developer Guide/tools.md b/website/content/en/docs/Developer Guide/tools.md deleted file mode 100644 index 95285d80..00000000 --- a/website/content/en/docs/Developer Guide/tools.md +++ /dev/null @@ -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 -``` diff --git a/website/content/en/docs/Getting Started/latest/aks.md b/website/content/en/docs/Getting Started/latest/aks.md index 806dfca0..8c190b9d 100644 --- a/website/content/en/docs/Getting Started/latest/aks.md +++ b/website/content/en/docs/Getting Started/latest/aks.md @@ -1,7 +1,7 @@ --- title: "AKS" linkTitle: "AKS" -weight: 9 +weight: 8 date: 2021-08-19 description: > Additional configuration for Azure Kubernetes Service diff --git a/website/content/en/docs/Getting Started/latest/custom-backup-and-restore.md b/website/content/en/docs/Getting Started/latest/custom-backup-and-restore.md index 65b0c3ab..da4258d3 100644 --- a/website/content/en/docs/Getting Started/latest/custom-backup-and-restore.md +++ b/website/content/en/docs/Getting Started/latest/custom-backup-and-restore.md @@ -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 diff --git a/website/content/en/docs/Getting Started/latest/deploying-jenkins.md b/website/content/en/docs/Getting Started/latest/deploying-jenkins.md index 88e4b7bd..a178012c 100644 --- a/website/content/en/docs/Getting Started/latest/deploying-jenkins.md +++ b/website/content/en/docs/Getting Started/latest/deploying-jenkins.md @@ -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. diff --git a/website/content/en/docs/Getting Started/latest/notifications.md b/website/content/en/docs/Getting Started/latest/notifications.md deleted file mode 100644 index 083c949a..00000000 --- a/website/content/en/docs/Getting Started/latest/notifications.md +++ /dev/null @@ -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= -``` - -Example configuration for Slack: - -```yaml -kind: Jenkins -spec: - master: - notifications: - - level: info - verbose: true - name: - slack: - webHookURLSecretKeySelector: - secret: - name: - 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: - teams: - webHookURLSecretKeySelector: - secret: - name: - key: -``` - -## Mailgun - -Example configuration for Mailgun: - -```yaml -kind: Jenkins -spec: - master: - notifications: - - level: info - verbose: true - name: - mailgun: - domain: - apiKeySecretKeySelector: - secret: - name: - key: - recipient: - from: -``` - -## 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: - key: - - level: info - verbose: true - name: nteams - teams: - webHookURLSecretKeySelector: - secret: - name: - key: -``` diff --git a/website/content/en/docs/Getting Started/latest/security.md b/website/content/en/docs/Getting Started/latest/separate-namespaces.md similarity index 74% rename from website/content/en/docs/Getting Started/latest/security.md rename to website/content/en/docs/Getting Started/latest/separate-namespaces.md index 26338b76..03001f82 100644 --- a/website/content/en/docs/Getting Started/latest/security.md +++ b/website/content/en/docs/Getting Started/latest/separate-namespaces.md @@ -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). diff --git a/website/content/en/docs/Security/_index.md b/website/content/en/docs/Security/_index.md new file mode 100644 index 00000000..187c7a9a --- /dev/null +++ b/website/content/en/docs/Security/_index.md @@ -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 \ No newline at end of file diff --git a/website/content/en/docs/Troubleshooting/_index.md b/website/content/en/docs/Troubleshooting/_index.md index 23dd27d0..989999a6 100644 --- a/website/content/en/docs/Troubleshooting/_index.md +++ b/website/content/en/docs/Troubleshooting/_index.md @@ -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 -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 ``` ## 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. \ No newline at end of file