Package com.pulumi.automation

Class Workspace

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    Direct Known Subclasses:
    LocalWorkspace
    public abstract class Workspace
extends java.lang.Object
implements java.lang.AutoCloseable
    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.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract void addEnvironments​(java.lang.String stackName, java.util.Collection<java.lang.String> environments)
      Adds environments to the end of a stack's import list.
      void changeSecretsProvider​(java.lang.String stackName, java.lang.String newSecretsProvider)
      Change the secrets provider for a stack.
      abstract void changeSecretsProvider​(java.lang.String stackName, java.lang.String newSecretsProvider, SecretsProviderOptions options)
      Change the secrets provider for a stack.
      abstract void createStack​(java.lang.String stackName)
      Creates and sets a new stack with the specified stack name, failing if one already exists.
      abstract java.util.Map<java.lang.String,​java.lang.String> environmentVariables()
      Environment values scoped to the current workspace.
      abstract StackDeployment exportStack​(java.lang.String stackName)
      Exports the deployment state of the stack.
      abstract java.util.Map<java.lang.String,​ConfigValue> getAllConfig​(java.lang.String stackName)
      Returns the config map for the specified stack name, scoped to the current Workspace.
      ConfigValue getConfig​(java.lang.String stackName, java.lang.String key)
      Returns the value associated with the specified stack name and key, scoped to the Workspace.
      abstract ConfigValue getConfig​(java.lang.String stackName, java.lang.String key, boolean path)
      Returns the value associated with the specified stack name and key, scoped to the Workspace.
      abstract java.util.Optional<ProjectSettings> getProjectSettings()
      Returns project settings for the current project if any.
      java.util.Optional<StackSummary> getStack()
      Returns a summary of the currently selected stack, if any.
      abstract java.util.Map<java.lang.String,​OutputValue> getStackOutputs​(java.lang.String stackName)
      Gets the current set of Stack outputs from the last WorkspaceStack.up() call.
      abstract java.util.Optional<StackSettings> getStackSettings​(java.lang.String stackName)
      Returns stack settings for the stack matching the specified stack name if any.
      abstract java.lang.String getTag​(java.lang.String stackName, java.lang.String key)
      Returns the value associated with the stack and key, scoped to the Workspace.
      abstract void importStack​(java.lang.String stackName, StackDeployment state)
      Imports the specified deployment state into a pre-existing stack.
      void installPlugin​(java.lang.String name, java.lang.String version)
      Installs a plugin in the Workspace, for example to use cloud providers like AWS or GCP.
      abstract void installPlugin​(java.lang.String name, java.lang.String version, PluginInstallOptions options)
      Installs a plugin in the Workspace, for example to use cloud providers like AWS or GCP.
      abstract java.util.List<PluginInfo> listPlugins()
      Returns a list of all plugins installed in the Workspace.
      abstract java.util.List<StackSummary> listStacks()
      Returns all stacks created under the current project.
      abstract java.util.Map<java.lang.String,​java.lang.String> listTags​(java.lang.String stackName)
      Returns the tag map for the specified stack name, scoped to the current Workspace.
      abstract java.util.logging.Logger logger()
      A custom logger instance that will be used for the action.
      abstract void postCommandCallback​(java.lang.String stackName)
      Hook executed after every command.
      abstract java.util.function.Consumer<Context> program()
      The inline program to be used for Preview/Update operations if any.
      abstract java.nio.file.Path pulumiHome()
      The directory override for CLI metadata if set.
      abstract java.lang.String pulumiVersion()
      The version of the underlying Pulumi CLI/Engine.
      abstract java.util.Map<java.lang.String,​ConfigValue> refreshConfig​(java.lang.String stackName)
      Gets and sets the config map used with the last update for the stack matching the specified stack name.
      void removeAllConfig​(java.lang.String stackName, java.util.Collection<java.lang.String> keys)
      Removes all values in the provided key collection from the config map for the specified stack name.
      abstract void removeAllConfig​(java.lang.String stackName, java.util.Collection<java.lang.String> keys, boolean path)
      Removes all values in the provided key collection from the config map for the specified stack name.
      void removeConfig​(java.lang.String stackName, java.lang.String key)
      Removes the specified key-value pair from the provided stack's config.
      abstract void removeConfig​(java.lang.String stackName, java.lang.String key, boolean path)
      Removes the specified key-value pair from the provided stack's config.
      abstract void removeEnvironment​(java.lang.String stackName, java.lang.String environment)
      Removes environments from a stack's import list.
      abstract void removePlugin​(PluginRemoveOptions options)
      Removes a plugin or plugins from the Workspace.
      abstract void removeStack​(java.lang.String stackName)
      Deletes the stack and all associated configuration and history.
      abstract void removeTag​(java.lang.String stackName, java.lang.String key)
      Removes the specified key-value pair on the provided stack name.
      abstract void saveProjectSettings​(ProjectSettings settings)
      Overwrites the settings for the current project.
      abstract void saveStackSettings​(java.lang.String stackName, StackSettings settings)
      Overwrite the settings for the stack matching the specified stack name.
      abstract java.lang.String secretsProvider()
      The secrets provider to use for encryption and decryption of stack secrets.
      abstract void selectStack​(java.lang.String stackName)
      Selects and sets an existing stack matching the stack name, failing if none exists.
      abstract java.util.List<java.lang.String> serializeArgsForOp​(java.lang.String stackName)
      Hook to provide additional args to every CLI command before they are executed.
      void setAllConfig​(java.lang.String stackName, java.util.Map<java.lang.String,​ConfigValue> configMap)
      Sets all values in the provided config map for the specified stack name.
      abstract void setAllConfig​(java.lang.String stackName, java.util.Map<java.lang.String,​ConfigValue> configMap, boolean path)
      Sets all values in the provided config map for the specified stack name.
      void setConfig​(java.lang.String stackName, java.lang.String key, ConfigValue value)
      Sets the specified key-value pair in the provided stack's config.
      abstract void setConfig​(java.lang.String stackName, java.lang.String key, ConfigValue value, boolean path)
      Sets the specified key-value pair in the provided stack's config.
      abstract void setTag​(java.lang.String stackName, java.lang.String key, java.lang.String value)
      Sets the specified key-value pair on the provided stack name.
      abstract WhoAmIResult whoAmI()
      Returns the currently authenticated user.
      abstract java.nio.file.Path workDir()
      The working directory to run Pulumi CLI commands.

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.lang.AutoCloseable

        close

    • Method Detail

      • workDir

        public abstract java.nio.file.Path workDir()
        The working directory to run Pulumi CLI commands.
        Returns:
        the working directory

      • pulumiHome

        @Nullable
public abstract java.nio.file.Path pulumiHome()
        The directory override for CLI metadata if set.

        This customizes the location of $PULUMI_HOME where metadata is stored and plugins are installed.

        Returns:
        the directory override

      • pulumiVersion

        public abstract java.lang.String pulumiVersion()
        The version of the underlying Pulumi CLI/Engine.
        Returns:
        the version

      • secretsProvider

        @Nullable
public abstract java.lang.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

        Returns:
        the secrets provider

      • program

        @Nullable
public abstract java.util.function.Consumer<Context> program()
        The inline program to be used for Preview/Update operations if any.

        If non specified, the stack will refer to ProjectSettings for this information.

        Returns:
        the inline program

      • logger

        @Nullable
public abstract java.util.logging.Logger logger()
        A custom logger instance that will be used for the action. Note that it will only be used program() is also provided.
        Returns:
        The logger

      • environmentVariables

        public abstract java.util.Map<java.lang.String,​java.lang.String> environmentVariables()
        Environment values scoped to the current workspace. These will be supplied to every Pulumi command.
        Returns:
        the environment variables

      • getProjectSettings

        public abstract java.util.Optional<ProjectSettings> getProjectSettings()
                                                                throws AutomationException
        Returns project settings for the current project if any.
        Returns:
        the project settings
        Throws:
        AutomationException - if there was an issue retrieving the project

      • saveProjectSettings

        public abstract void saveProjectSettings​(ProjectSettings settings)
                                  throws AutomationException
        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.

        Parameters:
        settings - the settings object to save
        Throws:
        AutomationException - if there was an issue saving the project

      • getStackSettings

        public abstract java.util.Optional<StackSettings> getStackSettings​(java.lang.String stackName)
                                                            throws AutomationException
        Returns stack settings for the stack matching the specified stack name if any.
        Parameters:
        stackName - the name of the stack
        Returns:
        the stack settings
        Throws:
        AutomationException - if there was an issue retrieving the stack

      • saveStackSettings

        public abstract void saveStackSettings​(java.lang.String stackName,
                                       StackSettings settings)
                                throws AutomationException
        Overwrite the settings for the stack matching the specified stack name.
        Parameters:
        stackName - the name of the stack to operation on
        settings - the settings object to save
        Throws:
        AutomationException - if there was an issue saving the stack

      • serializeArgsForOp

        public abstract java.util.List<java.lang.String> serializeArgsForOp​(java.lang.String stackName)
        Hook to provide additional args to every CLI command before they are executed.

        Provided with a stack name, returns a list of args to append to an invoked command ["--config=...", ].

        LocalWorkspace does not utilize this extensibility point.

        Parameters:
        stackName - the name of the stack
        Returns:
        the list of args to append

      • postCommandCallback

        public abstract void postCommandCallback​(java.lang.String stackName)
                                  throws AutomationException
        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.

        Parameters:
        stackName - the name of the stack
        Throws:
        AutomationException - if there was an issue executing the post command

      • addEnvironments

        public abstract void addEnvironments​(java.lang.String stackName,
                                     java.util.Collection<java.lang.String> environments)
                              throws AutomationException
        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.
        Parameters:
        stackName - the name of the stack
        environments - list of environments to add to the end of the stack's import list
        Throws:
        AutomationException - if there was an issue adding the environments

      • removeEnvironment

        public abstract void removeEnvironment​(java.lang.String stackName,
                                       java.lang.String environment)
                                throws AutomationException
        Removes environments from a stack's import list.
        Parameters:
        stackName - the name of the stack
        environment - the name of the environment to remove from the stack's configuration
        Throws:
        AutomationException - if there was an issue removing the environment

      • getTag

        public abstract java.lang.String getTag​(java.lang.String stackName,
                                        java.lang.String key)
                                 throws AutomationException
        Returns the value associated with the stack and key, scoped to the Workspace.
        Parameters:
        stackName - the name of the stack to read tag metadata from
        key - the key to use for the tag lookup
        Returns:
        the value associated with the key
        Throws:
        AutomationException - if there was an issue reading the tag

      • setTag

        public abstract void setTag​(java.lang.String stackName,
                            java.lang.String key,
                            java.lang.String value)
                     throws AutomationException
        Sets the specified key-value pair on the provided stack name.
        Parameters:
        stackName - the stack to operate on
        key - the tag key to set
        value - the tag value to set
        Throws:
        AutomationException - if there was an issue setting the tag

      • removeTag

        public abstract void removeTag​(java.lang.String stackName,
                               java.lang.String key)
                        throws AutomationException
        Removes the specified key-value pair on the provided stack name.
        Parameters:
        stackName - the stack to operate on
        key - the tag key to remove
        Throws:
        AutomationException - if there was an issue removing the tag

      • listTags

        public abstract java.util.Map<java.lang.String,​java.lang.String> listTags​(java.lang.String stackName)
                                                                         throws AutomationException
        Returns the tag map for the specified stack name, scoped to the current Workspace.
        Parameters:
        stackName - the stack to operate on
        Returns:
        the tag map for the specified stack name
        Throws:
        AutomationException - if there was an issue listing the tags

      • getConfig

        public ConfigValue getConfig​(java.lang.String stackName,
                             java.lang.String key)
                      throws AutomationException
        Returns the value associated with the specified stack name and key, scoped to the Workspace.
        Parameters:
        stackName - the name of the stack to read config from
        key - the key to use for the config lookup
        Returns:
        the value associated with the key
        Throws:
        AutomationException - if there was an issue reading the config

      • getConfig

        public abstract ConfigValue getConfig​(java.lang.String stackName,
                                      java.lang.String key,
                                      boolean path)
                               throws AutomationException
        Returns the value associated with the specified stack name and key, scoped to the Workspace.
        Parameters:
        stackName - the name of the stack to read config from
        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 there was an issue reading the config

      • getAllConfig

        public abstract java.util.Map<java.lang.String,​ConfigValue> getAllConfig​(java.lang.String stackName)
                                                                        throws AutomationException
        Returns the config map for the specified stack name, scoped to the current Workspace.
        Parameters:
        stackName - the name of the stack to read config from
        Returns:
        the config map for the specified stack name
        Throws:
        AutomationException - if there was an issue listing the config

      • setConfig

        public void setConfig​(java.lang.String stackName,
                      java.lang.String key,
                      ConfigValue value)
               throws AutomationException
        Sets the specified key-value pair in the provided stack's config.
        Parameters:
        stackName - the name of the stack to operate on
        key - the config key to set
        value - the config value to set
        Throws:
        AutomationException - if there was an issue setting the config

      • setConfig

        public abstract void setConfig​(java.lang.String stackName,
                               java.lang.String key,
                               ConfigValue value,
                               boolean path)
                        throws AutomationException
        Sets the specified key-value pair in the provided stack's config.
        Parameters:
        stackName - the name of the stack to operate on
        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 there was an issue setting the config

      • setAllConfig

        public void setAllConfig​(java.lang.String stackName,
                         java.util.Map<java.lang.String,​ConfigValue> configMap)
                  throws AutomationException
        Sets all values in the provided config map for the specified stack name.
        Parameters:
        stackName - the name of the stack to operate on
        configMap - the config map to upsert against the existing config
        Throws:
        AutomationException - if there was an issue setting the config

      • setAllConfig

        public abstract void setAllConfig​(java.lang.String stackName,
                                  java.util.Map<java.lang.String,​ConfigValue> configMap,
                                  boolean path)
                           throws AutomationException
        Sets all values in the provided config map for the specified stack name.
        Parameters:
        stackName - the name of the stack to operate on
        configMap - the config map to upsert against the existing config
        path - the keys contain a path to a property in a map or list to set
        Throws:
        AutomationException - if there was an issue setting the config

      • removeConfig

        public void removeConfig​(java.lang.String stackName,
                         java.lang.String key)
                  throws AutomationException
        Removes the specified key-value pair from the provided stack's config.
        Parameters:
        stackName - the name of the stack to operate on
        key - the config key to remove
        Throws:
        AutomationException - if there was an issue removing the config

      • removeConfig

        public abstract void removeConfig​(java.lang.String stackName,
                                  java.lang.String key,
                                  boolean path)
                           throws AutomationException
        Removes the specified key-value pair from the provided stack's config.
        Parameters:
        stackName - the name of the stack to operate on
        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 there was an issue removing the config

      • removeAllConfig

        public void removeAllConfig​(java.lang.String stackName,
                            java.util.Collection<java.lang.String> keys)
                     throws AutomationException
        Removes all values in the provided key collection from the config map for the specified stack name.
        Parameters:
        stackName - the name of the stack to operate on
        keys - the collection of keys to remove from the underlying config map
        Throws:
        AutomationException - if there was an issue removing the config

      • removeAllConfig

        public abstract void removeAllConfig​(java.lang.String stackName,
                                     java.util.Collection<java.lang.String> keys,
                                     boolean path)
                              throws AutomationException
        Removes all values in the provided key collection from the config map for the specified stack name.
        Parameters:
        stackName - the name of the stack to operate on
        keys - the collection of keys to remove from the underlying config map
        path - the keys contain a path to a property in a map or list to remove
        Throws:
        AutomationException - if there was an issue removing the config

      • refreshConfig

        public abstract java.util.Map<java.lang.String,​ConfigValue> refreshConfig​(java.lang.String stackName)
                                                                         throws AutomationException
        Gets and sets the config map used with the last update for the stack matching the specified stack name.
        Parameters:
        stackName - the name of the stack to operate on
        Returns:
        the config map used with the last update for the stack
        Throws:
        AutomationException - if there was an issue refreshing the config

      • getStack

        public java.util.Optional<StackSummary> getStack()
                                          throws AutomationException
        Returns a summary of the currently selected stack, if any.
        Returns:
        the summary of the currently selected stack
        Throws:
        AutomationException - if there was an issue getting the stack

      • createStack

        public abstract void createStack​(java.lang.String stackName)
                          throws AutomationException
        Creates and sets a new stack with the specified stack name, failing if one already exists.
        Parameters:
        stackName - the stack to create
        Throws:
        AutomationException - if there was an issue creating the stack

      • selectStack

        public abstract void selectStack​(java.lang.String stackName)
                          throws AutomationException
        Selects and sets an existing stack matching the stack name, failing if none exists.
        Parameters:
        stackName - the stack to select
        Throws:
        StackNotFoundException - if the stack does not exist
        AutomationException - if there was an issue selecting the stack

      • removeStack

        public abstract void removeStack​(java.lang.String stackName)
                          throws AutomationException
        Deletes the stack and all associated configuration and history.
        Parameters:
        stackName - the stack to remove
        Throws:
        AutomationException - if there was an issue removing the stack

      • listStacks

        public abstract java.util.List<StackSummary> listStacks()
                                                 throws AutomationException
        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).

        Returns:
        the list of stacks
        Throws:
        AutomationException - if there was an issue listing the stacks

      • importStack

        public abstract void importStack​(java.lang.String stackName,
                                 StackDeployment state)
                          throws AutomationException
        Imports the specified deployment state into a pre-existing stack.

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

        Parameters:
        stackName - the stack to import
        state - the deployment state to import
        Throws:
        AutomationException - if there was an issue importing the stack

      • installPlugin

        public void installPlugin​(java.lang.String name,
                          java.lang.String version)
                   throws AutomationException
        Installs a plugin in the Workspace, for example to use cloud providers like AWS or GCP.
        Parameters:
        name - the name of the plugin
        version - the version of the plugin, e.g. "v1.0.0"
        Throws:
        AutomationException - if there was an issue installing the plugin

      • installPlugin

        public abstract void installPlugin​(java.lang.String name,
                                   java.lang.String version,
                                   PluginInstallOptions options)
                            throws AutomationException
        Installs a plugin in the Workspace, for example to use cloud providers like AWS or GCP.
        Parameters:
        name - the name of the plugin
        version - the version of the plugin, e.g. "v1.0.0"
        options - additional plugin installation options
        Throws:
        AutomationException - if there was an issue installing the plugin

      • listPlugins

        public abstract java.util.List<PluginInfo> listPlugins()
                                                throws AutomationException
        Returns a list of all plugins installed in the Workspace.
        Returns:
        the list of plugins
        Throws:
        AutomationException - if there was an issue listing the plugins

      • getStackOutputs

        public abstract java.util.Map<java.lang.String,​OutputValue> getStackOutputs​(java.lang.String stackName)
                                                                           throws AutomationException
        Gets the current set of Stack outputs from the last WorkspaceStack.up() call.
        Parameters:
        stackName - the name of the stack
        Returns:
        the stack outputs
        Throws:
        AutomationException - if there was an issue getting the stack outputs

      • changeSecretsProvider

        public void changeSecretsProvider​(java.lang.String stackName,
                                  java.lang.String newSecretsProvider)
                           throws AutomationException
        Change the secrets provider for a stack.
        Parameters:
        stackName - the name of the stack
        newSecretsProvider - the new secrets provider
        Throws:
        AutomationException - if there was an issue changing the secrets provider

      • changeSecretsProvider

        public abstract void changeSecretsProvider​(java.lang.String stackName,
                                           java.lang.String newSecretsProvider,
                                           @Nullable
                                           SecretsProviderOptions options)
                                    throws AutomationException
        Change the secrets provider for a stack.
        Parameters:
        stackName - the name of the stack
        newSecretsProvider - the new secrets provider
        options - the options to change the secrets provider
        Throws:
        AutomationException - if there was an issue changing the secrets provider