Automation API concepts & terminology
Automation API lets you define a Pulumi program as a function within your codebase rather than in a separate project and use methods to get and set configuration parameters programmatically.
The package can be used for a number of use cases:
- Driving pulumi deployments within CI/CD workflows
- Integration testing
- Multi-stage deployments such as blue-green deployment patterns
- Deployments involving application code like database migrations
- Building higher level tools, custom CLIs over Pulumi, etc.
- Using Pulumi behind a REST or GRPC API
- Debugging Pulumi programs (by using a single main entrypoint with “inline” programs)
To enable a broad range of runtime customization the API defines a
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 class is the default implementation of
Workspace. This implementation relies on
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.
RemoteWorkspace class represents a workspace for running Pulumi operations remotely via Pulumi Deployments where the program is located in a remote Git repository.
Stack class represents an isolated, independently configurable instance of a Pulumi program.
Stack exposes methods for the full pulumi lifecycle (
destroy), as well as managing configuration. Multiple Stacks are commonly used to denote different phases of development (such as development, staging and production) or feature branches (such as feature-x-dev, jane-feature-x-dev). You can learn more about stacks in the intro docs.
RemoteStack class represents an isolated, independently configurable instance of a Pulumi program.
RemoteStack exposes methods for the full pulumi lifecycle (
destroy) for running these remotely from a remote workspace.
A local program is a traditional Pulumi CLI-driven program with its own directory, a
Pulumi.yaml file, along with a file that defines the Pulumi program. Automation API can be used to drive these programs, as well as the CLI.
Unlike traditional Pulumi programs, inline programs don’t require a separate package on disk, with its own file and a
Pulumi.yaml. Inline programs are functions that can be authored in the same file as your Automation API program or be imported from another package.
Thank you for your feedback!
If you have a question about how to use Pulumi, reach out in Community Slack.
Open an issue on GitHub to report a problem or suggest an improvement.