jenkins

Documentation

Overview

Package jenkins includes a client and the operational logic for managing Jenkins masters in prow. It has been used with the following versions of Jenkins:

* 2.60.3 * 2.73.2

It should most likely work for all versions but use at your own risk with a different version.

Index

• type Action
• type AuthConfig
• type BasicAuthConfig
• type BearerTokenAuthConfig
• type Build
  • func (jb *Build) BuildID() string
  • func (jb *Build) IsAborted() bool
  • func (jb *Build) IsEnqueued() bool
  • func (jb *Build) IsFailure() bool
  • func (jb *Build) IsRunning() bool
  • func (jb *Build) IsSuccess() bool
  • func (jb *Build) LighthouseJobID() string
• type BuildQueryParams
• type Client
  • func NewClient(url string, dryRun bool, tlsConfig *tls.Config, authConfig *AuthConfig, ...) (*Client, error)
  • func (c *Client) Abort(job string, build *Build) error
  • func (c *Client) Build(job *v1alpha1.LighthouseJob, buildID string) error
  • func (c *Client) BuildFromSpec(spec *v1alpha1.LighthouseJobSpec, buildID, lighthouseJobID string) error
  • func (c *Client) CrumbRequest() error
  • func (c *Client) EnsureBuildableJob(spec *v1alpha1.LighthouseJobSpec) error
  • func (c *Client) Get(path string) ([]byte, error)
  • func (c *Client) GetBuilds(job string) (map[string]Build, error)
  • func (c *Client) GetEnqueuedBuilds(jobs []BuildQueryParams) (map[string]Build, error)
  • func (c *Client) GetJobInfo(spec *v1alpha1.LighthouseJobSpec) (*JobInfo, error)
  • func (c *Client) GetSkipMetrics(path string) ([]byte, error)
  • func (c *Client) JobParameterized(jobInfo *JobInfo) bool
  • func (c *Client) LaunchBuild(spec *v1alpha1.LighthouseJobSpec, params url.Values) error
  • func (c *Client) ListBuilds(jobs []BuildQueryParams) (map[string]Build, error)
• type ClientMetrics
• type Controller
  • func NewController(lighthouseClient client.LighthouseJobInterface, jenkinsClient *Client, ...) (*Controller, error)
  • func (c *Controller) Sync() error
• type JobInfo
• type JobProperty
• type Metrics
  • func NewMetrics() *Metrics
• type NotFoundError
  • func NewNotFoundError(e error) NotFoundError
  • func (e NotFoundError) Error() string
• type Parameter
• type ParameterDefinition

Types

type Action

type Action struct {
	Parameters []Parameter `json:"parameters"`
}

Action holds a list of parameters

type AuthConfig

type AuthConfig struct {
	// Basic is used for doing basic auth with Jenkins.
	Basic *BasicAuthConfig
	// BearerToken is used for doing oauth-based authentication
	// with Jenkins. Works ootb with the Openshift Jenkins image.
	BearerToken *BearerTokenAuthConfig
	// CSRFProtect ensures the client will acquire a CSRF protection
	// token from Jenkins to use it in mutating requests. Required
	// for masters that prevent cross site request forgery exploits.
	CSRFProtect bool
	// contains filtered or unexported fields
}

AuthConfig configures how we auth with Jenkins. Only one of the fields will be non-nil.

type BasicAuthConfig

type BasicAuthConfig struct {
	User     string
	GetToken func() []byte
}

BasicAuthConfig authenticates with jenkins using user/pass.

type BearerTokenAuthConfig

type BearerTokenAuthConfig struct {
	GetToken func() []byte
}

BearerTokenAuthConfig authenticates jenkins using an oauth bearer token.

type Build

type Build struct {
	Actions []Action `json:"actions"`
	Task    struct {
		// Used for tracking unscheduled builds for jobs.
		Name string `json:"name"`
	} `json:"task"`
	Number int     `json:"number"`
	Result *string `json:"result"`
	// contains filtered or unexported fields
}

Build holds information about an instance of a jenkins job.

func (*Build) BuildID

func (jb *Build) BuildID() string

BuildID extracts the Jenkins build number We return an empty string if we are dealing with a build that does not have the LighthouseJobID set explicitly, as in that case the Jenkins build has not started by Lighthouse.

func (*Build) IsAborted

func (jb *Build) IsAborted() bool

IsAborted means something stopped the job before it could finish.

func (*Build) IsEnqueued

func (jb *Build) IsEnqueued() bool

IsEnqueued means the job has created but has not started.

func (*Build) IsFailure

func (jb *Build) IsFailure() bool

IsFailure means the job completed with problems.

func (*Build) IsRunning

func (jb *Build) IsRunning() bool

IsRunning means the job started but has not finished.

func (*Build) IsSuccess

func (jb *Build) IsSuccess() bool

IsSuccess means the job passed

func (*Build) LighthouseJobID

func (jb *Build) LighthouseJobID() string

LighthouseJobID extracts the LighthouseJob identifier for the Jenkins build in order to correlate the build with a LighthouseJob. If the build has an empty LIGHTHOUSE_JOB_ID it didn't start by Lighthouse.

type BuildQueryParams

type BuildQueryParams struct {
	JobName         string
	LighthouseJobID string
}

BuildQueryParams is used to query Jenkins for running and enqueued builds

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client can interact with jenkins to create/manage builds.

func NewClient

func NewClient(
	url string,
	dryRun bool,
	tlsConfig *tls.Config,
	authConfig *AuthConfig,
	logger *logrus.Entry,
	metrics *ClientMetrics,
) (*Client, error)

NewClient instantiates a client with provided values.

url: the jenkins master to connect to. dryRun: mutating calls such as starting/aborting a build will be skipped. tlsConfig: configures client transport if set, may be nil. authConfig: configures the client to connect to Jenkins via basic auth/bearer token

and optionally enables csrf protection

logger: creates a standard logger if nil. metrics: gathers prometheus metrics for the Jenkins client if set.

func (*Client) Abort

func (c *Client) Abort(job string, build *Build) error

Abort aborts the provided Jenkins build for job.

func (*Client) Build

func (c *Client) Build(job *v1alpha1.LighthouseJob, buildID string) error

Build triggers a Jenkins build for the provided LighthouseJob. The name of the LighthouseJob is going to be used as the Lighthouse Job ID parameter that will help us track the build before it's scheduled by Jenkins.

func (*Client) BuildFromSpec

func (c *Client) BuildFromSpec(spec *v1alpha1.LighthouseJobSpec, buildID, lighthouseJobID string) error

BuildFromSpec triggers a Jenkins build for the provided LighthouseJobSpec. lighthouseJobID helps us track the build before it's scheduled by Jenkins.

func (*Client) CrumbRequest

func (c *Client) CrumbRequest() error

CrumbRequest requests a CSRF protection token from Jenkins to use it in subsequent requests. Required for Jenkins masters that prevent cross site request forgery exploits.

func (*Client) EnsureBuildableJob

func (c *Client) EnsureBuildableJob(spec *v1alpha1.LighthouseJobSpec) error

EnsureBuildableJob attempts to detect a job that hasn't yet ran and populated its parameters. If detected, it tries to run a build until the job parameters are processed, then it aborts the build.

func (*Client) Get

func (c *Client) Get(path string) ([]byte, error)

Get fetches the data found in the provided path. It returns the content of the response or any errors that occurred during the request or http errors.

func (*Client) GetBuilds

func (c *Client) GetBuilds(job string) (map[string]Build, error)

GetBuilds lists all scheduled builds for the provided job. In newer Jenkins versions, this also includes enqueued builds (tested in 2.73.2).

func (*Client) GetEnqueuedBuilds

func (c *Client) GetEnqueuedBuilds(jobs []BuildQueryParams) (map[string]Build, error)

GetEnqueuedBuilds lists all enqueued builds for the provided jobs.

func (*Client) GetJobInfo

func (c *Client) GetJobInfo(spec *v1alpha1.LighthouseJobSpec) (*JobInfo, error)

GetJobInfo retrieves Jenkins job information

func (*Client) GetSkipMetrics

func (c *Client) GetSkipMetrics(path string) ([]byte, error)

GetSkipMetrics fetches the data found in the provided path. It returns the content of the response or any errors that occurred during the request or http errors. Metrics will not be gathered for this request.

func (*Client) JobParameterized

func (c *Client) JobParameterized(jobInfo *JobInfo) bool

JobParameterized tells us if the Jenkins job for this LighthouseJob is parameterized

func (*Client) LaunchBuild

func (c *Client) LaunchBuild(spec *v1alpha1.LighthouseJobSpec, params url.Values) error

LaunchBuild launches a regular or parameterized Jenkins build, depending on whether or not we have `params` to POST

func (*Client) ListBuilds

func (c *Client) ListBuilds(jobs []BuildQueryParams) (map[string]Build, error)

ListBuilds returns a list of all Jenkins builds for the provided jobs (both scheduled and enqueued).

type ClientMetrics

type ClientMetrics struct {
	Requests       *prometheus.CounterVec
	RequestRetries prometheus.Counter
	RequestLatency *prometheus.HistogramVec
}

ClientMetrics is a set of metrics gathered by the Jenkins client.

type Controller

type Controller struct {
	// contains filtered or unexported fields
}

Controller manages LighthouseJobs on a Jenkins server.

func NewController

func NewController(lighthouseClient client.LighthouseJobInterface, jenkinsClient *Client, logger *logrus.Entry, cfg config.Getter, selector string) (*Controller, error)

NewController creates a new Controller from the provided clients.

func (*Controller) Sync

func (c *Controller) Sync() error

Sync does one sync iteration.

type JobInfo

type JobInfo struct {
	Builds    []Build       `json:"builds"`
	LastBuild *Build        `json:"lastBuild,omitempty"`
	Property  []JobProperty `json:"property"`
}

JobInfo holds information about a job from $job/api/json endpoint

type JobProperty

type JobProperty struct {
	Class                string                `json:"_class"`
	ParameterDefinitions []ParameterDefinition `json:"parameterDefinitions,omitempty"`
}

JobProperty is a generic Jenkins job property, but ParameterDefinitions is specific to Build Parameters

type Metrics

type Metrics struct {
	ClientMetrics *ClientMetrics
	ResyncPeriod  prometheus.Histogram
}

Metrics is a set of metrics gathered by the Jenkins operator. It includes client metrics and metrics related to the controller loop.

func NewMetrics

func NewMetrics() *Metrics

NewMetrics creates a new set of metrics for the Jenkins operator.

type NotFoundError

type NotFoundError struct {
	// contains filtered or unexported fields
}

NotFoundError is returned by the Jenkins client when a job does not exist in Jenkins.

func NewNotFoundError

func NewNotFoundError(e error) NotFoundError

NewNotFoundError creates a new NotFoundError.

func (NotFoundError) Error

func (e NotFoundError) Error() string

type Parameter

type Parameter struct {
	Name string `json:"name"`
	// This needs to be an interface so we won't clobber
	// json unmarshaling when the Jenkins job has more
	// parameter types than strings.
	Value interface{} `json:"value"`
}

Parameter configures some aspect of the job.

type ParameterDefinition

type ParameterDefinition struct {
	DefaultParameterValue Parameter `json:"defaultParameterValue,omitempty"`
	Description           string    `json:"description"`
	Name                  string    `json:"name"`
	Type                  string    `json:"type"`
}

ParameterDefinition holds information about a build parameter