From be4d6b471d8af96f9a3223bf5378a2a728c91999 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20S=C4=99k?= Date: Wed, 19 Jun 2019 18:00:30 +0200 Subject: [PATCH] Add Jenkins scheme doc --- .gitignore | 1 + Makefile | 18 +- README.md | 4 +- config.env | 3 +- docs/getting-started.md | 16 +- docs/jenkins-v1alpha2-scheme.md | 1386 +++++++++++++++++ docs/migration-guide-v1alphav1-to-v1alpha2.md | 2 +- gen-crd-api-config.json | 24 + pkg/apis/jenkins/v1alpha2/jenkins_types.go | 427 ++++- 9 files changed, 1794 insertions(+), 87 deletions(-) create mode 100644 docs/jenkins-v1alpha2-scheme.md create mode 100644 gen-crd-api-config.json diff --git a/.gitignore b/.gitignore index caed9d11..e4e6b6be 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ .idea vendor deploy/namespace-init.yaml +/gen-crd-api-reference-docs # Temporary Build Files build/_output diff --git a/Makefile b/Makefile index 50589197..e8bed9d0 100644 --- a/Makefile +++ b/Makefile @@ -312,7 +312,7 @@ docker-run: ## Run the container in docker, you can use EXTRA_ARGS .PHONY: minikube-run minikube-run: export WATCH_NAMESPACE = $(NAMESPACE) minikube-run: export OPERATOR_NAME = $(NAME) -minikube-run: start-minikube ## Run the operator locally and use minikube as Kubernetes cluster, you can use EXTRA_ARGS +minikube-run: minikube-start ## Run the operator locally and use minikube as Kubernetes cluster, you can use EXTRA_ARGS @echo "+ $@" kubectl config use-context minikube kubectl apply -f deploy/crds/jenkins_v1alpha2_jenkins_crd.yaml @@ -324,8 +324,20 @@ deepcopy-gen: ## Generate deepcopy golang code @echo "+ $@" operator-sdk generate k8s -.PHONY: start-minikube -start-minikube: ## Start minikube +.PHONY: scheme-doc-gen +HAS_GEN_CRD_API_REFERENCE_DOCS := $(shell ls gen-crd-api-reference-docs) +scheme-doc-gen: ## Generate Jenkins CRD scheme doc + @echo "+ $@" +ifndef HAS_GEN_CRD_API_REFERENCE_DOCS + @wget https://github.com/ahmetb/$(GEN_CRD_API)/releases/download/v0.1.2/$(GEN_CRD_API)_linux_amd64.tar.gz + @mkdir -p $(GEN_CRD_API) + @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 + +.PHONY: minikube-start +minikube-start: ## Start minikube @echo "+ $@" @minikube status && exit 0 || \ minikube start --kubernetes-version $(MINIKUBE_KUBERNETES_VERSION) --vm-driver=$(MINIKUBE_DRIVER) --memory 4096 --cpus 3 diff --git a/README.md b/README.md index e69493e5..806864ef 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ Some of the problems we want to solve: 3. [How it works][how_it_works] 4. [Security][security] 5. [Developer Guide][developer_guide] +5. [Jenkins scheme][jenkins_scheme] ## Contribution @@ -54,4 +55,5 @@ This project was originally developed by [VirtusLab](https://virtuslab.com/) and [getting_started]:docs/getting-started.md [how_it_works]:docs/how-it-works.md [security]:docs/security.md -[developer_guide]:docs/developer-guide.md \ No newline at end of file +[developer_guide]:docs/developer-guide.md +[jenkins_scheme]:docs/jenkins-v1alpha2-scheme.md \ No newline at end of file diff --git a/config.env b/config.env index 274d34e8..f042d356 100644 --- a/config.env +++ b/config.env @@ -8,4 +8,5 @@ API_VERSION=v1alpha2 MINIKUBE_KUBERNETES_VERSION=v1.12.9 MINIKUBE_DRIVER=virtualbox ENVIRONMENT=minikube -ALL_IN_ONE_DEPLOY_FILE_PREFIX=all-in-one \ No newline at end of file +ALL_IN_ONE_DEPLOY_FILE_PREFIX=all-in-one +GEN_CRD_API=gen-crd-api-reference-docs \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md index 0bf5ba2e..022fabdb 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -280,10 +280,7 @@ spec: and create Kubernetes Secret(name of secret should be the same from `credentialID` field): -#### Create PVC - -Save to file pvc.yaml: -```yaml +``` apiVersion: v1 kind: Secret metadata: @@ -332,12 +329,13 @@ data: Jenkins jenkins = Jenkins.getInstance() -Run command: -```bash -$ kubectl -n create -f pvc.yaml -``` + def decorator = Jenkins.instance.getDescriptorByType(org.codefirst.SimpleThemeDecorator.class) -#### Configure Jenkins CR + 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 diff --git a/docs/jenkins-v1alpha2-scheme.md b/docs/jenkins-v1alpha2-scheme.md new file mode 100644 index 00000000..26c82943 --- /dev/null +++ b/docs/jenkins-v1alpha2-scheme.md @@ -0,0 +1,1386 @@ +

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/

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

+
+

Plugin +

+

+(Appears on: +JenkinsMaster) +

+

+

Plugin defines Jenkins plugin

+

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

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

diff --git a/docs/migration-guide-v1alphav1-to-v1alpha2.md b/docs/migration-guide-v1alphav1-to-v1alpha2.md index 66400e3e..6b70f3df 100644 --- a/docs/migration-guide-v1alphav1-to-v1alpha2.md +++ b/docs/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 [pkg/apis/jenkins/v1alpha2/jenkins_types.go](https://github.com/jenkinsci/kubernetes-operator/blob/master/pkg/apis/jenkins/v1alpha2/jenkins_types.go) +Code that defines the data structures can be found [here](jenkins-v1alpha2-scheme.md) ### Examples diff --git a/gen-crd-api-config.json b/gen-crd-api-config.json new file mode 100644 index 00000000..c2b2fb99 --- /dev/null +++ b/gen-crd-api-config.json @@ -0,0 +1,24 @@ +{ + "hideMemberFields": [ + "TypeMeta" + ], + "hideTypePatterns": [ + "ParseError$", + "List$" + ], + "externalPackages": [ + { + "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$", + "docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration" + }, + { + "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/", + "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}" + } + ], + "typeDisplayNamePrefixOverrides": { + "k8s.io/api/": "Kubernetes ", + "k8s.io/apimachinery/pkg/apis/": "Kubernetes " + }, + "markdownDisabled": false +} diff --git a/pkg/apis/jenkins/v1alpha2/jenkins_types.go b/pkg/apis/jenkins/v1alpha2/jenkins_types.go index 9c5bd055..a428c1f5 100644 --- a/pkg/apis/jenkins/v1alpha2/jenkins_types.go +++ b/pkg/apis/jenkins/v1alpha2/jenkins_types.go @@ -5,39 +5,132 @@ import ( metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" ) -// EDIT THIS FILE! THIS IS SCAFFOLDING FOR YOU TO OWN! -// NOTE: json tags are required. Any new fields you add must have json tags for the fields to be serialized. - -// JenkinsSpec defines the desired state of Jenkins +// JenkinsSpec defines the desired state of the Jenkins // +k8s:openapi-gen=true type JenkinsSpec struct { - // INSERT ADDITIONAL SPEC FIELDS - desired state of cluster - // Important: Run "operator-sdk generate k8s" to regenerate code after modifying this file - Master JenkinsMaster `json:"master,omitempty"` - SeedJobs []SeedJob `json:"seedJobs,omitempty"` - Service Service `json:"service,omitempty"` - SlaveService Service `json:"slaveService,omitempty"` - Backup Backup `json:"backup,omitempty"` - Restore Restore `json:"restore,omitempty"` + // Master represents Jenkins master pod properties and Jenkins plugins. + // Every single change here requires a pod restart. + Master JenkinsMaster `json:"master,omitempty"` + + // 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 + // +optional + SeedJobs []SeedJob `json:"seedJobs,omitempty"` + + // Service is Kubernetes service of Jenkins master HTTP pod + // Defaults to : + // port: 8080 + // type: ClusterIP + // +optional + Service Service `json:"service,omitempty"` + + // Service is Kubernetes service of Jenkins slave pods + // Defaults to : + // port: 50000 + // type: ClusterIP + // +optional + SlaveService Service `json:"slaveService,omitempty"` + + // Backup defines configuration of Jenkins backup + // More info: https://github.com/jenkinsci/kubernetes-operator/blob/master/docs/getting-started.md#configure-backup-and-restore + // +optional + Backup Backup `json:"backup,omitempty"` + + // 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 + // +optional + Restore Restore `json:"restore,omitempty"` } // Container defines Kubernetes container attributes type Container struct { - Name string `json:"name"` - Image string `json:"image"` - Command []string `json:"command,omitempty"` - Args []string `json:"args,omitempty"` - WorkingDir string `json:"workingDir,omitempty"` - Ports []corev1.ContainerPort `json:"ports,omitempty"` - EnvFrom []corev1.EnvFromSource `json:"envFrom,omitempty"` - Env []corev1.EnvVar `json:"env,omitempty"` - Resources corev1.ResourceRequirements `json:"resources,omitempty"` - VolumeMounts []corev1.VolumeMount `json:"volumeMounts,omitempty"` - LivenessProbe *corev1.Probe `json:"livenessProbe,omitempty"` - ReadinessProbe *corev1.Probe `json:"readinessProbe,omitempty"` - Lifecycle *corev1.Lifecycle `json:"lifecycle,omitempty"` - ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy,omitempty"` - SecurityContext *corev1.SecurityContext `json:"securityContext,omitempty"` + // Name of the container specified as a DNS_LABEL. + // Each container in a pod must have a unique name (DNS_LABEL). + Name string `json:"name"` + + // Docker image name. + // More info: https://kubernetes.io/docs/concepts/containers/images + Image string `json:"image"` + + // Image pull policy. + // One of Always, Never, IfNotPresent. + // Defaults to Always. + ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy"` + + // Compute Resources required by this container. + // More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ + Resources corev1.ResourceRequirements `json:"resources"` + + // 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 + // +optional + Command []string `json:"command,omitempty"` + + // 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 + // +optional + Args []string `json:"args,omitempty"` + + // Container's working directory. + // If not specified, the container runtime's default will be used, which + // might be configured in the container image. + // +optional + WorkingDir string `json:"workingDir,omitempty"` + + // 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. + // +optional + Ports []corev1.ContainerPort `json:"ports,omitempty"` + + // 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. + // +optional + EnvFrom []corev1.EnvFromSource `json:"envFrom,omitempty"` + + // List of environment variables to set in the container. + // +optional + Env []corev1.EnvVar `json:"env,omitempty"` + + // Pod volumes to mount into the container's filesystem. + // +optional + VolumeMounts []corev1.VolumeMount `json:"volumeMounts,omitempty"` + + // Periodic probe of container liveness. + // Container will be restarted if the probe fails. + // +optional + LivenessProbe *corev1.Probe `json:"livenessProbe,omitempty"` + + // Periodic probe of container service readiness. + // Container will be removed from service endpoints if the probe fails. + // +optional + ReadinessProbe *corev1.Probe `json:"readinessProbe,omitempty"` + + // Actions that the management system should take in response to container lifecycle events. + // +optional + Lifecycle *corev1.Lifecycle `json:"lifecycle,omitempty"` + + // 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/ + // +optional + SecurityContext *corev1.SecurityContext `json:"securityContext,omitempty"` } // Plugin defines Jenkins plugin @@ -47,45 +140,187 @@ type Plugin struct { } // JenkinsMaster defines the Jenkins master pod attributes and plugins, -// every single change requires Jenkins master pod restart +// every single change requires a Jenkins master pod restart type JenkinsMaster struct { - // pod properties - Annotations map[string]string `json:"masterAnnotations,omitempty"` + // 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 + // +optional + Annotations map[string]string `json:"masterAnnotations,omitempty"` + + // 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/ + // +optional NodeSelector map[string]string `json:"nodeSelector,omitempty"` - Containers []Container `json:"containers,omitempty"` - Volumes []corev1.Volume `json:"volumes,omitempty"` + + // 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 + Containers []Container `json:"containers,omitempty"` + + // List of volumes that can be mounted by containers belonging to the pod. + // More info: https://kubernetes.io/docs/concepts/storage/volumes + // +optional + Volumes []corev1.Volume `json:"volumes,omitempty"` // 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 BasePlugins []Plugin `json:"basePlugins,omitempty"` + // Plugins contains plugins required by user + // +optional Plugins []Plugin `json:"plugins,omitempty"` } -// Service defines Kubernetes service attributes which Operator will manage +// Service defines Kubernetes service attributes type Service struct { - Annotations map[string]string `json:"annotations,omitempty"` - Labels map[string]string `json:"labels,omitempty"` - Type corev1.ServiceType `json:"type,omitempty"` - Port int32 `json:"port,omitempty"` - NodePort int32 `json:"nodePort,omitempty"` - LoadBalancerSourceRanges []string `json:"loadBalancerSourceRanges,omitempty"` - LoadBalancerIP string `json:"loadBalancerIP,omitempty"` + // 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 + // +optional + Annotations map[string]string `json:"annotations,omitempty"` + + // 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/ + Labels map[string]string `json:"labels,omitempty"` + + // 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 + // +optional + Type corev1.ServiceType `json:"type,omitempty"` + + // The port that are exposed by this service. + // More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies + Port int32 `json:"port,omitempty"` + + // 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 + // +optional + NodePort int32 `json:"nodePort,omitempty"` + + // 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/ + // +optional + LoadBalancerSourceRanges []string `json:"loadBalancerSourceRanges,omitempty"` + + // 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. + // +optional + LoadBalancerIP string `json:"loadBalancerIP,omitempty"` } // JenkinsStatus defines the observed state of Jenkins // +k8s:openapi-gen=true type JenkinsStatus struct { - // INSERT ADDITIONAL STATUS FIELD - define observed state of cluster - // Important: Run "operator-sdk generate k8s" to regenerate code after modifying this file - OperatorVersion string `json:"operatorVersion,omitempty"` - ProvisionStartTime *metav1.Time `json:"provisionStartTime,omitempty"` + // OperatorVersion is the operator version which manages this CR + // +optional + OperatorVersion string `json:"operatorVersion,omitempty"` + + // ProvisionStartTime is a time when Jenkins master pod has been created + // +optional + ProvisionStartTime *metav1.Time `json:"provisionStartTime,omitempty"` + + // BaseConfigurationCompletedTime is a time when Jenkins base configuration phase has been completed + // +optional BaseConfigurationCompletedTime *metav1.Time `json:"baseConfigurationCompletedTime,omitempty"` + + // UserConfigurationCompletedTime is a time when Jenkins user configuration phase has been completed + // +optional UserConfigurationCompletedTime *metav1.Time `json:"userConfigurationCompletedTime,omitempty"` - Builds []Build `json:"builds,omitempty"` - RestoredBackup uint64 `json:"restoredBackup,omitempty"` - LastBackup uint64 `json:"lastBackup,omitempty"` - PendingBackup uint64 `json:"pendingBackup,omitempty"` - BackupDoneBeforePodDeletion bool `json:"backupDoneBeforePodDeletion,omitempty"` + + // Builds contains Jenkins builds statues + // +optional + Builds []Build `json:"builds,omitempty"` + + // RestoredBackup is the restored backup number after Jenkins master pod restart + // +optional + RestoredBackup uint64 `json:"restoredBackup,omitempty"` + + // LastBackup is the latest backup number + // +optional + LastBackup uint64 `json:"lastBackup,omitempty"` + + // PendingBackup is the pending backup number + // +optional + PendingBackup uint64 `json:"pendingBackup,omitempty"` + + // BackupDoneBeforePodDeletion tells if backup before pod deletion has been made + // +optional + BackupDoneBeforePodDeletion bool `json:"backupDoneBeforePodDeletion,omitempty"` } // BuildStatus defines type of Jenkins build job status @@ -110,15 +345,30 @@ const ( // Build defines Jenkins Build status with corresponding metadata type Build struct { - JobName string `json:"jobName,omitempty"` - Hash string `json:"hash,omitempty"` - Number int64 `json:"number,omitempty"` - Status BuildStatus `json:"status,omitempty"` - Retires int `json:"retries,omitempty"` - CreateTime *metav1.Time `json:"createTime,omitempty"` + + // JobName is the Jenkins job name + JobName string `json:"jobName,omitempty"` + + // Hash is the unique data identifier used in build + Hash string `json:"hash,omitempty"` + + // Number is the Jenkins build number + Number int64 `json:"number,omitempty"` + + // Status is the status of Jenkins build + Status BuildStatus `json:"status,omitempty"` + + // Retires is the amount of Jenkins job build retries + Retires int `json:"retries,omitempty"` + + // CreateTime is the time when the first build has been created + CreateTime *metav1.Time `json:"createTime,omitempty"` + + // LastUpdateTime is the last update status time LastUpdateTime *metav1.Time `json:"lastUpdateTime,omitempty"` } +// +genclient // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object // Jenkins is the Schema for the jenkins API @@ -128,7 +378,10 @@ type Jenkins struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec JenkinsSpec `json:"spec,omitempty"` + // Spec defines the desired state of the Jenkins + Spec JenkinsSpec `json:"spec,omitempty"` + + // Status defines the observed state of Jenkins Status JenkinsStatus `json:"status,omitempty"` } @@ -141,7 +394,7 @@ type JenkinsList struct { Items []Jenkins `json:"items"` } -// JenkinsCredentialType defines type of Jenkins credential used to seed job mechanisms +// JenkinsCredentialType defines type of Jenkins credential used to seed job mechanism type JenkinsCredentialType string const ( @@ -160,14 +413,30 @@ var AllowedJenkinsCredentialMap = map[string]string{ string(UsernamePasswordCredentialType): "", } -// SeedJob defines configuration for seed jobs and deploy keys +// 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 type SeedJob struct { - ID string `json:"id,omitempty"` - CredentialID string `json:"credentialID,omitempty"` - Description string `json:"description,omitempty"` - Targets string `json:"targets,omitempty"` - RepositoryBranch string `json:"repositoryBranch,omitempty"` - RepositoryURL string `json:"repositoryUrl,omitempty"` + // ID is the unique seed job name + ID string `json:"id,omitempty"` + + // CredentialID is the Kubernetes secret name which stores repository access credentials + CredentialID string `json:"credentialID,omitempty"` + + // Description is the description of the seed job + // +optional + Description string `json:"description,omitempty"` + + // Targets is the repository path where are seed job definitions + Targets string `json:"targets,omitempty"` + + // RepositoryBranch is the repository branch where are seed job definitions + RepositoryBranch string `json:"repositoryBranch,omitempty"` + + // RepositoryURL is the repository access URL. Can be SSH or HTTPS. + RepositoryURL string `json:"repositoryUrl,omitempty"` + + // JenkinsCredentialType is the https://jenkinsci.github.io/kubernetes-credentials-provider-plugin/ credential type + // +optional JenkinsCredentialType JenkinsCredentialType `json:"credentialType,omitempty"` } @@ -179,15 +448,29 @@ type Handler struct { // Backup defines configuration of Jenkins backup type Backup struct { - ContainerName string `json:"containerName"` - Action Handler `json:"action"` - Interval uint64 `json:"interval"` - MakeBackupBeforePodDeletion bool `json:"makeBackupBeforePodDeletion"` + // ContainerName is the container name responsible for backup operation + ContainerName string `json:"containerName"` + + // Action defines action which performs backup in backup container sidecar + Action Handler `json:"action"` + + // Interval tells how often make backup in seconds + // Defaults to 30. + Interval uint64 `json:"interval"` + + // MakeBackupBeforePodDeletion tells operator to make backup before Jenkins master pod deletion + MakeBackupBeforePodDeletion bool `json:"makeBackupBeforePodDeletion"` } -// Restore defines configuration of Jenkins backup restore +// Restore defines configuration of Jenkins backup restore operation type Restore struct { - ContainerName string `json:"containerName"` - Action Handler `json:"action"` - RecoveryOnce uint64 `json:"recoveryOnce,omitempty"` + // ContainerName is the container name responsible for restore backup operation + ContainerName string `json:"containerName"` + + // Action defines action which performs restore backup in restore container sidecar + Action Handler `json:"action"` + + // RecoveryOnce if want to restore specific backup set this field and then Jenkins will be restarted and desired backup will be restored + // +optional + RecoveryOnce uint64 `json:"recoveryOnce,omitempty"` }