run

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 27, 2023 License: MPL-2.0 Imports: 38 Imported by: 0

Documentation

Overview

Package run is responsible for OTF runs, the primary mechanism for executing terraform

Index

Constants

View Source
const (
	PlanFormatBinary = "bin"  // plan file in binary format
	PlanFormatJSON   = "json" // plan file in json format

	// When specified in place of a configuration version ID passed to
	// RunCreateOptions this magic string instructs the run factory to
	// automatically create a configuration version from the workspace connected
	// vcs repo.
	PullVCSMagicString = "__pull_vcs__"

	PlanOnlyOperation     Operation = "plan-only"
	PlanAndApplyOperation Operation = "plan-and-apply"
	DestroyAllOperation   Operation = "destroy-all"
)
View Source
const ReporterLockID int64 = 179366396344335597

ReporterLockID is a unique ID guaranteeing only one reporter on a cluster is running at any time.

Variables

View Source
var ErrInvalidRunStateTransition = errors.New("invalid run state transition")

Functions

func CompilePlanReports added in v0.0.51

func CompilePlanReports(planJSON []byte) (resources Report, outputs Report, err error)

CompilePlanReports compiles reports of planned changes from a JSON representation of a plan file: one report for planned *resources*, and another for planned *outputs*.

func NewService

func NewService(opts Options) *service

Types

type Change

type Change struct {
	Actions []ChangeAction
}

Change represents the type of change being made

type ChangeAction

type ChangeAction string
const (
	CreateAction ChangeAction = "create"
	UpdateAction ChangeAction = "update"
	DeleteAction ChangeAction = "delete"
)

type Client

type Client struct {
	internal.JSONAPIClient
	http.Config
}

func (*Client) FinishPhase

func (c *Client) FinishPhase(ctx context.Context, id string, phase internal.PhaseType, opts PhaseFinishOptions) (*Run, error)

func (*Client) GetLockFile

func (c *Client) GetLockFile(ctx context.Context, runID string) ([]byte, error)

func (*Client) GetPlanFile

func (c *Client) GetPlanFile(ctx context.Context, runID string, format PlanFormat) ([]byte, error)

func (*Client) GetRun

func (c *Client) GetRun(ctx context.Context, runID string) (*Run, error)

func (*Client) ListRuns

func (c *Client) ListRuns(ctx context.Context, opts RunListOptions) (*resource.Page[*Run], error)

func (*Client) StartPhase

func (c *Client) StartPhase(ctx context.Context, id string, phase internal.PhaseType, opts PhaseStartOptions) (*Run, error)

func (*Client) UploadLockFile

func (c *Client) UploadLockFile(ctx context.Context, runID string, lockfile []byte) error

func (*Client) UploadPlanFile

func (c *Client) UploadPlanFile(ctx context.Context, runID string, plan []byte, format PlanFormat) error

func (*Client) Watch

func (c *Client) Watch(ctx context.Context, opts WatchOptions) (<-chan pubsub.Event, error)

Watch returns a channel subscribed to run events.

type ConfigurationVersionService

type ConfigurationVersionService configversion.Service

type Operation

type Operation string

Run operation specifies the terraform execution mode.

type Phase

type Phase struct {
	RunID              string `json:"run_id"`
	internal.PhaseType `json:"phase"`
	Status             PhaseStatus            `json:"status"`
	StatusTimestamps   []PhaseStatusTimestamp `json:"status_timestamps"`

	// report of planned or applied resource changes
	ResourceReport *Report `json:"resource_report"`
	// report of planned or applied output changes
	OutputReport *Report `json:"output_report"`
}

Phase is a section of work performed by a run.

func NewPhase

func NewPhase(runID string, t internal.PhaseType) Phase

NewPhase constructs a new phase. A new phase always starts in pending status.

func (*Phase) HasChanges

func (p *Phase) HasChanges() bool

func (*Phase) StatusTimestamp

func (p *Phase) StatusTimestamp(status PhaseStatus) (time.Time, error)

StatusTimestamp looks up the timestamp for a status

func (*Phase) UpdateStatus

func (p *Phase) UpdateStatus(status PhaseStatus)

type PhaseFinishOptions

type PhaseFinishOptions struct {
	Type string `jsonapi:"primary,phase"`
	// Errored is true if the phase finished unsuccessfully.
	Errored bool `jsonapi:"attribute" json:"errored,omitempty"`
}

PhaseFinishOptions report the status of a phase upon finishing.

type PhaseStartOptions

type PhaseStartOptions struct {
	Type    string `jsonapi:"primary,phase"`
	AgentID string `jsonapi:"attribute" json:"agent-id,omitempty"`
}

type PhaseStatus

type PhaseStatus string
const (
	PhasePending     PhaseStatus = "pending"
	PhaseQueued      PhaseStatus = "queued"
	PhaseRunning     PhaseStatus = "running"
	PhaseFinished    PhaseStatus = "finished"
	PhaseCanceled    PhaseStatus = "canceled"
	PhaseErrored     PhaseStatus = "errored"
	PhaseUnreachable PhaseStatus = "unreachable"
)

func (PhaseStatus) String

func (s PhaseStatus) String() string

type PhaseStatusTimestamp

type PhaseStatusTimestamp struct {
	Status    PhaseStatus `json:"status"`
	Timestamp time.Time   `json:"timestamp"`
}

type PlanFile

type PlanFile struct {
	ResourceChanges []ResourceChange  `json:"resource_changes"`
	OutputChanges   map[string]Change `json:"output_changes"`
}

PlanFile represents the schema of a plan file

func (*PlanFile) Summarize added in v0.0.51

func (pf *PlanFile) Summarize() (resource, output Report)

Summarize provides a tally of the types of changes proposed in the plan file.

type PlanFileOptions

type PlanFileOptions struct {
	Format PlanFormat `schema:"format,required"`
}

PlanFileOptions are options for the plan file API

type PlanFormat

type PlanFormat string

type Report added in v0.0.51

type Report struct {
	Additions    int `json:"additions"`
	Changes      int `json:"changes"`
	Destructions int `json:"destructions"`
}

Report reports a summary of additions, changes, and deletions of resources in a plan or an apply.

func ParseApplyOutput

func ParseApplyOutput(output string) (Report, error)

func (Report) HasChanges added in v0.0.51

func (r Report) HasChanges() bool

func (Report) String added in v0.0.51

func (r Report) String() string

type Reporter

Reporter reports back to VCS providers the current status of VCS-triggered runs.

func (*Reporter) Start

func (r *Reporter) Start(ctx context.Context) error

Start starts the reporter daemon. Should be invoked in a go routine.

type ReporterOptions

type ReporterOptions struct {
	ConfigurationVersionService configversion.Service
	WorkspaceService            workspace.Service
	VCSProviderService          VCSProviderService

	logr.Logger
}

type ResourceChange

type ResourceChange struct {
	Change Change
}

ResourceChange represents a proposed change to a resource in a plan file

type Run

type Run struct {
	ID                     string                  `json:"id"`
	CreatedAt              time.Time               `json:"created_at"`
	IsDestroy              bool                    `json:"is_destroy"`
	ForceCancelAvailableAt *time.Time              `json:"force_cancel_available_at"`
	Message                string                  `json:"message"`
	Organization           string                  `json:"organization"`
	Refresh                bool                    `json:"refresh"`
	RefreshOnly            bool                    `json:"refresh_only"`
	ReplaceAddrs           []string                `json:"replace_addrs"`
	PositionInQueue        int                     `json:"position_in_queue"`
	TargetAddrs            []string                `json:"target_addrs"`
	AutoApply              bool                    `json:"auto_apply"`
	PlanOnly               bool                    `json:"plan_only"`
	Status                 internal.RunStatus      `json:"status"`
	StatusTimestamps       []RunStatusTimestamp    `json:"status_timestamps"`
	WorkspaceID            string                  `json:"workspace_id"`
	ConfigurationVersionID string                  `json:"configuration_version_id"`
	ExecutionMode          workspace.ExecutionMode `json:"execution_mode"`
	Plan                   Phase                   `json:"plan"`
	Apply                  Phase                   `json:"apply"`

	Latest bool    `json:"latest"` // is latest run for workspace
	Commit *string `json:"commit"` // commit sha that triggered this run
}

Run is a terraform run.

func UnmarshalJSONAPI

func UnmarshalJSONAPI(b []byte) (*Run, error)

func (*Run) CanAccessOrganization

func (r *Run) CanAccessOrganization(action rbac.Action, name string) bool

func (*Run) CanAccessSite

func (*Run) CanAccessSite(action rbac.Action) bool

func (*Run) CanAccessWorkspace

func (r *Run) CanAccessWorkspace(action rbac.Action, policy *internal.WorkspacePolicy) bool

func (*Run) Cancel

func (r *Run) Cancel() error

Cancel run. Returns a boolean indicating whether a cancel request should be enqueued (for an agent to kill an in progress process)

func (*Run) Cancelable

func (r *Run) Cancelable() bool

Cancelable determines whether run can be cancelled.

func (*Run) Confirmable

func (r *Run) Confirmable() bool

Confirmable determines whether run can be confirmed.

func (*Run) Discard

func (r *Run) Discard() error

Discard updates the state of a run to reflect it having been discarded.

func (*Run) Discardable

func (r *Run) Discardable() bool

Discardable determines whether run can be discarded.

func (*Run) Done

func (r *Run) Done() bool

Done determines whether run has reached an end state, e.g. applied, discarded, etc.

func (*Run) EnqueueApply

func (r *Run) EnqueueApply() error

func (*Run) EnqueuePlan

func (r *Run) EnqueuePlan() error

EnqueuePlan enqueues a plan for the run. It also sets the run as the latest run for its workspace (speculative runs are ignored).

func (*Run) Finish

func (r *Run) Finish(phase internal.PhaseType, opts PhaseFinishOptions) error

Finish updates the run to reflect its plan or apply phase having finished.

func (*Run) ForceCancel

func (r *Run) ForceCancel() error

ForceCancel force cancels a run. A cool-off period of 10 seconds must have elapsed following a cancelation request before a run can be force canceled.

func (*Run) HasApply

func (r *Run) HasApply() bool

HasApply determines whether the run has started applying yet.

func (*Run) HasChanges

func (r *Run) HasChanges() bool

func (*Run) Phase

func (r *Run) Phase() internal.PhaseType

Phase returns the current phase.

func (*Run) Queued

func (r *Run) Queued() bool

func (*Run) Start

func (r *Run) Start(phase internal.PhaseType) error

Start a run phase

func (*Run) StatusTimestamp

func (r *Run) StatusTimestamp(status internal.RunStatus) (time.Time, error)

type RunCreateOptions

type RunCreateOptions struct {
	IsDestroy   *bool
	Refresh     *bool
	RefreshOnly *bool
	Message     *string
	// Specifies the configuration version to use for this run. If the
	// configuration version object is omitted, the run will be created using the
	// workspace's latest configuration version.
	//
	// Alternatively, if PullVCSMagicString is specified, and the workspace
	// is connected to a vcs repo, then a configuration version is
	// automatically created from the vcs repo and the run uses that
	// configuration version. If the workspace is not connected to a
	// workspace then an error is returned.
	ConfigurationVersionID *string
	TargetAddrs            []string
	ReplaceAddrs           []string
	AutoApply              *bool
	// PlanOnly specifies if this is a speculative, plan-only run that
	// Terraform cannot apply. Takes precedence over whether the
	// configuration version is marked as speculative or not.
	PlanOnly *bool
}

RunCreateOptions represents the options for creating a new run. See api/types/RunCreateOptions for documentation on each field.

type RunList

type RunList struct {
	*resource.Pagination
	Items []*Run
}

RunList represents a list of runs.

type RunListOptions

type RunListOptions struct {
	resource.PageOptions
	// Filter by run statuses (with an implicit OR condition)
	Statuses []internal.RunStatus `schema:"statuses,omitempty"`
	// Filter by workspace ID
	WorkspaceID *string `schema:"workspace_id,omitempty"`
	// Filter by organization name
	Organization *string `schema:"organization_name,omitempty"`
	// Filter by workspace name
	WorkspaceName *string `schema:"workspace_name,omitempty"`
	// Filter by plan-only runs
	PlanOnly *bool `schema:"-"`
	// A list of relations to include. See available resources:
	// https://www.terraform.io/docs/cloud/api/run.html#available-related-resources
	Include *string `schema:"include,omitempty"`
}

RunListOptions are options for paginating and filtering a list of runs

type RunService

type RunService = Service

Alias services so they don't conflict when nested together in struct

type RunStatusTimestamp

type RunStatusTimestamp struct {
	Status    internal.RunStatus
	Timestamp time.Time
}

type Service

type Service interface {
	CreateRun(ctx context.Context, workspaceID string, opts RunCreateOptions) (*Run, error)
	GetRun(ctx context.Context, id string) (*Run, error)
	ListRuns(ctx context.Context, opts RunListOptions) (*resource.Page[*Run], error)
	EnqueuePlan(ctx context.Context, runID string) (*Run, error)
	// StartPhase starts a run phase.
	StartPhase(ctx context.Context, runID string, phase internal.PhaseType, _ PhaseStartOptions) (*Run, error)
	// FinishPhase finishes a phase. Creates a report of changes before updating the status of
	// the run.
	FinishPhase(ctx context.Context, runID string, phase internal.PhaseType, opts PhaseFinishOptions) (*Run, error)
	// GetPlanFile returns the plan file for the run.
	GetPlanFile(ctx context.Context, runID string, format PlanFormat) ([]byte, error)
	// UploadPlanFile persists a run's plan file. The plan format should be either
	// be binary or json.
	UploadPlanFile(ctx context.Context, runID string, plan []byte, format PlanFormat) error
	// Watch provides access to a stream of run events. The WatchOptions filters
	// events. Context must be cancelled to close stream.
	//
	// TODO(@leg100): it would be clearer to the caller if the stream is closed by
	// returning a stream object with a Close() method. The calling code would
	// call Watch(), and then defer a Close(), which is more readable IMO.
	Watch(ctx context.Context, opts WatchOptions) (<-chan pubsub.Event, error)
	// Cancel a run. If a run is in progress then a cancelation signal will be
	// sent out.
	Cancel(ctx context.Context, runID string) (*Run, error)
	// Apply enqueues an Apply for the run.
	Apply(ctx context.Context, runID string) error
	// Delete a run.
	Delete(ctx context.Context, runID string) error

	// RetryRun retries a run, creating a new run with the same config
	// version.
	RetryRun(ctx context.Context, id string) (*Run, error)

	// DiscardRun discards a run. Run must be in the planned state.
	DiscardRun(ctx context.Context, runID string) error
	// ForceCancelRun forcefully cancels a run.
	ForceCancelRun(ctx context.Context, runID string) error

	internal.Authorizer // run authorizer
	// contains filtered or unexported methods
}

type Spawner

Spawner spawns new runs in response to vcs events

func (*Spawner) Start

func (s *Spawner) Start(ctx context.Context) error

Start the run spawner.

type VCSProviderService

type VCSProviderService vcsprovider.Service

type WatchOptions

type WatchOptions struct {
	Organization *string `schema:"organization_name,omitempty"` // filter by organization name
	WorkspaceID  *string `schema:"workspace_id,omitempty"`      // filter by workspace ID; mutually exclusive with organization filter
}

WatchOptions filters events returned by the Watch endpoint.

type WorkspaceService

type WorkspaceService workspace.Service

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL