Package com.pulumi.automation

Class WorkspaceStack

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    public final class WorkspaceStack
extends java.lang.Object
implements java.lang.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 Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addEnvironments​(java.util.Collection<java.lang.String> environments)
      Adds environments to the end of the stack's import list.
      void cancel()
      Cancel stops a stack's currently running update.
      void changeSecretsProvider​(java.lang.String newSecretsProvider)
      Change the secrets provider for a stack.
      void changeSecretsProvider​(java.lang.String newSecretsProvider, SecretsProviderOptions options)
      Change the secrets provider for the stack.
      void close()  
      static WorkspaceStack create​(java.lang.String name, Workspace workspace)
      Creates a new stack using the given workspace, and stack name.
      static WorkspaceStack createOrSelect​(java.lang.String name, Workspace workspace)
      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.
      UpdateResult destroy()
      Destroy deletes all resources in a stack, leaving all history and configuration intact.
      UpdateResult destroy​(DestroyOptions options)
      Destroy deletes all resources in a stack, leaving all history and configuration intact.
      StackDeployment exportStack()
      Exports the deployment state of the stack.
      java.util.Map<java.lang.String,​ConfigValue> getAllConfig()
      Returns the full config map associated with the stack in the Workspace.
      ConfigValue getConfig​(java.lang.String key)
      Returns the config value associated with the specified key.
      ConfigValue getConfig​(java.lang.String key, boolean path)
      Returns the config value associated with the specified key.
      java.util.List<UpdateSummary> getHistory()
      Returns a list summarizing all previews and current results from Stack lifecycle operations (up/preview/refresh/destroy).
      java.util.List<UpdateSummary> getHistory​(HistoryOptions options)
      Returns a list summarizing all previews and current results from Stack lifecycle operations (up/preview/refresh/destroy).
      java.util.Optional<UpdateSummary> getInfo()
      Returns the current update summary for the stack.
      java.util.Map<java.lang.String,​OutputValue> getOutputs()
      Gets the current set of Stack outputs from the last up() call.
      java.lang.String getTag​(java.lang.String key)
      Returns the value associated with the stack and key, scoped to the Workspace.
      void importStack​(StackDeployment state)
      Imports the specified deployment state into a pre-existing stack.
      java.util.Map<java.lang.String,​java.lang.String> listTags()
      Returns the tag map for the specified stack name, scoped to the current Workspace.
      java.lang.String name()
      Gets the name identifying the Stack.
      PreviewResult preview()
      Performs a dry-run update to a stack, returning pending changes.
      PreviewResult preview​(PreviewOptions options)
      Performs a dry-run update to a stack, returning pending changes.
      UpdateResult refresh()
      Compares the current stack's resource state with the state known to exist in the actual cloud provider.
      UpdateResult refresh​(RefreshOptions options)
      Compares the current stack's resource state with the state known to exist in the actual cloud provider.
      java.util.Map<java.lang.String,​ConfigValue> refreshConfig()
      Gets and sets the config map used with the last update.
      void removeAllConfig​(java.util.Collection<java.lang.String> keys)
      Removes the specified config keys from the Stack in the associated Workspace.
      void removeAllConfig​(java.util.Collection<java.lang.String> keys, boolean path)
      Removes the specified config keys from the Stack in the associated Workspace.
      void removeConfig​(java.lang.String key)
      Removes the specified config key from the Stack in the associated Workspace.
      void removeConfig​(java.lang.String key, boolean path)
      Removes the specified config key from the Stack in the associated Workspace.
      void removeEnvironment​(java.lang.String environment)
      Removes environments from the stack's import list.
      void removeTag​(java.lang.String key)
      Removes the specified key-value pair on the provided stack name.
      static WorkspaceStack select​(java.lang.String name, Workspace workspace)
      Selects stack using the given workspace, and stack name.
      void setAllConfig​(java.util.Map<java.lang.String,​ConfigValue> configMap)
      Sets all specified config values on the stack in the associated Workspace.
      void setAllConfig​(java.util.Map<java.lang.String,​ConfigValue> configMap, boolean path)
      Sets all specified config values on the stack in the associated Workspace.
      void setConfig​(java.lang.String key, ConfigValue value)
      Sets the config key-value pair on the Stack in the associated Workspace.
      void setConfig​(java.lang.String key, ConfigValue value, boolean path)
      Sets the config key-value pair on the Stack in the associated Workspace.
      void setTag​(java.lang.String key, java.lang.String value)
      Sets the specified key-value pair on the stack.
      WorkspaceStackState state()
      Gets a module for editing the Stack's state.
      UpResult up()
      Creates or updates the resources in a stack by executing the program in the Workspace.
      UpResult up​(UpOptions options)
      Creates or updates the resources in a stack by executing the program in the Workspace.
      Workspace workspace()
      Gets the Workspace the Stack was created from.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • name

        public java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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 java.lang.String getTag​(java.lang.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​(java.lang.String key,
                   java.lang.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​(java.lang.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 java.util.Map<java.lang.String,​java.lang.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​(java.lang.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​(java.lang.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 java.util.Map<java.lang.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​(java.lang.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​(java.lang.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​(java.util.Map<java.lang.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​(java.util.Map<java.lang.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​(java.lang.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​(java.lang.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​(java.util.Collection<java.lang.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​(java.util.Collection<java.lang.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 java.util.Map<java.lang.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​(java.util.Collection<java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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

      • 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​(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

      • getHistory

        public java.util.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 java.util.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

      • 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

      • 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 java.lang.Exception
        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        java.lang.Exception