Package com.pulumi.automation

Class LocalWorkspace

java.lang.Object
com.pulumi.automation.Workspace
com.pulumi.automation.LocalWorkspace
All Implemented Interfaces:
AutoCloseable
public final class LocalWorkspace extends Workspace
LocalWorkspace is a default implementation of the Workspace interface.

A 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.

LocalWorkspace relies on Pulumi.yaml and Pulumi.{stack}.yaml as the intermediate format for Project and Stack settings. Modifying ProjectSettings will alter the Workspace Pulumi.yaml file, and setting config on a Stack will modify the Pulumi.{stack}.yaml file. This is identical to the behavior of Pulumi CLI driven workspaces.

If not provided a working directory - causing LocalWorkspace to create a temp directory, then the temp directory will be cleaned up when close() is called.

  • Method Details

    • create

      public static LocalWorkspace create() throws AutomationException
      Creates a workspace.
      Returns:
      the workspace
      Throws:
      AutomationException - if an error occurs

    • create

      public static LocalWorkspace create(@Nullable LocalWorkspaceOptions options) throws AutomationException
      Creates a workspace using the specified options. Used for maximal control and customization of the underlying environment before any stacks are created or selected.
      Parameters:
      options - Options used to configure the workspace
      Returns:
      the workspace
      Throws:
      AutomationException - if an error occurs

    • createStack

      public static WorkspaceStack createStack(String projectName, String stackName, Consumer<Context> program) throws AutomationException
      Creates a stack with a LocalWorkspace utilizing the specified inline (in process) program. This program is fully debuggable and runs in process. Default project settings will be created on behalf of the user and the working directory will default to a new temporary directory provided by the OS.
      Parameters:
      projectName - the name of the project
      stackName - the name of the stack
      program - the program to run
      Returns:
      the stack
      Throws:
      StackAlreadyExistsException - if a stack with the provided name already exists
      AutomationException - if an error occurs

    • createStack

      public static WorkspaceStack createStack(String projectName, String stackName, Consumer<Context> program, LocalWorkspaceOptions options) throws AutomationException
      Creates a stack with a LocalWorkspace utilizing the specified inline (in process) program. This program is fully debuggable and runs in process. If no LocalWorkspaceOptions.projectSettings() option is specified, default project settings will be created on behalf of the user. Similarly, unless a LocalWorkspaceOptions.workDir() option is specified, the working directory will default to a new temporary directory provided by the OS.
      Parameters:
      projectName - the name of the project
      stackName - the name of the stack
      program - the program to run
      options - options used to configure the workspace
      Returns:
      the stack
      Throws:
      StackAlreadyExistsException - if a stack with the provided name already exists
      AutomationException - if an error occurs

    • createStack

      public static WorkspaceStack createStack(String stackName, Path workDir) throws AutomationException
      Creates a Stack with a LocalWorkspace utilizing the local Pulumi CLI program from the specified workDir. This is a way to create drivers on top of pre-existing Pulumi programs. This Workspace will pick up any available Settings files(Pulumi.yaml, Pulumi.{stack}.yaml).
      Parameters:
      stackName - the name of the stack
      workDir - the working directory
      Returns:
      the stack
      Throws:
      StackAlreadyExistsException - if a stack with the provided name already exists
      AutomationException - if an error occurs

    • createStack

      public static WorkspaceStack createStack(String stackName, Path workDir, LocalWorkspaceOptions options) throws AutomationException
      Creates a Stack with a LocalWorkspace utilizing the local Pulumi CLI program from the specified workDir. This is a way to create drivers on top of pre-existing Pulumi programs. This Workspace will pick up any available Settings files(Pulumi.yaml, Pulumi.{stack}.yaml).
      Parameters:
      stackName - the name of the stack
      workDir - the working directory
      options - options used to configure the workspace
      Returns:
      the stack
      Throws:
      StackAlreadyExistsException - if a stack with the provided name already exists
      AutomationException - if an error occurs

    • selectStack

      public static WorkspaceStack selectStack(String projectName, String stackName, Consumer<Context> program) throws AutomationException
      Selects an existing Stack with a LocalWorkspace utilizing the specified inline (in process) program. This program is fully debuggable and runs in process. Default project settings will be created on behalf of the user and the working directory will default to a new temporary directory provided by the OS.
      Parameters:
      projectName - the name of the project
      stackName - the name of the stack
      program - the program to run
      Returns:
      the stack
      Throws:
      StackNotFoundException - if a stack with the provided name does not exist
      AutomationException - if an error occurs

    • selectStack

      public static WorkspaceStack selectStack(String projectName, String stackName, Consumer<Context> program, LocalWorkspaceOptions options) throws AutomationException
      Selects an existing Stack with a LocalWorkspace utilizing the specified inline (in process) program. This program is fully debuggable and runs in process. If no LocalWorkspaceOptions.projectSettings() option is specified, default project settings will be created on behalf of the user. Similarly, unless a LocalWorkspaceOptions.workDir() option is specified, the working directory will default to a new temporary directory provided by the OS.
      Parameters:
      projectName - the name of the project
      stackName - the name of the stack
      program - the program to run
      options - options used to configure the workspace
      Returns:
      the stack
      Throws:
      StackNotFoundException - if a stack with the provided name does not exist
      AutomationException - if an error occurs

    • selectStack

      public static WorkspaceStack selectStack(String stackName, Path workDir) throws AutomationException
      Selects an existing Stack with a LocalWorkspace utilizing the local Pulumi CLI program from the specified workDir. This is a way to create drivers on top of pre-existing Pulumi programs. This Workspace will pick up any available Settings files(Pulumi.yaml, Pulumi.{stack}.yaml).
      Parameters:
      stackName - the name of the stack
      workDir - the working directory
      Returns:
      the stack
      Throws:
      StackNotFoundException - if a stack with the provided name does not exist
      AutomationException - if an error occurs

    • selectStack

      public static WorkspaceStack selectStack(String stackName, Path workDir, LocalWorkspaceOptions options) throws AutomationException
      Selects an existing Stack with a LocalWorkspace utilizing the local Pulumi CLI program from the specified workDir. This is a way to create drivers on top of pre-existing Pulumi programs. This Workspace will pick up any available Settings files(Pulumi.yaml, Pulumi.{stack}.yaml).
      Parameters:
      stackName - the name of the stack
      workDir - the working directory
      options - options used to configure the workspace
      Returns:
      the stack
      Throws:
      StackNotFoundException - if a stack with the provided name does not exist
      AutomationException - if an error occurs

    • createOrSelectStack

      public static WorkspaceStack createOrSelectStack(String projectName, String stackName, Consumer<Context> program) throws AutomationException
      Creates or selects an existing Stack with a LocalWorkspace utilizing the specified inline (in process) program. This program is fully debuggable and runs in process. Default project settings will be created on behalf of the user and the working directory will default to a new temporary directory provided by the OS.
      Parameters:
      projectName - the name of the project
      stackName - the name of the stack
      program - the program to run
      Returns:
      the stack
      Throws:
      AutomationException - if an error occurs

    • createOrSelectStack

      public static WorkspaceStack createOrSelectStack(String projectName, String stackName, Consumer<Context> program, LocalWorkspaceOptions options) throws AutomationException
      Creates or selects an existing Stack with a LocalWorkspace utilizing the specified inline (in process) program. This program is fully debuggable and runs in process. If no LocalWorkspaceOptions.projectSettings() option is specified, default project settings will be created on behalf of the user. Similarly, unless a LocalWorkspaceOptions.workDir() option is specified, the working directory will default to a new temporary directory provided by the OS.
      Parameters:
      projectName - the name of the project
      stackName - the name of the stack
      program - the program to run
      options - options used to configure the workspace
      Returns:
      the stack
      Throws:
      AutomationException - if an error occurs

    • createOrSelectStack

      public static WorkspaceStack createOrSelectStack(String stackName, Path workDir) throws AutomationException
      Creates or selects an existing Stack with a LocalWorkspace utilizing the local Pulumi CLI program from the specified workDir. This is a way to create drivers on top of pre-existing Pulumi programs. This Workspace will pick up any available Settings files(Pulumi.yaml, Pulumi.{stack}.yaml).
      Parameters:
      stackName - the name of the stack
      workDir - the working directory
      Returns:
      the stack
      Throws:
      AutomationException - if an error occurs

    • createOrSelectStack

      public static WorkspaceStack createOrSelectStack(String stackName, Path workDir, LocalWorkspaceOptions options) throws AutomationException
      Creates or selects an existing Stack with a LocalWorkspace utilizing the local Pulumi CLI program from the specified workDir. This is a way to create drivers on top of pre-existing Pulumi programs. This Workspace will pick up any available Settings files(Pulumi.yaml, Pulumi.{stack}.yaml).
      Parameters:
      stackName - the name of the stack
      workDir - the working directory
      options - options used to configure the workspace
      Returns:
      the stack
      Throws:
      AutomationException - if an error occurs

    • workDir

      public Path workDir()
      The working directory to run Pulumi CLI commands.
      Specified by:
      workDir in class Workspace
      Returns:
      the working directory

    • pulumiHome

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

      Specified by:
      pulumiHome in class Workspace
      Returns:
      the directory override

    • pulumiVersion

      public String pulumiVersion()
      The version of the underlying Pulumi CLI/Engine.
      Specified by:
      pulumiVersion in class Workspace
      Returns:
      the version

    • secretsProvider

      @Nullable public 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

      Specified by:
      secretsProvider in class Workspace
      Returns:
      the secrets provider

    • program

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

      Specified by:
      program in class Workspace
      Returns:
      the inline program

    • logger

      @Nullable public Logger logger()
      A custom logger instance that will be used for the action. Note that it will only be used Workspace.program() is also provided.
      Specified by:
      logger in class Workspace
      Returns:
      The logger

    • environmentVariables

      public Map<String,String> environmentVariables()
      Environment values scoped to the current workspace. These will be supplied to every Pulumi command.
      Specified by:
      environmentVariables in class Workspace
      Returns:
      the environment variables

    • getProjectSettings

      public Optional<ProjectSettings> getProjectSettings() throws AutomationException
      Returns project settings for the current project if any.
      Specified by:
      getProjectSettings in class Workspace
      Returns:
      the project settings
      Throws:
      AutomationException - if there was an issue retrieving the project

    • saveProjectSettings

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

      Specified by:
      saveProjectSettings in class Workspace
      Parameters:
      settings - the settings object to save
      Throws:
      AutomationException - if there was an issue saving the project

    • getStackSettings

      public Optional<StackSettings> getStackSettings(String stackName) throws AutomationException
      Returns stack settings for the stack matching the specified stack name if any.
      Specified by:
      getStackSettings in class Workspace
      Parameters:
      stackName - the name of the stack
      Returns:
      the stack settings
      Throws:
      AutomationException - if there was an issue retrieving the stack

    • saveStackSettings

      public void saveStackSettings(String stackName, StackSettings settings) throws AutomationException
      Overwrite the settings for the stack matching the specified stack name.
      Specified by:
      saveStackSettings in class Workspace
      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 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.

      Specified by:
      serializeArgsForOp in class Workspace
      Parameters:
      stackName - the name of the stack
      Returns:
      the list of args to append

    • postCommandCallback

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

      Specified by:
      postCommandCallback in class Workspace
      Parameters:
      stackName - the name of the stack
      Throws:
      AutomationException - if there was an issue executing the post command

    • whoAmI

      public WhoAmIResult whoAmI() throws AutomationException
      Returns the currently authenticated user.
      Specified by:
      whoAmI in class Workspace
      Returns:
      the currently authenticated user
      Throws:
      AutomationException - if there was an issue determining the current user

    • createStack

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

    • selectStack

      public void selectStack(String stackName) throws AutomationException
      Selects and sets an existing stack matching the stack name, failing if none exists.
      Specified by:
      selectStack in class Workspace
      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 void removeStack(String stackName) throws AutomationException
      Deletes the stack and all associated configuration and history.
      Specified by:
      removeStack in class Workspace
      Parameters:
      stackName - the stack to remove
      Throws:
      AutomationException - if there was an issue removing the stack

    • listStacks

      public 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).

      Specified by:
      listStacks in class Workspace
      Returns:
      the list of stacks
      Throws:
      AutomationException - if there was an issue listing the stacks

    • exportStack

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

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

      Specified by:
      exportStack in class Workspace
      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 void importStack(String stackName, StackDeployment state) throws AutomationException
      Imports the specified deployment state into a pre-existing stack.

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

      Specified by:
      importStack in class Workspace
      Parameters:
      stackName - the stack to import
      state - the deployment state to import
      Throws:
      AutomationException - if there was an issue importing the stack

    • addEnvironments

      public 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.
      Specified by:
      addEnvironments in class Workspace
      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 void removeEnvironment(String stackName, String environment) throws AutomationException
      Removes environments from a stack's import list.
      Specified by:
      removeEnvironment in class Workspace
      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 String getTag(String stackName, String key) throws AutomationException
      Returns the value associated with the stack and key, scoped to the Workspace.
      Specified by:
      getTag in class 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 void setTag(String stackName, String key, String value) throws AutomationException
      Sets the specified key-value pair on the provided stack name.
      Specified by:
      setTag in class Workspace
      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 void removeTag(String stackName, String key) throws AutomationException
      Removes the specified key-value pair on the provided stack name.
      Specified by:
      removeTag in class Workspace
      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 Map<String,String> listTags(String stackName) throws AutomationException
      Returns the tag map for the specified stack name, scoped to the current Workspace.
      Specified by:
      listTags in class 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, boolean path) throws AutomationException
      Returns the value associated with the specified stack name and key, scoped to the Workspace.
      Specified by:
      getConfig in class 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 Map<String,ConfigValue> getAllConfig(String stackName) throws AutomationException
      Returns the config map for the specified stack name, scoped to the current Workspace.
      Specified by:
      getAllConfig in class 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, boolean path) throws AutomationException
      Sets the specified key-value pair in the provided stack's config.
      Specified by:
      setConfig in class Workspace
      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, boolean path) throws AutomationException
      Sets all values in the provided config map for the specified stack name.
      Specified by:
      setAllConfig in class Workspace
      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, boolean path) throws AutomationException
      Removes the specified key-value pair from the provided stack's config.
      Specified by:
      removeConfig in class Workspace
      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, boolean path) throws AutomationException
      Removes all values in the provided key collection from the config map for the specified stack name.
      Specified by:
      removeAllConfig in class Workspace
      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 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.
      Specified by:
      refreshConfig in class Workspace
      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

    • installPlugin

      public 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.
      Specified by:
      installPlugin in class Workspace
      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 void removePlugin(PluginRemoveOptions options) throws AutomationException
      Removes a plugin or plugins from the Workspace.
      Specified by:
      removePlugin in class Workspace
      Parameters:
      options - plugin removal options
      Throws:
      AutomationException - if there was an issue removing the plugin

    • listPlugins

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

    • getStackOutputs

      public Map<String,OutputValue> getStackOutputs(String stackName) throws AutomationException
      Gets the current set of Stack outputs from the last WorkspaceStack.up() call.
      Specified by:
      getStackOutputs in class Workspace
      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, @Nullable SecretsProviderOptions options) throws AutomationException
      Change the secrets provider for a stack.
      Specified by:
      changeSecretsProvider in class Workspace
      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

    • close

      public void close() throws Exception
      Throws:
      Exception