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

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/

website/content/en/docs/Developer Guide/tools.md

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

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

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

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.
 

website/content/en/docs/Getting Started/latest/notifications.md

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

website/content/en/docs/Getting Started/latest/separate-namespaces.md

@@ -1,63 +1,13 @@
 ---
-title: "Security"
+title: "Separate namespaces for Jenkins and Operator"
-linkTitle: "Security"
+linkTitle: "Separate namespaces for Jenkins and Operator"
-weight: 8
+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 
+## Create namespaces
-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
 
 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).

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

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