build

Documentation

Overview

Package build implements the logic for executing a single user build.

Index

• Constants
• Variables
• type ArtifactsInfo
• type Build
  • func New(r runner.Runner, b pb.Build, ts oauth2.TokenSource, bl Logger, ...) *Build
  • func (b *Build) FailBuild(err error)
  • func (b *Build) GetStatus() FullStatus
  • func (b *Build) LastStateStart() time.Time
  • func (b *Build) SetDockerAccessToken(ctx context.Context, tok string) error
  • func (b *Build) Start(ctx context.Context)
  • func (b *Build) Summary() BuildSummary
  • func (b *Build) Times() map[BuildStatus]time.Duration
  • func (b *Build) UpdateDockerAccessToken(ctx context.Context, tok string) error
  • func (b *Build) UpdateStatus(status BuildStatus)
• type BuildStatus
• type BuildSummary
• type BuiltImage
• type EventLogger
• type FullStatus
• type Hash
• type HashType
• type Logger
• type TimeSpan
• type TimingInfo

Constants

const StartStep = "-"

StartStep is a build step WaitFor dependency that is always satisfied.

Variables

var (

	// RunRm : if true, all `docker run` commands will be passed a `--rm` flag.
	RunRm = false
)

Types

type ArtifactsInfo

type ArtifactsInfo struct {
	ArtifactManifest string
	NumArtifacts     int64
}

ArtifactsInfo holds information about uploaded artifacts.

type Build

type Build struct {
	Request          pb.Build
	HasMultipleSteps bool
	TokenSource      oauth2.TokenSource
	Log              Logger
	EventLogger      EventLogger

	Runner runner.Runner
	Done   chan struct{}

	// PushErrors tracks how many times a push got retried. This
	// field is not protected by a mutex because the worker will
	// only read it once the build is done, and the build only
	// updates it before the build is done.
	PushErrors     int
	GCRErrors      map[string]int64
	NumSourceBytes int64

	// timing holds timing information for build execution phases.
	Timing TimingInfo
	// contains filtered or unexported fields
}

Build manages a single build.

func New

func New(r runner.Runner, b pb.Build, ts oauth2.TokenSource,
	bl Logger, eventLogger EventLogger, hostWorkspaceDir string, fs afero.Fs, local, push, dryrun bool) *Build

New constructs a new Build.

func (*Build) FailBuild

func (b *Build) FailBuild(err error)

FailBuild updates the build's status to failure.

func (*Build) GetStatus

func (b *Build) GetStatus() FullStatus

GetStatus returns the build's status in a thread-safe way.

func (*Build) LastStateStart

func (b *Build) LastStateStart() time.Time

LastStateStart returns start time of most recent state transition.

func (*Build) SetDockerAccessToken

func (b *Build) SetDockerAccessToken(ctx context.Context, tok string) error

SetDockerAccessToken sets the initial Docker config with the credentials we use to authorize requests to GCR. https://cloud.google.com/container-registry/docs/advanced-authentication#using_an_access_token

func (*Build) Start

func (b *Build) Start(ctx context.Context)

Start executes a single build.

func (*Build) Summary

func (b *Build) Summary() BuildSummary

Summary returns the build's summary in a thread-safe way.

func (*Build) Times

func (b *Build) Times() map[BuildStatus]time.Duration

Times returns build timings in a thread-safe way.

func (*Build) UpdateDockerAccessToken

func (b *Build) UpdateDockerAccessToken(ctx context.Context, tok string) error

UpdateDockerAccessToken updates the credentials we use to authorize requests to GCR. https://cloud.google.com/container-registry/docs/advanced-authentication#using_an_access_token

func (*Build) UpdateStatus

func (b *Build) UpdateStatus(status BuildStatus)

UpdateStatus updates the current status.

type BuildStatus

type BuildStatus string

BuildStatus is a pseudo-enum of valid build states.

const (
	// StatusNotStarted - Default status for newly-created builds until they begin.
	StatusNotStarted = ""
	// StatusFetchSource - Fetching source.
	StatusFetchSource BuildStatus = "FETCHSOURCE"
	// StatusBuild - Executing the build step images on the source.
	StatusBuild BuildStatus = "BUILD"
	// StatusPush - Pushing the resultant image to GCR.
	StatusPush BuildStatus = "PUSH"
	// StatusDone - Build completed successfully.
	StatusDone BuildStatus = "DONE"
	// StatusStepTimeout - A build step has timed out.
	StatusStepTimeout BuildStatus = "STEP_TIMEOUT"
	// StatusError - Build failed.
	StatusError BuildStatus = "ERROR"
	// StatusTimeout - Build timed out.
	StatusTimeout BuildStatus = "TIMEOUT"
	// StatusCancelled - Build was cancelled.
	StatusCancelled BuildStatus = "CANCELLED"
)

type BuildSummary

type BuildSummary struct {
	Status          BuildStatus
	StepStatus      []pb.Build_Status
	BuiltImages     []BuiltImage
	BuildStepImages []string // index of build step -> digest, else empty string
	FileHashes      map[string][]Hash
	Timing          TimingInfo
	Artifacts       ArtifactsInfo
}

BuildSummary is the data returned by the blocking /build/summary endpoint.

type BuiltImage

type BuiltImage struct {
	// Name is the full name of an image, as given to 'docker pull $NAME'.
	Name string
	// Digest is the digest reported by registry2.0, if available. If not
	// available, it will be the empty string.
	Digest string
}

BuiltImage is information about an image that resulted from this build and was pushed to an image registry.

type EventLogger

type EventLogger interface {
	StartStep(ctx context.Context, stepIdx int, startTime time.Time) error
	FinishStep(ctx context.Context, stepIdx int, success bool, endTime time.Time) error
}

EventLogger encapsulates logging events about build steps starting/finishing.

type FullStatus

type FullStatus struct {
	// BuildStatus is the overall build status.
	BuildStatus BuildStatus

	// StepStatus is the status of each individual build step; StepStatus is
	// listed in the same order as the build steps in the build request.
	StepStatus []pb.Build_Status
}

FullStatus contains detailed status of the build, including status of each build step.

type Hash

type Hash struct {
	// Type of the hash.
	Type HashType
	// Value of the hash.
	Value []byte
}

Hash captures a hash by HashType and Value.

type HashType

type HashType string

HashType is a pseudo-enum of valid SourceHashes.

const (
	// MD5 indicates hash type md5.
	MD5 HashType = "MD5"
	// SHA256 indicates hash type sha256.
	SHA256 HashType = "SHA256"
	// No hash requested.
	NONE HashType = "NONE"
)

These constants match those in pb cloudbuild.proto pb.Hash.HashType.

type Logger

type Logger interface {
	WriteMainEntry(msg string)
	Close() error
	MakeWriter(prefix string, stepIdx int, stdout bool) io.Writer
}

Logger encapsulates logging build output.

type TimeSpan

type TimeSpan struct {
	Start time.Time
	End   time.Time
}

TimeSpan holds the start and end time for a build execution phase.

type TimingInfo

type TimingInfo struct {
	BuildSteps      []*TimeSpan
	BuildTotal      *TimeSpan
	ImagePushes     map[string]*TimeSpan
	PushTotal       *TimeSpan // total time to push images and non-container artifacts
	SourceTotal     *TimeSpan
	ArtifactsPushes *TimeSpan // time to push all non-container artifacts
}

TimingInfo holds timing information for build execution phases.