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

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>

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

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

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

PulumiVersion

The version of the underlying Pulumi CLI/Engine.

Declaration

public abstract string PulumiVersion { get; }

Property Value

Type	Description
string

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

WorkDir

The working directory to run Pulumi CLI commands.

Declaration

public abstract string WorkDir { get; }

Property Value

Type	Description
string

Methods

AddEnvironmentsAsync(string, IEnumerable<string>, CancellationToken)

Adds environments to the end of a stack's import list. Imported environments are merged in order per the ESC merge rules. The list of environments behaves as if it were the import list in an anonymous environment.

Declaration

public abstract Task AddEnvironmentsAsync(string stackName, IEnumerable<string> environments, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack.
IEnumerable<string>	environments	List of environments to add to the end of the stack's import list.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

ChangeSecretsProviderAsync(string, string, SecretsProviderOptions?, CancellationToken)

Change the secrets provider for a stack.

Declaration

public abstract Task ChangeSecretsProviderAsync(string stackName, string newSecretsProvider, SecretsProviderOptions? secretsProviderOptions = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack.
string	newSecretsProvider	The new secrets provider.
SecretsProviderOptions	secretsProviderOptions	The options to change the secrets provider.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

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

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.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

Dispose(bool)

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing

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>

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

GetConfigAsync(string, string, bool, CancellationToken)

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

Declaration

public virtual Task<ConfigValue> GetConfigAsync(string stackName, string key, bool path, 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.
bool	path	The key contains a path to a property in a map or list to get.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ConfigValue>

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>

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>

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>

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

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>

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>

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

InstallAsync(InstallOptions?, CancellationToken)

Install packages and plugins for the current program or policy pack.

Declaration

public abstract Task InstallAsync(InstallOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
InstallOptions	options	The options to customize the install.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

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

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

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

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

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

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

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

RemoveAllConfigAsync(string, IEnumerable<string>, bool, CancellationToken)

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

Declaration

public virtual Task RemoveAllConfigAsync(string stackName, IEnumerable<string> keys, bool path, 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.
bool	path	The keys contain a path to a property in a map or list to remove.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

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

RemoveConfigAsync(string, string, bool, CancellationToken)

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

Declaration

public virtual Task RemoveConfigAsync(string stackName, string key, bool path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stackName	The name of the stack to operate on.
string	key	The config key to remove.
bool	path	The key contains a path to a property in a map or list to remove.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

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

RemoveEnvironmentAsync(string, string, CancellationToken)

Removes environments from a stack's import list.

Declaration

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

Parameters

Type	Name	Description
string	stackName	The name of the stack.
string	environment	The name of the environment to remove from the stack's configuration.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

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

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

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

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

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

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.

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

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

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

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

Declaration

public virtual Task SetAllConfigAsync(string stackName, IDictionary<string, ConfigValue> configMap, bool path, 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.
bool	path	The keys contain a path to a property in a map or list to set.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

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

SetConfigAsync(string, string, ConfigValue, bool, CancellationToken)

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

Declaration

public virtual Task SetConfigAsync(string stackName, string key, ConfigValue value, bool path, 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.
bool	path	The key contains a path to a property in a map or list to set.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

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

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

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