run

package
v0.0.47 Latest Latest
Warning

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

 Go to latest Published: Jun 25, 2023 License: MPL-2.0 Imports: 37 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")
View Source 
var ErrPhaseAlreadyStarted = errors.New("phase already started")

Functions

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) (*RunList, 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 Options 

type Options struct {
	WorkspaceAuthorizer internal.Authorizer

	WorkspaceService
	ConfigurationVersionService
	VCSProviderService

	logr.Logger
	internal.Cache
	internal.DB
	html.Renderer
	*pubsub.Broker
}

type Phase 

type Phase struct {
	RunID string `json:"run_id"`

	internal.PhaseType `json:"phase"`
	*ResourceReport    `json:"report"` // report of planned or applied resource changes

	Status           PhaseStatus            `json:"status"` // current phase status
	StatusTimestamps []PhaseStatusTimestamp `json:"status_timestamps"`
}

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"`
}

PlanFile represents the schema of a plan file

func (*PlanFile) Changes 

func (pf *PlanFile) Changes() (tally ResourceReport)

Changes 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 Reporter 

type Reporter struct {
	logr.Logger
	pubsub.Subscriber
	VCSProviderService
	ConfigurationVersionService
	WorkspaceService
	internal.HostnameService
}

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
	internal.DB
}

type ResourceChange 

type ResourceChange struct {
	Change Change
}

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

type ResourceReport 

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

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

func CompilePlanReport 

func CompilePlanReport(planJSON []byte) (ResourceReport, error)

CompilePlanReport compiles a report of planned changes from a JSON representation of a plan file.

func ParseApplyOutput 

func ParseApplyOutput(output string) (ResourceReport, error)

func (ResourceReport) HasChanges 

func (r ResourceReport) HasChanges() bool

func (ResourceReport) String 

func (r ResourceReport) String() string

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() (enqueue bool, err 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 {
	*internal.Pagination
	Items []*Run
}

RunList represents a list of runs.

type RunListOptions 

type RunListOptions struct {
	internal.ListOptions
	// 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) (*RunList, 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 

type Spawner struct {
	logr.Logger

	ConfigurationVersionService
	WorkspaceService
	VCSProviderService
	RunService
	pubsub.Subscriber
}

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.