engine

package
v2.25.2 Latest Latest
Warning

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

 Go to latest Published: Apr 17, 2021 License: Apache-2.0 Imports: 40 Imported by: 0

Documentation

Overview

Package engine contains the core logic for the Pulumi engine, which includes the following:

- Handle resource management and query operations by configuring and spawning goroutines to run the specified operations asynchronously. - Define events and their associated handlers. - Manage journal entries for resource operations. - Manage plugins, including installation, version handling, and loading.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ConvertLocalPolicyPacksToPaths 

func ConvertLocalPolicyPacksToPaths(localPolicyPack []LocalPolicyPack) []string

ConvertLocalPolicyPacksToPaths is a helper function for converting the list of LocalPolicyPacks to a list of paths.

func GetIndent 

func GetIndent(step StepEventMetadata, seen map[resource.URN]StepEventMetadata) int

GetIndent computes a step's parent indentation.

func GetIndentationString 

func GetIndentationString(indent int) string

func GetResourceOutputsPropertiesString 

func GetResourceOutputsPropertiesString(
	step StepEventMetadata, indent int, planning, debug, refresh, showSames bool) string

GetResourceOutputsPropertiesString prints only those properties that either differ from the input properties or, if there is an old snapshot of the resource, differ from the prior old snapshot's output properties.

func GetResourcePropertiesDetails 

func GetResourcePropertiesDetails(
	step StepEventMetadata, indent int, planning bool, summary bool, debug bool) string

func GetResourcePropertiesSummary 

func GetResourcePropertiesSummary(step StepEventMetadata, indent int) string

func PrintObject 

func PrintObject(
	b *bytes.Buffer, props resource.PropertyMap, planning bool,
	indent int, op deploy.StepOp, prefix bool, debug bool)

func PrintObjectDiff 

func PrintObjectDiff(b *bytes.Buffer, diff resource.ObjectDiff, include []resource.PropertyKey,
	planning bool, indent int, summary bool, debug bool)

func ProjectInfoContext 

func ProjectInfoContext(projinfo *Projinfo, host plugin.Host, config plugin.ConfigSource,
	diag, statusDiag diag.Sink, disableProviderPreview bool,
	tracingSpan opentracing.Span) (string, string, *plugin.Context, error)

ProjectInfoContext returns information about the current project, including its pwd, main, and plugin context.

func Query 

func Query(ctx *Context, q QueryInfo, opts UpdateOptions) result.Result

func RunInstallPlugins 

func RunInstallPlugins(
	proj *workspace.Project, pwd, main string, target *deploy.Target, plugctx *plugin.Context) error

RunInstallPlugins calls installPlugins and just returns the error (avoids having to export pluginSet).

func ShouldRecordReadStep 

func ShouldRecordReadStep(step deploy.Step) bool

Types

type Context 

type Context struct {
	Cancel          *cancel.Context
	Events          chan<- Event
	SnapshotManager SnapshotManager
	BackendClient   deploy.BackendClient
	ParentSpan      opentracing.SpanContext
}

Context provides cancellation, termination, and eventing options for an engine operation. It also provides a way for the engine to persist snapshots, using the `SnapshotManager`.

type DecryptError 

type DecryptError struct {
	Key config.Key // The configuration key whose value couldn't be decrypted
	Err error      // The error that occurred while decrypting
}

DecryptError is the type of errors that arise when the engine can't decrypt a configuration key. The most common reason why this happens is that this key is being decrypted in a stack that's not the same one that encrypted it.

func (DecryptError) Error 

func (d DecryptError) Error() string

type DiagEventPayload 

type DiagEventPayload struct {
	URN       resource.URN
	Prefix    string
	Message   string
	Color     colors.Colorization
	Severity  diag.Severity
	StreamID  int32
	Ephemeral bool
}

DiagEventPayload is the payload for an event with type `diag`

type Event 

type Event struct {
	Type EventType
	// contains filtered or unexported fields
}

Event represents an event generated by the engine during an operation. The underlying type for the `Payload` field will differ depending on the value of the `Type` field

func NewEvent added in v2.7.0 

func NewEvent(typ EventType, payload interface{}) Event

func (Event) Payload 

func (e Event) Payload() interface{}

type EventType 

type EventType string

EventType is the kind of event being emitted. 

const (
	CancelEvent             EventType = "cancel"
	StdoutColorEvent        EventType = "stdoutcolor"
	DiagEvent               EventType = "diag"
	PreludeEvent            EventType = "prelude"
	SummaryEvent            EventType = "summary"
	ResourcePreEvent        EventType = "resource-pre"
	ResourceOutputsEvent    EventType = "resource-outputs"
	ResourceOperationFailed EventType = "resource-operationfailed"
	PolicyViolationEvent    EventType = "policy-violation"
)

type Journal added in v2.12.1 

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

func NewJournal added in v2.12.1 

func NewJournal() *Journal

func (*Journal) BeginMutation added in v2.12.1 

func (j *Journal) BeginMutation(step deploy.Step) (SnapshotMutation, error)

func (*Journal) Close added in v2.12.1 

func (j *Journal) Close() error

func (*Journal) End added in v2.12.1 

func (j *Journal) End(step deploy.Step, success bool) error

func (*Journal) Entries added in v2.12.1 

func (j *Journal) Entries() []JournalEntry

func (*Journal) RecordPlugin added in v2.12.1 

func (j *Journal) RecordPlugin(plugin workspace.PluginInfo) error

func (*Journal) RegisterResourceOutputs added in v2.12.1 

func (j *Journal) RegisterResourceOutputs(step deploy.Step) error

func (*Journal) Snap added in v2.12.1 

func (j *Journal) Snap(base *deploy.Snapshot) *deploy.Snapshot

type JournalEntries added in v2.12.1 

type JournalEntries []JournalEntry

func (JournalEntries) Snap added in v2.12.1 

func (entries JournalEntries) Snap(base *deploy.Snapshot) *deploy.Snapshot

type JournalEntry added in v2.12.1 

type JournalEntry struct {
	Kind JournalEntryKind
	Step deploy.Step
}

type JournalEntryKind added in v2.12.1 

type JournalEntryKind int
const (
	JournalEntryBegin   JournalEntryKind = 0
	JournalEntrySuccess JournalEntryKind = 1
	JournalEntryFailure JournalEntryKind = 2
	JournalEntryOutputs JournalEntryKind = 4
)

type LocalPolicyPack 

type LocalPolicyPack struct {
	// Name provides the user-specified name of the Policy Pack.
	Name string
	// Path of the local Policy Pack.
	Path string
	// Path of the local Policy Pack's JSON config file.
	Config string
}

LocalPolicyPack represents a set of local Policy Packs to apply during an update.

func MakeLocalPolicyPacks 

func MakeLocalPolicyPacks(localPaths []string, configPaths []string) []LocalPolicyPack

MakeLocalPolicyPacks is a helper function for converting the list of local Policy Pack paths to list of LocalPolicyPack. The name of the Local Policy Pack is not set since we must load up the Policy Pack plugin to determine its name.

type PolicyPackInfo 

type PolicyPackInfo struct {
	Proj *workspace.PolicyPackProject
	Root string
}

func (*PolicyPackInfo) GetPwdMain 

func (projinfo *PolicyPackInfo) GetPwdMain() (string, string, error)

GetPwdMain returns the working directory and main entrypoint to use for this package.

type PolicyViolationEventPayload 

type PolicyViolationEventPayload struct {
	ResourceURN       resource.URN
	Message           string
	Color             colors.Colorization
	PolicyName        string
	PolicyPackName    string
	PolicyPackVersion string
	EnforcementLevel  apitype.EnforcementLevel
	Prefix            string
}

PolicyViolationEventPayload is the payload for an event with type `policy-violation`.

type PreludeEventPayload 

type PreludeEventPayload struct {
	IsPreview bool              // true if this prelude is for a plan operation
	Config    map[string]string // the keys and values for config. For encrypted config, the values may be blinded
}

type Projinfo 

type Projinfo struct {
	Proj *workspace.Project
	Root string
}

func (*Projinfo) GetPwdMain 

func (projinfo *Projinfo) GetPwdMain() (string, string, error)

GetPwdMain returns the working directory and main entrypoint to use for this package.

type QueryInfo 

type QueryInfo interface {
	// GetRoot returns the root directory for this update. This defines the scope for any filesystem resources
	// accessed by this update.
	GetRoot() string
	// GetProject returns information about the project associated with this update. This includes information such as
	// the runtime that will be used to execute the Pulumi program and the program's relative working directory.
	GetProject() *workspace.Project
}

QueryInfo handles information common to query operations (list, watch).

type QueryOptions 

type QueryOptions struct {
	Events     eventEmitter // the channel to write events from the engine to.
	Diag       diag.Sink    // the sink to use for diag'ing.
	StatusDiag diag.Sink    // the sink to use for diag'ing status messages.
	// contains filtered or unexported fields
}

type RequiredPolicy 

type RequiredPolicy interface {
	// Name provides the user-specified name of the PolicyPack.
	Name() string
	// Version of the PolicyPack.
	Version() string
	// Install will install the PolicyPack locally, returning the path it was installed to.
	Install(ctx context.Context) (string, error)
	// Config returns the PolicyPack's configuration.
	Config() map[string]*json.RawMessage
}

RequiredPolicy represents a set of policies to apply during an update.

type ResourceChanges 

type ResourceChanges map[deploy.StepOp]int

ResourceChanges contains the aggregate resource changes by operation type.

func Destroy 

func Destroy(u UpdateInfo, ctx *Context, opts UpdateOptions, dryRun bool) (ResourceChanges, result.Result)

func Import added in v2.12.0 

func Import(u UpdateInfo, ctx *Context, opts UpdateOptions, imports []deploy.Import,
	dryRun bool) (ResourceChanges, result.Result)

func Refresh 

func Refresh(u UpdateInfo, ctx *Context, opts UpdateOptions, dryRun bool) (ResourceChanges, result.Result)

func Update 

func Update(u UpdateInfo, ctx *Context, opts UpdateOptions, dryRun bool) (ResourceChanges, result.Result)

func (ResourceChanges) HasChanges 

func (changes ResourceChanges) HasChanges() bool

HasChanges returns true if there are any non-same changes in the resulting summary.

type ResourceOperationFailedPayload 

type ResourceOperationFailedPayload struct {
	Metadata StepEventMetadata
	Status   resource.Status
	Steps    int
}

type ResourceOutputsEventPayload 

type ResourceOutputsEventPayload struct {
	Metadata StepEventMetadata
	Planning bool
	Debug    bool
}

type ResourcePreEventPayload 

type ResourcePreEventPayload struct {
	Metadata StepEventMetadata
	Planning bool
	Debug    bool
}

type SnapshotManager 

type SnapshotManager interface {
	io.Closer

	// BeginMutation signals to the SnapshotManager that the planner intends to mutate the global
	// snapshot. It provides the step that it intends to execute. Based on that step, BeginMutation
	// will record this intent in the global snapshot and return a `SnapshotMutation` that, when ended,
	// will complete the transaction.
	BeginMutation(step deploy.Step) (SnapshotMutation, error)

	// RegisterResourceOutputs registers the set of resource outputs generated by performing the
	// given step. These outputs are persisted in the snapshot.
	RegisterResourceOutputs(step deploy.Step) error
}

SnapshotManager manages an in-memory resource graph.

type SnapshotMutation 

type SnapshotMutation interface {
	// End terminates the transaction and commits the results to the snapshot, returning an error if this
	// failed to complete.
	End(step deploy.Step, successful bool) error
}

SnapshotMutation represents an outstanding mutation that is yet to be completed. When the engine completes a mutation, it must call `End` in order to record the successful completion of the mutation.

type StdoutEventPayload 

type StdoutEventPayload struct {
	Message string
	Color   colors.Colorization
}

type StepEventMetadata 

type StepEventMetadata struct {
	Op           deploy.StepOp                  // the operation performed by this step.
	URN          resource.URN                   // the resource URN (for before and after).
	Type         tokens.Type                    // the type affected by this step.
	Old          *StepEventStateMetadata        // the state of the resource before performing this step.
	New          *StepEventStateMetadata        // the state of the resource after performing this step.
	Res          *StepEventStateMetadata        // the latest state for the resource that is known (worst case, old).
	Keys         []resource.PropertyKey         // the keys causing replacement (only for CreateStep and ReplaceStep).
	Diffs        []resource.PropertyKey         // the keys causing diffs
	DetailedDiff map[string]plugin.PropertyDiff // the rich, structured diff
	Logical      bool                           // true if this step represents a logical operation in the program.
	Provider     string                         // the provider that performed this step.
}

StepEventMetadata contains the metadata associated with a step the engine is performing.

type StepEventStateMetadata 

type StepEventStateMetadata struct {
	// State contains the raw, complete state, for this resource.
	State *resource.State
	// the resource's type.
	Type tokens.Type
	// the resource's object urn, a human-friendly, unique name for the resource.
	URN resource.URN
	// true if the resource is custom, managed by a plugin.
	Custom bool
	// true if this resource is pending deletion due to a replacement.
	Delete bool
	// the resource's unique ID, assigned by the resource provider (or blank if none/uncreated).
	ID resource.ID
	// an optional parent URN that this resource belongs to.
	Parent resource.URN
	// true to "protect" this resource (protected resources cannot be deleted).
	Protect bool
	// the resource's input properties (as specified by the program). Note: because this will cross
	// over rpc boundaries it will be slightly different than the Inputs found in resource_state.
	// Specifically, secrets will have been filtered out, and large values (like assets) will be
	// have a simple hash-based representation.  This allows clients to display this information
	// properly, without worrying about leaking sensitive data, and without having to transmit huge
	// amounts of data.
	Inputs resource.PropertyMap
	// the resource's complete output state (as returned by the resource provider).  See "Inputs"
	// for additional details about how data will be transformed before going into this map.
	Outputs resource.PropertyMap
	// the resource's provider reference
	Provider string
	// InitErrors is the set of errors encountered in the process of initializing resource (i.e.,
	// during create or update).
	InitErrors []string
}

StepEventStateMetadata contains detailed metadata about a resource's state pertaining to a given step.

type SummaryEventPayload 

type SummaryEventPayload struct {
	IsPreview       bool              // true if this summary is for a plan operation
	MaybeCorrupt    bool              // true if one or more resources may be corrupt
	Duration        time.Duration     // the duration of the entire update operation (zero values for previews)
	ResourceChanges ResourceChanges   // count of changed resources, useful for reporting
	PolicyPacks     map[string]string // {policy-pack: version} for each policy pack applied
}

type UpdateInfo 

type UpdateInfo interface {
	// GetRoot returns the root directory for this update. This defines the scope for any filesystem resources
	// accessed by this update.
	GetRoot() string
	// GetProject returns information about the project associated with this update. This includes information such as
	// the runtime that will be used to execute the Pulumi program and the program's relative working directory.
	GetProject() *workspace.Project
	// GetTarget returns information about the target of this update. This includes the name of the stack being
	// updated, the configuration values associated with the target and the target's latest snapshot.
	GetTarget() *deploy.Target
}

UpdateInfo handles information common to resource operations (update, preview, destroy, import, refresh).

type UpdateOptions 

type UpdateOptions struct {
	// LocalPolicyPacks contains an optional set of policy packs to run as part of this deployment.
	LocalPolicyPacks []LocalPolicyPack

	// RequiredPolicies is the set of policies that are required to run as part of the update.
	RequiredPolicies []RequiredPolicy

	// the degree of parallelism for resource operations (<=1 for serial).
	Parallel int

	// true if debugging output it enabled
	Debug bool

	// true if the plan should refresh before executing.
	Refresh bool

	// Specific resources to refresh during a refresh operation.
	RefreshTargets []resource.URN

	// Specific resources to replace during an update operation.
	ReplaceTargets []resource.URN

	// Specific resources to destroy during a destroy operation.
	DestroyTargets []resource.URN

	// Specific resources to update during an update operation.
	UpdateTargets []resource.URN

	// true if we're allowing dependent targets to change, even if not specified in one of the above
	// XXXTargets lists.
	TargetDependents bool

	// true if the engine should use legacy diffing behavior during an update.
	UseLegacyDiff bool

	// true if the engine should disable provider previews.
	DisableProviderPreview bool

	// true if the engine should disable resource reference support.
	DisableResourceReferences bool

	// the plugin host to use for this update
	Host plugin.Host
	// contains filtered or unexported fields
}

UpdateOptions contains all the settings for customizing how an update (deploy, preview, or destroy) is performed.

This structure is embedded in another which uses some of the unexported fields, which trips up the `structcheck` linter. nolint: structcheck

Source Files

View all Source files

Directories

Path Synopsis

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.