Package com.pulumi.automation

Class Workspace

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

    • workDir

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

    • pulumiHome

      @Nullable public abstract 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 String pulumiVersion()
      The version of the underlying Pulumi CLI/Engine.
      Returns:
      the version

    • secretsProvider

      @Nullable public abstract 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 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 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 Map<String,String> environmentVariables()
      Environment values scoped to the current workspace. These will be supplied to every Pulumi command.
      Returns:
      the environment variables

    • getProjectSettings

      public abstract 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 Optional<StackSettings> getStackSettings(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(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 List<String> serializeArgsForOp(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(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(String stackName, Collection<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(String stackName, 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 String getTag(String stackName, 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(String stackName, String key, 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(String stackName, 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 Map<String,String> listTags(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(String stackName, 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(String stackName, 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 Map<String,ConfigValue> getAllConfig(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(String stackName, 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(String stackName, 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(String stackName, Map<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(String stackName, Map<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(String stackName, 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(String stackName, 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(String stackName, Collection<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(String stackName, Collection<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 Map<String,ConfigValue> refreshConfig(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

    • whoAmI

      public abstract WhoAmIResult whoAmI() throws AutomationException
      Returns the currently authenticated user.
      Returns:
      the currently authenticated user
      Throws:
      AutomationException - if there was an issue determining the current user

    • getStack

      public 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(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(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(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 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

    • exportStack

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

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

      Parameters:
      stackName - the stack to export
      Returns:
      the deployment state of the stack
      Throws:
      AutomationException - if there was an issue exporting the stack

    • importStack

      public abstract void importStack(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(String name, 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(String name, 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

    • removePlugin

      public abstract void removePlugin(PluginRemoveOptions options) throws AutomationException
      Removes a plugin or plugins from the Workspace.
      Parameters:
      options - plugin removal options
      Throws:
      AutomationException - if there was an issue removing the plugin

    • listPlugins

      public abstract 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 Map<String,OutputValue> getStackOutputs(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(String stackName, 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(String stackName, 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