Package com.pulumi.automation

Class WorkspaceStack

java.lang.Object
com.pulumi.automation.WorkspaceStack
All Implemented Interfaces:
AutoCloseable
public final class WorkspaceStack extends Object implements AutoCloseable
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 close the Workspace on close().

  • Method Details

    • name

      public String name()
      Gets the name identifying the Stack.
      Returns:
      the stack name

    • workspace

      public Workspace workspace()
      Gets the Workspace the Stack was created from.
      Returns:
      the workspace

    • state

      public WorkspaceStackState state()
      Gets a module for editing the Stack's state.
      Returns:
      the module for editing the stack's state

    • create

      public static WorkspaceStack create(String name, Workspace workspace) throws AutomationException
      Creates a new stack using the given workspace, and stack name. It fails if a stack with that name already exists.
      Parameters:
      name - the name identifying the stack
      workspace - the workspace the stack was created from
      Returns:
      the stack
      Throws:
      StackAlreadyExistsException - if a stack with the provided name already exists
      AutomationException - if an error occurs

    • select

      public static WorkspaceStack select(String name, Workspace workspace) throws AutomationException
      Selects stack using the given workspace, and stack name. It returns an error if the given Stack does not exist.
      Parameters:
      name - the name identifying the stack
      workspace - the workspace the stack was created from
      Returns:
      the stack
      Throws:
      StackNotFoundException - if a stack with the provided name does not exist
      AutomationException - if an error occurs

    • createOrSelect

      public static WorkspaceStack createOrSelect(String name, Workspace workspace) throws AutomationException
      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.
      Parameters:
      name - the name identifying the stack
      workspace - the workspace the stack was created from
      Returns:
      the stack
      Throws:
      AutomationException - if an error occurs

    • getTag

      public String getTag(String key) throws AutomationException
      Returns the value associated with the stack and key, scoped to the Workspace.
      Parameters:
      key - the key to use for the tag lookup
      Returns:
      the value associated with the key
      Throws:
      AutomationException - if an error occurs

    • setTag

      public void setTag(String key, String value) throws AutomationException
      Sets the specified key-value pair on the stack.
      Parameters:
      key - the tag key to set
      value - the tag value to set
      Throws:
      AutomationException - if an error occurs

    • removeTag

      public void removeTag(String key) throws AutomationException
      Removes the specified key-value pair on the provided stack name.
      Parameters:
      key - the tag key to remove
      Throws:
      AutomationException - if an error occurs

    • listTags

      public Map<String,String> listTags() throws AutomationException
      Returns the tag map for the specified stack name, scoped to the current Workspace.
      Returns:
      the tag map for the specified stack name
      Throws:
      AutomationException - if an error occurs

    • getConfig

      public ConfigValue getConfig(String key) throws AutomationException
      Returns the config value associated with the specified key.
      Parameters:
      key - the key to use for the config lookup
      Returns:
      the value associated with the key
      Throws:
      AutomationException - if an error occurs

    • getConfig

      public ConfigValue getConfig(String key, boolean path) throws AutomationException
      Returns the config value associated with the specified key.
      Parameters:
      key - the key to use for the config lookup
      path - the key contains a path to a property in a map or list to get
      Returns:
      the value associated with the key
      Throws:
      AutomationException - if an error occurs

    • getAllConfig

      public Map<String,ConfigValue> getAllConfig() throws AutomationException
      Returns the full config map associated with the stack in the Workspace.
      Returns:
      the config map
      Throws:
      AutomationException - if an error occurs

    • setConfig

      public void setConfig(String key, ConfigValue value) throws AutomationException
      Sets the config key-value pair on the Stack in the associated Workspace.
      Parameters:
      key - the config key to set
      value - the config value to set
      Throws:
      AutomationException - if an error occurs

    • setConfig

      public void setConfig(String key, ConfigValue value, boolean path) throws AutomationException
      Sets the config key-value pair on the Stack in the associated Workspace.
      Parameters:
      key - the config key to set
      value - the config value to set
      path - the key contains a path to a property in a map or list to set
      Throws:
      AutomationException - if an error occurs

    • setAllConfig

      public void setAllConfig(Map<String,ConfigValue> configMap) throws AutomationException
      Sets all specified config values on the stack in the associated Workspace.
      Parameters:
      configMap - the map of config key-value pairs to set
      Throws:
      AutomationException - if an error occurs

    • setAllConfig

      public void setAllConfig(Map<String,ConfigValue> configMap, boolean path) throws AutomationException
      Sets all specified config values on the stack in the associated Workspace.
      Parameters:
      configMap - the map of config key-value pairs to set
      path - the keys contain a path to a property in a map or list to set
      Throws:
      AutomationException - if an error occurs

    • removeConfig

      public void removeConfig(String key) throws AutomationException
      Removes the specified config key from the Stack in the associated Workspace.
      Parameters:
      key - the config key to remove
      Throws:
      AutomationException - if an error occurs

    • removeConfig

      public void removeConfig(String key, boolean path) throws AutomationException
      Removes the specified config key from the Stack in the associated Workspace.
      Parameters:
      key - the config key to remove
      path - the key contains a path to a property in a map or list to remove
      Throws:
      AutomationException - if an error occurs

    • removeAllConfig

      public void removeAllConfig(Collection<String> keys) throws AutomationException
      Removes the specified config keys from the Stack in the associated Workspace.
      Parameters:
      keys - the config keys to remove
      Throws:
      AutomationException - if an error occurs

    • removeAllConfig

      public void removeAllConfig(Collection<String> keys, boolean path) throws AutomationException
      Removes the specified config keys from the Stack in the associated Workspace.
      Parameters:
      keys - the config keys to remove
      path - the keys contain a path to a property in a map or list to remove
      Throws:
      AutomationException - if an error occurs

    • refreshConfig

      public Map<String,ConfigValue> refreshConfig() throws AutomationException
      Gets and sets the config map used with the last update.
      Returns:
      the config map used with the last update
      Throws:
      AutomationException - if an error occurs

    • addEnvironments

      public void addEnvironments(Collection<String> environments) throws AutomationException
      Adds environments to the end of the 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.
      Parameters:
      environments - list of environments to add to the end of the stack's import list
      Throws:
      AutomationException - if an error occurs

    • removeEnvironment

      public void removeEnvironment(String environment) throws AutomationException
      Removes environments from the stack's import list.
      Parameters:
      environment - the name of the environment to remove from the stack's configuration
      Throws:
      AutomationException - if an error occurs

    • changeSecretsProvider

      public void changeSecretsProvider(String newSecretsProvider) throws AutomationException
      Change the secrets provider for a stack.
      Parameters:
      newSecretsProvider - the new secrets provider
      Throws:
      AutomationException - if an error occurs

    • changeSecretsProvider

      public void changeSecretsProvider(String newSecretsProvider, @Nullable SecretsProviderOptions options) throws AutomationException
      Change the secrets provider for the stack.
      Parameters:
      newSecretsProvider - the new secrets provider
      options - the options to change the secrets provider
      Throws:
      AutomationException - if an error occurs

    • up

      public UpResult up() throws AutomationException
      Creates or updates the resources in a stack by executing the program in the Workspace.

      https://www.pulumi.com/docs/reference/cli/pulumi_up/

      Returns:
      the result of the update
      Throws:
      AutomationException - if an error occurs

    • up

      public UpResult up(UpOptions options) throws AutomationException
      Creates or updates the resources in a stack by executing the program in the Workspace.

      https://www.pulumi.com/docs/reference/cli/pulumi_up/

      Parameters:
      options - options to customize the behavior of the update
      Returns:
      the result of the update
      Throws:
      AutomationException - if an error occurs

    • preview

      public PreviewResult preview() throws AutomationException
      Performs a dry-run update to a stack, returning pending changes.
      Returns:
      the result of the preview
      Throws:
      AutomationException - if an error occurs

    • preview

      public PreviewResult preview(PreviewOptions options) throws AutomationException
      Performs a dry-run update to a stack, returning pending changes.
      Parameters:
      options - options to customize the behavior of the update
      Returns:
      the result of the preview
      Throws:
      AutomationException - if an error occurs

    • refresh

      public UpdateResult refresh() throws AutomationException
      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.
      Returns:
      the result of the refresh
      Throws:
      AutomationException - if an error occurs

    • refresh

      public UpdateResult refresh(RefreshOptions options) throws AutomationException
      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.
      Parameters:
      options - options to customize the behavior of the refresh
      Returns:
      the result of the refresh
      Throws:
      AutomationException - if an error occurs

    • destroy

      public UpdateResult destroy() throws AutomationException
      Destroy deletes all resources in a stack, leaving all history and configuration intact.
      Returns:
      the result of the destroy
      Throws:
      AutomationException - if an error occurs

    • destroy

      public UpdateResult destroy(DestroyOptions options) throws AutomationException
      Destroy deletes all resources in a stack, leaving all history and configuration intact.
      Parameters:
      options - options to customize the behavior of the destroy
      Returns:
      the result of the destroy
      Throws:
      AutomationException - if an error occurs

    • getOutputs

      public Map<String,OutputValue> getOutputs() throws AutomationException
      Gets the current set of Stack outputs from the last up() call.
      Returns:
      the current set of stack outputs
      Throws:
      AutomationException - if an error occurs

    • getHistory

      public List<UpdateSummary> getHistory() throws AutomationException
      Returns a list summarizing all previews and current results from Stack lifecycle operations (up/preview/refresh/destroy).
      Returns:
      the list of summaries
      Throws:
      AutomationException - if an error occurs

    • getHistory

      public List<UpdateSummary> getHistory(HistoryOptions options) throws AutomationException
      Returns a list summarizing all previews and current results from Stack lifecycle operations (up/preview/refresh/destroy).
      Parameters:
      options - options to customize the behavior of the fetch history action
      Returns:
      the list of summaries
      Throws:
      AutomationException - if an error occurs

    • exportStack

      public StackDeployment exportStack() throws AutomationException
      Exports the deployment state of the stack.

      This can be combined with importStack(com.pulumi.automation.StackDeployment) to edit a stack's state (such as recovery from failed deployments).

      Returns:
      the deployment state of the stack
      Throws:
      AutomationException - if an error occurs

    • importStack

      public void importStack(StackDeployment state) throws AutomationException
      Imports the specified deployment state into a pre-existing stack.

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

      Parameters:
      state - the deployment state to import
      Throws:
      AutomationException - if an error occurs

    • getInfo

      public Optional<UpdateSummary> getInfo() throws AutomationException
      Returns the current update summary for the stack.
      Returns:
      the current update summary for the stack
      Throws:
      AutomationException - if an error occurs

    • cancel

      public void cancel() throws AutomationException
      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.
      Throws:
      AutomationException - if an error occurs

    • close

      public void close() throws Exception
      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception