From 4563b1851f1811bb871b9ae89407b15fb034a26c Mon Sep 17 00:00:00 2001 From: Mikolaj Karebski Date: Mon, 27 Apr 2020 12:31:21 +0200 Subject: [PATCH 1/2] #348 Add few documentation changes --- .../content/en/docs/Developer Guide/_index.md | 167 +++++++++++++++++- .../Getting Started/latest/customization.md | 122 +++++++------ 2 files changed, 235 insertions(+), 54 deletions(-) diff --git a/website/content/en/docs/Developer Guide/_index.md b/website/content/en/docs/Developer Guide/_index.md index d289b639..550a44b6 100644 --- a/website/content/en/docs/Developer Guide/_index.md +++ b/website/content/en/docs/Developer Guide/_index.md @@ -34,14 +34,170 @@ Build and run **Jenkins Operator** locally: ```bash make build minikube-run -``` -Once minikube and **Jenkins Operator** are up and running, apply Jenkins custom resource: +INFO[0000] Running deepcopy code-generation for Custom Resource group versions: [jenkins:[v1alpha2], ] +INFO[0005] Code-generation complete. +2020-04-27T09:52:26.520+0200 INFO controller-jenkins manager/main.go:51 Version: v0.4.0 +2020-04-27T09:52:26.520+0200 INFO controller-jenkins manager/main.go:52 Git commit: 4ffc58e-dirty +2020-04-27T09:52:26.520+0200 INFO controller-jenkins manager/main.go:53 Go Version: go1.13.1 +2020-04-27T09:52:26.520+0200 INFO controller-jenkins manager/main.go:54 Go OS/Arch: linux/amd64 +2020-04-27T09:52:26.520+0200 INFO controller-jenkins manager/main.go:55 operator-sdk Version: v0.15.1 +2020-04-27T09:52:26.520+0200 INFO controller-jenkins manager/main.go:80 Watch namespace: default +2020-04-27T09:52:26.527+0200 INFO leader leader/leader.go:46 Trying to become the leader. +2020-04-27T09:52:26.527+0200 INFO leader leader/leader.go:51 Skipping leader election; not running in a cluster. +2020-04-27T09:52:26.887+0200 INFO controller-runtime.metrics metrics/listener.go:40 metrics server is starting to listen {"addr": "0.0.0.0:8383"} +2020-04-27T09:52:26.887+0200 INFO controller-jenkins manager/main.go:105 Registering Components. +2020-04-27T09:52:26.897+0200 WARN controller-jenkins manager/main.go:138 Could not generate and serve custom resource metrics {"error": "namespace not found for current environment"} +2020-04-27T09:52:27.250+0200 INFO metrics metrics/metrics.go:55 Skipping metrics Service creation; not running in a cluster. +2020-04-27T09:52:27.601+0200 WARN controller-jenkins manager/main.go:157 Could not create ServiceMonitor object {"error": "no ServiceMonitor registered with the API"} +2020-04-27T09:52:27.601+0200 WARN controller-jenkins manager/main.go:161 Install prometheus-operator in your cluster to create ServiceMonitor objects {"error": "no ServiceMonitor registered with the API"} +2020-04-27T09:52:27.601+0200 INFO controller-jenkins manager/main.go:165 Starting the Cmd. +2020-04-27T09:52:27.601+0200 INFO controller-runtime.manager manager/internal.go:356 starting metrics server {"path": "/metrics"} +2020-04-27T09:52:27.601+0200 INFO controller-runtime.controller controller/controller.go:164 Starting EventSource {"controller": "jenkins-controller", "source": "kind source: jenkins.io/v1alpha2, Kind=Jenkins"} +2020-04-27T09:52:27.702+0200 INFO controller-runtime.controller controller/controller.go:164 Starting EventSource {"controller": "jenkins-controller", "source": "kind source: core/v1, Kind=Pod"} +2020-04-27T09:52:27.803+0200 INFO controller-runtime.controller controller/controller.go:164 Starting EventSource {"controller": "jenkins-controller", "source": "kind source: core/v1, Kind=Secret"} +2020-04-27T09:52:27.903+0200 INFO controller-runtime.controller controller/controller.go:164 Starting EventSource {"controller": "jenkins-controller", "source": "kind source: core/v1, Kind=Secret"} +2020-04-27T09:52:27.903+0200 INFO controller-runtime.controller controller/controller.go:164 Starting EventSource {"controller": "jenkins-controller", "source": "kind source: core/v1, Kind=ConfigMap"} +2020-04-27T09:52:28.005+0200 INFO controller-runtime.controller controller/controller.go:171 Starting Controller {"controller": "jenkins-controller"} +2020-04-27T09:52:28.005+0200 INFO controller-runtime.controller controller/controller.go:190 Starting workers {"controller": "jenkins-controller", "worker count": 1} +``` ```bash kubectl apply -f deploy/crds/jenkins_v1alpha2_jenkins_cr.yaml + +2020-04-27T09:56:40.153+0200 INFO controller-jenkins jenkins/jenkins_controller.go:404 Setting default Jenkins container command {"cr": "example"} +2020-04-27T09:56:40.153+0200 INFO controller-jenkins jenkins/jenkins_controller.go:409 Setting default Jenkins container JAVA_OPTS environment variable {"cr": "example"} +2020-04-27T09:56:40.153+0200 INFO controller-jenkins jenkins/jenkins_controller.go:417 Setting default operator plugins {"cr": "example"} +2020-04-27T09:56:40.153+0200 INFO controller-jenkins jenkins/jenkins_controller.go:436 Setting default Jenkins master service {"cr": "example"} +2020-04-27T09:56:40.153+0200 INFO controller-jenkins jenkins/jenkins_controller.go:449 Setting default Jenkins slave service {"cr": "example"} +2020-04-27T09:56:40.153+0200 INFO controller-jenkins jenkins/jenkins_controller.go:479 Setting default Jenkins API settings {"cr": "example"} +2020-04-27T09:56:40.158+0200 INFO controller-jenkins jenkins/handler.go:89 *v1alpha2.Jenkins/example has been updated {"cr": "example"} +2020-04-27T09:56:40.562+0200 INFO controller-jenkins base/pod.go:161 Creating a new Jenkins Master Pod default/jenkins-example {"cr": "example"} +2020-04-27T09:56:40.575+0200 INFO controller-jenkins base/reconcile.go:528 The Admission controller has changed the Jenkins master pod spec.securityContext, changing the Jenkinc CR spec.master.securityContext to '&PodSecurityContext{SELinuxOptions:nil,RunAsUser:nil,RunAsNonRoot:nil,SupplementalGroups:[],FSGroup:nil,RunAsGroup:nil,Sysctls:[]Sysctl{},WindowsOptions:nil,}' {"cr": "example"} +2020-04-27T09:56:40.584+0200 INFO controller-jenkins jenkins/handler.go:89 *v1alpha2.Jenkins/example has been updated {"cr": "example"} +2020-04-27T09:59:40.409+0200 INFO controller-jenkins base/reconcile.go:466 Generating Jenkins API token for operator {"cr": "example"} +2020-04-27T09:59:40.410+0200 WARN controller-jenkins jenkins/jenkins_controller.go:171 Reconcile loop failed: couldn't init Jenkins API client: Get http://192.168.99.100:32380/api/json: dial tcp 192.168.99.100:32380: connect: connection refused {"cr": "example"} +2020-04-27T09:59:40.455+0200 INFO controller-jenkins base/reconcile.go:466 Generating Jenkins API token for operator {"cr": "example"} +2020-04-27T09:59:41.415+0200 INFO controller-jenkins groovy/groovy.go:145 base-groovy ConfigMap 'jenkins-operator-base-configuration-example' name '1-basic-settings.groovy' running groovy script {"cr": "example"} +... +2020-04-27T09:59:49.030+0200 INFO controller-jenkins groovy/groovy.go:145 base-groovy ConfigMap 'jenkins-operator-base-configuration-example' name '8-disable-job-dsl-script-approval.groovy' running groovy script {"cr": "example"} + +2020-04-27T09:59:49.257+0200 INFO controller-jenkins jenkins/jenkins_controller.go:289 Base configuration phase is complete, took 3m9s {"cr": "example"} +2020-04-27T09:59:51.165+0200 INFO controller-jenkins seedjobs/seedjobs.go:232 Waiting for Seed Job Agent `seed-job-agent`... {"cr": "example"} +... +2020-04-27T10:00:03.886+0200 INFO controller-jenkins seedjobs/seedjobs.go:232 Waiting for Seed Job Agent `seed-job-agent`... {"cr": "example"} +2020-04-27T10:00:06.140+0200 INFO controller-jenkins jenkins/jenkins_controller.go:338 User configuration phase is complete, took 3m26s {"cr": "example"} +``` + +```bash kubectl get jenkins -o yaml + +apiVersion: v1 +items: +- apiVersion: jenkins.io/v1alpha2 + kind: Jenkins + metadata: + ... + spec: + backup: + action: {} + containerName: "" + interval: 0 + makeBackupBeforePodDeletion: false + configurationAsCode: + configurations: null + secret: + name: "" + groovyScripts: + configurations: null + secret: + name: "" + jenkinsAPISettings: + authorizationStrategy: createUser + master: + basePlugins: + ... + - command: + - bash + - -c + - /var/jenkins/scripts/init.sh && exec /sbin/tini -s -- /usr/local/bin/jenkins.sh + env: + - name: JAVA_OPTS + value: -XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap + -XX:MaxRAMFraction=1 -Djenkins.install.runSetupWizard=false -Djava.awt.headless=true + image: jenkins/jenkins:lts + imagePullPolicy: Always + livenessProbe: + ... + name: jenkins-master + readinessProbe: + ... + resources: + limits: + cpu: 1500m + memory: 3Gi + requests: + cpu: "1" + memory: 500Mi + disableCSRFProtection: false + securityContext: {} + restore: + action: {} + containerName: "" + seedJobs: + - additionalClasspath: "" + bitbucketPushTrigger: false + buildPeriodically: "" + description: Jenkins Operator repository + failOnMissingPlugin: false + githubPushTrigger: false + id: jenkins-operator + ignoreMissingFiles: false + pollSCM: "" + repositoryBranch: master + repositoryUrl: https://github.com/jenkinsci/kubernetes-operator.git + targets: cicd/jobs/*.jenkins + unstableOnDeprecation: false + service: + port: 8080 + type: NodePort + serviceAccount: {} + slaveService: + port: 50000 + type: ClusterIP + status: + appliedGroovyScripts: + - configurationType: base-groovy + hash: 2ownqpRyBjQYmzTRttUx7axok3CKe2E45frI5iRwH0w= + name: 1-basic-settings.groovy + source: jenkins-operator-base-configuration-example + ... + baseConfigurationCompletedTime: "2020-04-27T07:59:49Z" + createdSeedJobs: + - jenkins-operator + operatorVersion: v0.4.0 + provisionStartTime: "2020-04-27T07:56:40Z" + userAndPasswordHash: kAeBnhHKU3LZuw+uo9oHILB59kAFSGDUbHwCSDgtMnE= + userConfigurationCompletedTime: "2020-04-27T08:00:06Z" +kind: List +metadata: + resourceVersion: "" + selfLink: "" +``` + +```bash kubectl get po + +NAME READY STATUS RESTARTS AGE +jenkins-example 1/1 Running 0 15m +seed-job-agent-example-56569459c9-l69qf 1/1 Running 0 12m + +``` + +### Debug Jenkins Operator + +```bash +make build minikube-run OPERATOR_EXTRA_ARGS="--debug" ``` ## Build and run with a remote Kubernetes cluster @@ -120,3 +276,10 @@ kubectl get secret jenkins-operator-credentials- -o 'jsonpath={.data.pa [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/ + +## Self-learning + +* [Tutorial: Deep Dive into the Operator Framework for... Melvin Hillsman, Michael Hrivnak, & Matt Dorn +](https://www.youtube.com/watch?v=8_DaCcRMp5I) + +* [Operator Framework Training By OpenShift](https://www.katacoda.com/openshift/courses/operatorframework) diff --git a/website/content/en/docs/Getting Started/latest/customization.md b/website/content/en/docs/Getting Started/latest/customization.md index a1152397..994cf755 100644 --- a/website/content/en/docs/Getting Started/latest/customization.md +++ b/website/content/en/docs/Getting Started/latest/customization.md @@ -7,11 +7,77 @@ description: > How to customize Jenkins --- -Jenkins can be customized using groovy scripts or the [configuration as code plugin](https://github.com/jenkinsci/configuration-as-code-plugin). +## How to customize Jenkins +Jenkins can be customized with plugins. +Plugin's configuration is applied as groovy scripts or the [configuration as code plugin](https://github.com/jenkinsci/configuration-as-code-plugin). +Any plugin working for Jenkins can be installed by the Jenkins Operator. + +Pre-installed plugins: +* configuration-as-code v1.38 +* git v4.2.2 +* job-dsl v1.77 +* kubernetes-credentials-provider v0.13 +* kubernetes v1.25.2 +* workflow-aggregator v2.6 +* workflow-job v2.38 + +Rest of the plugins can be found in [plugins repository](https://plugins.jenkins.io/). + + +#### Install plugins + +Edit Custom Resource under `spec.master.plugins`: + +``` +apiVersion: jenkins.io/v1alpha2 +kind: Jenkins +metadata: + name: example +spec: + master: + plugins: + - name: simple-theme-plugin + version: 0.5.1 +``` + +Under `spec.master.basePlugins` you can find plugins for a valid **Jenkins Operator**: + +```yaml +apiVersion: jenkins.io/v1alpha2 +kind: Jenkins +metadata: + name: example +spec: + master: + basePlugins: + - name: kubernetes + version: 1.18.3 + - name: workflow-job + version: "2.34" + - name: workflow-aggregator + version: "2.6" + - name: git + version: 3.12.0 + - name: job-dsl + version: "1.76" + - name: configuration-as-code + version: "1.29" + - name: configuration-as-code-support + version: "1.19" + - name: kubernetes-credentials-provider + version: 0.12.1 +``` + +You can change their versions. + +The **Jenkins Operator** will then automatically install plugins after the Jenkins master pod restarts. + +#### Apply plugin's config + By using a [ConfigMap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) you can create your own **Jenkins** customized configuration. Then you must reference the **`ConfigMap`** in the **Jenkins** pod customization file in `spec.groovyScripts` or `spec.configurationAsCode` -For example create a **`ConfigMap`** with name `jenkins-operator-user-configuration`. Then, modify the **Jenkins** manifest to look like this: +Create a **`ConfigMap`** with specific name (eg. `jenkins-operator-user-configuration`). Then, modify the **Jenkins** manifest: ```yaml apiVersion: jenkins.io/v1alpha2 @@ -65,7 +131,7 @@ data: If you want to correct your configuration you can edit it while the **Jenkins Operator** is running. Jenkins will reconcile and apply the new configuration. -### Using secrets from a Groovy script +## How to use secrets from a Groovy scripts If you configured `spec.groovyScripts.secret.name`, then this secret is available to use from map Groovy scripts. The secrets are loaded to `secrets` map. @@ -135,52 +201,4 @@ data: ``` -After this, you should see the `Hello world` system message from the **Jenkins** homepage. - -## Install Plugins - -Edit Custom Resource under `spec.master.plugins`: - -``` -apiVersion: jenkins.io/v1alpha2 -kind: Jenkins -metadata: - name: example -spec: - master: - plugins: - - name: simple-theme-plugin - version: 0.5.1 -``` - -Under `spec.master.basePlugins` you can find plugins for a valid **Jenkins Operator**: - -```yaml -apiVersion: jenkins.io/v1alpha2 -kind: Jenkins -metadata: - name: example -spec: - master: - basePlugins: - - name: kubernetes - version: 1.18.3 - - name: workflow-job - version: "2.34" - - name: workflow-aggregator - version: "2.6" - - name: git - version: 3.12.0 - - name: job-dsl - version: "1.76" - - name: configuration-as-code - version: "1.29" - - name: configuration-as-code-support - version: "1.19" - - name: kubernetes-credentials-provider - version: 0.12.1 -``` - -You can change their versions. - -The **Jenkins Operator** will then automatically install plugins after the Jenkins master pod restarts. +After this, you should see the `Hello world` system message from the **Jenkins** homepage. \ No newline at end of file From 5e6c031f032314b7f2d3ea50f1b4cc58d5114954 Mon Sep 17 00:00:00 2001 From: Mikolaj Karebski Date: Mon, 27 Apr 2020 12:50:32 +0200 Subject: [PATCH 2/2] #348 Fix code review issues --- website/content/en/docs/Developer Guide/_index.md | 8 ++++++++ .../en/docs/Getting Started/latest/customization.md | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/website/content/en/docs/Developer Guide/_index.md b/website/content/en/docs/Developer Guide/_index.md index 550a44b6..f1bc4600 100644 --- a/website/content/en/docs/Developer Guide/_index.md +++ b/website/content/en/docs/Developer Guide/_index.md @@ -89,6 +89,14 @@ kubectl apply -f deploy/crds/jenkins_v1alpha2_jenkins_cr.yaml 2020-04-27T10:00:06.140+0200 INFO controller-jenkins jenkins/jenkins_controller.go:338 User configuration phase is complete, took 3m26s {"cr": "example"} ``` +Two log lines says that Jenkins Operator works correctly: + +* `Base configuration phase is complete` - ensures manifests, Jenkins pod, Jenkins configuration and Jenkins API token +* `User configuration phase is complete` - ensures Jenkins restore, backup and seed jobs along with user configuration + +> Details about base and user phase can be found [here](https://jenkinsci.github.io/kubernetes-operator/docs/how-it-works/architecture-and-design/). + + ```bash kubectl get jenkins -o yaml diff --git a/website/content/en/docs/Getting Started/latest/customization.md b/website/content/en/docs/Getting Started/latest/customization.md index 994cf755..0b29bbf3 100644 --- a/website/content/en/docs/Getting Started/latest/customization.md +++ b/website/content/en/docs/Getting Started/latest/customization.md @@ -70,7 +70,7 @@ spec: You can change their versions. -The **Jenkins Operator** will then automatically install plugins after the Jenkins master pod restarts. +The **Jenkins Operator** will then automatically install plugins after the Jenkins master pod restart. #### Apply plugin's config