Docs: information architecture and security guide update (#634)

* Add FAQ section * Add Troubleshooting section * Use Jenkins Operator as project name instead of jenkins-operator * Move installation and security pages to section on version they are for * Fix order of versions in getting started in section menu * Configure side bar menu to be compact * Rename getting started subpages * Update Security docs for 0.6 (#611) * Fix ordering of main sections in docs section menu * Add more descriptive names for customization and configuration sections * Update Getting Started index to link to latest version installation
jenkinsci · Aug 19, 2021 · 03cfa75 · 03cfa75
1 parent f8621fc
commit 03cfa75
Show file tree

Hide file tree

Showing 25 changed files with 764 additions and 197 deletions.
diff --git a/website/config.toml b/website/config.toml
@@ -90,7 +90,7 @@ gcs_engine_id = "011737558837375720776:fsdu1nryfng"
 # User interface configuration
 [params.ui]
 # Enable to show the side bar menu in its compact state.
-sidebar_menu_compact = false
+sidebar_menu_compact = true
 #  Set to true to disable breadcrumb navigation.
 breadcrumb_disable = false
 #  Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)

diff --git 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: 60
+weight: 4
 date: 2021-07-30
 description: >
   Jenkins Operator for developers

diff --git a/website/content/en/docs/FAQ/_index.md b/website/content/en/docs/FAQ/_index.md
@@ -0,0 +1,28 @@
+---
+title: "FAQ"
+linkTitle: "FAQ"
+date: 2021-07-01
+weight: 6
+description: >
+    Frequently Asked Questions about running Jenkins Operator
+---
+
+This document answers the most frequently asked questions.
+
+### My Jenkins pod keeps restarting with ‘missing-plugins’ errors.
+Jenkins can lose compatibility with its plugins or their dependencies.
+If you want to reduce the probability of it happening, don’t use ‘latest’ Jenkins image tag.
+Use set version of Jenkins image and declare plugins and all their dependencies in the Jenkins
+Custom Resource under ‘plugins’. If you are not sure which plugins to pin, you can check the logs
+from the ‘initial-config’ initcontainer or ‘jenkins-master’.
+
+### My job fails saying I don't have necessary permissions.
+You can always add a custom Role for your Jenkins with the permissions you need and reference it in the
+Jenkins Custom Resource under 'spec.roles'. The Operator will create a RoleBinding for it. Be careful.
+Operator may also not have these permissions. As a quick temporary workaround, you can manually bind this
+role to the Operator service account.
+
+### How can I change JENKINS_HOME from volume to Persistent Volume?
+In order to provide smooth extension, scalability and errorless backups, Jenkins needs to stay ephemeral.
+There is no way to change volume for JENKINS_HOME. All the configurations should be volatile in Jenkins
+and kept in a VCS.
diff --git a/website/content/en/docs/Getting Started/_index.md b/website/content/en/docs/Getting Started/_index.md
@@ -1,10 +1,10 @@
 ---
 title: "Getting Started"
 linkTitle: "Getting Started"
-weight: 10
+weight: 2
 date: 2019-08-05
 description: >
-  How to work with jenkins-operator
+  How to work with Jenkins Operator
 ---
 
 {{% pageinfo %}}
@@ -15,4 +15,5 @@ This document describes a getting started guide for **Jenkins Operator**
 
 Prepare your Kubernetes cluster and set up your `kubectl` access.
 
-Once you have a running Kubernetes cluster you can focus on installing **Jenkins Operator** according to the [Installation](/kubernetes-operator/docs/installation/) guide.
+Once you have a running Kubernetes cluster you can focus on installing **Jenkins Operator** according to the
+[Installation](/kubernetes-operator/docs/getting-started/latest/installing-the-operator/) guide.
diff --git a/website/content/en/docs/Getting Started/latest/_index.md b/website/content/en/docs/Getting Started/latest/_index.md
@@ -1,8 +1,8 @@
 ---
 title: "Latest (v0.6.x)"
 linkTitle: "Latest (v0.6.x)"
-weight: 10
-date: 2021-08-18
+weight: 1
+date: 2021-01-18
 description: >
   How to work with the latest, currently supported Jenkins Operator version.
 ---
@@ -15,4 +15,5 @@ This document describes a getting started guide for **Jenkins Operator** `v0.6.x
 
 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.
+Once you have a running Kubernetes cluster you can focus on installing **Jenkins Operator** according to the 
+[Installation](/kubernetes-operator/docs/getting-started/latest/installing-the-operator/) guide.
diff --git 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: 10
+weight: 9
 date: 2021-01-18
 description: >
     Additional configuration for Azure Kubernetes Service

diff --git a/...ed/latest/configure-backup-and-restore.md → .../latest/configuring-backup-and-restore.md b/...ed/latest/configure-backup-and-restore.md → .../latest/configuring-backup-and-restore.md
@@ -1,7 +1,7 @@
 ---
-title: "Configure backup and restore"
-linkTitle: "Configure backup and restore"
-weight: 10
+title: "Configuring backup and restore"
+linkTitle: "Configuring backup and restore"
+weight: 5
 date: 2021-01-25
 description: >
   Prevent loss of job history

diff --git a/...s/Getting Started/latest/configuration.md → ...st/configuring-seed-jobs-and-pipelines.md b/...s/Getting Started/latest/configuration.md → ...st/configuring-seed-jobs-and-pipelines.md
@@ -1,7 +1,7 @@
 ---
-title: "Configuration"
-linkTitle: "Configuration"
-weight: 2
+title: "Configuring Seed Jobs and Pipelines"
+linkTitle: "Configuring Seed Jobs and Pipelines"
+weight: 4
 date: 2021-01-25
 description: >
   How to configure Jenkins with Operator

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
@@ -1,7 +1,7 @@
 ---
-title: "Custom Backup and Restore Providers"
-linkTitle: "Custom Backup and Restore Providers"
-weight: 10
+title: "Custom backup and restore providers"
+linkTitle: "Custom backup and restore providers"
+weight: 6
 date: 2021-01-18
 description: >
   Custom backup and restore provider

diff --git a/...s/Getting Started/latest/customization.md → ...omization-with-groovy-scripts-and-casc.md b/...s/Getting Started/latest/customization.md → ...omization-with-groovy-scripts-and-casc.md
@@ -1,6 +1,6 @@
 ---
-title: "Customization"
-linkTitle: "Customization"
+title: "Customization with Groovy Scripts and CasC"
+linkTitle: "Customization with Groovy Scripts and CasC"
 weight: 3
 date: 2021-01-25
 description: >

diff --git a/.../Getting Started/latest/deploy-jenkins.md → ...tting Started/latest/deploying-jenkins.md b/.../Getting Started/latest/deploy-jenkins.md → ...tting Started/latest/deploying-jenkins.md
@@ -1,10 +1,10 @@
 ---
-title: "Deploy Jenkins"
-linkTitle: "Deploy Jenkins"
-weight: 1
+title: "Deploying Jenkins"
+linkTitle: "Deploying Jenkins"
+weight: 2
 date: 2021-01-25
 description: >
-  Deploy production ready Jenkins Operator manifest
+  Deploy production ready Jenkins manifest
 ---
 
 Once Jenkins Operator is up and running let's deploy actual Jenkins instance.

diff --git a/website/content/en/docs/Getting Started/latest/diagnostics.md b/website/content/en/docs/Getting Started/latest/diagnostics.md
diff --git a/...te/content/en/docs/Installation/_index.md → ...Started/latest/installing-the-operator.md b/...te/content/en/docs/Installation/_index.md → ...Started/latest/installing-the-operator.md
@@ -1,6 +1,6 @@
 ---
-title: "Installation"
-linkTitle: "Installation"
+title: "Installing the Operator"
+linkTitle: "Installing the Operator"
 weight: 1
 date: 2021-08-16
 description: >
@@ -20,7 +20,7 @@ To run **Jenkins Operator**, you will need:
 - `kubectl` version `1.17+`
 
 
-Listed below are the two ways to deploy Jenkins Operator. For details on how to customize your Jenkins instance, refer to [Getting Started](/kubernetes-operator/docs/getting-started/).
+Listed below are the two ways to deploy Jenkins Operator.
 
 ## Deploy Jenkins Operator using YAML's
 
@@ -30,7 +30,7 @@ First, install Jenkins Custom Resource Definition:
 kubectl apply -f https://raw.githubusercontent.com/jenkinsci/kubernetes-operator/master/config/crd/bases/jenkins.io_jenkins.yaml 
 ```
 
-Then, apply the operator and other required resources:
+Then, install the Operator and other required resources:
 
 ```bash
 kubectl apply -f https://raw.githubusercontent.com/jenkinsci/kubernetes-operator/master/deploy/all-in-one-v1alpha2.yaml
@@ -62,12 +62,6 @@ $ helm repo add jenkins https://raw.githubusercontent.com/jenkinsci/kubernetes-o
 $ helm install <name> jenkins/jenkins-operator -n <your-namespace>
 ```
 
-In case you want to use released Chart **v0.4.1**, before installing/upgrading please install additional CRD into the cluster:
-
-```bash
-$ kubectl apply -f https://raw.githubusercontent.com/jenkinsci/kubernetes-operator/master/chart/jenkins-operator/crds/jenkinsimage-crd.yaml
-```
-
 To add custom labels and annotations, you can use `values.yaml` file or pass them into `helm install` command, e.g.:
 
 ```bash
@@ -881,7 +875,7 @@ Example:<br />
 ## Note on Operator's nightly built images
 If you wish to use the newest, not yet released version of the Operator, you can use one of nightly built snapshot images, however the maintainers of this project cannot guarantee their stability.
 
-You can find nightly built images by heading to [virtuslab/jenkins-operator](https://hub.docker.com/r/virtuslab/jenkins-operator) Docker Hub repository and looking for images with tag in the form of "{git-hash}", {git-hash} being the hash of master branch commit that you want to use snapshot of.
+You can find nightly built images by heading to [virtuslab/jenkins-operator](https://hub.docker.com/r/virtuslab/jenkins-operator) Docker Hub repository and looking for images with tag in the form of `{git-hash}`, {git-hash} being the hash of master branch commit that you want to use snapshot of.
 
 ## Note on restricted Jenkins controller pod volumeMounts
 Current design of the Operator puts an emphasis on creating a full GitOps flow of work for Jenkins users.

diff --git a/website/content/en/docs/Getting Started/latest/notifications.md b/website/content/en/docs/Getting Started/latest/notifications.md
@@ -1,7 +1,7 @@
 ---
 title: "Notifications"
 linkTitle: "Notifications"
-weight: 10
+weight: 7
 date: 2021-01-18
 description: >
     How to setup operator notifications.

diff --git a/website/content/en/docs/Getting Started/latest/openshift.md b/website/content/en/docs/Getting Started/latest/openshift.md
@@ -1,7 +1,7 @@
 ---
 title: "OpenShift"
 linkTitle: "OpenShift"
-weight: 20
+weight: 10
 date: 2020-04-29
 description: >
     Additional configuration for OpenShift

diff --git a/website/content/en/docs/Getting Started/latest/schema.md b/website/content/en/docs/Getting Started/latest/schema.md
@@ -1,7 +1,7 @@
 ---
 title: "Schema"
 linkTitle: "Schema"
-weight: 40
+weight: 11
 date: 2021-01-18
 description: >
   API Schema definitions for Jenkins CRD