backend

package
v3.113.2 Latest Latest
Warning

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

 Go to latest Published: Apr 19, 2024 License: Apache-2.0 Imports: 43 Imported by: 4

Documentation

Overview

Package backend defines several core interfaces and logic common across pluggable backends. This package also contains the SnapshotManager, which is an implementation of the engine.SnapshotManager interface.

Index

Constants

View Source 
const (
	// GitHead is the commit hash of HEAD.
	GitHead = "git.head"
	// GitHeadName is the name of the HEAD ref. e.g. "refs/heads/master" or "refs/tags/v1.0.0".
	GitHeadName = "git.headName"
	// GitDirty ("true", "false") indicates if there are any unstaged or modified files in the local repo.
	GitDirty = "git.dirty"

	// GitCommitter is the name of the person who committed the commit at HEAD.
	GitCommitter = "git.committer"
	// GitCommitterEmail is the Email address associated with the committer.
	GitCommitterEmail = "git.committer.email"
	// GitAuthor is the name of the person who authored the commit at HEAD.
	GitAuthor = "git.author"
	// GitAuthorEmail is the email address associated with the commit's author.
	GitAuthorEmail = "git.author.email"

	// VCSRepoOwner is the user who owns the local repo, if the origin remote is a cloud host.
	VCSRepoOwner = "vcs.owner"
	// VCSRepoName is the name of the repo, if the local git repo's remote origin is a cloud host.
	VCSRepoName = "vcs.repo"
	// VCSRepoKind is the cloud host where the repo is hosted.
	VCSRepoKind = "vcs.kind"
	// VCSRepoRoot is the root directory of the project in the repo.
	VCSRepoRoot = "vcs.root"

	// CISystem is the name of the CI system running the pulumi operation.
	CISystem = "ci.system"
	// CIBuildID is an opaque ID of the build in the CI system.
	CIBuildID = "ci.build.id"
	// CIBuildNumber is a sequentially incrementing number specific for a project/repo.
	// This value is only set for CI systems that have separate Build ID and a Build Number.
	// If this value is blank, use `CIBuildID` always.
	CIBuildNumer = "ci.build.number"
	// CIBuildType is the type of build of the CI system, e.g. "push", "pull_request", "test_only".
	CIBuildType = "ci.build.type"
	// CIBuildURL is a URL to get more information about the particular CI build.
	CIBuildURL = "ci.build.url"

	// CIPRHeadSHA is the SHA of the HEAD commit of a pull request running on CI. This is needed since the CI
	// server will run at a different, merge commit. (headSHA merged into the target branch.)
	CIPRHeadSHA = "ci.pr.headSHA"
	// CIPRNumber is the PR number, for which the current CI job may be executing.
	// Combining this information with the `VCSRepoKind` will give us the PR URL.
	CIPRNumber = "ci.pr.number"

	// ExecutionKind indicates how the update was executed. One of "cli", "auto.local", or "auto.inline".
	ExecutionKind = "exec.kind"
	// ExecutionAgent indicates the user agent of the updater for automated scenarios (GHA, Kubernetes Operator).
	ExecutionAgent = "exec.agent"

	// UpdatePlan ("true", "false") indicates if an explicit update plan was used for the update (either
	// saving one, or constraining to one).
	UpdatePlan = "updatePlan"

	// StackEnvironments indicates the list of ESC environments imported by the stack being updated.
	StackEnvironments = "stack.environments"
)

Keys we use for values put into UpdateInfo.Environment.

Variables

View Source 
var CancellationScopes = CancellationScopeSource(cancellationScopeSource(0))
View Source 
var DisableIntegrityChecking bool

DisableIntegrityChecking can be set to true to disable checkpoint state integrity verification. This is not recommended, because it could mean proceeding even in the face of a corrupted checkpoint state file, but can be used as a last resort when a command absolutely must be run.

View Source 
var ErrNoPreviousDeployment = errors.New("no previous deployment")

ErrNoPreviousDeployment is returned when there isn't a previous deployment.

View Source 
var ErrTeamsNotSupported = errors.New("teams are not supported")

ErrTeamsNotSupported is returned by backends which do not support the teams feature.

Functions

func ActionLabel 

func ActionLabel(kind apitype.UpdateKind, dryRun bool) string

func DestroyStack 

func DestroyStack(ctx context.Context, s Stack, op UpdateOperation) (display.ResourceChanges, result.Result)

DestroyStack destroys all of this stack's resources.

func ExportStackDeployment 

func ExportStackDeployment(
	ctx context.Context,
	s Stack,
) (*apitype.UntypedDeployment, error)

ExportStackDeployment exports the given stack's deployment as an opaque JSON message.

func GetEnvironmentTagsForCurrentStack 

func GetEnvironmentTagsForCurrentStack(root string,
	project *workspace.Project, cfg config.Map,
) (map[apitype.StackTagName]string, error)

GetEnvironmentTagsForCurrentStack returns the set of tags for the "current" stack, based on the environment and Pulumi.yaml file.

func GetLatestConfiguration 

func GetLatestConfiguration(ctx context.Context, s Stack) (config.Map, error)

GetLatestConfiguration returns the configuration for the most recent deployment of the stack.

func GetMergedStackTags 

func GetMergedStackTags(ctx context.Context, s Stack,
	root string, project *workspace.Project, cfg config.Map,
) (map[apitype.StackTagName]string, error)

GetMergedStackTags returns the stack's existing tags merged with fresh tags from the environment and Pulumi.yaml file.

func GetStackLogs 

func GetStackLogs(ctx context.Context, secretsProvider secrets.Provider, s Stack, cfg StackConfiguration,
	query operations.LogQuery,
) ([]operations.LogEntry, error)

GetStackLogs fetches a list of log entries for the current stack in the current backend.

func ImportStack 

func ImportStack(ctx context.Context, s Stack, op UpdateOperation,
	imports []deploy.Import,
) (display.ResourceChanges, result.Result)

ImportStack updates the target stack with the current workspace's contents (config and code).

func ImportStackDeployment 

func ImportStackDeployment(ctx context.Context, s Stack, deployment *apitype.UntypedDeployment) error

ImportStackDeployment imports the given deployment into the indicated stack.

func NewBackendClient 

func NewBackendClient(backend Backend, secretsProvider secrets.Provider) deploy.BackendClient

NewBackendClient returns a deploy.BackendClient that wraps the given Backend.

func PreviewStack 

func PreviewStack(
	ctx context.Context,
	s Stack,
	op UpdateOperation,
	events chan<- engine.Event,
) (*deploy.Plan, display.ResourceChanges, result.Result)

PreviewStack previews changes to this stack.

func PreviewThenPrompt 

func PreviewThenPrompt(ctx context.Context, kind apitype.UpdateKind, stack Stack,
	op UpdateOperation, apply Applier,
) (*deploy.Plan, sdkDisplay.ResourceChanges, result.Result)

func PreviewThenPromptThenExecute 

func PreviewThenPromptThenExecute(ctx context.Context, kind apitype.UpdateKind, stack Stack,
	op UpdateOperation, apply Applier,
) (sdkDisplay.ResourceChanges, result.Result)

func RefreshStack 

func RefreshStack(ctx context.Context, s Stack, op UpdateOperation) (display.ResourceChanges, result.Result)

RefreshStack refresh's the stack's state from the cloud provider.

func RemoveStack 

func RemoveStack(ctx context.Context, s Stack, force bool) (bool, error)

RemoveStack returns the stack, or returns an error if it cannot.

func RunQuery 

func RunQuery(ctx context.Context, b Backend, op QueryOperation,
	callerEventsOpt chan<- engine.Event, newQuery MakeQuery,
) error

RunQuery executes a query program against the resource outputs of a diy hosted stack.

func UpdateStack 

func UpdateStack(ctx context.Context, s Stack, op UpdateOperation) (display.ResourceChanges, result.Result)

UpdateStack updates the target stack with the current workspace's contents (config and code).

func UpdateStackTags 

func UpdateStackTags(ctx context.Context, s Stack, tags map[apitype.StackTagName]string) error

UpdateStackTags updates the stacks's tags, replacing all existing tags.

func Watch 

func Watch(ctx context.Context, b Backend, stack Stack, op UpdateOperation,
	apply Applier, paths []string,
) result.Result

Watch watches the project's working directory for changes and automatically updates the active stack.

func WatchStack 

func WatchStack(ctx context.Context, s Stack, op UpdateOperation, paths []string) result.Result

WatchStack watches the projects working directory for changes and automatically updates the active stack.

Types

type Applier 

type Applier func(ctx context.Context, kind apitype.UpdateKind, stack Stack, op UpdateOperation,
	opts ApplierOptions, events chan<- engine.Event) (*deploy.Plan, sdkDisplay.ResourceChanges, result.Result)

Applier applies the changes specified by this update operation against the target stack.

type ApplierOptions 

type ApplierOptions struct {
	// DryRun indicates if the update should not change any resource state and instead just preview changes.
	DryRun bool
	// ShowLink indicates if a link to the update persisted result can be displayed.
	ShowLink bool
}

ApplierOptions is a bag of configuration settings for an Applier.

type Backend 

type Backend interface {
	// Name returns a friendly name for this backend.
	Name() string
	// URL returns a URL at which information about this backend may be seen.
	URL() string

	// SetCurrentProject sets the current ambient project for this backend.
	SetCurrentProject(proj *workspace.Project)

	// GetPolicyPack returns a PolicyPack object tied to this backend, or nil if it cannot be found.
	GetPolicyPack(ctx context.Context, policyPack string, d diag.Sink) (PolicyPack, error)

	// ListPolicyGroups returns all Policy Groups for an organization in this backend or an error if it cannot be found.
	ListPolicyGroups(ctx context.Context, orgName string, inContToken ContinuationToken) (
		apitype.ListPolicyGroupsResponse, ContinuationToken, error)

	// ListPolicyPacks returns all Policy Packs for an organization in this backend, or an error if it cannot be found.
	ListPolicyPacks(ctx context.Context, orgName string, inContToken ContinuationToken) (
		apitype.ListPolicyPacksResponse, ContinuationToken, error)

	// SupportsTags tells whether a stack can have associated tags stored with it in this backend.
	SupportsTags() bool

	// SupportsOrganizations tells whether a user can belong to multiple organizations in this backend.
	SupportsOrganizations() bool

	// SupportsProgress tells whether the backend supports showing whether an operation is currently in progress
	SupportsProgress() bool

	// ParseStackReference takes a string representation and parses it to a reference which may be used for other
	// methods in this backend.
	ParseStackReference(s string) (StackReference, error)
	// ValidateStackName verifies that the string is a legal identifier for a (potentially qualified) stack.
	// Will check for any backend-specific naming restrictions.
	ValidateStackName(s string) error

	// DoesProjectExist returns true if a project with the given name exists in this backend, or false otherwise.
	DoesProjectExist(ctx context.Context, orgName string, projectName string) (bool, error)

	// GetStack returns a stack object tied to this backend with the given name, or nil if it cannot be found.
	GetStack(ctx context.Context, stackRef StackReference) (Stack, error)
	// CreateStack creates a new stack with the given name and options that are specific to the backend provider.
	CreateStack(ctx context.Context, stackRef StackReference, root string, opts *CreateStackOptions) (Stack, error)

	// RemoveStack removes a stack with the given name.  If force is true, the stack will be removed even if it
	// still contains resources.  Otherwise, if the stack contains resources, a non-nil error is returned, and the
	// first boolean return value will be set to true.
	RemoveStack(ctx context.Context, stack Stack, force bool) (bool, error)
	// ListStacks returns a list of stack summaries for all known stacks in the target backend.
	ListStacks(ctx context.Context, filter ListStacksFilter, inContToken ContinuationToken) (
		[]StackSummary, ContinuationToken, error)

	// RenameStack renames the given stack to a new name, and then returns an updated stack reference that
	// can be used to refer to the newly renamed stack.
	RenameStack(ctx context.Context, stack Stack, newName tokens.QName) (StackReference, error)

	// Preview shows what would be updated given the current workspace's contents.
	Preview(
		ctx context.Context, stack Stack, op UpdateOperation, events chan<- engine.Event,
	) (*deploy.Plan, sdkDisplay.ResourceChanges, result.Result)
	// Update updates the target stack with the current workspace's contents (config and code).
	Update(ctx context.Context, stack Stack, op UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)
	// Import imports resources into a stack.
	Import(ctx context.Context, stack Stack, op UpdateOperation,
		imports []deploy.Import) (sdkDisplay.ResourceChanges, result.Result)
	// Refresh refreshes the stack's state from the cloud provider.
	Refresh(ctx context.Context, stack Stack, op UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)
	// Destroy destroys all of this stack's resources.
	Destroy(ctx context.Context, stack Stack, op UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)
	// Watch watches the project's working directory for changes and automatically updates the active stack.
	Watch(ctx context.Context, stack Stack, op UpdateOperation, paths []string) result.Result

	// Query against the resource outputs in a stack's state checkpoint.
	Query(ctx context.Context, op QueryOperation) error

	// GetHistory returns all updates for the stack. The returned UpdateInfo slice will be in
	// descending order (newest first).
	GetHistory(ctx context.Context, stackRef StackReference, pageSize int, page int) ([]UpdateInfo, error)
	// GetLogs fetches a list of log entries for the given stack, with optional filtering/querying.
	GetLogs(ctx context.Context, secretsProvider secrets.Provider, stack Stack, cfg StackConfiguration,
		query operations.LogQuery) ([]operations.LogEntry, error)
	// Get the configuration from the most recent deployment of the stack.
	GetLatestConfiguration(ctx context.Context, stack Stack) (config.Map, error)

	// UpdateStackTags updates the stacks's tags, replacing all existing tags.
	UpdateStackTags(ctx context.Context, stack Stack, tags map[apitype.StackTagName]string) error

	// ExportDeployment exports the deployment for the given stack as an opaque JSON message.
	ExportDeployment(ctx context.Context, stack Stack) (*apitype.UntypedDeployment, error)
	// ImportDeployment imports the given deployment into the indicated stack.
	ImportDeployment(ctx context.Context, stack Stack, deployment *apitype.UntypedDeployment) error
	// Returns the identity of the current user and any organizations they are in for the backend.
	CurrentUser() (string, []string, *workspace.TokenInformation, error)

	// Cancel the current update for the given stack.
	CancelCurrentUpdate(ctx context.Context, stackRef StackReference) error
}

Backend is the contract between the Pulumi engine and pluggable backend implementations of the Pulumi Cloud Service.

type CancellationScope 

type CancellationScope interface {
	// Context returns the cancellation context used to observe cancellation and termination requests for this scope.
	Context() *cancel.Context
	// Close closes the cancellation scope.
	Close()
}

CancellationScope provides a scoped source of cancellation and termination requests.

type CancellationScopeSource 

type CancellationScopeSource interface {
	// NewScope creates a new cancellation scope.
	NewScope(events chan<- engine.Event, isPreview bool) CancellationScope
}

CancellationScopeSource provides a source for cancellation scopes.

type ConflictingUpdateError 

type ConflictingUpdateError struct {
	Err error // The error that occurred while starting the operation.
}

ConflictingUpdateError represents an error which occurred while starting an update/destroy operation. Another update of the same stack was in progress, so the operation got cancelled due to this conflict.

func (ConflictingUpdateError) Error 

func (c ConflictingUpdateError) Error() string

type ContinuationToken added in v3.9.1 

type ContinuationToken *string

ContinuationToken is an opaque string used for paginated backend requests. If non-nil, means there are more results to be returned and the continuation token should be passed into a subsequent call to the backend method. A nil continuation token means all results have been returned.

type CreateStackOptions added in v3.59.0 

type CreateStackOptions struct {
	// Teams is a list of teams who should have access to
	// the newly created stack.
	// This option is only appropriate for backends
	// which support teams (i.e. the Pulumi Service).
	//
	// The backend may return ErrTeamsNotSupported
	// if Teams is specified but not supported.
	Teams []string
}

CreateStackOptions provides options for stack creation. At present, options only apply to the Service.

type EnvironmentsBackend added in v3.88.0 

type EnvironmentsBackend interface {
	CreateEnvironment(
		ctx context.Context,
		org string,
		name string,
		yaml []byte,
	) (apitype.EnvironmentDiagnostics, error)

	CheckYAMLEnvironment(
		ctx context.Context,
		org string,
		yaml []byte,
	) (*esc.Environment, apitype.EnvironmentDiagnostics, error)

	// OpenYAMLEnvironment opens a literal environment.
	OpenYAMLEnvironment(
		ctx context.Context,
		org string,
		yaml []byte,
		duration time.Duration,
	) (*esc.Environment, apitype.EnvironmentDiagnostics, error)
}

EnvironmentsBackend is an interface that defines an optional capability for a backend to work with environments.

type InMemoryPersister added in v3.113.0 

type InMemoryPersister struct {
	Snap *deploy.Snapshot
}

func (*InMemoryPersister) Save added in v3.113.0 

func (p *InMemoryPersister) Save(snap *deploy.Snapshot) error

type ListStacksFilter 

type ListStacksFilter struct {
	Organization *string
	Project      *string
	TagName      *string
	TagValue     *string
}

ListStacksFilter describes optional filters when listing stacks.

type MakeQuery 

type MakeQuery func(context.Context, QueryOperation) (engine.QueryInfo, error)

type MockBackend 

type MockBackend struct {
	NameF                  func() string
	URLF                   func() string
	SetCurrentProjectF     func(proj *workspace.Project)
	GetPolicyPackF         func(ctx context.Context, policyPack string, d diag.Sink) (PolicyPack, error)
	SupportsTagsF          func() bool
	SupportsOrganizationsF func() bool
	SupportsProgressF      func() bool
	ParseStackReferenceF   func(s string) (StackReference, error)
	ValidateStackNameF     func(s string) error
	DoesProjectExistF      func(context.Context, string, string) (bool, error)
	GetStackF              func(context.Context, StackReference) (Stack, error)
	CreateStackF           func(context.Context, StackReference, string, *CreateStackOptions) (Stack, error)
	RemoveStackF           func(context.Context, Stack, bool) (bool, error)
	ListStacksF            func(context.Context, ListStacksFilter, ContinuationToken) (
		[]StackSummary, ContinuationToken, error)
	RenameStackF            func(context.Context, Stack, tokens.QName) (StackReference, error)
	GetStackCrypterF        func(StackReference) (config.Crypter, error)
	QueryF                  func(context.Context, QueryOperation) error
	GetLatestConfigurationF func(context.Context, Stack) (config.Map, error)
	GetHistoryF             func(context.Context, StackReference, int, int) ([]UpdateInfo, error)
	UpdateStackTagsF        func(context.Context, Stack, map[apitype.StackTagName]string) error
	ExportDeploymentF       func(context.Context, Stack) (*apitype.UntypedDeployment, error)
	ImportDeploymentF       func(context.Context, Stack, *apitype.UntypedDeployment) error
	CurrentUserF            func() (string, []string, *workspace.TokenInformation, error)
	PreviewF                func(context.Context, Stack,
		UpdateOperation) (*deploy.Plan, sdkDisplay.ResourceChanges, result.Result)
	UpdateF func(context.Context, Stack,
		UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)
	ImportF func(context.Context, Stack,
		UpdateOperation, []deploy.Import) (sdkDisplay.ResourceChanges, result.Result)
	RefreshF func(context.Context, Stack,
		UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)
	DestroyF func(context.Context, Stack,
		UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)
	WatchF func(context.Context, Stack,
		UpdateOperation, []string) result.Result
	GetLogsF func(context.Context, secrets.Provider, Stack, StackConfiguration,
		operations.LogQuery) ([]operations.LogEntry, error)

	CancelCurrentUpdateF func(ctx context.Context, stackRef StackReference) error
}

func (*MockBackend) CancelCurrentUpdate added in v3.26.0 

func (be *MockBackend) CancelCurrentUpdate(ctx context.Context, stackRef StackReference) error

func (*MockBackend) CreateStack 

func (be *MockBackend) CreateStack(ctx context.Context, stackRef StackReference,
	root string, opts *CreateStackOptions,
) (Stack, error)

func (*MockBackend) CurrentUser 

func (be *MockBackend) CurrentUser() (string, []string, *workspace.TokenInformation, error)

func (*MockBackend) Destroy 

func (be *MockBackend) Destroy(ctx context.Context, stack Stack,
	op UpdateOperation,
) (sdkDisplay.ResourceChanges, result.Result)

func (*MockBackend) DoesProjectExist 

func (be *MockBackend) DoesProjectExist(ctx context.Context, orgName string, projectName string) (bool, error)

func (*MockBackend) ExportDeployment 

func (be *MockBackend) ExportDeployment(ctx context.Context,
	stack Stack,
) (*apitype.UntypedDeployment, error)

func (*MockBackend) GetHistory 

func (be *MockBackend) GetHistory(ctx context.Context,
	stackRef StackReference,
	pageSize int,
	page int,
) ([]UpdateInfo, error)

func (*MockBackend) GetLatestConfiguration 

func (be *MockBackend) GetLatestConfiguration(ctx context.Context,
	stack Stack,
) (config.Map, error)

func (*MockBackend) GetLogs 

func (be *MockBackend) GetLogs(
	ctx context.Context, secretsProvider secrets.Provider, stack Stack,
	cfg StackConfiguration, query operations.LogQuery,
) ([]operations.LogEntry, error)

func (*MockBackend) GetPolicyPack 

func (be *MockBackend) GetPolicyPack(
	ctx context.Context, policyPack string, d diag.Sink,
) (PolicyPack, error)

func (*MockBackend) GetStack 

func (be *MockBackend) GetStack(ctx context.Context, stackRef StackReference) (Stack, error)

func (*MockBackend) GetStackCrypter 

func (be *MockBackend) GetStackCrypter(stackRef StackReference) (config.Crypter, error)

func (*MockBackend) Import 

func (be *MockBackend) Import(ctx context.Context, stack Stack,
	op UpdateOperation, imports []deploy.Import,
) (sdkDisplay.ResourceChanges, result.Result)

func (*MockBackend) ImportDeployment 

func (be *MockBackend) ImportDeployment(ctx context.Context, stack Stack,
	deployment *apitype.UntypedDeployment,
) error

func (*MockBackend) ListPolicyGroups 

func (be *MockBackend) ListPolicyGroups(context.Context, string, ContinuationToken) (
	apitype.ListPolicyGroupsResponse, ContinuationToken, error,
)

func (*MockBackend) ListPolicyPacks 

func (be *MockBackend) ListPolicyPacks(context.Context, string, ContinuationToken) (
	apitype.ListPolicyPacksResponse, ContinuationToken, error,
)

func (*MockBackend) ListStacks 

func (be *MockBackend) ListStacks(ctx context.Context, filter ListStacksFilter, inContToken ContinuationToken) (
	[]StackSummary, ContinuationToken, error,
)

func (*MockBackend) Name 

func (be *MockBackend) Name() string

func (*MockBackend) ParseStackReference 

func (be *MockBackend) ParseStackReference(s string) (StackReference, error)

func (*MockBackend) Preview 

func (be *MockBackend) Preview(ctx context.Context, stack Stack,
	op UpdateOperation, events chan<- engine.Event,
) (*deploy.Plan, sdkDisplay.ResourceChanges, result.Result)

func (*MockBackend) Query 

func (be *MockBackend) Query(ctx context.Context, op QueryOperation) error

func (*MockBackend) Refresh 

func (be *MockBackend) Refresh(ctx context.Context, stack Stack,
	op UpdateOperation,
) (sdkDisplay.ResourceChanges, result.Result)

func (*MockBackend) RemoveStack 

func (be *MockBackend) RemoveStack(ctx context.Context, stack Stack, force bool) (bool, error)

func (*MockBackend) RenameStack 

func (be *MockBackend) RenameStack(ctx context.Context, stack Stack,
	newName tokens.QName,
) (StackReference, error)

func (*MockBackend) SetCurrentProject added in v3.57.0 

func (be *MockBackend) SetCurrentProject(project *workspace.Project)

func (*MockBackend) SupportsOrganizations 

func (be *MockBackend) SupportsOrganizations() bool

func (*MockBackend) SupportsProgress added in v3.91.1 

func (be *MockBackend) SupportsProgress() bool

func (*MockBackend) SupportsTags added in v3.27.0 

func (be *MockBackend) SupportsTags() bool

func (*MockBackend) URL 

func (be *MockBackend) URL() string

func (*MockBackend) Update 

func (be *MockBackend) Update(ctx context.Context, stack Stack,
	op UpdateOperation,
) (sdkDisplay.ResourceChanges, result.Result)

func (*MockBackend) UpdateStackTags 

func (be *MockBackend) UpdateStackTags(ctx context.Context, stack Stack,
	tags map[apitype.StackTagName]string,
) error

func (*MockBackend) ValidateStackName 

func (be *MockBackend) ValidateStackName(s string) error

func (*MockBackend) Watch 

func (be *MockBackend) Watch(ctx context.Context, stack Stack,
	op UpdateOperation, paths []string,
) result.Result

type MockEnvironmentsBackend added in v3.88.0 

type MockEnvironmentsBackend struct {
	MockBackend

	CreateEnvironmentF func(
		ctx context.Context,
		org string,
		name string,
		yaml []byte,
	) (apitype.EnvironmentDiagnostics, error)

	CheckYAMLEnvironmentF func(
		ctx context.Context,
		org string,
		yaml []byte,
	) (*esc.Environment, apitype.EnvironmentDiagnostics, error)

	OpenYAMLEnvironmentF func(
		ctx context.Context,
		org string,
		yaml []byte,
		duration time.Duration,
	) (*esc.Environment, apitype.EnvironmentDiagnostics, error)
}

func (*MockEnvironmentsBackend) CheckYAMLEnvironment added in v3.95.0 

func (be *MockEnvironmentsBackend) CheckYAMLEnvironment(
	ctx context.Context,
	org string,
	yaml []byte,
) (*esc.Environment, apitype.EnvironmentDiagnostics, error)

func (*MockEnvironmentsBackend) CreateEnvironment added in v3.95.0 

func (be *MockEnvironmentsBackend) CreateEnvironment(
	ctx context.Context,
	org string,
	name string,
	yaml []byte,
) (apitype.EnvironmentDiagnostics, error)

func (*MockEnvironmentsBackend) OpenYAMLEnvironment added in v3.88.0 

func (be *MockEnvironmentsBackend) OpenYAMLEnvironment(
	ctx context.Context,
	org string,
	yaml []byte,
	duration time.Duration,
) (*esc.Environment, apitype.EnvironmentDiagnostics, error)

type MockPolicyPack added in v3.87.0 

type MockPolicyPack struct {
	RefF      func() PolicyPackReference
	BackendF  func() Backend
	PublishF  func(context.Context, PublishOperation) result.Result
	EnableF   func(context.Context, string, PolicyPackOperation) error
	DisableF  func(context.Context, string, PolicyPackOperation) error
	ValidateF func(context.Context, PolicyPackOperation) error
	RemoveF   func(context.Context, PolicyPackOperation) error
}

func (*MockPolicyPack) Backend added in v3.87.0 

func (mp *MockPolicyPack) Backend() Backend

func (*MockPolicyPack) Disable added in v3.87.0 

func (mp *MockPolicyPack) Disable(ctx context.Context, orgName string, op PolicyPackOperation) error

func (*MockPolicyPack) Enable added in v3.87.0 

func (mp *MockPolicyPack) Enable(ctx context.Context, orgName string, op PolicyPackOperation) error

func (*MockPolicyPack) Publish added in v3.87.0 

func (mp *MockPolicyPack) Publish(ctx context.Context, op PublishOperation) result.Result

func (*MockPolicyPack) Ref added in v3.87.0 

func (mp *MockPolicyPack) Ref() PolicyPackReference

func (*MockPolicyPack) Remove added in v3.87.0 

func (mp *MockPolicyPack) Remove(ctx context.Context, op PolicyPackOperation) error

func (*MockPolicyPack) Validate added in v3.87.0 

func (mp *MockPolicyPack) Validate(ctx context.Context, op PolicyPackOperation) error

type MockStack 

type MockStack struct {
	RefF      func() StackReference
	OrgNameF  func() string
	ConfigF   func() config.Map
	SnapshotF func(ctx context.Context, secretsProvider secrets.Provider) (*deploy.Snapshot, error)
	TagsF     func() map[apitype.StackTagName]string
	BackendF  func() Backend
	PreviewF  func(ctx context.Context, op UpdateOperation) (*deploy.Plan, sdkDisplay.ResourceChanges, result.Result)
	UpdateF   func(ctx context.Context, op UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)
	ImportF   func(ctx context.Context, op UpdateOperation,
		imports []deploy.Import) (sdkDisplay.ResourceChanges, result.Result)
	RefreshF func(ctx context.Context, op UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)
	DestroyF func(ctx context.Context, op UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)
	WatchF   func(ctx context.Context, op UpdateOperation, paths []string) result.Result
	QueryF   func(ctx context.Context, op UpdateOperation) result.Result
	RemoveF  func(ctx context.Context, force bool) (bool, error)
	RenameF  func(ctx context.Context, newName tokens.QName) (StackReference, error)
	GetLogsF func(ctx context.Context, secretsProvider secrets.Provider, cfg StackConfiguration,
		query operations.LogQuery) ([]operations.LogEntry, error)
	ExportDeploymentF     func(ctx context.Context) (*apitype.UntypedDeployment, error)
	ImportDeploymentF     func(ctx context.Context, deployment *apitype.UntypedDeployment) error
	DefaultSecretManagerF func(info *workspace.ProjectStack) (secrets.Manager, error)
}

func (*MockStack) Backend 

func (ms *MockStack) Backend() Backend

func (*MockStack) Config 

func (ms *MockStack) Config() config.Map

func (*MockStack) DefaultSecretManager added in v3.39.0 

func (ms *MockStack) DefaultSecretManager(info *workspace.ProjectStack) (secrets.Manager, error)

func (*MockStack) Destroy 

func (ms *MockStack) Destroy(ctx context.Context, op UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)

func (*MockStack) ExportDeployment 

func (ms *MockStack) ExportDeployment(ctx context.Context) (*apitype.UntypedDeployment, error)

func (*MockStack) GetLogs 

func (ms *MockStack) GetLogs(ctx context.Context, secretsProvider secrets.Provider, cfg StackConfiguration,
	query operations.LogQuery,
) ([]operations.LogEntry, error)

func (*MockStack) Import 

func (ms *MockStack) Import(ctx context.Context, op UpdateOperation,
	imports []deploy.Import,
) (sdkDisplay.ResourceChanges, result.Result)

func (*MockStack) ImportDeployment 

func (ms *MockStack) ImportDeployment(ctx context.Context, deployment *apitype.UntypedDeployment) error

func (*MockStack) OrgName added in v3.88.0 

func (ms *MockStack) OrgName() string

func (*MockStack) Preview 

func (ms *MockStack) Preview(
	ctx context.Context,
	op UpdateOperation, events chan<- engine.Event,
) (*deploy.Plan, sdkDisplay.ResourceChanges, result.Result)

func (*MockStack) Query 

func (ms *MockStack) Query(ctx context.Context, op UpdateOperation) result.Result

func (*MockStack) Ref 

func (ms *MockStack) Ref() StackReference

func (*MockStack) Refresh 

func (ms *MockStack) Refresh(ctx context.Context, op UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)

func (*MockStack) Remove 

func (ms *MockStack) Remove(ctx context.Context, force bool) (bool, error)

func (*MockStack) Rename 

func (ms *MockStack) Rename(ctx context.Context, newName tokens.QName) (StackReference, error)

func (*MockStack) Snapshot 

func (ms *MockStack) Snapshot(ctx context.Context, secretsProvider secrets.Provider) (*deploy.Snapshot, error)

func (*MockStack) Tags added in v3.27.0 

func (ms *MockStack) Tags() map[apitype.StackTagName]string

func (*MockStack) Update 

func (ms *MockStack) Update(ctx context.Context, op UpdateOperation) (sdkDisplay.ResourceChanges, result.Result)

func (*MockStack) Watch 

func (ms *MockStack) Watch(ctx context.Context, op UpdateOperation, paths []string) result.Result

type MockStackReference added in v3.60.0 

type MockStackReference struct {
	StringV             string
	NameV               tokens.StackName
	ProjectV            tokens.Name
	FullyQualifiedNameV tokens.QName
}

MockStackReference is a mock implementation of StackReference. Set the fields on this struct to control the behavior of the mock.

func (*MockStackReference) FullyQualifiedName added in v3.60.0 

func (r *MockStackReference) FullyQualifiedName() tokens.QName

func (*MockStackReference) Name added in v3.60.0 

func (r *MockStackReference) Name() tokens.StackName

func (*MockStackReference) Project added in v3.65.0 

func (r *MockStackReference) Project() (tokens.Name, bool)

func (*MockStackReference) String added in v3.60.0 

func (r *MockStackReference) String() string

type OverStackLimitError 

type OverStackLimitError struct {
	Message string
}

OverStackLimitError is returned from CreateStack when the organization is billed per-stack and is over its stack limit.

func (OverStackLimitError) Error 

func (e OverStackLimitError) Error() string

type PolicyPack 

type PolicyPack interface {
	// Ref returns a reference to this PolicyPack.
	Ref() PolicyPackReference
	// Backend returns the backend this PolicyPack is managed by.
	Backend() Backend
	// Publish the PolicyPack to the service.
	Publish(ctx context.Context, op PublishOperation) result.Result
	// Enable the PolicyPack to a Policy Group in an organization. If Policy Group is
	// empty, it enables it for the default Policy Group.
	Enable(ctx context.Context, policyGroup string, op PolicyPackOperation) error

	// Disable the PolicyPack for a Policy Group in an organization. If Policy Group is
	// empty, it disables it for the default Policy Group.
	Disable(ctx context.Context, policyGroup string, op PolicyPackOperation) error

	// Validate the PolicyPack configuration against configuration schema.
	Validate(ctx context.Context, op PolicyPackOperation) error

	// Remove the PolicyPack from an organization. The Policy Pack must be removed from
	// all Policy Groups before it can be removed.
	Remove(ctx context.Context, op PolicyPackOperation) error
}

PolicyPack is used to manage policy against a pluggable backend.

type PolicyPackOperation 

type PolicyPackOperation struct {
	// If nil, the latest version is assumed.
	VersionTag *string
	Scopes     CancellationScopeSource
	Config     map[string]*json.RawMessage
}

PolicyPackOperation is used to make various operations against a Policy Pack.

type PolicyPackReference 

type PolicyPackReference interface {
	// fmt.Stringer's String() method returns a string of the stack identity, suitable for display in the CLI
	fmt.Stringer
	// OrgName is the name of the organization that is managing the PolicyPack.
	OrgName() string
	// Name is the name of the PolicyPack being referenced.
	Name() tokens.QName
}

PolicyPackReference is an opaque type that refers to a PolicyPack managed by a backend. The CLI uses the ParsePolicyPackReference method to turn a string like "myOrg/mySecurityRules" into a PolicyPackReference that can be used to interact with the PolicyPack via the backend. PolicyPackReferences are specific to a given backend and different back ends may interpret the string passed to ParsePolicyPackReference differently.

type PublishOperation 

type PublishOperation struct {
	Root       string
	PlugCtx    *plugin.Context
	PolicyPack *workspace.PolicyPackProject
	Scopes     CancellationScopeSource
}

PublishOperation publishes a PolicyPack to the backend.

type QueryOperation 

type QueryOperation struct {
	Proj               *workspace.Project
	Root               string
	Opts               UpdateOptions
	SecretsManager     secrets.Manager
	SecretsProvider    secrets.Provider
	StackConfiguration StackConfiguration
	Scopes             CancellationScopeSource
}

QueryOperation configures a query operation.

type QueryOptions 

type QueryOptions struct {
	// Engine contains all of the engine-specific options.
	Engine engine.UpdateOptions
	// Display contains all of the backend display options.
	Display display.Options
}

QueryOptions configures a query to operate against a backend and the engine.

type SnapshotManager 

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

SnapshotManager is an implementation of engine.SnapshotManager that inspects steps and performs mutations on the global snapshot object serially. This implementation maintains two bits of state: the "base" snapshot, which is completely immutable and represents the state of the world prior to the application of the current plan, and a "new" list of resources, which consists of the resources that were operated upon by the current plan.

Important to note is that, although this SnapshotManager is designed to be easily convertible into a thread-safe implementation, the code as it is today is *not thread safe*. In particular, it is not legal for there to be more than one `SnapshotMutation` active at any point in time. This is because this SnapshotManager invalidates the last persisted snapshot in `BeginSnapshot`. This is designed to match existing behavior and will not be the state of things going forward.

The resources stored in the `resources` slice are pointers to resource objects allocated by the engine. This is subtle and a little confusing. The reason for this is that the engine directly mutates resource objects that it creates and expects those mutations to be persisted directly to the snapshot.

func NewSnapshotManager 

func NewSnapshotManager(
	persister SnapshotPersister,
	secretsManager secrets.Manager,
	baseSnap *deploy.Snapshot,
) *SnapshotManager

NewSnapshotManager creates a new SnapshotManager for the given stack name, using the given persister, default secrets manager and base snapshot.

It is *very important* that the baseSnap pointer refers to the same Snapshot given to the engine! The engine will mutate this object and correctness of the SnapshotManager depends on being able to observe this mutation. (This is not ideal...)

func (*SnapshotManager) BeginMutation 

func (sm *SnapshotManager) BeginMutation(step deploy.Step) (engine.SnapshotMutation, error)

BeginMutation signals to the SnapshotManager that the engine intends to mutate the global snapshot by performing the given Step. This function gives the SnapshotManager a chance to record the intent to mutate before the mutation occurs.

func (*SnapshotManager) Close 

func (sm *SnapshotManager) Close() error

func (*SnapshotManager) RegisterResourceOutputs 

func (sm *SnapshotManager) RegisterResourceOutputs(step deploy.Step) error

RegisterResourceOutputs handles the registering of outputs on a Step that has already completed. This is accomplished by doing an in-place mutation of the resources currently resident in the snapshot.

Due to the way this is currently implemented, the engine directly mutates output properties on the resource State object that it created. Since we are storing pointers to these objects in the `resources` slice, we need only to do a no-op mutation in order to flush these new mutations to disk.

Note that this is completely not thread-safe and defeats the purpose of having a `mutate` callback entirely, but the hope is that this state of things will not be permament.

type SnapshotPersister 

type SnapshotPersister interface {
	// Persists the given snapshot. Returns an error if the persistence failed.
	Save(snapshot *deploy.Snapshot) error
}

SnapshotPersister is an interface implemented by our backends that implements snapshot persistence. In order to fit into our current model, snapshot persisters have two functions: saving snapshots and invalidating already-persisted snapshots.

type SpecificDeploymentExporter 

type SpecificDeploymentExporter interface {
	// ExportDeploymentForVersion exports a specific deployment from the history of a stack. The meaning of
	// version is backend-specific. For the Pulumi Console, it is the numeric version. (The first update
	// being version "1", the second "2", and so on.) Though this might change in the future to use some
	// other type of identifier or commitish .
	ExportDeploymentForVersion(ctx context.Context, stack Stack, version string) (*apitype.UntypedDeployment, error)
}

SpecificDeploymentExporter is an interface defining an additional capability of a Backend, specifically the ability to export a specific versions of a stack's deployment. This isn't a requirement for all backends and should be checked for dynamically.

type Stack 

type Stack interface {
	// Ref returns this stack's identity.
	Ref() StackReference
	// Snapshot returns the latest deployment snapshot.
	Snapshot(ctx context.Context, secretsProvider secrets.Provider) (*deploy.Snapshot, error)
	// Backend returns the backend this stack belongs to.
	Backend() Backend
	// Tags return the stack's existing tags.
	Tags() map[apitype.StackTagName]string
	// Preview changes to this stack if an Update was run.
	Preview(
		ctx context.Context, op UpdateOperation, events chan<- engine.Event,
	) (*deploy.Plan, display.ResourceChanges, result.Result)
	// Update this stack.
	Update(ctx context.Context, op UpdateOperation) (display.ResourceChanges, result.Result)
	// Import resources into this stack.
	Import(ctx context.Context, op UpdateOperation, imports []deploy.Import) (display.ResourceChanges, result.Result)
	// Refresh this stack's state from the cloud provider.
	Refresh(ctx context.Context, op UpdateOperation) (display.ResourceChanges, result.Result)
	Destroy(ctx context.Context, op UpdateOperation) (display.ResourceChanges, result.Result)
	// Watch this stack.
	Watch(ctx context.Context, op UpdateOperation, paths []string) result.Result

	// Remove this stack.
	Remove(ctx context.Context, force bool) (bool, error)
	// Rename this stack.
	Rename(ctx context.Context, newName tokens.QName) (StackReference, error)
	// GetLogs lists log entries for this stack.
	GetLogs(ctx context.Context, secretsProvider secrets.Provider,
		cfg StackConfiguration, query operations.LogQuery) ([]operations.LogEntry, error)
	// ExportDeployment exports this stack's deployment.
	ExportDeployment(ctx context.Context) (*apitype.UntypedDeployment, error)
	// ImportDeployment imports the given deployment into this stack.
	ImportDeployment(ctx context.Context, deployment *apitype.UntypedDeployment) error

	// DefaultSecretManager returns the default secrets manager to use for this stack.
	DefaultSecretManager(info *workspace.ProjectStack) (secrets.Manager, error)
}

Stack is used to manage stacks of resources against a pluggable backend.

type StackAlreadyExistsError 

type StackAlreadyExistsError struct {
	StackName string
}

StackAlreadyExistsError is returned from CreateStack when the stack already exists in the backend.

func (StackAlreadyExistsError) Error 

func (e StackAlreadyExistsError) Error() string

type StackConfiguration 

type StackConfiguration struct {
	Environment esc.Value
	Config      config.Map
	Decrypter   config.Decrypter
}

StackConfiguration holds the configuration for a stack and it's associated decrypter.

type StackReference 

type StackReference interface {
	// fmt.Stringer's String() method returns a string of the stack identity, suitable for display in the CLI
	fmt.Stringer
	// Name is the name that will be passed to the Pulumi engine when preforming operations on this stack. This
	// name may not uniquely identify the stack (e.g. the cloud backend embeds owner information in the StackReference
	// but that information is not part of the StackName() we pass to the engine.
	Name() tokens.StackName

	// Project is the project name that this stack belongs to.
	// For old diy backends this will return false.
	Project() (tokens.Name, bool)

	// Fully qualified name of the stack, including any organization, project, or other information.
	FullyQualifiedName() tokens.QName
}

StackReference is an opaque type that refers to a stack managed by a backend. The CLI uses the ParseStackReference method to turn a string like "my-great-stack" or "pulumi/my-great-stack" into a stack reference that can be used to interact with the stack via the backend. Stack references are specific to a given backend and different back ends may interpret the string passed to ParseStackReference differently.

func RenameStack 

func RenameStack(ctx context.Context, s Stack, newName tokens.QName) (StackReference, error)

RenameStack renames the stack, or returns an error if it cannot.

type StackSummary 

type StackSummary interface {
	Name() StackReference

	// LastUpdate returns when the stack was last updated, as applicable.
	LastUpdate() *time.Time
	// ResourceCount returns the stack's resource count, as applicable.
	ResourceCount() *int
}

StackSummary provides a basic description of a stack, without the ability to inspect its resources or make changes.

type UpdateInfo 

type UpdateInfo struct {
	// Information known before an update is started.
	Kind      apitype.UpdateKind `json:"kind"`
	StartTime int64              `json:"startTime"`

	// Message is an optional message associated with the update.
	Message string `json:"message"`

	// Environment contains optional data from the deploying environment. e.g. the current
	// source code control commit information.
	Environment map[string]string `json:"environment"`

	// Config used for the update.
	Config config.Map `json:"config"`

	// Information obtained from an update completing.
	Version         int                     `json:"version"`
	Result          UpdateResult            `json:"result"`
	EndTime         int64                   `json:"endTime"`
	ResourceChanges display.ResourceChanges `json:"resourceChanges,omitempty"`
}

UpdateInfo describes a previous update.

type UpdateMetadata 

type UpdateMetadata struct {
	// Message is an optional message associated with the update.
	Message string `json:"message"`
	// Environment contains optional data from the deploying environment. e.g. the current
	// source code control commit information.
	Environment map[string]string `json:"environment"`
}

UpdateMetadata describes optional metadata about an update.

type UpdateOperation 

type UpdateOperation struct {
	Proj               *workspace.Project
	Root               string
	Imports            []deploy.Import
	M                  *UpdateMetadata
	Opts               UpdateOptions
	SecretsManager     secrets.Manager
	SecretsProvider    secrets.Provider
	StackConfiguration StackConfiguration
	Scopes             CancellationScopeSource
}

UpdateOperation is a complete stack update operation (preview, update, import, refresh, or destroy).

type UpdateOptions 

type UpdateOptions struct {
	// Engine contains all of the engine-specific options.
	Engine engine.UpdateOptions
	// Display contains all of the backend display options.
	Display display.Options

	// AutoApprove, when true, will automatically approve previews.
	AutoApprove bool
	// SkipPreview, when true, causes the preview step to be skipped.
	SkipPreview bool
	// PreviewOnly, when true, causes only the preview step to be run, without running the Update.
	PreviewOnly bool
	// ContinueOnError, when true, causes the update to continue even if there are errors.
	ContinueOnError bool
}

UpdateOptions is the full set of update options, including backend and engine options.

type UpdateResult 

type UpdateResult string

UpdateResult is an enum for the result of the update. 

const (
	// InProgressResult is for updates that have not yet completed.
	InProgressResult UpdateResult = "in-progress"
	// SucceededResult is for updates that completed successfully.
	SucceededResult UpdateResult = "succeeded"
	// FailedResult is for updates that have failed.
	FailedResult UpdateResult = "failed"
)

Source Files

View all Source files

Directories

Path Synopsis
Package display implements the logic for displaying the status of resource operations.
 Package display implements the logic for displaying the status of resource operations.
internal/terminal
Package diy implements the logic for interacting with a diy backend such as AWS S3, Azure blob storage, or GCP cloud storage.
 Package diy implements the logic for interacting with a diy backend such as AWS S3, Azure blob storage, or GCP cloud storage.
Package httpstate implements the logic for interacting with a web backend.
 Package httpstate implements the logic for interacting with a web backend.
client
Package client implements a client for the Pulumi Service HTTP/REST API.
 Package client implements a client for the Pulumi Service HTTP/REST API.

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.