Node.js Automation API
Relevant source files
The following files were used as context for generating this wiki page:The Node.js Automation API provides a programmatic interface for driving Pulumi programs without the CLI. It encapsulates the functionality of CLI commands like pulumi up, pulumi preview, and pulumi stack init, allowing developers to embed Pulumi's deployment capabilities directly into their Node.js applications. This enables a variety of powerful use cases, such as building custom tooling, creating CI/CD workflows, integration testing, and orchestrating complex multi-stack deployments.
The API is designed around two primary concepts: the Workspace and the Stack. A Workspace is the execution context for a Pulumi project, managing aspects like plugin installation and environment configuration. A Stack is an isolated instance of a Pulumi program, and the API provides methods to manage its entire lifecycle, from configuration to deployment and destruction. The Node.js implementation, LocalWorkspace, relies on a local Pulumi CLI binary being installed and available on the system's $PATH.
Sources: sdk/go/auto/README.md, sdk/nodejs/automation/localWorkspace.ts, sdk/nodejs/automation/stack.ts
Core Components
The Automation API is composed of two main classes: LocalWorkspace and Stack. The LocalWorkspace represents the project and its environment, while Stack represents a specific deployment instance of that project.
Class Diagram
The following diagram illustrates the relationship between the main classes in the Node.js Automation API.
Workspace
A Workspace is the execution context for a Pulumi project. The LocalWorkspace class is the primary implementation, which uses a local directory on the filesystem. It manages project and stack settings, which are stored in Pulumi.yaml and Pulumi.<stack-name>.yaml files, respectively.
Sources: sdk/go/auto/README.md, sdk/nodejs/automation/localWorkspace.ts:25-32
Creating a Workspace
A LocalWorkspace can be created in several ways, primarily using the static create method. The behavior is configured through LocalWorkspaceOptions.
// From sdk/nodejs/tests/automation/localWorkspace.spec.ts:40-49
const ws = await LocalWorkspace.create(
withTestBackend(
{ workDir: upath.joinSafe(__dirname, "data", ext) },
"testproj",
"A minimal Go Pulumi program",
"go",
),
);
LocalWorkspaceOptions
| Option | Type | Description |
|---|---|---|
workDir | string | Path to the directory containing the Pulumi project. If not set, the current working directory is used. |
projectSettings | ProjectSettings | The project settings to use. If not provided, they are loaded from the workDir. |
envVars | {[key: string]: string} | Environment variables to use for CLI commands. |
pulumiCommand | PulumiCommand | An explicit PulumiCommand instance to use. |
remote | boolean | If true, the workspace will be configured for remote operations. |
pulumiHome | string | The path to the Pulumi home directory. |
Sources: sdk/nodejs/automation/localWorkspace.ts:34-58
Workspace Management
LocalWorkspace provides methods for managing stacks, plugins, and project settings.
- Stack Management:
createStack,selectStack,removeStack,listStacks. These methods correspond topulumi stack init,pulumi stack select,pulumi stack rm, andpulumi stack ls. - Plugin Management:
installPlugin,removePlugin,listPlugins. These correspond topulumi plugin install,pulumi plugin rm, andpulumi plugin ls. - Settings:
projectSettings()andstackSettings(stackName)allow reading and writingPulumi.yamlandPulumi.<stack>.yamlfiles.
Sources: sdk/nodejs/automation/localWorkspace.ts:133-255
Stack
A Stack is an instance of a Pulumi program. It can be created from a LocalWorkspace or instantiated directly. Stacks can be defined by a local filesystem path (workDir) or by an inline program function (program).
Stack Creation
There are three primary ways to define the Pulumi program for a stack:
- Local Filesystem Program: By specifying a
workDirinLocalWorkspaceOptions, the Pulumi program is sourced from that directory. - Inline Program: By providing a
programfunction of typePulumiFntoLocalWorkspace.createStackorcreateOrSelectStack. This is useful for defining infrastructure alongside the automation code. - Remote Git Program: The Go Automation API supports fetching programs from a Git URL, a feature that can be conceptually mirrored in Node.js.
Sources: sdk/go/auto/README.md:21-42, sdk/nodejs/tests/automation/localWorkspace.spec.ts:321-331
The following diagram shows the flow for creating or selecting a stack.
Stack Lifecycle
The Stack class provides methods to drive the entire lifecycle of the infrastructure.
| Method | Description |
|---|---|
up() | Creates or updates resources in a stack. Corresponds to pulumi up. |
preview() | Previews changes to a stack's resources. Corresponds to pulumi preview. |
refresh() | Refreshes the state of a stack's resources. Corresponds to pulumi refresh. |
destroy() | Destroys all resources in a stack. Corresponds to pulumi destroy. |
Each of these methods accepts an options object (e.g., UpOptions) that allows for customization, such as receiving real-time engine events and standard output.
Sources: sdk/nodejs/automation/stack.ts:104-180
stack.up() Sequence Diagram
This diagram shows the high-level interactions during a stack.up() call for an inline program.
Configuration and Outputs
Stacks have configuration values and produce outputs. The Automation API provides methods to manage these programmatically.
- Configuration:
setConfig,setAllConfig,getConfig,getAllConfig, andremoveConfigallow for managing a stack's configuration. These methods modify thePulumi.<stack-name>.yamlfile. - Outputs: The
outputs()method retrieves the last-known outputs from a stack's state.
Sources: sdk/nodejs/automation/stack.ts:200-264, sdk/nodejs/tests/automation/localWorkspace.spec.ts:203-270
Stack State Management
The Stack class also offers methods to manage the underlying deployment state.
| Method | Description |
|---|---|
history() | Returns the update history of the stack. |
exportStack() | Exports the stack's deployment state as a JSON object. |
importStack() | Imports a previously exported deployment state into the stack. |
rename() | Renames a stack. |
Sources: sdk/nodejs/automation/stack.ts:182-198,284-297
Conclusion
The Node.js Automation API is a powerful tool for developers who want to integrate Pulumi's infrastructure as code capabilities directly within their JavaScript or TypeScript applications. By providing programmatic access to workspaces and stack lifecycles, it unlocks advanced orchestration, testing, and custom tool development. It combines the flexibility of a general-purpose programming language with the robust deployment engine of Pulumi, enabling a new class of infrastructure management solutions.
Sources: sdk/go/auto/README.md, README.md