config

README

Jenkins Configuration Controller

Features

• Reload Jenkins configuration automatically
• Easily switch Jenkins configuration between pre-defined and custom
• Smoothly upgrade Jenkins configuration
• Jenkins configuration management in GitOps way (TODO)

Background

Configuration as Code is the crucial part of Jenkins configuration. Users need to modify the YAML file (in CasC format) if they want to change Jenkins configuration.

Since CasC v1.51, it only support loading config files from a local file or URL. So, Jenkins cannot loads the config file from Kubernetes (e.g. ConfigMap). Our solution is that mount a ConfigMap into the Jenkins Pod.

kubelet can reload a ConfigMap into a Pod automatically once it detects changes from ConfigMaps. But it's not real time. This controller will let Jenkins try to reload the YAML config file.

It's easy to install Jenkins helm chart for once. But you might meet other issues when you try to upgrade it. Helm will overwrite all ConfigMaps when you try to upgrade a chart.

Design

This is an example of ConfigMap for Jenkins configuration:

apiVersion: v1
kind: ConfigMap
data:
  jenkins.yaml: |
    xxx: xxx

1. Make sure the new config file exists
   1. Copy jenkins.yaml 'root-key' into jenkins_user.yaml if data jenkins_user.yaml not exists
   2. The jenkins.securityRealm and unclassified in jenkins.yaml only support update in extension-configurations and copy them into jenkins_user.yaml
   3. Copy jenkins.clouds.kubernetes in jenkins.yaml into jenkins_user.yaml if not exists, and only update them in jenkins_user.yaml
2. Make sure the annotation devops.kubesphere.io/jenkins-config-formula: xxx exists
   1. Set the value of this annotation as custom if it's invalid (support values: low, high, custom)
   2. Add annotation devops.kubesphere.io/jenkins-config-customized: "true" if it's custom
3. Provide the pre-defined configuration according to the formula name(don't make sure pre-defined work in 4.x)
   1. Skip this process if the formula is custom (or invalid)
   2. Take jenkins.yaml as a template to transform the configuration
4. Reload CasC via Jenkins API
   1. Change the config file to jenkins_user.yaml

An example of target ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  annotations:
    devops.kubesphere.io/ks-jenkins-config: ks-jenkins.yaml
    devops.kubesphere.io/jenkins-config-formula: custom
    devops.kubesphere.io/jenkins-config-customized: "true"
data:
  jenkins.yaml: |
    xxx: xxx
  jenkins_user.yaml: |
    xxx: xxx

How-to

Users should only modify the configuration from jenkins_user.yaml, and make sure the annotation has an expected value devops.kubesphere.io/jenkins-config-formula: custom.

Documentation

Index

• Constants
• type AgentLabelsReconciler
  • func (r *AgentLabelsReconciler) GetGroupName() string
  • func (r *AgentLabelsReconciler) GetName() string
  • func (r *AgentLabelsReconciler) Reconcile(ctx context.Context, req ctrl.Request) (result ctrl.Result, err error)
  • func (r *AgentLabelsReconciler) SetupWithManager(mgr ctrl.Manager) error
• type Controller
  • func NewController(options *ControllerOptions, devopsOptions *jenkins.Options) *Controller
  • func (c *Controller) Start(ctx context.Context) error
• type ControllerOptions
• type PodTemplateReconciler
  • func (r *PodTemplateReconciler) GetGroupName() string
  • func (r *PodTemplateReconciler) GetName() string
  • func (r *PodTemplateReconciler) Reconcile(ctx context.Context, req ctrl.Request) (result ctrl.Result, err error)
  • func (r *PodTemplateReconciler) SetupWithManager(mgr ctrl.Manager) error
• type ResourceLimit

Constants

const (
	// ANNOJenkinsConfigFormula represents the formula name
	ANNOJenkinsConfigFormula = "devops.kubesphere.io/jenkins-config-formula"
	// ANNOJenkinsConfigCustomized indicates if the formula was customized
	ANNOJenkinsConfigCustomized = "devops.kubesphere.io/jenkins-config-customized"
)

const (
	// FormulaCustom is a formula name - custom
	FormulaCustom = "custom"
	// FormulaHigh is a formula name - high
	FormulaHigh = "high"
	// FormulaLow is a formula name - low
	FormulaLow = "low"
)

Types

type AgentLabelsReconciler

type AgentLabelsReconciler struct {
	// TargetNamespace indicate which namespace the target ConfigMap located in
	TargetNamespace string
	JenkinsClient   core.Client

	client.Client
	// contains filtered or unexported fields
}

AgentLabelsReconciler responsible for the Jenkins agent labels sync

func (*AgentLabelsReconciler) GetGroupName

func (r *AgentLabelsReconciler) GetGroupName() string

GetGroupName returns the group name of this reconciler

func (*AgentLabelsReconciler) GetName

func (r *AgentLabelsReconciler) GetName() string

GetName returns the name of this reconciler

func (*AgentLabelsReconciler) Reconcile

func (r *AgentLabelsReconciler) Reconcile(ctx context.Context, req ctrl.Request) (result ctrl.Result, err error)

Reconcile makes sure the target ConfigMap has all the Jenkins agent labels

func (*AgentLabelsReconciler) SetupWithManager

func (r *AgentLabelsReconciler) SetupWithManager(mgr ctrl.Manager) error

SetupWithManager setups the all necessary fields

type Controller

type Controller struct {
	ReloadCasCDelay time.Duration
	// contains filtered or unexported fields
}

Controller is used to maintain the state of the jenkins-casc-config ConfigMap.

func NewController

func NewController(
	options *ControllerOptions,
	devopsOptions *jenkins.Options,
) *Controller

NewController creates a new JenkinsConfigController

func (*Controller) Start

func (c *Controller) Start(ctx context.Context) error

Start implements for Runnable interface.

type ControllerOptions

type ControllerOptions struct {
	LimitRangeClient    typed.LimitRangesGetter
	ResourceQuotaClient typed.ResourceQuotasGetter
	ConfigMapClient     typed.ConfigMapsGetter

	ConfigMapInformer informer.ConfigMapInformer
	NamespaceInformer informer.NamespaceInformer

	InformerFactory informers.InformerFactory
	ConfigOperator  devops.ConfigurationOperator

	ReloadCasCDelay time.Duration
}

ControllerOptions is the option of Jenkins configuration controller

type PodTemplateReconciler

type PodTemplateReconciler struct {
	LabelSelector            string
	TargetConfigMapName      string
	TargetConfigMapNamespace string
	TargetConfigMapKey       string
	Interval                 time.Duration

	client.Client
	// contains filtered or unexported fields
}

PodTemplateReconciler responsible for the Jenkins podTemplate sync

func (*PodTemplateReconciler) GetGroupName

func (r *PodTemplateReconciler) GetGroupName() string

GetGroupName ret

func (*PodTemplateReconciler) GetName

func (r *PodTemplateReconciler) GetName() string

GetName returns the name of this reconcile

func (*PodTemplateReconciler) Reconcile

func (r *PodTemplateReconciler) Reconcile(ctx context.Context, req ctrl.Request) (result ctrl.Result, err error)

Reconcile is the entrypoint of this reconciler

func (*PodTemplateReconciler) SetupWithManager

func (r *PodTemplateReconciler) SetupWithManager(mgr ctrl.Manager) error

SetupWithManager setups the reconciler

type ResourceLimit

type ResourceLimit string

ResourceLimit describes the limitation level of jenkins agent pod resource