Python Automation API
Relevant source files
The following files were used as context for generating this wiki page:The Python Automation API provides a programmatic interface for driving Pulumi programs without using the command-line interface (CLI). It encapsulates the functionality of the CLI (e.g., pulumi up, pulumi preview, pulumi stack init) into a Python library, allowing for greater flexibility and integration. This enables a variety of use cases, such as embedding Pulumi into CI/CD workflows, creating custom tooling, integration testing, and orchestrating complex multi-stack deployments.
The API is built around two primary concepts: the Workspace and the Stack. A Workspace is an execution context for a Pulumi project, managing aspects like plugin installation and stack management. A Stack represents a specific instance of a Pulumi program and provides methods for all lifecycle operations like updates, previews, and destruction, as well as configuration management. While the API provides a programmatic interface, it still requires a Pulumi CLI binary to be installed and available on the system's PATH.
Sources: sdk/go/auto/README.md:12-16, 47-53, README.md:13-14
Core Components
The Python Automation API is primarily composed of the Workspace and Stack classes, which work together to manage and execute Pulumi programs.
This diagram illustrates the relationship between the main classes in the Automation API.
Workspace
A Workspace is the execution context for a Pulumi project and its associated stacks. It handles environment configuration, plugin management, and the creation or selection of stacks. The primary implementation provided is LocalWorkspace.
Sources: sdk/go/auto/README.md:47-53
LocalWorkspace
LocalWorkspace is the default implementation of the Workspace interface. It relies on the local filesystem and uses Pulumi.yaml and Pulumi.<stack-name>.yaml files to manage project and stack settings, mirroring the behavior of the Pulumi CLI.
Sources: sdk/go/auto/README.md:57-61, sdk/python/lib/pulumi/automation/_local_workspace.py:100-102
Initialization
A LocalWorkspace can be initialized in several ways, primarily by specifying a working directory for a Pulumi project.
| Parameter | Type | Description |
|---|---|---|
work_dir | Optional[str] | Path to the directory containing the Pulumi project. Defaults to the current working directory. |
pulumi_home | Optional[str] | The directory to use for Pulumi state. Defaults to ~/.pulumi. |
program | Optional[PulumiFn] | The inline Pulumi program to be used for all stacks created in this workspace. |
env_vars | Optional[Dict[str, str]] | Environment variables to set for workspace operations. |
secrets_provider | Optional[str] | The type of secrets provider to use. |
Sources: sdk/python/lib/pulumi/automation/_local_workspace.py:102-127
Key Methods
The LocalWorkspace class provides methods to manage stacks and the environment.
| Method | Description |
|---|---|
create_stack(stack_name, program) | Creates a new stack with the given name and an optional inline program. |
select_stack(stack_name, program) | Selects an existing stack with the given name and an optional inline program. |
stack_init(stack_name) | Initializes a new stack, returning a Stack object for further configuration. |
list_stacks() | Returns a list of StackSummary objects for all known stacks in the workspace. |
remove_stack(stack_name) | Removes a stack and its configuration. |
install_plugin(name, version) | Installs a plugin with a specific name and version into the workspace. |
project_settings() | Returns the ProjectSettings for the workspace. |
save_project_settings(settings) | Saves the provided ProjectSettings to Pulumi.yaml. |
Sources: sdk/python/lib/pulumi/automation/_local_workspace.py:238-410
Stack
A Stack object represents a single Pulumi stack. It is the primary entry point for all deployment-related actions, such as up, preview, destroy, and refresh. It also provides methods for managing stack configuration and accessing outputs.
Sources: sdk/python/lib/pulumi/automation/_stack.py:102-104
Stack Creation
Stacks are typically created or selected via a Workspace instance. The Automation API supports different ways to define the Pulumi program associated with a stack.
- Inline Programs: The Pulumi program is defined as a Python function (
PulumiFn) and passed directly to the workspace. This is useful for self-contained automation scripts. - Local Source: The Pulumi program exists on the local filesystem. The
work_dirof theLocalWorkspacepoints to the project directory.
The following diagram shows the flow for creating and running an inline program.
Lifecycle Operations
The Stack class provides methods that correspond to the standard Pulumi CLI commands for managing infrastructure.
| Method | Return Type | Description |
|---|---|---|
up(...) | UpResult | Creates or updates resources in a stack. |
preview(...) | PreviewResult | Previews changes that will be made by an up operation. |
refresh(...) | RefreshResult | Refreshes the state of the stack against the cloud provider. |
destroy(...) | DestroyResult | Destroys all resources in the stack. |
These methods accept a variety of optional parameters to customize their execution, such as on_output for streaming logs, parallel for controlling concurrency, and message for setting an update message.
Sources: sdk/python/lib/pulumi/automation/_stack.py:201-308
Configuration Management
Stack configuration can be managed programmatically.
| Method | Description |
|---|---|
set_config(key, value) | Sets a configuration value for the stack. The value is a ConfigValue object which can be marked as secret. |
get_config(key) | Retrieves a configuration value. |
get_all_config() | Retrieves all configuration values for the stack. |
remove_config(key) | Removes a configuration key. |
refresh_config() | Reloads the configuration from the backend. |
Sources: sdk/python/lib/pulumi/automation/_stack.py:325-385
Error Handling
The API provides specific exception types for common failure scenarios. A key example is ConcurrentUpdateError, which is raised if an update is initiated while another is already in progress on the same stack. This allows for robust error handling and retry logic in automation scripts.
Sources: sdk/go/auto/README.md:70-72, sdk/python/lib/pulumi/automation/_stack.py:68-71
Typical Workflow
The following diagram illustrates a common workflow using the Python Automation API.
Summary
The Python Automation API is a powerful tool for developers who need to programmatically manage their infrastructure as code. By providing Pythonic wrappers around the core Pulumi engine, it enables advanced orchestration, automation, and integration scenarios that go beyond the capabilities of the standard CLI. Its design, centered on the Workspace and Stack abstractions, offers a clear and structured way to embed infrastructure management directly into applications and deployment pipelines.
Sources: README.md:13-14, sdk/go/auto/README.md:12-16, 41-46