Go Automation API
Relevant source files
The following files were used as context for generating this wiki page:
The Go Automation API provides a programmatic interface for driving Pulumi programs without using the command-line interface (CLI). It encapsulates the functionality of the CLI (pulumi up, pulumi preview, pulumi destroy, pulumi stack init, etc.) while offering greater flexibility for integration into custom tools and workflows. The API still requires a Pulumi CLI binary to be installed and available on the system's $PATH.
This API is designed for a variety of use cases, including embedding Pulumi deployments in CI/CD pipelines, integration testing, orchestrating multi-stack or multi-stage deployments (like blue-green patterns), and building custom tooling or APIs on top of Pulumi. It allows for the management of infrastructure as code directly from Go applications, enabling complex orchestration logic, such as feeding the outputs of one stack as inputs to another.
Sources: sdk/go/auto/README.md
Core Concepts
The Automation API is built around two primary concepts: Workspace and Stack. These components provide the execution context and control plane for managing your infrastructure programmatically.
Workspace
A Workspace is the main execution context, containing a single Pulumi project, its associated program, and multiple stacks. It is responsible for managing the execution environment, including plugin installation and environment configuration (e.g., $PULUMI_HOME).
The primary implementation is LocalWorkspace, which relies on Pulumi.yaml and Pulumi.<stack>.yaml files for project and stack settings, mirroring the behavior of the Pulumi CLI. Custom Workspace implementations can be created to store settings in different backends like a database or cloud object storage.
The following diagram shows the conceptual model of a Workspace.
This diagram illustrates that a Workspace encapsulates a Pulumi Project and manages its associated Stacks and execution environment.
Sources: sdk/go/auto/README.md, sdk/go/auto/local_workspace.go
Stack
A Stack is an isolated, independently configurable instance of a Pulumi program. The Automation API provides access to the full Pulumi lifecycle for a stack, including methods for deployment (Up), preview (Preview), and destruction (Destroy), as well as for managing its configuration.
Every Stack is associated with a Workspace, which can be accessed via the stack.Workspace() method.
Sources: sdk/go/auto/README.md, sdk/go/auto/stack.go
Stack Creation
The Automation API offers three primary methods for initializing a stack, each corresponding to a different way of sourcing the Pulumi program.
This diagram shows the three main pathways to create a Stack object from different program sources.
Sources: sdk/go/auto/README.md
Local Source
For Pulumi programs that exist on the local filesystem, NewStackLocalSource is used. It creates a stack from a project specified by a local path.
Function Signature:
func NewStackLocalSource(ctx context.Context, stackName, workDir string, opts ...LocalWorkspaceOption) (Stack, error)
stackName: The fully qualified name of the stack (e.g.,org/project/stack).workDir: The path to the directory containing the Pulumi program.
Sources: sdk/go/auto/stack.go:40-43, sdk/go/auto/README.md
Remote Source (Git)
For Pulumi programs stored in a Git repository, NewStackRemoteSource is used. It clones the repository and creates a stack from a project within it.
Function Signature:
func NewStackRemoteSource(ctx context.Context, stackName string, repo GitRepo, opts ...LocalWorkspaceOption) (Stack, error)
stackName: The fully qualified name of the stack.repo: AGitRepostruct specifying the repository URL, branch, and an optional path to the project within the repo.
The GitRepo struct has the following fields:
| Field | Type | Description |
|---|---|---|
URL | string | The URL of the Git repository. |
Branch | string | The branch to checkout. Defaults to the remote's default branch. |
CommitHash | string | A specific commit to checkout. |
ProjectPath | string | The relative path to the project within the repository. |
Auth | *GitAuth | Authentication options for private repositories. |
Sources: sdk/go/auto/stack.go:50-53, sdk/go/auto/README.md
Inline Source
For Pulumi programs defined directly within the Go application, NewStackInlineSource is used. This is useful for simple programs or for creating dynamic infrastructure based on runtime logic.
Function Signature:
func NewStackInlineSource(ctx context.Context, stackName, projectName string, program pulumi.RunFunc, opts ...LocalWorkspaceOption) (Stack, error)
stackName: The fully qualified name of the stack.projectName: The name of the project.program: Apulumi.RunFuncthat contains the infrastructure definition.
Sources: sdk/go/auto/stack.go:45-48, sdk/go/auto/README.md
Stack Operations
Once a Stack object is created, you can perform various lifecycle and configuration operations on it.
Lifecycle Methods
The core deployment actions are available as methods on the Stack object.
| Method | Description |
|---|---|
Up(ctx, opts...) | Creates or updates resources in the stack to match the program's desired state. |
Preview(ctx, opts...) | Previews the changes that will be made by an Up operation. |
Refresh(ctx, opts...) | Compares the stack's state with the actual state of resources in the cloud and updates the state file. |
Destroy(ctx, opts...) | Destroys all resources managed by the stack. |
Each of these methods returns a Summary and an error.
Sources: sdk/go/auto/stack.go:124-150
Configuration Management
Stack configuration can be managed programmatically.
| Method | Description |
|---|---|
SetConfig(ctx, key, value) | Sets a configuration value for the stack. The ConfigValue struct allows specifying if the value is a secret. |
GetAllConfig(ctx) | Retrieves all configuration values for the stack. |
GetConfig(ctx, key) | Retrieves a single configuration value by its key. |
RemoveConfig(ctx, key) | Removes a configuration value. |
RefreshConfig(ctx) | Reloads the configuration from the backend. |
Sources: sdk/go/auto/stack.go:88-111
Typical Workflow
The following sequence diagram illustrates a common workflow using the Automation API.
This diagram shows the sequence of creating a stack, setting configuration, running an update, and retrieving the outputs.
Sources: sdk/go/auto/README.md, sdk/go/auto/stack.go
Workspace Management
The Workspace provides utilities for managing the environment in which Pulumi programs run. A workspace can be explicitly created and customized.
Example of explicit workspace creation:
w, err := NewLocalWorkspace(ctx,
WorkDir(filepath.Join(".", "project", "path")),
PulumiHome("~/.pulumi"),
)
s, err := NewStack(ctx, "org/proj/stack", w)
Sources: sdk/go/auto/README.md
Project Settings
The LocalWorkspace implementation uses a Pulumi.yaml file to store project settings. The structure of this file is defined by a JSON schema. Key properties include:
| Property | Type | Description |
|---|---|---|
name | string | The project name. |
runtime | string or object | The language runtime (e.g., "go", "nodejs"). Can include options. |
description | string | An optional description for the project. |
main | string | An optional path to the Pulumi program's entry point. |
backend | object | Optional backend configuration, such as a URL. |
template | object | Information about the template used to create the project. |
Modifying project settings via the API will alter the Pulumi.yaml file.
Sources: sdk/go/common/workspace/project.json, sdk/go/auto/README.md
Plugin Management
The Workspace interface provides methods for managing plugins.
| Method | Description |
|---|---|
InstallPlugin(ctx, name, version, kind) | Installs a plugin of a specific name, version, and kind (e.g., "resource"). |
RemovePlugin(ctx, name, version, kind) | Removes a plugin. |
ListPlugins(ctx) | Lists all installed plugins in the workspace. |
Sources: sdk/go/auto/local_workspace.go:215-273
Error Handling
The Automation API provides utilities for handling common errors, such as concurrent update conflicts. This allows for building more resilient automation by implementing retry logic.
The IsConcurrentUpdateError function can be used to check if an error returned from an Up, Preview, Refresh, or Destroy operation is due to a conflicting update already in progress.
Example:
uRes, err := stack.Up(ctx)
if err != nil && IsConcurrentUpdateError(err) {
// Implement retry logic here
}