Class WorkspaceStack
WorkspaceStack is an isolated, independently configurable instance of a Pulumi program. WorkspaceStack exposes methods for the full pulumi lifecycle (up/preview/refresh/destroy), as well as managing configuration.
Multiple stacks are commonly used to denote different phases of development (such as development, staging, and production) or feature branches (such as feature-x-dev, jane-feature-x-dev). Will dispose the Workspace on Dispose().Implements
Inherited Members
Namespace: Pulumi.Automation
Assembly: Pulumi.Automation.dll
Syntax
public sealed class WorkspaceStack : IDisposable
Properties
View SourceName
The name identifying the Stack.
Declaration
public string Name { get; }
Property Value
Type | Description |
---|---|
string |
State
A module for editing the Stack's state.
Declaration
public WorkspaceStackState State { get; }
Property Value
Type | Description |
---|---|
WorkspaceStackState |
Workspace
The Workspace the Stack was created from.
Declaration
public Workspace Workspace { get; }
Property Value
Type | Description |
---|---|
Workspace |
Methods
View SourceCancelAsync(CancellationToken)
Cancel stops a stack's currently running update. It throws an exception if no update is currently running. Note that this operation is very dangerous, and may leave the stack in an inconsistent state if a resource operation was pending when the update was canceled. This command is not supported for local backends.
Declaration
public Task CancelAsync(CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
CancellationToken | cancellationToken |
Returns
Type | Description |
---|---|
Task |
CreateAsync(string, Workspace, CancellationToken)
Creates a new stack using the given workspace, and stack name. It fails if a stack with that name already exists.
Declaration
public static Task<WorkspaceStack> CreateAsync(string name, Workspace workspace, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
string | name | The name identifying the stack. |
Workspace | workspace | The Workspace the Stack was created from. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<WorkspaceStack> |
Exceptions
Type | Condition |
---|---|
StackAlreadyExistsException | If a stack with the provided name already exists. |
CreateOrSelectAsync(string, Workspace, CancellationToken)
Tries to create a new Stack using the given workspace, and stack name if the stack does not already exist, or falls back to selecting an existing stack. If the stack does not exist, it will be created and selected.
Declaration
public static Task<WorkspaceStack> CreateOrSelectAsync(string name, Workspace workspace, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
string | name | The name of the identifying stack. |
Workspace | workspace | The Workspace the Stack was created from. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<WorkspaceStack> |
DestroyAsync(DestroyOptions?, CancellationToken)
Destroy deletes all resources in a stack, leaving all history and configuration intact.
Declaration
public Task<UpdateResult> DestroyAsync(DestroyOptions? options = null, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
DestroyOptions | options | Options to customize the behavior of the destroy. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<UpdateResult> |
Dispose()
Declaration
public void Dispose()
ExportStackAsync(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 Task<StackDeployment> ExportStackAsync(CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
CancellationToken | cancellationToken |
Returns
Type | Description |
---|---|
Task<StackDeployment> |
GetAllConfigAsync(CancellationToken)
Returns the full config map associated with the stack in the Workspace.
Declaration
public Task<ImmutableDictionary<string, ConfigValue>> GetAllConfigAsync(CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<ImmutableDictionary<string, ConfigValue>> |
GetConfigAsync(string, CancellationToken)
Returns the config value associated with the specified key.
Declaration
public Task<ConfigValue> GetConfigAsync(string key, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
string | key | The key to use for the config lookup. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<ConfigValue> |
GetHistoryAsync(HistoryOptions?, CancellationToken)
Returns a list summarizing all previews and current results from Stack lifecycle operations (up/preview/refresh/destroy).
Declaration
public Task<ImmutableList<UpdateSummary>> GetHistoryAsync(HistoryOptions? options = null, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
HistoryOptions | options | Options to customize the behavior of the fetch history action. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<ImmutableList<UpdateSummary>> |
GetInfoAsync(CancellationToken)
Declaration
public Task<UpdateSummary?> GetInfoAsync(CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
CancellationToken | cancellationToken |
Returns
Type | Description |
---|---|
Task<UpdateSummary> |
GetOutputsAsync(CancellationToken)
Gets the current set of Stack outputs from the last UpAsync(UpOptions?, CancellationToken).
Declaration
public Task<ImmutableDictionary<string, OutputValue>> GetOutputsAsync(CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
CancellationToken | cancellationToken |
Returns
Type | Description |
---|---|
Task<ImmutableDictionary<string, OutputValue>> |
GetTagAsync(string, CancellationToken)
Returns the value associated with the stack and key, scoped to the Workspace.
Declaration
public Task<string> GetTagAsync(string key, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
string | key | The key to use for the tag lookup. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<string> |
ImportStackAsync(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 Task ImportStackAsync(StackDeployment state, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
StackDeployment | state | |
CancellationToken | cancellationToken |
Returns
Type | Description |
---|---|
Task |
ListTagsAsync(CancellationToken)
Returns the tag map for the stack, scoped to the current Workspace.
Declaration
public Task<Dictionary<string, string>> ListTagsAsync(CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<Dictionary<string, string>> |
PreviewAsync(PreviewOptions?, CancellationToken)
Performs a dry-run update to a stack, returning pending changes.
https://www.pulumi.com/docs/reference/cli/pulumi_preview/Declaration
public Task<PreviewResult> PreviewAsync(PreviewOptions? options = null, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
PreviewOptions | options | Options to customize the behavior of the update. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<PreviewResult> |
RefreshAsync(RefreshOptions?, CancellationToken)
Compares the current stack’s resource state with the state known to exist in the actual cloud provider. Any such changes are adopted into the current stack.
Declaration
public Task<UpdateResult> RefreshAsync(RefreshOptions? options = null, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
RefreshOptions | options | Options to customize the behavior of the refresh. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<UpdateResult> |
RefreshConfigAsync(CancellationToken)
Gets and sets the config map used with the last update.
Declaration
public Task<ImmutableDictionary<string, ConfigValue>> RefreshConfigAsync(CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<ImmutableDictionary<string, ConfigValue>> |
RemoveAllConfigAsync(IEnumerable<string>, CancellationToken)
Removes the specified config keys from the Stack in the associated Workspace.
Declaration
public Task RemoveAllConfigAsync(IEnumerable<string> keys, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<string> | keys | The config keys to remove. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task |
RemoveConfigAsync(string, CancellationToken)
Removes the specified config key from the Stack in the associated Workspace.
Declaration
public Task RemoveConfigAsync(string key, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
string | key | The config key to remove. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task |
RemoveTagAsync(string, CancellationToken)
Sets the specified key-value pair on the stack.
Declaration
public Task RemoveTagAsync(string key, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
string | key | The tag key to set. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task |
SelectAsync(string, Workspace, CancellationToken)
Selects stack using the given workspace, and stack name. It returns an error if the given Stack does not exist.
Declaration
public static Task<WorkspaceStack> SelectAsync(string name, Workspace workspace, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
string | name | The name identifying the stack. |
Workspace | workspace | The Workspace the Stack was created from. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<WorkspaceStack> |
Exceptions
Type | Condition |
---|---|
StackNotFoundException | If a stack with the provided name does not exists. |
SetAllConfigAsync(IDictionary<string, ConfigValue>, CancellationToken)
Sets all specified config values on the stack in the associated Workspace.
Declaration
public Task SetAllConfigAsync(IDictionary<string, ConfigValue> configMap, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
IDictionary<string, ConfigValue> | configMap | The map of config key-value pairs to set. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task |
SetConfigAsync(string, ConfigValue, CancellationToken)
Sets the config key-value pair on the Stack in the associated Workspace.
Declaration
public Task SetConfigAsync(string key, ConfigValue value, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
string | key | The key to set. |
ConfigValue | value | The config value to set. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task |
SetTagAsync(string, string, CancellationToken)
Sets the specified key-value pair on the stack.
Declaration
public Task SetTagAsync(string key, string value, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
string | key | The tag key to set. |
string | value | The tag value to set. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task |
UpAsync(UpOptions?, CancellationToken)
Creates or updates the resources in a stack by executing the program in the Workspace.
https://www.pulumi.com/docs/reference/cli/pulumi_up/Declaration
public Task<UpResult> UpAsync(UpOptions? options = null, CancellationToken cancellationToken = default)
Parameters
Type | Name | Description |
---|---|---|
UpOptions | options | Options to customize the behavior of the update. |
CancellationToken | cancellationToken | A cancellation token. |
Returns
Type | Description |
---|---|
Task<UpResult> |