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) ProwJobID() string
• 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(pj *kube.ProwJob, buildID string) error
  • func (c *Client) BuildFromSpec(spec *kube.ProwJobSpec, buildID, prowJobID string) error
  • func (c *Client) CrumbRequest() error
  • func (c *Client) Get(path string) ([]byte, error)
  • func (c *Client) GetBuilds(job string) (map[string]Build, error)
  • func (c *Client) GetEnqueuedBuilds(jobs []string) (map[string]Build, error)
  • func (c *Client) GetSkipMetrics(path string) ([]byte, error)
  • func (c *Client) ListBuilds(jobs []string) (map[string]Build, error)
• type ClientMetrics
• type Controller
  • func NewController(kc *kube.Client, jc *Client, ghc *github.Client, logger *logrus.Entry, ...) (*Controller, error)
  • func (c *Controller) RunAfterSuccessCanRun(parent, child *kube.ProwJob, ca configAgent, ghc githubClient) bool
  • func (c *Controller) Sync() error
  • func (c *Controller) SyncMetrics()
• type Metrics
  • func NewMetrics() *Metrics
• type NotFoundError
  • func NewNotFoundError(e error) NotFoundError
  • func (e NotFoundError) Error() string
• type Parameter

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 build identifier used for placing and discovering build artifacts. This identifier can either originate from tot or the snowflake library, depending on how the Jenkins operator is configured to run. We return an empty string if we are dealing with a build that does not have the ProwJobID set explicitly, as in that case the Jenkins build has not started by prow.

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) ProwJobID

func (jb *Build) ProwJobID() string

ProwJobID extracts the ProwJob identifier for the Jenkins build in order to correlate the build with a ProwJob. If the build has an empty PROW_JOB_ID it didn't start by prow.

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(pj *kube.ProwJob, buildID string) error

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

func (*Client) BuildFromSpec

func (c *Client) BuildFromSpec(spec *kube.ProwJobSpec, buildID, prowJobID string) error

BuildFromSpec triggers a Jenkins build for the provided ProwJobSpec. prowJobID 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) 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 []string) (map[string]Build, error)

GetEnqueuedBuilds lists all enqueued builds for the provided jobs.

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) ListBuilds

func (c *Client) ListBuilds(jobs []string) (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 ProwJobs.

func NewController

func NewController(kc *kube.Client, jc *Client, ghc *github.Client, logger *logrus.Entry, ca *config.Agent, totURL, selector string) (*Controller, error)

NewController creates a new Controller from the provided clients.

func (*Controller) RunAfterSuccessCanRun

func (c *Controller) RunAfterSuccessCanRun(parent, child *kube.ProwJob, ca configAgent, ghc githubClient) bool

RunAfterSuccessCanRun returns whether a child job (specified as run_after_success in the prow config) can run once its parent job succeeds. The only case we will not run a child job is when it is a presubmit job and has a run_if_changed regular expression specified which does not match the changed filenames in the pull request the job was meant to run for. TODO: Collapse with plank, impossible to reuse as is due to the interfaces.

func (*Controller) Sync

func (c *Controller) Sync() error

Sync does one sync iteration.

func (*Controller) SyncMetrics

func (c *Controller) SyncMetrics()

SyncMetrics records metrics for the cached prowjobs.

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.