Metadata-Version: 2.5
Name: pulumi-remote-stack
Version: 0.1.8
Summary: Pulumi Remote Stack
Project-URL: Homepage, https://github.com/allusio/pulumi-remote-stack
Project-URL: Repository, https://github.com/allusio/pulumi-remote-stack
Project-URL: Bug Tracker, https://github.com/allusio/pulumi-remote-stack/issues
Author-email: Jan Češpivo <developers@allusio.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: pulumi>=3.0.0
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# Pulumi Remote Stack

[![PyPI version](https://img.shields.io/pypi/v/pulumi-remote-stack.svg)](https://pypi.org/project/pulumi-remote-stack/)
[![Python versions](https://img.shields.io/pypi/pyversions/pulumi-remote-stack.svg)](https://pypi.org/project/pulumi-remote-stack/)
[![License](https://img.shields.io/pypi/l/pulumi-remote-stack.svg)](https://github.com/allusio/pulumi-remote-stack/blob/main/LICENSE)

A [Pulumi](https://www.pulumi.com/) Dynamic Resource provider for provisioning, configuring, and managing remote Pulumi stacks via the [Pulumi Automation API](https://www.pulumi.com/docs/using-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`](https://www.pulumi.com/docs/concepts/stack/#stackreferences).

## 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`:

```shell
uv add pulumi-remote-stack
```

Or using `pip`:

```shell
pip install pulumi-remote-stack
```

## Usage

```python
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

| Parameter | Type | Required | Description |
|:---|:---|:---:|:---|
| `project_name` | `Input[str]` | Yes | Name of the Pulumi project to manage. |
| `stack_name` | `Input[str]` | Yes | Name of the stack (e.g., `dev`, `prod`). |
| `backend_url` | `Input[str]` | Yes | Target Pulumi backend URL (passed to `PULUMI_BACKEND_URL`). |
| `secrets_provider` | `Input[str]` | Yes | Type and URI of secrets provider (e.g., `default`, `passphrase`, `awskms://...`, `azurekeyvault://...`). |
| `config` | `Input[dict[str, ConfigValue]]` | No | Stack configuration map. Accepts primitive types (`str`, `int`, `bool`) and nested structures (`dict`, `list`). |
| `secrets` | `Input[dict[str, ConfigValue]]` | No | Secret configuration values to encrypt and store securely in the target stack. |
| `backend_azure_storage_account` | `Input[str]` | No | Azure Storage Account name if using Azure Blob backend. Triggers automated SAS token acquisition via Azure CLI. |
| `only_create` | `Input[bool]` | No | When `True`, provisions the stack only once and skips updates during subsequent runs. Default: `False`. |

## Development

See [DEVELOPMENT.md](DEVELOPMENT.md) for local environment setup, build, and publishing guides.

## License

This project is licensed under the [Apache-2.0 License](LICENSE).
