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.Implements
Inherited Members
Namespace: Pulumi.Automation
Assembly: Pulumi.Automation.dll
Syntax
public abstract class Workspace : IDisposable
Properties
View SourceEnvironmentVariables
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-providersDeclaration
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
View SourceCreateStackAsync(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. |
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 |
Dispose()
Declaration
public virtual void Dispose()
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, 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 |
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>, 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, 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 |
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, 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 |
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. |
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>, 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, 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> |