diff --git a/Makefile b/Makefile index 61b0bf0f..2407b8c9 100644 --- a/Makefile +++ b/Makefile @@ -362,7 +362,7 @@ ifndef HAS_GEN_CRD_API_REFERENCE_DOCS @tar -C $(GEN_CRD_API) -zxf $(GEN_CRD_API)_linux_amd64.tar.gz @rm $(GEN_CRD_API)_linux_amd64.tar.gz endif - $(GEN_CRD_API)/$(GEN_CRD_API) -config gen-crd-api-config.json -api-dir github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/$(API_VERSION) -template-dir $(GEN_CRD_API)/template -out-file docs/jenkins-$(API_VERSION)-scheme.md + $(GEN_CRD_API)/$(GEN_CRD_API) -config gen-crd-api-config.json -api-dir github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/$(API_VERSION) -template-dir $(GEN_CRD_API)/template -out-file documentation/$(VERSION)/jenkins-$(API_VERSION)-scheme.md .PHONY: minikube-start minikube-start: ## Start minikube diff --git a/README.md b/README.md index f65b4c32..2ebd2ef3 100644 --- a/README.md +++ b/README.md @@ -51,9 +51,9 @@ Feel free to file [issues](https://github.com/jenkinsci/kubernetes-operator/issu This project was originally developed by [VirtusLab](https://virtuslab.com/) and the following [CONTRIBUTORS](https://github.com/jenkinsci/kubernetes-operator/graphs/contributors). -[installation]:docs/installation.md -[getting_started]:docs/getting-started.md -[how_it_works]:docs/how-it-works.md -[security]:docs/security.md -[developer_guide]:docs/developer-guide.md -[jenkins_scheme]:docs/jenkins-v1alpha2-scheme.md \ No newline at end of file +[installation]:documentation/installation.md +[getting_started]:documentation/v0.1.1/getting-started.md +[how_it_works]:documentation/how-it-works.md +[security]:documentation/security.md +[developer_guide]:documentation/developer-guide.md +[jenkins_scheme]:documentation/v0.1.1/jenkins-v1alpha2-scheme.md \ No newline at end of file diff --git a/docs/developer-guide.md b/documentation/developer-guide.md similarity index 98% rename from docs/developer-guide.md rename to documentation/developer-guide.md index 06786beb..9f5aaa3c 100644 --- a/docs/developer-guide.md +++ b/documentation/developer-guide.md @@ -112,5 +112,5 @@ 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 [jenkins-operator]:../README.md -[install_dev_tools]:./install_dev_tools.md +[install_dev_tools]:install_dev_tools.md diff --git a/docs/how-it-works.md b/documentation/how-it-works.md similarity index 100% rename from docs/how-it-works.md rename to documentation/how-it-works.md diff --git a/docs/install_dev_tools.md b/documentation/install_dev_tools.md similarity index 100% rename from docs/install_dev_tools.md rename to documentation/install_dev_tools.md diff --git a/docs/installation.md b/documentation/installation.md similarity index 100% rename from docs/installation.md rename to documentation/installation.md diff --git a/docs/migration-guide-v1alphav1-to-v1alpha2.md b/documentation/migration-guide-v1alphav1-to-v1alpha2.md similarity index 98% rename from docs/migration-guide-v1alphav1-to-v1alpha2.md rename to documentation/migration-guide-v1alphav1-to-v1alpha2.md index 7c7ac93a..856b6f8f 100644 --- a/docs/migration-guide-v1alphav1-to-v1alpha2.md +++ b/documentation/migration-guide-v1alphav1-to-v1alpha2.md @@ -85,7 +85,7 @@ spec: ``` See also the examples bellow for more details. For even more details please look at the source code. -Code that defines the data structures can be found [here](jenkins-v1alpha2-scheme.md) +Code that defines the data structures can be found [here](v0.1.1/jenkins-v1alpha2-scheme.md) ### Examples diff --git a/docs/security.md b/documentation/security.md similarity index 98% rename from docs/security.md rename to documentation/security.md index 32468422..5ba2e20d 100644 --- a/docs/security.md +++ b/documentation/security.md @@ -6,7 +6,7 @@ By default **jenkins-operator** performs an initial security hardening of Jenkin 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](getting-started.md#jenkins-customisation). +For more information take a look at [getting-started#jenkins-customization](v0.1.1/getting-started.md#jenkins-customisation). Any change to Security Realm or Authorization requires that user called `jenkins-operator` must have admin rights because **jenkins-operator** calls Jenkins API. diff --git a/documentation/v0.1.1/getting-started.md b/documentation/v0.1.1/getting-started.md new file mode 100644 index 00000000..83ad6e81 --- /dev/null +++ b/documentation/v0.1.1/getting-started.md @@ -0,0 +1,555 @@ +# Getting Started + +This document describes a getting started guide for **jenkins-operator** and an additional configuration. + +1. [First Steps](#first-steps) +2. [Deploy Jenkins](#deploy-jenkins) +3. [Configure Seed Jobs and Pipelines](#configure-seed-jobs-and-pipelines) +4. [Install Plugins](#install-plugins) +5. [Configure Backup & Restore](#configure-backup-and-restore) +6. [AKS](#aks) +7. [Jenkins login credentials](#jenkins-login-credentials) +8. [Override default Jenkins container command](#override-default-Jenkins-container-command) +9. [Debugging](#debugging) + +## First Steps + +Prepare your Kubernetes cluster and set up access. +Once you have running Kubernetes cluster you can focus on installing **jenkins-operator** according to the [Installation](../installation.md) guide. + +## Deploy Jenkins + +Once jenkins-operator is up and running let's deploy actual Jenkins instance. +Create manifest ie. **jenkins_instance.yaml** with following data and save it on drive. + +```bash +apiVersion: jenkins.io/v1alpha2 +kind: Jenkins +metadata: + name: example +spec: + master: + containers: + - name: jenkins-master + image: jenkins/jenkins:lts + imagePullPolicy: Always + livenessProbe: + failureThreshold: 12 + httpGet: + path: /login + port: http + scheme: HTTP + initialDelaySeconds: 80 + periodSeconds: 10 + successThreshold: 1 + timeoutSeconds: 5 + readinessProbe: + failureThreshold: 3 + httpGet: + path: /login + port: http + scheme: HTTP + initialDelaySeconds: 30 + 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 +``` + +Deploy Jenkins to K8s: + +```bash +kubectl create -f jenkins_instance.yaml +``` +Watch Jenkins instance being created: + +```bash +kubectl get pods -w +``` + +Get Jenkins credentials: + +```bash +kubectl get secret jenkins-operator-credentials- -o 'jsonpath={.data.user}' | base64 -d +kubectl get secret jenkins-operator-credentials- -o 'jsonpath={.data.password}' | base64 -d +``` + +Connect to Jenkins (minikube): + +```bash +minikube service jenkins-operator-http- --url +``` + +Connect to Jenkins (actual Kubernetes cluster): + +```bash +kubectl port-forward jenkins- 8080:8080 +``` +Then open browser with address `http://localhost:8080`. +![jenkins](../../assets/jenkins.png) + +## Configure Seed Jobs and Pipelines + +Jenkins operator uses [job-dsl][job-dsl] and [kubernetes-credentials-provider][kubernetes-credentials-provider] plugins for configuring jobs +and deploy keys. + +## Prepare job definitions and pipelines + +First you have to prepare pipelines and job definition in your GitHub repository using the following structure: + +``` +cicd/ +├── jobs +│   └── build.jenkins +└── pipelines + └── build.jenkins +``` + +**cicd/jobs/build.jenkins** it's a job definition: + +``` +#!/usr/bin/env groovy + +pipelineJob('build-jenkins-operator') { + displayName('Build jenkins-operator') + + definition { + cpsScm { + scm { + git { + remote { + url('https://github.com/jenkinsci/kubernetes-operator.git') + credentials('jenkins-operator') + } + branches('*/master') + } + } + scriptPath('cicd/pipelines/build.jenkins') + } + } +} +``` + +**cicd/jobs/build.jenkins** it's an actual Jenkins pipeline: + +``` +#!/usr/bin/env groovy + +def label = "build-jenkins-operator-${UUID.randomUUID().toString()}" +def home = "/home/jenkins" +def workspace = "${home}/workspace/build-jenkins-operator" +def workdir = "${workspace}/src/github.com/jenkinsci/kubernetes-operator/" + +podTemplate(label: label, + containers: [ + containerTemplate(name: 'jnlp', image: 'jenkins/jnlp-slave:alpine'), + containerTemplate(name: 'go', image: 'golang:1-alpine', command: 'cat', ttyEnabled: true), + ], + envVars: [ + envVar(key: 'GOPATH', value: workspace), + ], + ) { + + node(label) { + dir(workdir) { + stage('Init') { + timeout(time: 3, unit: 'MINUTES') { + checkout scm + } + container('go') { + sh 'apk --no-cache --update add make git gcc libc-dev' + } + } + + stage('Dep') { + container('go') { + sh 'make dep' + } + } + + stage('Test') { + container('go') { + sh 'make test' + } + } + + stage('Build') { + container('go') { + sh 'make build' + } + } + } + } +} +``` + +## Configure Seed Jobs + +Jenkins Seed Jobs are configured using `Jenkins.spec.seedJobs` section from your custom resource manifest: + +``` +apiVersion: jenkins.io/v1alpha2 +kind: Jenkins +metadata: + name: example +spec: + seedJobs: + - id: jenkins-operator + targets: "cicd/jobs/*.jenkins" + description: "Jenkins Operator repository" + repositoryBranch: master + repositoryUrl: https://github.com/jenkinsci/kubernetes-operator.git +``` + +**jenkins-operator** will automatically discover and configure all seed jobs. + +You can verify if deploy keys were successfully configured in Jenkins **Credentials** tab. + +![jenkins](../../assets/jenkins-credentials.png) + +You can verify if your pipelines were successfully configured in Jenkins Seed Job console output. + +![jenkins](../../assets/jenkins-seed.png) + +If your GitHub repository is **private** you have to configure SSH or username/password authentication. + +### SSH authentication + +Configure seed job like: + +``` +apiVersion: jenkins.io/v1alpha2 +kind: Jenkins +metadata: + name: example +spec: + seedJobs: + - id: jenkins-operator-ssh + credentialType: basicSSHUserPrivateKey + credentialID: k8s-ssh + targets: "cicd/jobs/*.jenkins" + description: "Jenkins Operator repository" + repositoryBranch: master + repositoryUrl: git@github.com:jenkinsci/kubernetes-operator.git +``` + +and create Kubernetes Secret(name of secret should be the same from `credentialID` field): + +``` +apiVersion: v1 +kind: Secret +metadata: + name: k8s-ssh +data: + privateKey: | + -----BEGIN RSA PRIVATE KEY----- + MIIJKAIBAAKCAgEAxxDpleJjMCN5nusfW/AtBAZhx8UVVlhhhIKXvQ+dFODQIdzO + oDXybs1zVHWOj31zqbbJnsfsVZ9Uf3p9k6xpJ3WFY9b85WasqTDN1xmSd6swD4N8 + ... + username: github_user_name +``` + +### Username & password authentication + +Configure seed job like: + +``` +apiVersion: jenkins.io/v1alpha2 +kind: Jenkins +metadata: + name: example +spec: + seedJobs: + - id: jenkins-operator-user-pass + credentialType: usernamePassword + credentialID: k8s-user-pass + targets: "cicd/jobs/*.jenkins" + description: "Jenkins Operator repository" + repositoryBranch: master + repositoryUrl: https://github.com/jenkinsci/kubernetes-operator.git +``` + +and create Kubernetes Secret(name of secret should be the same from `credentialID` field): + +``` +apiVersion: v1 +kind: Secret +metadata: + name: k8s-user-pass +data: + username: github_user_name + password: password_or_token +``` + +## Jenkins Customisation + +Jenkins can be customized using groovy scripts or configuration as code plugin. All custom configuration is stored in +the **jenkins-operator-user-configuration-** ConfigMap which is automatically created by **jenkins-operator**. + +**jenkins-operator** creates **jenkins-operator-user-configuration-** secret where user can store sensitive +information used for custom configuration. If you have entry in secret named `PASSWORD` then you can use it in +Configuration as Plugin as `adminAddress: "${PASSWORD}"`. + +``` +kubectl get secret jenkins-operator-user-configuration- -o yaml + +kind: Secret +apiVersion: v1 +type: Opaque +metadata: + name: jenkins-operator-user-configuration- + namespace: default +data: + SECRET_JENKINS_ADMIN_ADDRESS: YXNkZgo= + +``` + +``` +kubectl get configmap jenkins-operator-user-configuration- -o yaml + +apiVersion: v1 +data: + 1-configure-theme.groovy: |2 + import jenkins.* + import jenkins.model.* + import hudson.* + import hudson.model.* + import org.jenkinsci.plugins.simpletheme.ThemeElement + import org.jenkinsci.plugins.simpletheme.CssTextThemeElement + import org.jenkinsci.plugins.simpletheme.CssUrlThemeElement + + Jenkins jenkins = Jenkins.getInstance() + + def decorator = Jenkins.instance.getDescriptorByType(org.codefirst.SimpleThemeDecorator.class) + + List configElements = new ArrayList<>(); + configElements.add(new CssTextThemeElement("DEFAULT")); + configElements.add(new CssUrlThemeElement("https://cdn.rawgit.com/afonsof/jenkins-material-theme/gh-pages/dist/material-light-green.css")); + decorator.setElements(configElements); + decorator.save(); + + jenkins.save() + 1-system-message.yaml: |2 + jenkins: + systemMessage: "Configuration as Code integration works!!!" + adminAddress: "${SECRET_JENKINS_ADMIN_ADDRESS}" +kind: ConfigMap +metadata: + name: jenkins-operator-user-configuration- + namespace: default +``` + +When **jenkins-operator-user-configuration-** ConfigMap is updated Jenkins automatically +runs the **jenkins-operator-user-configuration** Jenkins Job which executes all scripts then +runs the **jenkins-operator-user-configuration-casc** Jenkins Job which applies Configuration as Code configuration. + +## Install Plugins + +Edit CR under `spec.master.plugins`: + +``` +apiVersion: jenkins.io/v1alpha2 +kind: Jenkins +metadata: + name: example +spec: + master: + plugins: + - name: simple-theme-plugin + version: 0.5.1 +``` + +Then **jenkins-operator** will automatically install plugins after Jenkins master pod restart. + +## Configure backup and restore + +Backup and restore is done by container sidecar. + +### PVC + +#### Create PVC + +Save to file pvc.yaml: +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: + namespace: +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 500Gi +``` + +Run command: +```bash +$ kubectl -n create -f pvc.yaml +``` + +#### Configure Jenkins CR + +```yaml +apiVersion: jenkins.io/v1alpha2 +kind: Jenkins +metadata: + name: + namespace: +spec: + master: + securityContext: + runAsUser: 1000 + fsGroup: 1000 + containers: + - name: jenkins-master + image: jenkins/jenkins:lts + - name: backup # container responsible for backup and restore + env: + - name: BACKUP_DIR + value: /backup + - name: JENKINS_HOME + value: /jenkins-home + - name: BACKUP_COUNT + value: "2" # keep only the 2 most recent backups + image: virtuslab/jenkins-operator-backup-pvc:v0.0.5 # look at backup/pvc directory + imagePullPolicy: IfNotPresent + volumeMounts: + - mountPath: /jenkins-home # Jenkins home volume + name: jenkins-home + - mountPath: /backup # backup volume + name: backup + volumes: + - name: backup # PVC volume where backups will be stored + persistentVolumeClaim: + claimName: + backup: + containerName: backup # container name is responsible for backup + action: + exec: + command: + - /home/user/bin/backup.sh # this command is invoked on "backup" container to make backup, for example /home/user/bin/backup.sh , is passed by operator + interval: 30 # how often make backup in seconds + makeBackupBeforePodDeletion: true # make backup before pod deletion + restore: + containerName: backup # container name is responsible for restore backup + action: + exec: + command: + - /home/user/bin/restore.sh # this command is invoked on "backup" container to make restore backup, for example /home/user/bin/restore.sh , is passed by operator + #recoveryOnce: # if want to restore specific backup configure this field and then Jenkins will be restarted and desired backup will be restored +``` + +## AKS + +Azure AKS managed Kubernetes service adds to every pod the following envs: + +```yaml +- name: KUBERNETES_PORT_443_TCP_ADDR + value: +- name: KUBERNETES_PORT + value: tcp:// +- name: KUBERNETES_PORT_443_TCP + value: tcp:// +- name: KUBERNETES_SERVICE_HOST + value: +``` + +The operator is aware of it and omits these envs when checking if Jenkins pod envs have been changed. It prevents +restart Jenkins pod over and over again. + +## Jenkins login credentials + +The operator automatically generate Jenkins user name and password and stores it in Kubernetes secret named +`jenkins-operator-credentials-` in namespace where Jenkins CR has been deployed. + +If you want change it you can override the secret: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: jenkins-operator-credentials- + namespace: +data: + user: + password: +``` + +If needed **jenkins-operator** will restart Jenkins master pod and then you can login with the new user and password +credentials. + +## Override default Jenkins container command + +The default command for the Jenkins master container `jenkins/jenkins:lts` looks like: + +```yaml +command: +- bash +- -c +- /var/jenkins/scripts/init.sh && /sbin/tini -s -- /usr/local/bin/jenkins.sh +``` + +The script`/var/jenkins/scripts/init.sh` is provided be the operator and configures init.groovy.d(creates Jenkins user) +and installs plugins. +The `/sbin/tini -s -- /usr/local/bin/jenkins.sh` command runs the Jenkins master main process. + +You can overwrite it in the following pattern: + +```yaml +command: +- bash +- -c +- /var/jenkins/scripts/init.sh && && /sbin/tini -s -- /usr/local/bin/jenkins.sh +``` + +## Debugging + +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 jenkins-operator logs: + +```bash +kubectl logs deployment/jenkins-operator +``` + +## Troubleshooting + +Delete Jenkins master pod and wait for the new one to come up: + +```bash +kubectl delete pod jenkins- +``` + +[job-dsl]:https://github.com/jenkinsci/job-dsl-plugin +[kubernetes-credentials-provider]:https://jenkinsci.github.io/kubernetes-credentials-provider-plugin/ diff --git a/docs/jenkins-v1alpha2-scheme.md b/documentation/v0.1.1/jenkins-v1alpha2-scheme.md similarity index 100% rename from docs/jenkins-v1alpha2-scheme.md rename to documentation/v0.1.1/jenkins-v1alpha2-scheme.md diff --git a/docs/getting-started.md b/documentation/v0.2.0/getting-started.md similarity index 97% rename from docs/getting-started.md rename to documentation/v0.2.0/getting-started.md index 1a1bc9de..241fe6e0 100644 --- a/docs/getting-started.md +++ b/documentation/v0.2.0/getting-started.md @@ -6,17 +6,18 @@ This document describes a getting started guide for **jenkins-operator** and an 2. [Deploy Jenkins](#deploy-jenkins) 3. [Configure Seed Jobs and Pipelines](#configure-seed-jobs-and-pipelines) 4. [Pulling Docker images from private repositories](#pulling-docker-images-from-private-repositories) -5. [Install Plugins](#install-plugins) -6. [Configure Backup & Restore](#configure-backup-and-restore) -7. [AKS](#aks) -8. [Jenkins login credentials](#jenkins-login-credentials) -9. [Override default Jenkins container command](#override-default-Jenkins-container-command) -10. [Debugging](#debugging) +5. [Jenkins Customisation](#jenkins-customisation) +6. [Install Plugins](#install-plugins) +7. [Configure Backup & Restore](#configure-backup-and-restore) +8. [AKS](#aks) +9. [Jenkins login credentials](#jenkins-login-credentials) +10. [Override default Jenkins container command](#override-default-Jenkins-container-command) +11. [Debugging](#debugging) ## First Steps Prepare your Kubernetes cluster and set up access. -Once you have running Kubernetes cluster you can focus on installing **jenkins-operator** according to the [Installation](installation.md) guide. +Once you have running Kubernetes cluster you can focus on installing **jenkins-operator** according to the [Installation](../installation.md) guide. ## Deploy Jenkins @@ -99,7 +100,7 @@ Connect to Jenkins (actual Kubernetes cluster): kubectl port-forward jenkins- 8080:8080 ``` Then open browser with address `http://localhost:8080`. -![jenkins](../assets/jenkins.png) +![jenkins](../../assets/jenkins.png) ## Configure Seed Jobs and Pipelines @@ -218,11 +219,11 @@ spec: You can verify if deploy keys were successfully configured in Jenkins **Credentials** tab. -![jenkins](../assets/jenkins-credentials.png) +![jenkins](../../assets/jenkins-credentials.png) You can verify if your pipelines were successfully configured in Jenkins Seed Job console output. -![jenkins](../assets/jenkins-seed.png) +![jenkins](../../assets/jenkins-seed.png) If your GitHub repository is **private** you have to configure SSH or username/password authentication. diff --git a/documentation/v0.2.0/jenkins-v1alpha2-scheme.md b/documentation/v0.2.0/jenkins-v1alpha2-scheme.md new file mode 100644 index 00000000..de25e2ae --- /dev/null +++ b/documentation/v0.2.0/jenkins-v1alpha2-scheme.md @@ -0,0 +1,1431 @@ +

Packages:

+ +

jenkins.io

+

+

Package v1alpha2 contains API Schema definitions for the jenkins.io v1alpha2 API group

+

+Resource Types: + +

Jenkins +

+

+

Jenkins is the Schema for the jenkins API

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+string		 + +jenkins.io/v1alpha2 + +
+kind
+string +		Jenkins
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +JenkinsSpec + + +		 +

Spec defines the desired state of the Jenkins

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
+master
+ + +JenkinsMaster + + +		 +

Master represents Jenkins master pod properties and Jenkins plugins. +Every single change here requires a pod restart.

+
+seedJobs
+ + +[][]github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.SeedJob + + +		 +(Optional) +

SeedJobs defines list of Jenkins Seed Job configurations +More info: https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-seed-jobs-and-pipelines

+
+service
+ + +Service + + +		 +(Optional) +

Service is Kubernetes service of Jenkins master HTTP pod +Defaults to : +port: 8080 +type: ClusterIP

+
+slaveService
+ + +Service + + +		 +(Optional) +

Service is Kubernetes service of Jenkins slave pods +Defaults to : +port: 50000 +type: ClusterIP

+
+backup
+ + +Backup + + +		 +(Optional) +

Backup defines configuration of Jenkins backup +More info: https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-backup-and-restore

+
+restore
+ + +Restore + + +		 +(Optional) +

Backup defines configuration of Jenkins backup restore +More info: https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-backup-and-restore

+
+
+status
+ + +JenkinsStatus + + +		 +

Status defines the observed state of Jenkins

+
+

Backup +

+

+(Appears on: +JenkinsSpec) +

+

+

Backup defines configuration of Jenkins backup

+

+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+containerName
+ +string + +		 +

ContainerName is the container name responsible for backup operation

+
+action
+ + +Handler + + +		 +

Action defines action which performs backup in backup container sidecar

+
+interval
+ +uint64 + +		 +

Interval tells how often make backup in seconds +Defaults to 30.

+
+makeBackupBeforePodDeletion
+ +bool + +		 +

MakeBackupBeforePodDeletion tells operator to make backup before Jenkins master pod deletion

+
+

Build +

+

+(Appears on: +JenkinsStatus) +

+

+

Build defines Jenkins Build status with corresponding metadata

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+jobName
+ +string + +		 +

JobName is the Jenkins job name

+
+hash
+ +string + +		 +

Hash is the unique data identifier used in build

+
+number
+ +int64 + +		 +

Number is the Jenkins build number

+
+status
+ + +BuildStatus + + +		 +

Status is the status of Jenkins build

+
+retries
+ +int + +		 +

Retires is the amount of Jenkins job build retries

+
+createTime
+ + +Kubernetes meta/v1.Time + + +		 +

CreateTime is the time when the first build has been created

+
+lastUpdateTime
+ + +Kubernetes meta/v1.Time + + +		 +

LastUpdateTime is the last update status time

+
+

BuildStatus +(string alias)

+

+(Appears on: +Build) +

+

+

BuildStatus defines type of Jenkins build job status

+

+

Container +

+

+(Appears on: +JenkinsMaster) +

+

+

Container defines Kubernetes container attributes

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +

Name of the container specified as a DNS_LABEL. +Each container in a pod must have a unique name (DNS_LABEL).

+
+image
+ +string + +		 +

Docker image name. +More info: https://kubernetes.io/docs/concepts/containers/images

+
+imagePullPolicy
+ + +Kubernetes core/v1.PullPolicy + + +		 +

Image pull policy. +One of Always, Never, IfNotPresent. +Defaults to Always.

+
+resources
+ + +Kubernetes core/v1.ResourceRequirements + + +		 +

Compute Resources required by this container. +More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/

+
+command
+ +[]string + +		 +(Optional) +

Entrypoint array. Not executed within a shell. +The docker image’s ENTRYPOINT is used if this is not provided. +Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable +cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax +can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, +regardless of whether the variable exists or not. +More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell

+
+args
+ +[]string + +		 +(Optional) +

Arguments to the entrypoint. +The docker image’s CMD is used if this is not provided. +Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable +cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax +can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, +regardless of whether the variable exists or not. +More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell

+
+workingDir
+ +string + +		 +(Optional) +

Container’s working directory. +If not specified, the container runtime’s default will be used, which +might be configured in the container image.

+
+ports
+ + +[]Kubernetes core/v1.ContainerPort + + +		 +(Optional) +

List of ports to expose from the container. Exposing a port here gives +the system additional information about the network connections a +container uses, but is primarily informational. Not specifying a port here +DOES NOT prevent that port from being exposed. Any port which is +listening on the default “0.0.0.0” address inside a container will be +accessible from the network.

+
+envFrom
+ + +[]Kubernetes core/v1.EnvFromSource + + +		 +(Optional) +

List of sources to populate environment variables in the container. +The keys defined within a source must be a C_IDENTIFIER. All invalid keys +will be reported as an event when the container is starting. When a key exists in multiple +sources, the value associated with the last source will take precedence. +Values defined by an Env with a duplicate key will take precedence.

+
+env
+ + +[]Kubernetes core/v1.EnvVar + + +		 +(Optional) +

List of environment variables to set in the container.

+
+volumeMounts
+ + +[]Kubernetes core/v1.VolumeMount + + +		 +(Optional) +

Pod volumes to mount into the container’s filesystem.

+
+livenessProbe
+ + +Kubernetes core/v1.Probe + + +		 +(Optional) +

Periodic probe of container liveness. +Container will be restarted if the probe fails.

+
+readinessProbe
+ + +Kubernetes core/v1.Probe + + +		 +(Optional) +

Periodic probe of container service readiness. +Container will be removed from service endpoints if the probe fails.

+
+lifecycle
+ + +Kubernetes core/v1.Lifecycle + + +		 +(Optional) +

Actions that the management system should take in response to container lifecycle events.

+
+securityContext
+ + +Kubernetes core/v1.SecurityContext + + +		 +(Optional) +

Security options the pod should run with. +More info: https://kubernetes.io/docs/concepts/policy/security-context/ +More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/

+
+

Handler +

+

+(Appears on: +Backup, +Restore) +

+

+

Handler defines a specific action that should be taken

+

+ + + + + + + + + + + + + +
FieldDescription
+exec
+ + +Kubernetes core/v1.ExecAction + + +		 +

Exec specifies the action to take.

+
+

JenkinsCredentialType +(string alias)

+

+(Appears on: +SeedJob) +

+

+

JenkinsCredentialType defines type of Jenkins credential used to seed job mechanism

+

+

JenkinsMaster +

+

+(Appears on: +JenkinsSpec) +

+

+

JenkinsMaster defines the Jenkins master pod attributes and plugins, +every single change requires a Jenkins master pod restart

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+masterAnnotations
+ +map[string]string + +		 +(Optional) +

Annotations is an unstructured key value map stored with a resource that may be +set by external tools to store and retrieve arbitrary metadata. They are not +queryable and should be preserved when modifying objects. +More info: http://kubernetes.io/docs/user-guide/annotations

+
+nodeSelector
+ +map[string]string + +		 +(Optional) +

NodeSelector is a selector which must be true for the pod to fit on a node. +Selector which must match a node’s labels for the pod to be scheduled on that node. +More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/

+
+securityContext
+ + +Kubernetes core/v1.PodSecurityContext + + +		 +(Optional) +

SecurityContext that applies to all the containers of the Jenkins +Master. As per kubernetes specification, it can be overridden +for each container individually. +Defaults to: +runAsUser: 1000 +fsGroup: 1000

+
+containers
+ + +[][]github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Container + + +		 +

List of containers belonging to the pod. +Containers cannot currently be added or removed. +There must be at least one container in a Pod. +Defaults to: +- image: jenkins/jenkins:lts +imagePullPolicy: Always +livenessProbe: +failureThreshold: 12 +httpGet: +path: /login +port: http +scheme: HTTP +initialDelaySeconds: 80 +periodSeconds: 10 +successThreshold: 1 +timeoutSeconds: 5 +name: jenkins-master +readinessProbe: +failureThreshold: 3 +httpGet: +path: /login +port: http +scheme: HTTP +initialDelaySeconds: 30 +periodSeconds: 10 +successThreshold: 1 +timeoutSeconds: 1 +resources: +limits: +cpu: 1500m +memory: 3Gi +requests: +cpu: “1” +memory: 600Mi

+
+volumes
+ + +[]Kubernetes core/v1.Volume + + +		 +(Optional) +

List of volumes that can be mounted by containers belonging to the pod. +More info: https://kubernetes.io/docs/concepts/storage/volumes

+
+basePlugins
+ + +[][]github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Plugin + + +		 +

BasePlugins contains plugins required by operator +Defaults to : +- name: kubernetes +version: 1.15.7 +- name: workflow-job +version: “2.32” +- name: workflow-aggregator +version: “2.6” +- name: git +version: 3.10.0 +- name: job-dsl +version: “1.74” +- name: configuration-as-code +version: “1.19” +- name: configuration-as-code-support +version: “1.19” +- name: kubernetes-credentials-provider +version: 0.12.1

+
+plugins
+ + +[][]github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Plugin + + +		 +(Optional) +

Plugins contains plugins required by user

+
+

JenkinsSpec +

+

+(Appears on: +Jenkins) +

+

+

JenkinsSpec defines the desired state of the Jenkins

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+master
+ + +JenkinsMaster + + +		 +

Master represents Jenkins master pod properties and Jenkins plugins. +Every single change here requires a pod restart.

+
+seedJobs
+ + +[][]github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.SeedJob + + +		 +(Optional) +

SeedJobs defines list of Jenkins Seed Job configurations +More info: https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-seed-jobs-and-pipelines

+
+service
+ + +Service + + +		 +(Optional) +

Service is Kubernetes service of Jenkins master HTTP pod +Defaults to : +port: 8080 +type: ClusterIP

+
+slaveService
+ + +Service + + +		 +(Optional) +

Service is Kubernetes service of Jenkins slave pods +Defaults to : +port: 50000 +type: ClusterIP

+
+backup
+ + +Backup + + +		 +(Optional) +

Backup defines configuration of Jenkins backup +More info: https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-backup-and-restore

+
+restore
+ + +Restore + + +		 +(Optional) +

Backup defines configuration of Jenkins backup restore +More info: https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-backup-and-restore

+
+

JenkinsStatus +

+

+(Appears on: +Jenkins) +

+

+

JenkinsStatus defines the observed state of Jenkins

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+operatorVersion
+ +string + +		 +(Optional) +

OperatorVersion is the operator version which manages this CR

+
+provisionStartTime
+ + +Kubernetes meta/v1.Time + + +		 +(Optional) +

ProvisionStartTime is a time when Jenkins master pod has been created

+
+baseConfigurationCompletedTime
+ + +Kubernetes meta/v1.Time + + +		 +(Optional) +

BaseConfigurationCompletedTime is a time when Jenkins base configuration phase has been completed

+
+userConfigurationCompletedTime
+ + +Kubernetes meta/v1.Time + + +		 +(Optional) +

UserConfigurationCompletedTime is a time when Jenkins user configuration phase has been completed

+
+builds
+ + +[][]github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Build + + +		 +(Optional) +

Builds contains Jenkins builds statues

+
+restoredBackup
+ +uint64 + +		 +(Optional) +

RestoredBackup is the restored backup number after Jenkins master pod restart

+
+lastBackup
+ +uint64 + +		 +(Optional) +

LastBackup is the latest backup number

+
+pendingBackup
+ +uint64 + +		 +(Optional) +

PendingBackup is the pending backup number

+
+backupDoneBeforePodDeletion
+ +bool + +		 +(Optional) +

BackupDoneBeforePodDeletion tells if backup before pod deletion has been made

+
+userAndPasswordHash
+ +string + +		 +(Optional) +

UserAndPasswordHash is a SHA256 hash made from user and password

+
+createdSeedJobs
+ +[]string + +		 +(Optional) +

CreatedSeedJobs contains list of seed job id already created in Jenkins

+
+

Plugin +

+

+(Appears on: +JenkinsMaster) +

+

+

Plugin defines Jenkins plugin

+

+ + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +

Name is the name of Jenkins plugin

+
+version
+ +string + +		 +

Version is the version of Jenkins plugin

+
+

Restore +

+

+(Appears on: +JenkinsSpec) +

+

+

Restore defines configuration of Jenkins backup restore operation

+

+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+containerName
+ +string + +		 +

ContainerName is the container name responsible for restore backup operation

+
+action
+ + +Handler + + +		 +

Action defines action which performs restore backup in restore container sidecar

+
+recoveryOnce
+ +uint64 + +		 +(Optional) +

RecoveryOnce if want to restore specific backup set this field and then Jenkins will be restarted and desired backup will be restored

+
+

SeedJob +

+

+(Appears on: +JenkinsSpec) +

+

+

SeedJob defines configuration for seed job +More info: https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-seed-jobs-and-pipelines

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+id
+ +string + +		 +

ID is the unique seed job name

+
+credentialID
+ +string + +		 +

CredentialID is the Kubernetes secret name which stores repository access credentials

+
+description
+ +string + +		 +(Optional) +

Description is the description of the seed job

+
+targets
+ +string + +		 +

Targets is the repository path where are seed job definitions

+
+repositoryBranch
+ +string + +		 +

RepositoryBranch is the repository branch where are seed job definitions

+
+repositoryUrl
+ +string + +		 +

RepositoryURL is the repository access URL. Can be SSH or HTTPS.

+
+credentialType
+ + +JenkinsCredentialType + + +		 +(Optional) +

JenkinsCredentialType is the https://jenkinsci.github.io/kubernetes-credentials-provider-plugin/ credential type

+
+

Service +

+

+(Appears on: +JenkinsSpec) +

+

+

Service defines Kubernetes service attributes

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+annotations
+ +map[string]string + +		 +(Optional) +

Annotations is an unstructured key value map stored with a resource that may be +set by external tools to store and retrieve arbitrary metadata. They are not +queryable and should be preserved when modifying objects. +More info: http://kubernetes.io/docs/user-guide/annotations

+
+labels
+ +map[string]string + +		 +

Route service traffic to pods with label keys and values matching this +selector. If empty or not present, the service is assumed to have an +external process managing its endpoints, which Kubernetes will not +modify. Only applies to types ClusterIP, NodePort, and LoadBalancer. +Ignored if type is ExternalName. +More info: https://kubernetes.io/docs/concepts/services-networking/service/

+
+type
+ + +Kubernetes core/v1.ServiceType + + +		 +(Optional) +

Type determines how the Service is exposed. Defaults to ClusterIP. Valid +options are ExternalName, ClusterIP, NodePort, and LoadBalancer. +“ExternalName” maps to the specified externalName. +“ClusterIP” allocates a cluster-internal IP address for load-balancing to +endpoints. Endpoints are determined by the selector or if that is not +specified, by manual construction of an Endpoints object. If clusterIP is +“None”, no virtual IP is allocated and the endpoints are published as a +set of endpoints rather than a stable IP. +“NodePort” builds on ClusterIP and allocates a port on every node which +routes to the clusterIP. +“LoadBalancer” builds on NodePort and creates an +external load-balancer (if supported in the current cloud) which routes +to the clusterIP. +More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services—service-types

+
+port
+ +int32 + +		 +

The port that are exposed by this service. +More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

+
+nodePort
+ +int32 + +		 +(Optional) +

The port on each node on which this service is exposed when type=NodePort or LoadBalancer. +Usually assigned by the system. If specified, it will be allocated to the service +if unused or else creation of the service will fail. +Default is to auto-allocate a port if the ServiceType of this Service requires one. +More info: https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport

+
+loadBalancerSourceRanges
+ +[]string + +		 +(Optional) +

If specified and supported by the platform, this will restrict traffic through the cloud-provider +load-balancer will be restricted to the specified client IPs. This field will be ignored if the +cloud-provider does not support the feature.” +More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/

+
+loadBalancerIP
+ +string + +		 +(Optional) +

Only applies to Service Type: LoadBalancer +LoadBalancer will get created with the IP specified in this field. +This feature depends on whether the underlying cloud-provider supports specifying +the loadBalancerIP when a load balancer is created. +This field will be ignored if the cloud-provider does not support the feature.

+
+
+

+Generated with gen-crd-api-reference-docs +on git commit 37e531a. +