Pulumi Remote Stack

A Pulumi Dynamic Resource provider for provisioning, configuring, and managing remote Pulumi stacks via the Pulumi Automation API.

How It Works

Under the hood, RemoteStack dynamically generates an inline pass-through Pulumi program that:

1. Reads all supplied configuration entries and secrets from the Pulumi stack configuration.
2. Directly exports them as stack outputs (with secrets appropriately marked as secret).
3. Executes stack lifecycle operations (up, destroy) using the Pulumi Automation API.

The entire flow is wrapped in a Pulumi Dynamic Resource Provider, allowing you to create, populate, and manage independent remote stacks declaratively inside ordinary Pulumi programs. Downstream stacks can then consume these configurations and secrets as outputs using standard pulumi.StackReference.

Features

• Lifecycle Management: Declaratively manage remote stacks (create, update, destroy) as first-class Pulumi resources.
• Dynamic Configuration & Secrets: Pass plain configuration values or encrypted secrets directly to target stacks.
• Pluggable Backends: Compatible with any standard Pulumi backend URL (e.g., cloud object stores, self-hosted backends, or Pulumi Service).
• Azure Blob Storage Support: Automatic User SAS token generation for Azure Blob Storage backends via Azure CLI credentials.
• Configurable Secrets Providers: Integrate custom encryption providers supported by Pulumi (e.g., HashiCorp Vault, AWS KMS, Azure KeyVault, GCP KMS).

Installation

Install using uv:

uv add pulumi-remote-stack

Or using pip:

pip install pulumi-remote-stack

Usage

import pulumi
from pulumi_remote_stack import RemoteStack

# Provision or manage the remote stack
remote_stack = RemoteStack(
    "production-infrastructure",
    project_name="my-infra",
    stack_name="prod",
    backend_url="azblob://my-pulumi-state",
    secrets_provider="azurekeyvault://my-vault.vault.azure.net/keys/my-key",
    backend_azure_storage_account="mystorageaccount",
    config={
        "environment": "production",
        "instance_count": 3,
    },
    secrets={
        "database_password": "supersecretpassword",
    },
)

# Consume exported configurations and secrets from the remote stack via standard Pulumi StackReference
stack_ref = pulumi.StackReference(
    "prod-ref",
    stack_name="prod",
    opts=pulumi.ResourceOptions(depends_on=[remote_stack]),
)

# Access values originally passed to the remote stack's config or secrets
env_name = stack_ref.get_output("environment")
db_password = stack_ref.get_output("database_password")

Inputs

Development

See DEVELOPMENT.md for local environment setup, build, and publishing guides.

License

This project is licensed under the Apache-2.0 License.