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

• Constants
• type Action
• type AuthConfig
• type BasicAuthConfig
• type BearerTokenAuthConfig
• type Client
  • func NewClient(url string, dryRun bool, tlsConfig *tls.Config, authConfig *AuthConfig, ...) (*Client, error)
  • func (c *Client) Abort(job string, build *JenkinsBuild) 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]JenkinsBuild, error)
  • func (c *Client) GetEnqueuedBuilds(jobs []string) (map[string]JenkinsBuild, error)
  • func (c *Client) GetSkipMetrics(path string) ([]byte, error)
  • func (c *Client) ListBuilds(jobs []string) (map[string]JenkinsBuild, 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 JenkinsBuild
  • func (jb *JenkinsBuild) BuildID() string
  • func (jb *JenkinsBuild) IsAborted() bool
  • func (jb *JenkinsBuild) IsEnqueued() bool
  • func (jb *JenkinsBuild) IsFailure() bool
  • func (jb *JenkinsBuild) IsRunning() bool
  • func (jb *JenkinsBuild) IsSuccess() bool
  • func (jb *JenkinsBuild) ProwJobID() string
• type Metrics
  • func NewMetrics() *Metrics
• type NotFoundError
  • func NewNotFoundError(e error) NotFoundError
  • func (e NotFoundError) Error() string
• type Parameter

Constants

const (
	Succeess = "SUCCESS"
	Failure  = "FAILURE"
	Aborted  = "ABORTED"
)

Types

type Action

type Action struct {
	Parameters []Parameter `json:"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
	Token string
}

type BearerTokenAuthConfig

type BearerTokenAuthConfig struct {
	Token string
}

type Client

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

func NewClient

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

func (*Client) Abort

func (c *Client) Abort(job string, build *JenkinsBuild) 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]JenkinsBuild, 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]JenkinsBuild, 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]JenkinsBuild, 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 regural 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 JenkinsBuild

type JenkinsBuild 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
}

func (*JenkinsBuild) BuildID

func (jb *JenkinsBuild) 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 (*JenkinsBuild) IsAborted

func (jb *JenkinsBuild) IsAborted() bool

func (*JenkinsBuild) IsEnqueued

func (jb *JenkinsBuild) IsEnqueued() bool

func (*JenkinsBuild) IsFailure

func (jb *JenkinsBuild) IsFailure() bool

func (*JenkinsBuild) IsRunning

func (jb *JenkinsBuild) IsRunning() bool

func (*JenkinsBuild) IsSuccess

func (jb *JenkinsBuild) IsSuccess() bool

func (*JenkinsBuild) ProwJobID

func (jb *JenkinsBuild) 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 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"`
}