Add Jenkins scheme doc

This commit is contained in:
Tomasz Sęk 2019-06-19 18:00:30 +02:00
parent 0af2235603
commit be4d6b471d
No known key found for this signature in database
GPG Key ID: DC356D23F6A644D0
9 changed files with 1794 additions and 87 deletions

1
.gitignore vendored
View File

@ -1,6 +1,7 @@
.idea
vendor
deploy/namespace-init.yaml
/gen-crd-api-reference-docs
# Temporary Build Files
build/_output

View File

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

View File

@ -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
@ -55,3 +56,4 @@ This project was originally developed by [VirtusLab](https://virtuslab.com/) and
[how_it_works]:docs/how-it-works.md
[security]:docs/security.md
[developer_guide]:docs/developer-guide.md
[jenkins_scheme]:docs/jenkins-v1alpha2-scheme.md

View File

@ -9,3 +9,4 @@ MINIKUBE_KUBERNETES_VERSION=v1.12.9
MINIKUBE_DRIVER=virtualbox
ENVIRONMENT=minikube
ALL_IN_ONE_DEPLOY_FILE_PREFIX=all-in-one
GEN_CRD_API=gen-crd-api-reference-docs

View File

@ -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 <namesapce> create -f pvc.yaml
```
def decorator = Jenkins.instance.getDescriptorByType(org.codefirst.SimpleThemeDecorator.class)
#### Configure Jenkins CR
List<ThemeElement> 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

File diff suppressed because it is too large Load Diff

View File

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

24
gen-crd-api-config.json Normal file
View File

@ -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
}

View File

@ -5,38 +5,131 @@ 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 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 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"`
Resources corev1.ResourceRequirements `json:"resources,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"`
ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy,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"`
}
@ -47,44 +140,186 @@ 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 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"`
// 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 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 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 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"`
}
@ -110,15 +345,30 @@ const (
// Build defines Jenkins Build status with corresponding metadata
type Build struct {
// 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 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 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 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 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"`
}