Automation API

The Pulumi Automation API is a programmatic interface for running Pulumi programs without the Pulumi CLI. It encapsulates the functionality of the CLI—pulumi up, pulumi preview, pulumi destroy, pulumi stack init, and so on—as a strongly typed SDK, so you can drive the Pulumi engine from within your own application instead of invoking the pulumi command from a shell.

With Automation API you define a Pulumi program, its resources, stacks, and stack configuration entirely in code, then run that code as an ordinary executable in your language of choice (for example, python3 main.py instead of pulumi up). Automation API is distributed as a namespace within the Pulumi SDK and is part of Pulumi IaC’s open source offering.

For a step-by-step walkthrough of building an Automation API program, see Using Automation API.

Use cases

Automation API is well suited to scenarios where infrastructure provisioning is part of a larger application or workflow, including:

• Driving infrastructure deployments within CI/CD workflows
• Integration testing
• Multi-stage deployments such as blue-green deployment patterns
• Deployments involving application code, such as database migrations
• Building higher-level tools, such as custom CLIs over Pulumi
• Exposing Pulumi behind a REST or gRPC API
• Debugging Pulumi programs by using a single entrypoint with inline programs

Workspaces

To enable a broad range of runtime customization, Automation API defines a Workspace interface. A Workspace is the execution context that contains a single Pulumi project, a program, and one or more stacks. Workspaces manage the execution environment, providing utilities such as plugin installation, environment configuration ($PULUMI_HOME), and the creation, deletion, and listing of stacks.

LocalWorkspace

LocalWorkspace is the default implementation of Workspace. It relies on Pulumi.yaml and Pulumi.<stack>.yaml as the on-disk format for project and stack settings. Modifying ProjectSettings alters the workspace’s Pulumi.yaml file, and setting configuration on a stack modifies the corresponding Pulumi.<stack>.yaml file. This is identical to the behavior of CLI-driven workspaces.

RemoteWorkspace

RemoteWorkspace represents a workspace for running Pulumi operations remotely with Pulumi Deployments, where the program is located in a remote Git repository.

Stacks

A Stack is an isolated, independently configurable instance of a Pulumi program. It exposes methods for the full Pulumi lifecycle (up, preview, refresh, and destroy) as well as methods for managing configuration. Multiple stacks are commonly used to represent different phases of development—such as development, staging, and production—or feature branches. For background on stacks, see Stacks.

A RemoteStack is the equivalent of a Stack for a RemoteWorkspace. It exposes the same lifecycle methods, run remotely from a remote workspace.

Programs

Automation API can drive two kinds of Pulumi programs.

Local programs

A local program is a traditional, CLI-driven Pulumi program with its own directory, a Pulumi.yaml file, and a file that defines the program. Automation API can drive these programs the same way the CLI does.

Inline programs

Unlike traditional Pulumi programs, an inline program doesn’t require a separate package on disk with its own file and Pulumi.yaml. Inline programs are functions that can be authored in the same file as your Automation API program or imported from another package.

The program’s lifecycle must be fully contained within the function, callback, or closure passed as the inline program. Performing actions outside the scope of the inline program function is unsafe and can lead to unpredictable behavior.

Supported languages

Like the rest of Pulumi, Automation API is available in multiple languages, so you can build applications that use it in TypeScript/JavaScript, Python, Go, C#, and Java. Automation API also supports cross-language use, where it runs in a program written in a different language than the Pulumi programs it manages.

	Language	Status
	TypeScript	Stable
	JavaScript	Stable
	Python	Stable
	.NET	Stable
	Go	Stable
	Java	Stable

Examples

The automation-api-examples repository contains runnable examples for every supported language, covering common patterns such as inline and local programs, cross-language programs, database migrations, and exposing Pulumi over HTTP:

Giving feedback

We encourage you to file an issue if you have feedback on using Automation API.