diff --git a/website/content/en/docs/Getting Started/latest/_index.md b/website/content/en/docs/Getting Started/latest/_index.md index 2f46cfcd..98b30225 100644 --- a/website/content/en/docs/Getting Started/latest/_index.md +++ b/website/content/en/docs/Getting Started/latest/_index.md @@ -1,14 +1,14 @@ --- -title: "Latest (v0.2.x)" -linkTitle: "Latest (v0.2.x)" +title: "Latest (v0.3.x)" +linkTitle: "Latest (v0.3.x)" weight: 10 -date: 2019-08-05 +date: 2019-12-20 description: > How to work with jenkins-operator latest version --- {{% pageinfo %}} -This document describes a getting started guide for **Jenkins Operator** `v0.2.x` and an additional configuration. +This document describes a getting started guide for **Jenkins Operator** `v0.3.x` and an additional configuration. {{% /pageinfo %}} ## First Steps diff --git a/website/content/en/docs/Getting Started/latest/aks.md b/website/content/en/docs/Getting Started/latest/aks.md index 7eab9a40..f9f27d03 100644 --- a/website/content/en/docs/Getting Started/latest/aks.md +++ b/website/content/en/docs/Getting Started/latest/aks.md @@ -2,7 +2,7 @@ title: "AKS" linkTitle: "AKS" weight: 10 -date: 2019-08-05 +date: 2019-12-20 description: > Additional configuration for Azure Kubernetes Service --- diff --git a/website/content/en/docs/Getting Started/latest/configuration.md b/website/content/en/docs/Getting Started/latest/configuration.md index ef8086b1..f0edd538 100644 --- a/website/content/en/docs/Getting Started/latest/configuration.md +++ b/website/content/en/docs/Getting Started/latest/configuration.md @@ -2,7 +2,7 @@ title: "Configuration" linkTitle: "Configuration" weight: 2 -date: 2019-08-05 +date: 2019-12-20 description: > How to configure Jenkins with Operator --- diff --git a/website/content/en/docs/Getting Started/latest/configure-backup-and-restore.md b/website/content/en/docs/Getting Started/latest/configure-backup-and-restore.md index c8987e0e..ce65e8ba 100644 --- a/website/content/en/docs/Getting Started/latest/configure-backup-and-restore.md +++ b/website/content/en/docs/Getting Started/latest/configure-backup-and-restore.md @@ -2,7 +2,7 @@ title: "Configure backup and restore" linkTitle: "Configure backup and restore" weight: 10 -date: 2019-08-05 +date: 2019-12-20 description: > Prevent loss of job history --- 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 cc927599..3207fb2b 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 @@ -2,7 +2,7 @@ title: "Custom Backup and Restore Providers" linkTitle: "Custom Backup and Restore Providers" weight: 10 -date: 2019-08-05 +date: 2019-12-20 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.md index 7d953c71..ba75397d 100644 --- a/website/content/en/docs/Getting Started/latest/customization.md +++ b/website/content/en/docs/Getting Started/latest/customization.md @@ -2,7 +2,7 @@ title: "Customization" linkTitle: "Customization" weight: 3 -date: 2019-08-05 +date: 2019-12-20 description: > How to customize Jenkins --- diff --git a/website/content/en/docs/Getting Started/latest/deploy-jenkins.md b/website/content/en/docs/Getting Started/latest/deploy-jenkins.md index 4f7b5a96..237157b6 100644 --- a/website/content/en/docs/Getting Started/latest/deploy-jenkins.md +++ b/website/content/en/docs/Getting Started/latest/deploy-jenkins.md @@ -2,7 +2,7 @@ title: "Deploy Jenkins" linkTitle: "Deploy Jenkins" weight: 1 -date: 2019-08-05 +date: 2019-12-20 description: > Deploy production ready Jenkins Operator manifest --- diff --git a/website/content/en/docs/Getting Started/latest/diagnostics.md b/website/content/en/docs/Getting Started/latest/diagnostics.md index 87286adb..8e159bad 100644 --- a/website/content/en/docs/Getting Started/latest/diagnostics.md +++ b/website/content/en/docs/Getting Started/latest/diagnostics.md @@ -2,7 +2,7 @@ title: "Diagnostics" linkTitle: "Diagnostics" weight: 40 -date: 2019-08-05 +date: 2019-12-20 description: > How to deal with Jenkins Operator problems --- diff --git a/website/content/en/docs/Getting Started/latest/notifications.md b/website/content/en/docs/Getting Started/latest/notifications.md new file mode 100644 index 00000000..4a69d2f1 --- /dev/null +++ b/website/content/en/docs/Getting Started/latest/notifications.md @@ -0,0 +1,114 @@ +--- +title: "Notifications" +linkTitle: "Notifications" +weight: 10 +date: 2019-12-20 +description: > + How to setup operator notifications. +--- + +## Slack + +Please follow [this](https://api.slack.com/incoming-webhooks) instructions to get web hook URL. + +Create web hook secret with name `jenkins-operator-notification-data`. Contains key `url` with provided web hook URL. + +```bash +$ kubectl create secret generic jenkins-operator-notification-data --from-literal=url= +``` + +Example configuration for Slack: + +``` +kind: Jenkins +spec: + master: + notifications: + - loggingLevel: info + verbose: true + name: + slack: + webHookURLSecretKeySelector: + secret: + name: + key: +``` + +## Microsoft Teams + +Please follow [this](https://docs.microsoft.com/en-gb/outlook/actionable-messages/send-via-connectors) instructions to get web hook URL. + +Example configuration for Microsoft Teams: + +``` +kind: Jenkins +spec: + master: + notifications: + - loggingLevel: info + verbose: true + name: + teams: + webHookURLSecretKeySelector: + secret: + name: + key: +``` + +## Mailgun + +Example configuration for Mailgun: + +``` +kind: Jenkins +spec: + master: + notifications: + - loggingLevel: info + verbose: true + name: + mailgun: + domain: + apiKeySecretKeySelector: + secret: + name: + key: + recipient: + from: +``` + +## Debug options + +As you see there is two debugging options: + +* `loggingLevel` (warning/info) - Set level of messages to send. + +* `verbose` - Print stacktrace and additional error messages + +## Multiple providers + +You can use multiple providers to send notification to another communication channels at the same time. +For example you will send notifications to Slack and Teams. + +``` +kind: Jenkins +spec: + master: + notifications: + - loggingLevel: info + verbose: true + name: nslack + slack: + webHookURLSecretKeySelector: + secret: + name: + key: + - loggingLevel: info + verbose: true + name: nteams + teams: + webHookURLSecretKeySelector: + secret: + name: + key: +``` \ No newline at end of file diff --git a/website/content/en/docs/Getting Started/latest/schema.md b/website/content/en/docs/Getting Started/latest/schema.md index 008414be..ab9e3fdb 100644 --- a/website/content/en/docs/Getting Started/latest/schema.md +++ b/website/content/en/docs/Getting Started/latest/schema.md @@ -2,7 +2,7 @@ title: "Schema" linkTitle: "Schema" weight: 40 -date: 2019-08-05 +date: 2019-12-20 description: > API Schema definitions for Jenkins CRD --- @@ -19,7 +19,7 @@ This document contains API scheme for `jenkins-operator` Custom Resource Definit

jenkins.io

-

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

+

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

Resource Types:
  • @@ -108,12 +108,26 @@ Every single change here requires a pod restart.

    (Optional) -

    SeedJobs defines a list of Jenkins Seed Job configurations +

    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

    +notifications
    + + +[][]github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Notification + + + + +

    Notifications defines list of a services which are used to inform about Jenkins status +Can be used to integrate chat services like Slack, Microsoft Teams or Mailgun

    + + + + service
    @@ -123,7 +137,7 @@ Service (Optional) -

    Service is the Kubernetes service of the Jenkins master HTTP pod +

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

    @@ -140,7 +154,7 @@ Service (Optional) -

    Service is the Kubernetes service of the Jenkins slave pods +

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

    @@ -157,7 +171,7 @@ Backup (Optional) -

    Backup defines the configuration of a Jenkins backup +

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

    @@ -172,7 +186,7 @@ Restore (Optional) -

    Backup defines the configuration of a Jenkins backup restore +

    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

    @@ -187,7 +201,7 @@ GroovyScripts (Optional) -

    GroovyScripts defines the configuration of Jenkins customization via groovy scripts

    +

    GroovyScripts defines configuration of Jenkins customization via groovy scripts

    @@ -201,7 +215,7 @@ ConfigurationAsCode (Optional) -

    ConfigurationAsCode defines the configuration of Jenkins customization via the Configuration as Code Jenkins plugin

    +

    ConfigurationAsCode defines configuration of Jenkins customization via Configuration as Code Jenkins plugin

    @@ -292,7 +306,7 @@ string JenkinsSpec)

    -

    Backup defines the configuration of a Jenkins backup

    +

    Backup defines configuration of Jenkins backup

    @@ -323,7 +337,7 @@ Handler @@ -334,7 +348,7 @@ uint64 @@ -346,7 +360,7 @@ bool @@ -358,7 +372,7 @@ bool Customization)

    -

    ConfigMapRef is the reference to Kubernetes ConfigMap

    +

    ConfigMapRef is reference to Kubernetes ConfigMap

    -

    Action defines the action which performs the backup in the backup container sidecar

    +

    Action defines action which performs backup in backup container sidecar
    -

    Interval tells you how often the backup is made in seconds +

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

    MakeBackupBeforePodDeletion tells the operator to make a backup before Jenkins master pod deletion

    +

    MakeBackupBeforePodDeletion tells operator to make backup before Jenkins master pod deletion
    @@ -387,7 +401,7 @@ string JenkinsSpec)

    -

    ConfigurationAsCode defines configuration of Jenkins customization via the Configuration as Code Jenkins plugin

    +

    ConfigurationAsCode defines configuration of Jenkins customization via Configuration as Code Jenkins plugin

    @@ -418,7 +432,7 @@ Customization JenkinsMaster)

    -

    Container defines the Kubernetes container attributes

    +

    Container defines Kubernetes container attributes

    @@ -773,7 +787,7 @@ Kubernetes core/v1.ExecAction SeedJob)

    -

    JenkinsCredentialType defines the type of Jenkins credential used in the seed job mechanism

    +

    JenkinsCredentialType defines type of Jenkins credential used to seed job mechanism

    JenkinsMaster

    @@ -795,7 +809,7 @@ every single change requires a Jenkins master pod restart

    + + + + + + + +
    -masterAnnotations
    +annotations
    map[string]string @@ -810,6 +824,22 @@ More info: http://kub
    +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 +Deprecated: will be removed in the future, please use Annotations(annotations)

    +
    nodeSelector
    map[string]string @@ -963,6 +993,17 @@ version: 0.12.1

    Plugins contains plugins required by user
    +disableCSRFProtection
    + +bool + +    		 +

    DisableCSRFProtection allows you to toggle CSRF Protection on Jenkins

    +

    JenkinsSpec @@ -1013,6 +1054,20 @@ More info: +[][]github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Notification + + + + +

    Notifications defines list of a services which are used to inform about Jenkins status +Can be used to integrate chat services like Slack, Microsoft Teams or Mailgun

    + + + + service
    @@ -1233,7 +1288,7 @@ string (Optional) -

    UserAndPasswordHash is a SHA256 hash made from the username and password

    +

    UserAndPasswordHash is a SHA256 hash made from user and password

    @@ -1245,7 +1300,7 @@ string (Optional) -

    CreatedSeedJobs contains list of seed job ids already created in Jenkins

    +

    CreatedSeedJobs contains list of seed job id already created in Jenkins

    @@ -1360,6 +1415,10 @@ SecretKeySelector

    Notification

    +(Appears on: +JenkinsSpec) +

    +

    Notification is a service configuration used to send notifications about Jenkins status

    @@ -1372,10 +1431,10 @@ SecretKeySelector @@ -1438,16 +1497,28 @@ github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Mailgun + + + +
    -loggingLevel
    +level
    - -NotificationLogLevel + +NotificationLevel
    +smtp
    + + +github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.SMTP + + +    		 +
    -

    NotificationLogLevel +

    NotificationLevel (string alias)

    (Appears on: Notification)

    -

    NotificationLogLevel defines logging level of Notification

    +

    NotificationLevel defines the level of a Notification

    Plugin

    @@ -1545,12 +1616,106 @@ uint64 +

    SMTP +

    +

    +(Appears on: +Notification) +

    +

    +

    SMTP is handler for sending emails via this protocol

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +usernameSecretKeySelector
    + + +SecretKeySelector + + +    		 +
    +passwordSecretKeySelector
    + + +SecretKeySelector + + +    		 +
    +port
    + +int + +    		 +
    +server
    + +string + +    		 +
    +tlsInsecureSkipVerify
    + +bool + +    		 +
    +from
    + +string + +    		 +
    +to
    + +string + +    		 +

    SecretKeySelector

    (Appears on: Mailgun, MicrosoftTeams, +SMTP, Slack)

    @@ -1679,7 +1844,7 @@ string -

    Targets is the repository path where the seed job definitions are

    +

    Targets is the repository path where are seed job definitions

    @@ -1690,7 +1855,7 @@ string -

    RepositoryBranch is the repository branch where the seed job definitions are

    +

    RepositoryBranch is the repository branch where are seed job definitions

    @@ -1887,7 +2052,7 @@ int32 -

    The port that is exposed by this service. +

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

    @@ -1902,7 +2067,7 @@ 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. +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

    @@ -1917,7 +2082,7 @@ More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/

    @@ -1975,5 +2140,5 @@ SecretKeySelector

    Generated with gen-crd-api-reference-docs -on git commit f4c4235. +on git commit b6e1057.

    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 new file mode 100644 index 00000000..2f46cfcd --- /dev/null +++ b/website/content/en/docs/Getting Started/v0.2.x/_index.md @@ -0,0 +1,18 @@ +--- +title: "Latest (v0.2.x)" +linkTitle: "Latest (v0.2.x)" +weight: 10 +date: 2019-08-05 +description: > + How to work with jenkins-operator latest version +--- + +{{% pageinfo %}} +This document describes a getting started guide for **Jenkins Operator** `v0.2.x` and an additional configuration. +{{% /pageinfo %}} + +## First Steps + +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. diff --git a/website/content/en/docs/Getting Started/v0.2.x/aks.md b/website/content/en/docs/Getting Started/v0.2.x/aks.md new file mode 100644 index 00000000..7eab9a40 --- /dev/null +++ b/website/content/en/docs/Getting Started/v0.2.x/aks.md @@ -0,0 +1,24 @@ +--- +title: "AKS" +linkTitle: "AKS" +weight: 10 +date: 2019-08-05 +description: > + Additional configuration for Azure Kubernetes Service +--- + +Azure AKS managed Kubernetes service adds to every pod the following environment variables: + +```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 environment variables when checking if a Jenkins pod environment has been changed. It prevents the +restart of a Jenkins pod over and over again. \ No newline at end of file diff --git a/website/content/en/docs/Getting Started/v0.2.x/configuration.md b/website/content/en/docs/Getting Started/v0.2.x/configuration.md new file mode 100644 index 00000000..ef8086b1 --- /dev/null +++ b/website/content/en/docs/Getting Started/v0.2.x/configuration.md @@ -0,0 +1,325 @@ +--- +title: "Configuration" +linkTitle: "Configuration" +weight: 2 +date: 2019-08-05 +description: > + How to configure Jenkins with Operator +--- + +## 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`** is 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/pipelines/build.jenkins`** is 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 the seed jobs. + +You can verify if deploy keys were successfully configured in the Jenkins **Credentials** tab. + +![jenkins](/kubernetes-operator/img/jenkins-credentials.png) + +You can verify if your pipelines were successfully configured in the Jenkins Seed Job console output. + +![jenkins](/kubernetes-operator/img/jenkins-seed.png) + +If your GitHub repository is **private** you have to configure SSH or username/password authentication. + +### SSH authentication + +#### Generate SSH Keys + +There are two methods of SSH private key generation: + +```bash +$ openssl genrsa -out 2048 +``` + +or + +```bash +$ ssh-keygen -t rsa -b 2048 +$ ssh-keygen -p -f -m pem +``` + +Then copy content from generated file. + +#### Public key + +If you want to upload your public key to your Git server you need to extract it. + +If key was generated by `openssl` then you need to type this to extract public key: + +```bash +$ openssl rsa -in -pubout > .pub +``` + +If key was generated by `ssh-keygen` the public key content is located in .pub and there is no need to extract public key + +#### Configure SSH authentication + +Configure a seed job like this: + +``` +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 a Kubernetes Secret (name of secret should be the same from `credentialID` field): + +``` +apiVersion: v1 +kind: Secret +metadata: + name: k8s-ssh +stringData: + privateKey: | + -----BEGIN RSA PRIVATE KEY----- + MIIJKAIBAAKCAgEAxxDpleJjMCN5nusfW/AtBAZhx8UVVlhhhIKXvQ+dFODQIdzO + oDXybs1zVHWOj31zqbbJnsfsVZ9Uf3p9k6xpJ3WFY9b85WasqTDN1xmSd6swD4N8 + ... + username: github_user_name +``` + +### Username & password authentication + +Configure the 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 a Kubernetes Secret (name of secret should be the same from `credentialID` field): + +``` +apiVersion: v1 +kind: Secret +metadata: + name: k8s-user-pass +stringData: + username: github_user_name + password: password_or_token +``` + +## HTTP Proxy for downloading plugins + +To use forwarding proxy with an operator to download plugins you need to add the following environment variable to Jenkins Custom Resource (CR), e.g.: + +```yaml +spec: + master: + containers: + - name: jenkins-master + env: + - name: CURL_OPTIONS + value: -L -x +``` + +In `CURL_OPTIONS` var you can set additional arguments to `curl` command. + +## Pulling Docker images from private repositories + +To pull a Docker Image from private repository you can use `imagePullSecrets`. + +Please follow the instructions on [creating a secret with a docker config](https://kubernetes.io/docs/concepts/containers/images/?origin_team=T42NTAGHM#creating-a-secret-with-a-docker-config). + +### Docker Hub Configuration +To use Docker Hub additional steps are required. + +Edit the previously created secret: +```bash +kubectl -n edit secret +``` + +The `.dockerconfigjson` key's value needs to be replaced with a modified version. + +After modifications, it needs to be encoded as a Base64 value before setting the `.dockerconfigjson` key. + +Example config file to modify and use: +``` +{ + "auths":{ + "https://index.docker.io/v1/":{ + "username":"user", + "password":"password", + "email":"yourdockeremail@gmail.com", + "auth":"base64 of string user:password" + }, + "auth.docker.io":{ + "username":"user", + "password":"password", + "email":"yourdockeremail@gmail.com", + "auth":"base64 of string user:password" + }, + "registry.docker.io":{ + "username":"user", + "password":"password", + "email":"yourdockeremail@gmail.com", + "auth":"base64 of string user:password" + }, + "docker.io":{ + "username":"user", + "password":"password", + "email":"yourdockeremail@gmail.com", + "auth":"base64 of string user:password" + }, + "https://registry-1.docker.io/v2/": { + "username":"user", + "password":"password", + "email":"yourdockeremail@gmail.com", + "auth":"base64 of string user:password" + }, + "registry-1.docker.io/v2/": { + "username":"user", + "password":"password", + "email":"yourdockeremail@gmail.com", + "auth":"base64 of string user:password" + }, + "registry-1.docker.io": { + "username":"user", + "password":"password", + "email":"yourdockeremail@gmail.com", + "auth":"base64 of string user:password" + }, + "https://registry-1.docker.io": { + "username":"user", + "password":"password", + "email":"yourdockeremail@gmail.com", + "auth":"base64 of string user:password" + } + } +} +``` + +[job-dsl]:https://github.com/jenkinsci/job-dsl-plugin +[kubernetes-credentials-provider]:https://jenkinsci.github.io/kubernetes-credentials-provider-plugin/ diff --git a/website/content/en/docs/Getting Started/v0.2.x/configure-backup-and-restore.md b/website/content/en/docs/Getting Started/v0.2.x/configure-backup-and-restore.md new file mode 100644 index 00000000..c8987e0e --- /dev/null +++ b/website/content/en/docs/Getting Started/v0.2.x/configure-backup-and-restore.md @@ -0,0 +1,86 @@ +--- +title: "Configure backup and restore" +linkTitle: "Configure backup and restore" +weight: 10 +date: 2019-08-05 +description: > + Prevent loss of job history +--- + +Backup and restore is done by a container sidecar. + +### PVC + +#### Create PVC + +Save to the file named pvc.yaml: +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: + namespace: +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 500Gi +``` + +Run the following 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 the backup and restore + env: + - name: BACKUP_DIR + value: /backup + - name: JENKINS_HOME + value: /jenkins-home + - name: BACKUP_COUNT + value: "3" # keep only the 2 most recent backups + image: virtuslab/jenkins-operator-backup-pvc:v0.0.7 # 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 a 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 +``` diff --git a/website/content/en/docs/Getting Started/v0.2.x/custom-backup-and-restore.md b/website/content/en/docs/Getting Started/v0.2.x/custom-backup-and-restore.md new file mode 100644 index 00000000..cc927599 --- /dev/null +++ b/website/content/en/docs/Getting Started/v0.2.x/custom-backup-and-restore.md @@ -0,0 +1,184 @@ +--- +title: "Custom Backup and Restore Providers" +linkTitle: "Custom Backup and Restore Providers" +weight: 10 +date: 2019-08-05 +description: > + Custom backup and restore provider +--- + +With enough effort one can create a custom backup and restore provider +for the Jenkins Operator. + +## Requirements + +Two commands (e.g. scripts) are required: + +- a backup command, e.g. `backup.sh` that takes one argument, a **backup number** +- a restore command, e.g. `backup.sh` that takes one argument, a **backup number** + +Both scripts need to return an exit code of `0` on success and `1` or greater for failure. + +One of those scripts (or the entry point of the container) needs to be responsible +for backup cleanup or rotation if required, or an external system. + +## How it works + +The mechanism relies on basic Kubernetes and UNIX functionalities. + +The backup (and restore) container runs as a sidecar in the same +Kubernetes pod as the Jenkins master. + +Name of the backup and restore containers can be set as necessary using +`spec.backup.containerName` and `spec.restore.containerName`. +In most cases it will be the same container, but we allow for less common use cases. + +The operator will call a backup or restore commands inside a sidecar container when necessary: + +- backup command (defined in `spec.backup.action.exec.command`) + will be called every `N` seconds configurable in: `spec.backup.interval` + and on pod shutdown (if enabled in `spec.backup.makeBackupBeforePodDeletion`) + with an integer representing the current backup number as first and only argument +- restore command (defined in `spec.restore.action.exec.command`) + will be called at Jenkins startup + with an integer representing the backup number to restore as first and only argument + (can be overridden using `spec.restore.recoveryOnce`) + +## Example AWS S3 backup using the CLI + +This example shows abbreviated version of a simple AWS S3 backup implementation +using: `aws-cli`, `bash` and `kube2iam`. + +In addition to your normal `Jenkins` `CustomResource` some additional settings +for backup and restore are required, e.g.: + +```yaml +kind: Jenkins +apiVersion: jenkins.io/v1alpha1 +metadata: + name: example + namespace: jenkins +spec: + master: + masterAnnotations: + iam.amazonaws.com/role: "my-example-backup-role" # tell kube2iam where the AWS IAM role is + containers: + - name: jenkins-master + ... + - name: backup # container responsible for backup and restore + image: quay.io/virtuslab/aws-cli:1.16.263-2 + workingDir: /home/user/bin/ + command: # our container entry point + - sleep + - infinity + env: + - name: BACKUP_BUCKET + value: my-example-bucket # the S3 bucket name to use + - name: BACKUP_PATH + value: my-backup-path # the S3 bucket path prefix to use + - name: JENKINS_HOME + value: /jenkins-home # the path to mount jenkins home dir in the backup container + volumeMounts: + - mountPath: /jenkins-home # Jenkins home volume + name: jenkins-home + - mountPath: /home/user/bin/backup.sh + name: backup-scripts + subPath: backup.sh + readOnly: true + - mountPath: /home/user/bin/restore.sh + name: backup-scripts + subPath: restore.sh + readOnly: true + volumes: + - name: backup-scripts + configMap: + defaultMode: 0754 + name: jenkins-operator-backup-s3 + securityContext: # make sure both containers use the same UID and GUID + runAsUser: 1000 + fsGroup: 1000 + ... + backup: + containerName: backup # container name responsible for backup + interval: 3600 # how often make a backup in seconds + makeBackupBeforePodDeletion: true # trigger backup just before deleting the pod + action: + exec: + command: + # this command is invoked on "backup" container to create a backup, + # is passed by operator, + # for example /home/user/bin/backup.sh + - /home/user/bin/backup.sh + restore: + containerName: backup # container name is responsible for restore backup + action: + exec: + command: + # this command is invoked on "backup" container to restore a backup, + # is passed by operator + # for example /home/user/bin/restore.sh + - /home/user/bin/restore.sh +# recoveryOnce: # if want to restore specific backup configure this field and then Jenkins will be restarted and desired backup will be restored +``` + +The actual backup and restore scripts will be provided in a `ConfigMap`: + +```yaml +kind: ConfigMap +apiVersion: v1 +metadata: + name: jenkins-operator-backup-s3 + namespace: jenkins + labels: + app: jenkins-operator +data: + backup.sh: |- + #!/bin/bash -xeu + [[ ! $# -eq 1 ]] && echo "Usage: $0 backup_number" && exit 1; + [[ -z "${BACKUP_BUCKET}" ]] && echo "Required 'BACKUP_BUCKET' env not set" && exit 1; + [[ -z "${BACKUP_PATH}" ]] && echo "Required 'BACKUP_PATH' env not set" && exit 1; + [[ -z "${JENKINS_HOME}" ]] && echo "Required 'JENKINS_HOME' env not set" && exit 1; + + backup_number=$1 + echo "Running backup #${backup_number}" + + BACKUP_TMP_DIR=$(mktemp -d) + tar -C ${JENKINS_HOME} -czf "${BACKUP_TMP_DIR}/${backup_number}.tar.gz" --exclude jobs/*/workspace* -c jobs && \ + + aws s3 cp ${BACKUP_TMP_DIR}/${backup_number}.tar.gz s3://${BACKUP_BUCKET}/${BACKUP_PATH}/${backup_number}.tar.gz + echo Done + + restore.sh: |- + #!/bin/bash -xeu + [[ ! $# -eq 1 ]] && echo "Usage: $0 backup_number" && exit 1 + [[ -z "${BACKUP_BUCKET}" ]] && echo "Required 'BACKUP_BUCKET' env not set" && exit 1; + [[ -z "${BACKUP_PATH}" ]] && echo "Required 'BACKUP_PATH' env not set" && exit 1; + [[ -z "${JENKINS_HOME}" ]] && echo "Required 'JENKINS_HOME' env not set" && exit 1; + + backup_number=$1 + echo "Running restore #${backup_number}" + + BACKUP_TMP_DIR=$(mktemp -d) + aws s3 cp s3://${BACKUP_BUCKET}/${BACKUP_PATH}/${backup_number}.tar.gz ${BACKUP_TMP_DIR}/${backup_number}.tar.gz + + tar -C ${JENKINS_HOME} -zxf "${BACKUP_TMP_DIR}/${backup_number}.tar.gz" + echo Done +``` + +In our example we will use S3 bucket lifecycle policy to keep +the number of backups under control, e.g. Cloud Formation fragment: +```yaml + Type: AWS::S3::Bucket + Properties: + BucketName: my-example-bucket + ... + LifecycleConfiguration: + Rules: + - Id: BackupCleanup + Status: Enabled + Prefix: my-backup-path + ExpirationInDays: 7 + NoncurrentVersionExpirationInDays: 14 + AbortIncompleteMultipartUpload: + DaysAfterInitiation: 3 +``` diff --git a/website/content/en/docs/Getting Started/v0.2.x/customization.md b/website/content/en/docs/Getting Started/v0.2.x/customization.md new file mode 100644 index 00000000..7d953c71 --- /dev/null +++ b/website/content/en/docs/Getting Started/v0.2.x/customization.md @@ -0,0 +1,186 @@ +--- +title: "Customization" +linkTitle: "Customization" +weight: 3 +date: 2019-08-05 +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). +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: + +```yaml +apiVersion: jenkins.io/v1alpha2 +kind: Jenkins +metadata: + name: example +spec: + configurationAsCode: + configurations: + - name: jenkins-operator-user-configuration + groovyScripts: + configurations: + - name: jenkins-operator-user-configuration +``` + +Here is an example of `jenkins-operator-user-configuration`: +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: jenkins-operator-user-configuration +data: + 1-configure-theme.groovy: | + 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: | + jenkins: + systemMessage: "Configuration as Code integration works!!!" +``` + +* `*.groovy` is Groovy script configuration +* `*.yaml is` configuration as code + +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 + +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. + +Create a [secret](https://kubernetes.io/docs/concepts/configuration/secret/) with for example the name `jenkins-conf-secrets`. + +```yaml +kind: Secret +apiVersion: v1 +type: Opaque +metadata: + name: jenkins-conf-secrets + namespace: default +data: + SYSTEM_MESSAGE: SGVsbG8gd29ybGQ= +``` + +Then modify the **Jenkins** pod manifest by changing `spec.groovyScripts.secret.name` to `jenkins-conf-secrets`. + +```yaml +apiVersion: jenkins.io/v1alpha2 +kind: Jenkins +metadata: + name: example +spec: + configurationAsCode: + configurations: + - name: jenkins-operator-user-configuration + secret: + name: jenkins-conf-secrets + groovyScripts: + configurations: + - name: jenkins-operator-user-configuration + secret: + name: jenkins-conf-secrets +``` + +Now you can test that the secret is mounted by applying this `ConfigMap` for Groovy script: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: jenkins-operator-user-configuration +data: + 1-system-message.groovy: | + import jenkins.* + import jenkins.model.* + import hudson.* + import hudson.model.* + Jenkins jenkins = Jenkins.getInstance() + + jenkins.setSystemMessage(secrets["SYSTEM_MESSAGE"]) + jenkins.save() +``` + +Or by applying this configuration as code: +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: jenkins-operator-user-configuration +data: + 1-system-message.yaml: | + jenkins: + systemMessage: ${SYSTEM_MESSAGE} +``` + + +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. diff --git a/website/content/en/docs/Getting Started/v0.2.x/deploy-jenkins.md b/website/content/en/docs/Getting Started/v0.2.x/deploy-jenkins.md new file mode 100644 index 00000000..4f7b5a96 --- /dev/null +++ b/website/content/en/docs/Getting Started/v0.2.x/deploy-jenkins.md @@ -0,0 +1,89 @@ +--- +title: "Deploy Jenkins" +linkTitle: "Deploy Jenkins" +weight: 1 +date: 2019-08-05 +description: > + Deploy production ready Jenkins Operator manifest +--- + +Once Jenkins Operator is up and running let's deploy actual Jenkins instance. +Create manifest e.g. **`jenkins_instance.yaml`** with following data and save it on drive. + +```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 a Jenkins to Kubernetes: + +```bash +kubectl create -f jenkins_instance.yaml +``` +Watch the Jenkins instance being created: + +```bash +kubectl get pods -w +``` + +Get the 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 the Jenkins instance (minikube): + +```bash +minikube service jenkins-operator-http- --url +``` + +Connect to the Jenkins instance (actual Kubernetes cluster): + +```bash +kubectl port-forward jenkins- 8080:8080 +``` +Then open browser with address `http://localhost:8080`. +![jenkins](/img/jenkins.png) diff --git a/website/content/en/docs/Getting Started/v0.2.x/diagnostics.md b/website/content/en/docs/Getting Started/v0.2.x/diagnostics.md new file mode 100644 index 00000000..87286adb --- /dev/null +++ b/website/content/en/docs/Getting Started/v0.2.x/diagnostics.md @@ -0,0 +1,42 @@ +--- +title: "Diagnostics" +linkTitle: "Diagnostics" +weight: 40 +date: 2019-08-05 +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/Getting Started/latest/migration.md b/website/content/en/docs/Getting Started/v0.2.x/migration.md similarity index 100% rename from website/content/en/docs/Getting Started/latest/migration.md rename to website/content/en/docs/Getting Started/v0.2.x/migration.md diff --git a/website/content/en/docs/Getting Started/v0.2.x/schema.md b/website/content/en/docs/Getting Started/v0.2.x/schema.md new file mode 100644 index 00000000..008414be --- /dev/null +++ b/website/content/en/docs/Getting Started/v0.2.x/schema.md @@ -0,0 +1,1979 @@ +--- +title: "Schema" +linkTitle: "Schema" +weight: 40 +date: 2019-08-05 +description: > + API Schema definitions for Jenkins CRD +--- + +{{% pageinfo %}} +This document contains API scheme for `jenkins-operator` Custom Resource Definition manifest +{{% /pageinfo %}} + +

    Packages:

    + +

    jenkins.io

    +

    +

    Package v1alpha2 contains the 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 a 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 the Kubernetes service of the Jenkins master HTTP pod +Defaults to : +port: 8080 +type: ClusterIP

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

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

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

    Backup defines the configuration of a 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 the configuration of a Jenkins backup restore +More info: https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-backup-and-restore

    +
    +groovyScripts
    + + +GroovyScripts + + +    		 +(Optional) +

    GroovyScripts defines the configuration of Jenkins customization via groovy scripts

    +
    +configurationAsCode
    + + +ConfigurationAsCode + + +    		 +(Optional) +

    ConfigurationAsCode defines the configuration of Jenkins customization via the Configuration as Code Jenkins plugin

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

    Status defines the observed state of Jenkins

    +
    +

    AppliedGroovyScript +

    +

    +(Appears on: +JenkinsStatus) +

    +

    +

    AppliedGroovyScript is the applied groovy script in Jenkins by the operator

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +configurationType
    + +string + +    		 +

    ConfigurationType is the name of the configuration type(base-groovy, user-groovy, user-casc)

    +
    +source
    + +string + +    		 +

    Source is the name of source where is located groovy script

    +
    +name
    + +string + +    		 +

    Name is the name of the groovy script

    +
    +Hash
    + +string + +    		 +

    Hash is the hash of the groovy script and secrets which it uses

    +
    +

    Backup +

    +

    +(Appears on: +JenkinsSpec) +

    +

    +

    Backup defines the configuration of a Jenkins backup

    +

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

    ContainerName is the container name responsible for backup operation

    +
    +action
    + + +Handler + + +    		 +

    Action defines the action which performs the backup in the backup container sidecar

    +
    +interval
    + +uint64 + +    		 +

    Interval tells you how often the backup is made in seconds +Defaults to 30.

    +
    +makeBackupBeforePodDeletion
    + +bool + +    		 +

    MakeBackupBeforePodDeletion tells the operator to make a backup before Jenkins master pod deletion

    +
    +

    ConfigMapRef +

    +

    +(Appears on: +Customization) +

    +

    +

    ConfigMapRef is the reference to Kubernetes ConfigMap

    +

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

    ConfigurationAsCode +

    +

    +(Appears on: +JenkinsSpec) +

    +

    +

    ConfigurationAsCode defines configuration of Jenkins customization via the Configuration as Code Jenkins plugin

    +

    + + + + + + + + + + + + + +
    FieldDescription
    +Customization
    + + +Customization + + +    		 +
    +

    Container +

    +

    +(Appears on: +JenkinsMaster) +

    +

    +

    Container defines the 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/

    +
    +

    Customization +

    +

    +(Appears on: +ConfigurationAsCode, +GroovyScripts) +

    +

    +

    Customization defines configuration of Jenkins customization

    +

    + + + + + + + + + + + + + + + + + +
    FieldDescription
    +secret
    + + +SecretRef + + +    		 +
    +configurations
    + + +[][]github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.ConfigMapRef + + +    		 +
    +

    GroovyScripts +

    +

    +(Appears on: +JenkinsSpec) +

    +

    +

    GroovyScripts defines configuration of Jenkins customization via groovy scripts

    +

    + + + + + + + + + + + + + +
    FieldDescription
    +Customization
    + + +Customization + + +    		 +
    +

    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 the type of Jenkins credential used in the 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

    +
    +imagePullSecrets
    + + +[]Kubernetes core/v1.LocalObjectReference + + +    		 +(Optional) +

    ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec. +If specified, these secrets will be passed to individual puller implementations for them to use. For example, +in the case of docker, only DockerConfig type secrets are honored. +More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod

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

    +
    +groovyScripts
    + + +GroovyScripts + + +    		 +(Optional) +

    GroovyScripts defines configuration of Jenkins customization via groovy scripts

    +
    +configurationAsCode
    + + +ConfigurationAsCode + + +    		 +(Optional) +

    ConfigurationAsCode defines configuration of Jenkins customization via Configuration as Code Jenkins plugin

    +
    +

    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

    +
    +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 the username and password

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

    CreatedSeedJobs contains list of seed job ids already created in Jenkins

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

    AppliedGroovyScripts is a list with all applied groovy scripts in Jenkins by the operator

    +
    +

    Mailgun +

    +

    +(Appears on: +Notification) +

    +

    +

    Mailgun is handler for Mailgun email service notification channel

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +domain
    + +string + +    		 +
    +apiKeySecretKeySelector
    + + +SecretKeySelector + + +    		 +
    +recipient
    + +string + +    		 +
    +from
    + +string + +    		 +
    +

    MicrosoftTeams +

    +

    +(Appears on: +Notification) +

    +

    +

    MicrosoftTeams is handler for Microsoft MicrosoftTeams notification channel

    +

    + + + + + + + + + + + + + +
    FieldDescription
    +webHookURLSecretKeySelector
    + + +SecretKeySelector + + +    		 +

    The web hook URL to MicrosoftTeams App

    +
    +

    Notification +

    +

    +

    Notification is a service configuration used to send notifications about Jenkins status

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +loggingLevel
    + + +NotificationLogLevel + + +    		 +
    +verbose
    + +bool + +    		 +
    +name
    + +string + +    		 +
    +slack
    + + +github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Slack + + +    		 +
    +teams
    + + +github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.MicrosoftTeams + + +    		 +
    +mailgun
    + + +github.com/jenkinsci/kubernetes-operator/pkg/apis/jenkins/v1alpha2.Mailgun + + +    		 +
    +

    NotificationLogLevel +(string alias)

    +

    +(Appears on: +Notification) +

    +

    +

    NotificationLogLevel defines logging level of Notification

    +

    +

    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

    +
    +

    SecretKeySelector +

    +

    +(Appears on: +Mailgun, +MicrosoftTeams, +Slack) +

    +

    +

    SecretKeySelector selects a key of a Secret.

    +

    + + + + + + + + + + + + + + + + + +
    FieldDescription
    +secret
    + + +Kubernetes core/v1.LocalObjectReference + + +    		 +

    The name of the secret in the pod’s namespace to select from.

    +
    +key
    + +string + +    		 +

    The key of the secret to select from. Must be a valid secret key.

    +
    +

    SecretRef +

    +

    +(Appears on: +Customization) +

    +

    +

    SecretRef is reference to Kubernetes secret

    +

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

    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 the seed job definitions are

    +
    +repositoryBranch
    + +string + +    		 +

    RepositoryBranch is the repository branch where the seed job definitions are

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

    +
    +githubPushTrigger
    + +bool + +    		 +(Optional) +

    GitHubPushTrigger is used for GitHub web hooks

    +
    +buildPeriodically
    + +string + +    		 +(Optional) +

    BuildPeriodically is setting for scheduled trigger

    +
    +pollSCM
    + +string + +    		 +(Optional) +

    PollSCM is setting for polling changes in SCM

    +
    +ignoreMissingFiles
    + +bool + +    		 +(Optional) +

    IgnoreMissingFiles is setting for Job DSL API plugin to ignore files that miss

    +
    +additionalClasspath
    + +string + +    		 +(Optional) +

    AdditionalClasspath is setting for Job DSL API plugin to set Additional Classpath

    +
    +failOnMissingPlugin
    + +bool + +    		 +(Optional) +

    FailOnMissingPlugin is setting for Job DSL API plugin that fails job if required plugin is missing

    +
    +unstableOnDeprecation
    + +bool + +    		 +(Optional) +

    UnstableOnDeprecation is setting for Job DSL API plugin that sets build status as unstable if build using deprecated features

    +
    +

    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 is 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 +the 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.

    +
    +

    Slack +

    +

    +(Appears on: +Notification) +

    +

    +

    Slack is handler for Slack notification channel

    +

    + + + + + + + + + + + + + +
    FieldDescription
    +webHookURLSecretKeySelector
    + + +SecretKeySelector + + +    		 +

    The web hook URL to Slack App

    +
    +
    +

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