backend

package
v0.15.0 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2018 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

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

Index

Constants

View Source 
const (
	// InProgressResult is for updates that have not yet completed.
	InProgressResult = "in-progress"
	// SucceededResult is for updates that completed successfully.
	SucceededResult UpdateResult = "succeeded"
	// FailedResult is for updates that have failed.
	FailedResult = "failed"
)
View Source 
const (
	// GitHead is the commit hash of HEAD.
	GitHead = "git.head"
	// 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.
	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"

	// 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 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, proj *workspace.Project, root string, m UpdateMetadata,
	opts UpdateOptions, scopes CancellationScopeSource) (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 GetLatestConfiguration 

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

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

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() (map[apitype.StackTagName]string, error)

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

func ImportStackDeployment 

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

ImportStackDeployment imports the given deployment into the indicated stack.

func PreviewStack 

func PreviewStack(ctx context.Context, s Stack, proj *workspace.Project, root string, m UpdateMetadata,
	opts UpdateOptions, scopes CancellationScopeSource) (engine.ResourceChanges, error)

PreviewStack previews changes to this stack.

func RefreshStack 

func RefreshStack(ctx context.Context, s Stack, proj *workspace.Project, root string, m UpdateMetadata,
	opts UpdateOptions, scopes CancellationScopeSource) (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, proj *workspace.Project, root string, m UpdateMetadata,
	opts UpdateOptions, scopes CancellationScopeSource) (engine.ResourceChanges, error)

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

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.

Types

type Backend 

type Backend interface {
	// Name returns a friendly name for this backend.
	Name() 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) ([]Stack, 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, proj *workspace.Project, root string,
		m UpdateMetadata, opts UpdateOptions, scopes CancellationScopeSource) (engine.ResourceChanges, error)
	// Update updates the target stack with the current workspace's contents (config and code).
	Update(ctx context.Context, stackRef StackReference, proj *workspace.Project, root string,
		m UpdateMetadata, opts UpdateOptions, scopes CancellationScopeSource) (engine.ResourceChanges, error)
	// Refresh refreshes the stack's state from the cloud provider.
	Refresh(ctx context.Context, stackRef StackReference, proj *workspace.Project, root string,
		m UpdateMetadata, opts UpdateOptions, scopes CancellationScopeSource) (engine.ResourceChanges, error)
	// Destroy destroys all of this stack's resources.
	Destroy(ctx context.Context, stackRef StackReference, proj *workspace.Project, root string,
		m UpdateMetadata, opts UpdateOptions, scopes CancellationScopeSource) (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)

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

type DisplayOptions struct {
	Color                colors.Colorization // colorization to apply to events.
	ShowConfig           bool                // true if we should show configuration information.
	ShowReplacementSteps bool                // true to show the replacement steps in the plan.
	ShowSameResources    bool                // true to show the resources that aren't updated in addition to updates.
	SummaryDiff          bool                // If the diff display should be summarized
	IsInteractive        bool                // If we should display things interactively
	DiffDisplay          bool                // true if we should display things as a rich diff
	Debug                bool
}

DisplayOptions controls how the output of events are rendered

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 {
	Name() 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, proj *workspace.Project, root string, m UpdateMetadata, opts UpdateOptions,
		scopes CancellationScopeSource) (engine.ResourceChanges, error)
	// Update this stack.
	Update(ctx context.Context, proj *workspace.Project, root string, m UpdateMetadata, opts UpdateOptions,
		scopes CancellationScopeSource) (engine.ResourceChanges, error)
	// Refresh this stack's state from the cloud provider.
	Refresh(ctx context.Context, proj *workspace.Project, root string, m UpdateMetadata, opts UpdateOptions,
		scopes CancellationScopeSource) (engine.ResourceChanges, error)
	// Destroy this stack's resources.
	Destroy(ctx context.Context, proj *workspace.Project, root string, m UpdateMetadata, opts UpdateOptions,
		scopes CancellationScopeSource) (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
	// StackName 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.
	StackName() 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 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      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 UpdateKind 

type UpdateKind string

UpdateKind is an enum for the type of update performed. 

const (
	// DeployUpdate is the prototypical Pulumi program update.
	DeployUpdate UpdateKind = "update"
	// PreviewUpdate is a preview of an update, without impacting resources.
	PreviewUpdate UpdateKind = "preview"
	// RefreshUpdate is an update that adopts a cloud's existing resource state.
	RefreshUpdate UpdateKind = "refresh"
	// DestroyUpdate is an update which removes all resources.
	DestroyUpdate UpdateKind = "destroy"
)

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 UpdateOptions 

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

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

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.