diff --git a/website/config.toml b/website/config.toml index af73b400..0a5cbb5a 100644 --- 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 index 2753f3fb..1f86ea64 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: 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 new file mode 100644 index 00000000..6e841f77 --- /dev/null +++ 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 index 8a61c895..9a407186 100644 --- 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 index 3bc43db6..796ea988 100644 --- 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 index 166643c9..09963f61 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: 10 +weight: 9 date: 2021-01-18 description: > Additional configuration for Azure Kubernetes Service diff --git a/website/content/en/docs/Getting Started/latest/configure-backup-and-restore.md b/website/content/en/docs/Getting Started/latest/configuring-backup-and-restore.md similarity index 96% rename from website/content/en/docs/Getting Started/latest/configure-backup-and-restore.md rename to website/content/en/docs/Getting Started/latest/configuring-backup-and-restore.md index fbc5bccc..5e9e7ece 100644 --- a/website/content/en/docs/Getting Started/latest/configure-backup-and-restore.md +++ b/website/content/en/docs/Getting Started/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/website/content/en/docs/Getting Started/latest/configuration.md b/website/content/en/docs/Getting Started/latest/configuring-seed-jobs-and-pipelines.md similarity index 98% rename from website/content/en/docs/Getting Started/latest/configuration.md rename to website/content/en/docs/Getting Started/latest/configuring-seed-jobs-and-pipelines.md index e543e544..1fdcede9 100644 --- a/website/content/en/docs/Getting Started/latest/configuration.md +++ b/website/content/en/docs/Getting Started/latest/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 index f632953a..1e44e0c6 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: 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/website/content/en/docs/Getting Started/latest/customization.md b/website/content/en/docs/Getting Started/latest/customization-with-groovy-scripts-and-casc.md similarity index 97% rename from website/content/en/docs/Getting Started/latest/customization.md rename to website/content/en/docs/Getting Started/latest/customization-with-groovy-scripts-and-casc.md index 167c556f..845a8e85 100644 --- a/website/content/en/docs/Getting Started/latest/customization.md +++ b/website/content/en/docs/Getting Started/latest/customization-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/website/content/en/docs/Getting Started/latest/deploy-jenkins.md b/website/content/en/docs/Getting Started/latest/deploying-jenkins.md similarity index 95% rename from website/content/en/docs/Getting Started/latest/deploy-jenkins.md rename to website/content/en/docs/Getting Started/latest/deploying-jenkins.md index cca283eb..70895f2c 100644 --- a/website/content/en/docs/Getting Started/latest/deploy-jenkins.md +++ b/website/content/en/docs/Getting 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 deleted file mode 100644 index 18ecf679..00000000 --- a/website/content/en/docs/Getting Started/latest/diagnostics.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Diagnostics" -linkTitle: "Diagnostics" -weight: 40 -date: 2021-01-18 -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- -``` - -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- -``` diff --git a/website/content/en/docs/Installation/_index.md b/website/content/en/docs/Getting Started/latest/installing-the-operator.md similarity index 96% rename from website/content/en/docs/Installation/_index.md rename to website/content/en/docs/Getting Started/latest/installing-the-operator.md index 671e3fe1..268cd47f 100644 --- a/website/content/en/docs/Installation/_index.md +++ b/website/content/en/docs/Getting 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 jenkins/jenkins-operator -n ``` -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:
## 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 index 06845e29..8497f4c4 100644 --- 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 index e6c43c0f..9b725e61 100644 --- 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 index 58638cbd..103b027e 100644 --- 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 diff --git a/website/content/en/docs/Getting Started/latest/security.md b/website/content/en/docs/Getting Started/latest/security.md new file mode 100644 index 00000000..d04be598 --- /dev/null +++ b/website/content/en/docs/Getting Started/latest/security.md @@ -0,0 +1,631 @@ +--- +title: "Security" +linkTitle: "Security" +weight: 8 +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 [getting-started#jenkins-customization](/kubernetes-operator/docs/getting-started/latest/customization/). + +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](kubernetes-operator/blob/v0.6.0/deploy/all-in-one-v1alpha2.yaml) +- [Jenkins Master role](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 +$ kubectl create ns jenkins-operator +$ kubectl create ns jenkins +``` + +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. + +```yaml +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: jenkins-operator +--- +# permissions to do leader election. +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: leader-election-role +rules: +- apiGroups: + - "" + - coordination.k8s.io + resources: + - configmaps + - leases + verbs: + - get + - list + - watch + - create + - update + - patch + - delete +- apiGroups: + - "" + resources: + - events + verbs: + - create + - patch +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: leader-election-rolebinding +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: leader-election-role +subjects: +- kind: ServiceAccount + name: jenkins-operator +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: jenkins-operator +rules: +- apiGroups: + - apps + resources: + - daemonsets + - deployments + - replicasets + - statefulsets + verbs: + - '*' +- apiGroups: + - apps + - jenkins-operator + resources: + - deployments/finalizers + verbs: + - update +- apiGroups: + - build.openshift.io + resources: + - buildconfigs + - builds + verbs: + - get + - list + - watch +- apiGroups: + - "" + resources: + - configmaps + - secrets + - services + verbs: + - create + - get + - list + - update + - watch +- apiGroups: + - "" + resources: + - events + verbs: + - create + - get + - list + - patch + - watch +- apiGroups: + - "" + resources: + - persistentvolumeclaims + verbs: + - get + - list + - watch +- apiGroups: + - "" + resources: + - pods + verbs: + - create + - delete + - get + - list + - patch + - update + - watch +- apiGroups: + - "" + resources: + - pods + - pods/exec + verbs: + - '*' +- apiGroups: + - "" + resources: + - pods/log + verbs: + - get + - list + - watch +- apiGroups: + - "" + resources: + - pods/portforward + verbs: + - create +- apiGroups: + - "" + resources: + - serviceaccounts + verbs: + - create + - get + - list + - update + - watch +- apiGroups: + - image.openshift.io + resources: + - imagestreams + verbs: + - get + - list + - watch +- apiGroups: + - jenkins.io + resources: + - '*' + verbs: + - '*' +- apiGroups: + - jenkins.io + resources: + - jenkins + verbs: + - create + - delete + - get + - list + - patch + - update + - watch +- apiGroups: + - jenkins.io + resources: + - jenkins/finalizers + verbs: + - update +- apiGroups: + - jenkins.io + resources: + - jenkins/status + verbs: + - get + - patch + - update +- apiGroups: + - rbac.authorization.k8s.io + resources: + - rolebindings + - roles + verbs: + - create + - get + - list + - update + - watch +- apiGroups: + - route.openshift.io + resources: + - routes + verbs: + - create + - get + - list + - update + - watch +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: jenkins-operator +subjects: + - kind: ServiceAccount + name: jenkins-operator +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: jenkins-operator +``` + +Now install the required resources in `jenkins-operator` namespace with: +```bash +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/) +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. + +```bash +apiVersion: apps/v1 +kind: Deployment +metadata: + name: jenkins-operator + labels: + control-plane: controller-manager +spec: + selector: + matchLabels: + control-plane: controller-manager + replicas: 1 + template: + metadata: + labels: + control-plane: controller-manager + spec: + serviceAccountName: jenkins-operator + securityContext: + runAsUser: 65532 + containers: + - command: + - /manager + args: + - --leader-elect + image: virtuslab/jenkins-operator:v0.6.0 + name: jenkins-operator + imagePullPolicy: IfNotPresent + securityContext: + allowPrivilegeEscalation: false + livenessProbe: + httpGet: + path: /healthz + port: 8081 + initialDelaySeconds: 15 + periodSeconds: 20 + readinessProbe: + httpGet: + path: /readyz + port: 8081 + initialDelaySeconds: 5 + periodSeconds: 10 + resources: + limits: + cpu: 100m + memory: 30Mi + requests: + cpu: 100m + memory: 20Mi + env: + - name: WATCH_NAMESPACE + value: jenkins + terminationGracePeriodSeconds: 10 +``` + +Install the Operator in `jenkins-operator` namespace with: + +```bash +kubectl apply -n jenkins-operator -f jenkins-operator.yaml +``` + +You have installed the Operator in `jenkins-operator` namespace, watching for Jenkins in `jenkins` namespace. Now +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. + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: jenkins-operator +rules: + - apiGroups: + - apps + resources: + - daemonsets + - deployments + - replicasets + - statefulsets + verbs: + - '*' + - apiGroups: + - apps + - jenkins-operator + resources: + - deployments/finalizers + verbs: + - update + - apiGroups: + - build.openshift.io + resources: + - buildconfigs + - builds + verbs: + - get + - list + - watch + - apiGroups: + - "" + resources: + - configmaps + - secrets + - services + verbs: + - create + - get + - list + - update + - watch + - apiGroups: + - "" + resources: + - events + verbs: + - create + - get + - list + - patch + - watch + - apiGroups: + - "" + resources: + - persistentvolumeclaims + verbs: + - get + - list + - watch + - apiGroups: + - "" + resources: + - pods + verbs: + - create + - delete + - get + - list + - patch + - update + - watch + - apiGroups: + - "" + resources: + - pods + - pods/exec + verbs: + - '*' + - apiGroups: + - "" + resources: + - pods/log + verbs: + - get + - list + - watch + - apiGroups: + - "" + resources: + - pods/portforward + verbs: + - create + - apiGroups: + - "" + resources: + - serviceaccounts + verbs: + - create + - get + - list + - update + - watch + - apiGroups: + - image.openshift.io + resources: + - imagestreams + verbs: + - get + - list + - watch + - apiGroups: + - jenkins.io + resources: + - '*' + verbs: + - '*' + - apiGroups: + - jenkins.io + resources: + - jenkins + verbs: + - create + - delete + - get + - list + - patch + - update + - watch + - apiGroups: + - jenkins.io + resources: + - jenkins/finalizers + verbs: + - update + - apiGroups: + - jenkins.io + resources: + - jenkins/status + verbs: + - get + - patch + - update + - apiGroups: + - rbac.authorization.k8s.io + resources: + - rolebindings + - roles + verbs: + - create + - get + - list + - update + - watch + - apiGroups: + - route.openshift.io + resources: + - routes + verbs: + - create + - get + - list + - update + - watch +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: jenkins-operator +subjects: + - kind: ServiceAccount + name: jenkins-operator + namespace: jenkins-operator +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: jenkins-operator +``` + +Now apply it with: +```bash +kubectl apply -n jenkins -f jenkins-ns-rbac.yaml +``` + +The last thing to do is to deploy Jenkins. Below you can find an example Jenkins resource manifest. +It's the same as one used in [Deploying Jenkins](/kubernetes-operator/docs/getting-started/latest/deploying-jenkins/). +Copy it to `jenkins-instance.yaml` + +```yaml +apiVersion: jenkins.io/v1alpha2 +kind: Jenkins +metadata: + name: example +spec: + configurationAsCode: + configurations: [] + secret: + name: "" + groovyScripts: + configurations: [] + secret: + name: "" + jenkinsAPISettings: + authorizationStrategy: createUser + master: + disableCSRFProtection: false + containers: + - name: jenkins-master + image: jenkins/jenkins:2.277.4-lts-alpine + imagePullPolicy: Always + livenessProbe: + failureThreshold: 12 + httpGet: + path: /login + port: http + scheme: HTTP + initialDelaySeconds: 100 + periodSeconds: 10 + successThreshold: 1 + timeoutSeconds: 5 + readinessProbe: + failureThreshold: 10 + httpGet: + path: /login + port: http + scheme: HTTP + initialDelaySeconds: 80 + 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 +``` + +Now you can deploy it with: + +```bash +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/Getting Started/v0.1.x/_index.md b/website/content/en/docs/Getting Started/v0.1.x/_index.md index 62ba2daf..21254579 100644 --- a/website/content/en/docs/Getting Started/v0.1.x/_index.md +++ b/website/content/en/docs/Getting Started/v0.1.x/_index.md @@ -1,8 +1,8 @@ --- title: "v0.1.x" linkTitle: "v0.1.x" -weight: 10 -date: 2021-08-18 +weight: 6 +date: 2019-08-05 description: > How to work with Jenkins Operator 0.1.x version. We recommend migrating to a newer version. --- diff --git a/website/content/en/docs/Getting Started/v0.2.x/_index.md b/website/content/en/docs/Getting Started/v0.2.x/_index.md index 03481c9f..b0ebd883 100644 --- a/website/content/en/docs/Getting Started/v0.2.x/_index.md +++ b/website/content/en/docs/Getting Started/v0.2.x/_index.md @@ -1,8 +1,8 @@ --- title: "v0.2.x" linkTitle: "v0.2.x" -weight: 10 -date: 2021-08-18 +weight: 5 +date: 2019-08-05 description: > How to work with Jenkins Operator 0.2.x version. We recommend migrating to a newer version. --- diff --git a/website/content/en/docs/Getting Started/v0.3.x/_index.md b/website/content/en/docs/Getting Started/v0.3.x/_index.md index 41002724..50eaea5b 100644 --- a/website/content/en/docs/Getting Started/v0.3.x/_index.md +++ b/website/content/en/docs/Getting Started/v0.3.x/_index.md @@ -1,8 +1,8 @@ --- title: "v0.3.x" linkTitle: "v0.3.x" -weight: 10 -date: 2021-08-18 +weight: 4 +date: 2019-12-20 description: > How to work with Jenkins Operator 0.3.x version. We recommend migrating to a newer version. --- diff --git a/website/content/en/docs/Getting Started/v0.4.x/_index.md b/website/content/en/docs/Getting Started/v0.4.x/_index.md index 13282bec..e3c5b785 100644 --- a/website/content/en/docs/Getting Started/v0.4.x/_index.md +++ b/website/content/en/docs/Getting Started/v0.4.x/_index.md @@ -1,8 +1,8 @@ --- title: "v0.4.x" linkTitle: "v0.4.x" -weight: 10 -date: 2021-08-18 +weight: 3 +date: 2020-04-13 description: > How to work with Jenkins Operator 0.4.x version. We recommend migrating to a newer version. --- diff --git a/website/content/en/docs/Getting Started/v0.5.x/_index.md b/website/content/en/docs/Getting Started/v0.5.x/_index.md index ff184651..48f2ea9a 100644 --- a/website/content/en/docs/Getting Started/v0.5.x/_index.md +++ b/website/content/en/docs/Getting Started/v0.5.x/_index.md @@ -1,8 +1,8 @@ --- title: "v0.5.x" linkTitle: "v0.5.x" -weight: 10 -date: 2021-08-18 +weight: 2 +date: 2021-01-18 description: > How to work with Jenkins Operator 0.5.x version. We recommend migrating to a newer version. --- diff --git a/website/content/en/docs/How it works/_index.md b/website/content/en/docs/How it works/_index.md index 86e8999b..5c295c15 100644 --- a/website/content/en/docs/How it works/_index.md +++ b/website/content/en/docs/How it works/_index.md @@ -1,13 +1,13 @@ --- title: "How it works" linkTitle: "How it works" -weight: 8 +weight: 1 date: 2019-08-05 description: > How Jenkins Operator works --- {{% pageinfo %}} -This document describes a high level overview of how jenkins-operator works. +This document describes a high level overview of how Jenkins Operator works. {{% /pageinfo %}} diff --git a/website/content/en/docs/Security/_index.md b/website/content/en/docs/Security/_index.md deleted file mode 100644 index e45710c1..00000000 --- a/website/content/en/docs/Security/_index.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "Security" -linkTitle: "Security" -weight: 50 -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 [getting-started#jenkins-customization](/kubernetes-operator/docs/getting-started/latest/customization/). - -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.5.0/deploy/role.yaml) -- [Jenkins Master role](https://github.com/jenkinsci/kubernetes-operator/blob/v0.5.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 separate namespace. -To achieve it change watch namespace in [https://github.com/jenkinsci/kubernetes-operator/blob/master/deploy/operator.yaml#L25](https://github.com/jenkinsci/kubernetes-operator/blob/master/deploy/operator.yaml#L25) - -## Setup Jenkins Operator and Jenkins in separated namespaces - -You need to create two namespaces, for example we'll call them **jenkins** for Jenkins and **Jenkins Operator** for Jenkins Operator. -```bash -$ kubectl create ns jenkins-operator -$ kubectl create ns jenkins -``` - -Next, apply the RBAC manifests for **Jenkins Operator** namespace -```bash -$ kubectl -n jenkins-operator apply -f deploy/service_account.yaml -$ kubectl -n jenkins-operator apply -f deploy/role_binding.yaml -``` - -Create file `role_binding_jenkins.yaml` in `deploy` folder: -```yaml -kind: RoleBinding -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: jenkins-operator - namespace: jenkins -subjects: -- kind: ServiceAccount - name: jenkins-operator - namespace: jenkins-operator -roleRef: - kind: Role - name: jenkins-operator - apiGroup: rbac.authorization.k8s.io -``` - -Then, apply RBAC rules for **jenkins** namespace -```bash -$ kubectl -n jenkins apply -f deploy/role.yaml -$ kubectl -n jenkins apply -f role_binding_jenkins.yaml -``` - -Finally, you must create operator pod by: -```bash -$ kubectl -n jenkins -n jenkins-operator apply -f deploy/operator.yaml -``` - - -## 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/Troubleshooting/_index.md b/website/content/en/docs/Troubleshooting/_index.md new file mode 100644 index 00000000..e3cabcef --- /dev/null +++ b/website/content/en/docs/Troubleshooting/_index.md @@ -0,0 +1,59 @@ +--- +title: "Troubleshooting" +linkTitle: "Troubleshooting" +weight: 3 +date: 2019-08-05 +description: > + Jenkins security and hardening out of the box +--- + +This document helps you to state the reason for an error in the Jenkins Operator, which is the first step in solving it. + +## Operator logs +Jenkins Operator can provide some useful logs. To get them, run: +```bash +$ kubectl logs -f +``` + +In the logs look for WARNING, ERROR and SEVERE keywords. + +## Jenkins logs + +If the container is in a CrashLoopBackOff, the fault is in the Jenkins itself. +If the Operator is constantly terminating the pod with ‘missing-plugins’ messages that means the plugins lost compatibility +with the Jenkins image and their version need to be updated. +To learn more about the possible error, check the state of the pod: + +```bash +$ kubectl -n get po -w +``` +or +```bash +$ kubectl -n describe po +``` +and check the logs from the Jenkins container: +```bash +$ kubectl -n logs -f +``` + + +## Kubernetes Events + +Sometimes Events provide a great dose of information, especially in the case some Kubernetes resource doesn’t want to become Ready. +To obtain the events in your Cluster run: + +```bash +$ kubectl -n get events --sort-by='{.lastTimestamp}' +``` + +## Quick soft reset +You can always kill the Jenkins pod and wait for it to come up again. All the version-controlled configurations will be downloaded again +and the rest will be discarded. Chances are the buggy part will be gone. + +```bash +$ 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""`` +argument to jenkins-operator container args in your Operator deployment. \ No newline at end of file