Class Workspace

Workspace is the execution context containing a single Pulumi project, a program, and multiple stacks.

Workspaces are used to manage the execution environment, providing various utilities such as plugin installation, environment configuration ($PULUMI_HOME), and creation, deletion, and listing of Stacks.

Inheritance

object

Workspace

LocalWorkspace

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Pulumi.Automation

Assembly: Pulumi.Automation.dll

Syntax

public abstract class Workspace : IDisposable

Properties

View Source

EnvironmentVariables

Environment values scoped to the current workspace. These will be supplied to every Pulumi command.

Declaration

public abstract IDictionary<string, string?>? EnvironmentVariables { get; set; }

Property Value

Type	Description
IDictionary<string, string>

View Source

Logger

A custom logger instance that will be used for the action. Note that it will only be used if Program is also provided.

Declaration

public abstract ILogger? Logger { get; set; }

Property Value

Type	Description
ILogger

View Source

Program

The inline program PulumiFn to be used for Preview/Update operations if any.

If none is specified, the stack will refer to ProjectSettings for this information.

Declaration

public abstract PulumiFn? Program { get; set; }

Property Value

Type	Description
PulumiFn

View Source

PulumiHome

The directory override for CLI metadata if set.

This customizes the location of $PULUMI_HOME where metadata is stored and plugins are installed.

Declaration

public abstract string? PulumiHome { get; }

Property Value

Type	Description
string

View Source

PulumiVersion

The version of the underlying Pulumi CLI/Engine.

Declaration

public abstract string PulumiVersion { get; }

Property Value

Type	Description
string

View Source

SecretsProvider

The secrets provider to use for encryption and decryption of stack secrets.

See: https://www.pulumi.com/docs/intro/concepts/secrets/#available-encryption-providers

Declaration

public abstract string? SecretsProvider { get; }

Property Value

Type	Description
string

View Source

WorkDir

The working directory to run Pulumi CLI commands.

Declaration

public abstract string WorkDir { get; }

Property Value

Type	Description
string

Methods

View Source

CreateStackAsync(string, CancellationToken)

Creates and sets a new stack with the specified stack name, failing if one already exists.

Declaration

public abstract Task CreateStackAsync(string stackName, CancellationToken cancellationToken)

Parameters

Type	Name	Description
string	stackName	The stack to create.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

Exceptions

Type	Condition
StackAlreadyExistsException	If a stack already exists by the provided name.

View Source

CreateStackAsync(string)

Creates and sets a new stack with the specified stack name, failing if one already exists.

Declaration

public Task CreateStackAsync(string stackName)

Parameters

Type	Name	Description
string	stackName	The stack to create.

Returns

Type	Description
Task

View Source

Dispose()

Declaration

public virtual void Dispose()

View Source

ExportStackAsync(string, CancellationToken)

Exports the deployment state of the stack.

This can be combined with ImportStackAsync to edit a stack's state (such as recovery from failed deployments).

Declaration

public abstract Task<StackDeployment> ExportStackAsync(string stackName, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName
CancellationToken	cancellationToken

Returns

Type	Description
Task<StackDeployment>

View Source

GetAllConfigAsync(string, CancellationToken)

Returns the config map for the specified stack name, scoped to the current Workspace.

Declaration

public abstract Task<ImmutableDictionary<string, ConfigValue>> GetAllConfigAsync(string stackName, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack to read config from.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ImmutableDictionary<string, ConfigValue>>

View Source

GetConfigAsync(string, string, CancellationToken)

Returns the value associated with the specified stack name and key, scoped to the Workspace.

Declaration

public abstract Task<ConfigValue> GetConfigAsync(string stackName, string key, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack to read config from.
string	key	The key to use for the config lookup.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ConfigValue>

View Source

GetProjectSettingsAsync(CancellationToken)

Returns project settings for the current project if any.

Declaration

public abstract Task<ProjectSettings?> GetProjectSettingsAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<ProjectSettings>

View Source

GetStackAsync(CancellationToken)

Returns a summary of the currently selected stack, if any.

Declaration

public virtual Task<StackSummary?> GetStackAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<StackSummary>

View Source

GetStackOutputsAsync(string, CancellationToken)

Gets the current set of Stack outputs from the last UpAsync(UpOptions?, CancellationToken).

Declaration

public abstract Task<ImmutableDictionary<string, OutputValue>> GetStackOutputsAsync(string stackName, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ImmutableDictionary<string, OutputValue>>

View Source

GetStackSettingsAsync(string, CancellationToken)

Returns stack settings for the stack matching the specified stack name if any.

Declaration

public abstract Task<StackSettings?> GetStackSettingsAsync(string stackName, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<StackSettings>

View Source

GetTagAsync(string, string, CancellationToken)

Returns the value associated with the specified stack name and key, scoped to the Workspace.

Declaration

public abstract Task<string> GetTagAsync(string stackName, string key, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack to read tag metadata from.
string	key	The key to use for the tag lookup.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<string>

View Source

ImportStackAsync(string, StackDeployment, CancellationToken)

Imports the specified deployment state into a pre-existing stack.

This can be combined with ExportStackAsync to edit a stack's state (such as recovery from failed deployments).

Declaration

public abstract Task ImportStackAsync(string stackName, StackDeployment state, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName
StackDeployment	state
CancellationToken	cancellationToken

Returns

Type	Description
Task

View Source

InstallPluginAsync(string, string, PluginKind, PluginInstallOptions?, CancellationToken)

Installs a plugin in the Workspace, for example to use cloud providers like AWS or GCP.

Declaration

public abstract Task InstallPluginAsync(string name, string version, PluginKind kind = PluginKind.Resource, PluginInstallOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	name	The name of the plugin.
string	version	The version of the plugin e.g. "v1.0.0".
PluginKind	kind	The kind of plugin e.g. "resource".
PluginInstallOptions	options	Any additional plugin installation options.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

InstallPluginAsync(string, string, PluginKind, CancellationToken)

Installs a plugin in the Workspace, for example to use cloud providers like AWS or GCP.

Declaration

public Task InstallPluginAsync(string name, string version, PluginKind kind, CancellationToken cancellationToken)

Parameters

Type	Name	Description
string	name	The name of the plugin.
string	version	The version of the plugin e.g. "v1.0.0".
PluginKind	kind	The kind of plugin e.g. "resource".
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

ListPluginsAsync(CancellationToken)

Returns a list of all plugins installed in the Workspace.

Declaration

public abstract Task<ImmutableList<PluginInfo>> ListPluginsAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<ImmutableList<PluginInfo>>

View Source

ListStacksAsync(CancellationToken)

Returns all stacks created under the current project.

This queries underlying backend and may return stacks not present in the Workspace (as Pulumi.{stack}.yaml files).

Declaration

public abstract Task<ImmutableList<StackSummary>> ListStacksAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<ImmutableList<StackSummary>>

View Source

ListTagsAsync(string, CancellationToken)

Returns the tag map for the specified stack name, scoped to the current Workspace.

Declaration

public abstract Task<Dictionary<string, string>> ListTagsAsync(string stackName, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The stack to operate on.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<Dictionary<string, string>>

View Source

PostCommandCallbackAsync(string, CancellationToken)

Hook executed after every command. Called with the stack name.

An extensibility point to perform workspace cleanup (CLI operations may create/modify a Pulumi.stack.yaml).

LocalWorkspace does not utilize this extensibility point.

Declaration

public abstract Task PostCommandCallbackAsync(string stackName, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

RefreshConfigAsync(string, CancellationToken)

Gets and sets the config map used with the last update for the stack matching the specified stack name.

Declaration

public abstract Task<ImmutableDictionary<string, ConfigValue>> RefreshConfigAsync(string stackName, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack to operate on.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ImmutableDictionary<string, ConfigValue>>

View Source

RemoveAllConfigAsync(string, IEnumerable<string>, CancellationToken)

Removes all values in the provided key collection from the config map for the specified stack name.

Declaration

public abstract Task RemoveAllConfigAsync(string stackName, IEnumerable<string> keys, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack to operate on.
IEnumerable<string>	keys	The collection of keys to remove from the underlying config map.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

RemoveConfigAsync(string, string, CancellationToken)

Removes the specified key-value pair from the provided stack's config.

Declaration

public abstract Task RemoveConfigAsync(string stackName, string key, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack to operate on.
string	key	The config key to remove.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

RemovePluginAsync(string?, string?, PluginKind, CancellationToken)

Removes a plugin from the Workspace matching the specified name and version.

Declaration

public abstract Task RemovePluginAsync(string? name = null, string? versionRange = null, PluginKind kind = PluginKind.Resource, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	name	The optional name of the plugin.
string	versionRange	The optional semver range to check when removing plugins matching the given name e.g. "1.0.0", ">1.0.0".
PluginKind	kind	The kind of plugin e.g. "resource".
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

RemoveStackAsync(string, CancellationToken)

Deletes the stack and all associated configuration and history.

Declaration

public abstract Task RemoveStackAsync(string stackName, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The stack to remove.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

RemoveTagAsync(string, string, CancellationToken)

Sets the specified key-value pair on the provided stack name.

Declaration

public abstract Task RemoveTagAsync(string stackName, string key, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The stack to operate on.
string	key	The tag key to set.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

SaveProjectSettingsAsync(ProjectSettings, CancellationToken)

Overwrites the settings for the current project.

There can only be a single project per workspace. Fails if new project name does not match old.

Declaration

public abstract Task SaveProjectSettingsAsync(ProjectSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ProjectSettings	settings	The settings object to save.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

SaveStackSettingsAsync(string, StackSettings, CancellationToken)

Overwrite the settings for the stack matching the specified stack name.

Declaration

public abstract Task SaveStackSettingsAsync(string stackName, StackSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack to operate on.
StackSettings	settings	The settings object to save.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

SelectStackAsync(string, CancellationToken)

Selects and sets an existing stack matching the stack name, failing if none exists.

Declaration

public abstract Task SelectStackAsync(string stackName, CancellationToken cancellationToken)

Parameters

Type	Name	Description
string	stackName	The stack to select.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

SelectStackAsync(string)

Selects and sets an existing stack matching the stack name, failing if none exists.

Declaration

public Task SelectStackAsync(string stackName)

Parameters

Type	Name	Description
string	stackName	The stack to select.

Returns

Type	Description
Task

Exceptions

Type	Condition
StackNotFoundException	If no stack was found by the provided name.

View Source

SerializeArgsForOpAsync(string, CancellationToken)

Hook to provide additional args to every CLI command before they are executed.

Provided with a stack name, returns an array of args to append to an invoked command ["--config=...", ].

LocalWorkspace does not utilize this extensibility point.

Declaration

public abstract Task<ImmutableList<string>> SerializeArgsForOpAsync(string stackName, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ImmutableList<string>>

View Source

SetAllConfigAsync(string, IDictionary<string, ConfigValue>, CancellationToken)

Sets all values in the provided config map for the specified stack name.

Declaration

public abstract Task SetAllConfigAsync(string stackName, IDictionary<string, ConfigValue> configMap, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack to operate on.
IDictionary<string, ConfigValue>	configMap	The config map to upsert against the existing config.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

SetConfigAsync(string, string, ConfigValue, CancellationToken)

Sets the specified key-value pair in the provided stack's config.

Declaration

public abstract Task SetConfigAsync(string stackName, string key, ConfigValue value, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack to operate on.
string	key	The config key to set.
ConfigValue	value	The config value to set.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

SetTagAsync(string, string, string, CancellationToken)

Sets the specified key-value pair on the provided stack name.

Declaration

public abstract Task SetTagAsync(string stackName, string key, string value, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The stack to operate on.
string	key	The tag key to set.
string	value	The tag value to set.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

View Source

WhoAmIAsync(CancellationToken)

Returns the currently authenticated user.

Declaration

public abstract Task<WhoAmIResult> WhoAmIAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<WhoAmIResult>

Implements

IDisposable