backend

package
v0.17.2 Latest Latest
Warning

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

 Go to latest Published: Mar 15, 2019 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package backend encapsulates all extensibility points required to fully implement a new cloud provider.

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") indiciates 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"

	// GitHubLogin is the user/organization who owns the local repo, if the origin remote is hosted on GitHub.com.
	// TODO [pulumi/pulumi-service#2306] Once the UI is updated, we would no longer need the GitHub specific keys.
	GitHubLogin = "github.login"
	// GitHubRepo is the name of the GitHub repo, if the local git repo's remote origin is hosted on GitHub.com.
	GitHubRepo = "github.repo"

	// 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"

	// 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"
	// 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"
)

Keys we use for values put into UpdateInfo.Environment.

Variables

View Source 
var (
	// ErrNoPreviousDeployment is returned when there isn't a previous deployment.
	ErrNoPreviousDeployment = errors.New("no previous deployment")
)

Functions

func ActionLabel added in v0.15.1 

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

func ContextWithTracingOptions 

func ContextWithTracingOptions(ctx context.Context, opts TracingOptions) context.Context

ContextWithTracingOptions returns a new context.Context with the indicated tracing options.

func DestroyStack 

func DestroyStack(ctx context.Context, s Stack, op UpdateOperation) (engine.ResourceChanges, error)

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 added in v0.16.10 

func GetEnvironmentTagsForCurrentStack() (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 added in v0.16.10 

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

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

func GetStackCrypter 

func GetStackCrypter(s Stack) (config.Crypter, error)

GetStackCrypter fetches the encrypter/decrypter for a stack.

func GetStackLogs 

func GetStackLogs(ctx context.Context, s Stack, query operations.LogQuery) ([]operations.LogEntry, error)

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

func GetStackTags 

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

GetStackTags fetches the stack's existing tags.

func ImportStackDeployment 

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

ImportStackDeployment imports the given deployment into the indicated stack.

func NewBackendClient added in v0.16.6 

func NewBackendClient(backend Backend) deploy.BackendClient

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

func PreviewStack 

func PreviewStack(ctx context.Context, s Stack, op UpdateOperation) (engine.ResourceChanges, error)

PreviewStack previews changes to this stack.

func PreviewThenPrompt added in v0.15.1 

func PreviewThenPrompt(ctx context.Context, kind apitype.UpdateKind, stack Stack,
	op UpdateOperation, apply Applier) (engine.ResourceChanges, error)

func PreviewThenPromptThenExecute added in v0.15.1 

func PreviewThenPromptThenExecute(ctx context.Context, kind apitype.UpdateKind, stack Stack,
	op UpdateOperation, apply Applier) (engine.ResourceChanges, error)

func RefreshStack 

func RefreshStack(ctx context.Context, s Stack, op UpdateOperation) (engine.ResourceChanges, error)

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 UpdateStack 

func UpdateStack(ctx context.Context, s Stack, op UpdateOperation) (engine.ResourceChanges, error)

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

func UpdateStackTags added in v0.16.10 

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

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

func ValidateStackProperties 

func ValidateStackProperties(stack string, tags map[apitype.StackTagName]string) error

ValidateStackProperties validates the stack name and its tags to confirm they adhear to various naming and length restrictions.

func ValidateStackTags added in v0.16.10 

func ValidateStackTags(tags map[apitype.StackTagName]string) error

ValidateStackTags validates the tag names and values.

Types

type Applier added in v0.15.1 

type Applier func(ctx context.Context, kind apitype.UpdateKind, stack Stack, op UpdateOperation,
	opts ApplierOptions, events chan<- engine.Event) (engine.ResourceChanges, error)

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

type ApplierOptions added in v0.16.0 

type ApplierOptions struct {
	// DryRun indiciates if the update should not change any resource state and instead just preview changes.
	DryRun bool
	// ShowLink indiciates if a link to the update persisted result should 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

	// 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)

	// 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, opts interface{}) (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, stackRef StackReference, force bool) (bool, error)
	// ListStacks returns a list of stack summaries for all known stacks in the target backend.
	ListStacks(ctx context.Context, projectFilter *tokens.PackageName) ([]StackSummary, error)

	// GetStackCrypter returns an encrypter/decrypter for the given stack's secret config values.
	GetStackCrypter(stackRef StackReference) (config.Crypter, error)

	// Preview shows what would be updated given the current workspace's contents.
	Preview(ctx context.Context, stackRef StackReference, op UpdateOperation) (engine.ResourceChanges, error)
	// Update updates the target stack with the current workspace's contents (config and code).
	Update(ctx context.Context, stackRef StackReference, op UpdateOperation) (engine.ResourceChanges, error)
	// Refresh refreshes the stack's state from the cloud provider.
	Refresh(ctx context.Context, stackRef StackReference, op UpdateOperation) (engine.ResourceChanges, error)
	// Destroy destroys all of this stack's resources.
	Destroy(ctx context.Context, stackRef StackReference, op UpdateOperation) (engine.ResourceChanges, 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) ([]UpdateInfo, error)
	// GetLogs fetches a list of log entries for the given stack, with optional filtering/querying.
	GetLogs(ctx context.Context, stackRef StackReference, query operations.LogQuery) ([]operations.LogEntry, error)
	// Get the configuration from the most recent deployment of the stack.
	GetLatestConfiguration(ctx context.Context, stackRef StackReference) (config.Map, error)

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

	// ExportDeployment exports the deployment for the given stack as an opaque JSON message.
	ExportDeployment(ctx context.Context, stackRef StackReference) (*apitype.UntypedDeployment, error)
	// ImportDeployment imports the given deployment into the indicated stack.
	ImportDeployment(ctx context.Context, stackRef StackReference, deployment *apitype.UntypedDeployment) error
	// Logout logs you out of the backend and removes any stored credentials.
	Logout() error
	// Returns the identity of the current user for the backend.
	CurrentUser() (string, error)
}

Backend is an interface that represents actions the engine will interact with to manage stacks of cloud resources. It can be implemented any number of ways to provide pluggable backend implementations of the Pulumi Cloud.

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 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, baseSnap *deploy.Snapshot) *SnapshotManager

NewSnapshotManager creates a new SnapshotManager for the given stack name, using the given persister 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) RecordPlugin 

func (sm *SnapshotManager) RecordPlugin(plugin workspace.PluginInfo) error

RecordPlugin records that the current plan loaded a plugin and saves it in the snapshot.

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 Stack 

type Stack interface {
	Ref() StackReference                                    // this stack's identity.
	Config() config.Map                                     // the current config map.
	Snapshot(ctx context.Context) (*deploy.Snapshot, error) // the latest deployment snapshot.
	Backend() Backend                                       // the backend this stack belongs to.

	// Preview changes to this stack.
	Preview(ctx context.Context, op UpdateOperation) (engine.ResourceChanges, error)
	// Update this stack.
	Update(ctx context.Context, op UpdateOperation) (engine.ResourceChanges, error)
	// Refresh this stack's state from the cloud provider.
	Refresh(ctx context.Context, op UpdateOperation) (engine.ResourceChanges, error)
	// Destroy this stack's resources.
	Destroy(ctx context.Context, op UpdateOperation) (engine.ResourceChanges, error)

	// remove this stack.
	Remove(ctx context.Context, force bool) (bool, error)
	// list log entries for this stack.
	GetLogs(ctx context.Context, query operations.LogQuery) ([]operations.LogEntry, error)
	// export this stack's deployment.
	ExportDeployment(ctx context.Context) (*apitype.UntypedDeployment, error)
	// import the given deployment into this stack.
	ImportDeployment(ctx context.Context, deployment *apitype.UntypedDeployment) error
}

Stack is a stack associated with a particular backend implementation.

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 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 informaion is not part of the StackName() we pass to the engine.
	Name() 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

type StackSummary added in v0.15.3 

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 TracingOptions 

type TracingOptions struct {
	// PropagateSpans indicates that spans should be propagated from the client to the Pulumi service when making API
	// calls.
	PropagateSpans bool
	// IncludeTracingHeader indicates that API calls should include the indicated tracing header contents.
	TracingHeader string
}

TracingOptions describes the set of options available for configuring tracing on a per-request basis.

func TracingOptionsFromContext 

func TracingOptionsFromContext(ctx context.Context) TracingOptions

TracingOptionsFromContext retrieves any tracing options present in the given context. If no options are present, this function returns the zero value.

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.
	Result          UpdateResult           `json:"result"`
	EndTime         int64                  `json:"endTime"`
	ResourceChanges engine.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 added in v0.15.1 

type UpdateOperation struct {
	Proj   *workspace.Project
	Root   string
	M      *UpdateMetadata
	Opts   UpdateOptions
	Scopes CancellationScopeSource
}

UpdateOperation is a complete stack update operation (preview, update, 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
}

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
client

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.