microsoft / microsoft/aspire

Add environment management commands (`aspire env new/list/select/set`)

Open
#16,170 1 comment 0 reactions 0 assignees View on GitHub
area-deployment
Dominant language
C#
Stars
6.3k
Forks
991
Avg merge
2d 15h
Merged PRs (30d)
196

Description

## Problem

When deploying the same application to multiple environments (dev, staging, production), teams need isolated configuration and deployment state per environment. Today, `aspire deploy --environment staging` passes the environment name as a string to the AppHost, but there is no CLI-managed state separation — no way to store per-environment parameters, track what was deployed to each environment, or switch between environments.

Developers deploying to multiple targets must manually manage configuration differences, re-enter parameters each time, and have no visibility into what state each environment is in.

## Current State

- `--environment` on deploy/publish is a pass-through flag with no managed lifecycle
- `IDeploymentStateManager` stores per-environment state files internally, but this is not exposed through CLI commands
- Parameters must be re-entered on every deployment (no per-environment persistence beyond the state manager)
- No way to list, compare, or switch between environments

## Proposed Experience

```bash
# Create a new named environment
aspire env new staging

# List all environments (* marks active)
aspire env list
# dev
# staging *
# production

# Switch active environment
aspire env select production

# Set a parameter value for the current environment
aspire env set DB_SKU P1
aspire env set AZURE_LOCATION westus2

# View all resolved values for the current environment
aspire env get-values
# AZURE_LOCATION=westus2
# DB_SKU=P1
# Azure__SubscriptionId=12345...

# Deploy uses active environment's config + state
aspire deploy

# Override environment for a single command without switching
aspire deploy --environment staging
```

## Why This Matters

- **Team workflows** — Multiple developers deploying to shared staging/prod environments need consistent, isolated configuration per target
- **CI/CD pipelines** — Different pipeline stages target different environments with different parameters (regions, SKUs, secrets)
- **Parameter persistence** — Users should not re-enter subscription ID, location, and resource group on every deploy. Once set for an environment, they should persist.
- **Deployment state isolation** — Knowing what was deployed to staging vs production prevents accidental cross-environment operations
- **Complements #16090** — First-class parameters become much more useful when they persist per-environment rather than being entered every time

## Implementation Notes

The internal infrastructure largely exists:

- **`IDeploymentStateManager`** already stores per-environment JSON state files with optimistic concurrency control and section-based storage
- **`aspire.config.json`** has a profiles system that could be extended or paralleled for environment configuration
- **Pipeline steps** already receive environment context — the state manager namespaces by environment

The main work is:

1. **CLI commands** — `aspire env new`, `list`, `select`, `set`, `get-values` (thin wrappers over existing state infrastructure)
2. **Active environment tracking** — Store the currently selected environment in local config (similar to how profiles work)
3. **Parameter flow** — Parameters set via `aspire env set` should be automatically provided to the pipeline, reducing interactive prompts
4. **State directory convention** — Define where per-environment state lives (e.g., `.aspire/environments//`)

## Design Questions

- Should environment state live in the project directory (`.aspire/environments/`) or in the user config directory?
- How does `aspire env set` interact with the parameter system in #16090? Should `--set` values on the CLI override persisted environment values?
- Should `aspire env get-values` show both user-set parameters AND computed deployment outputs (resource IDs, endpoints)?
- Can environments be shared across team members (e.g., committed to source control or stored remotely)?

## Related Issues

- #16090 — Improve parameter experience during deployment (persisted env values reduce prompting friction)
- #14830 — Multi-pipeline deployment state (per-environment state enables pipeline-to-pipeline state transfer)
- #16063 — Unified resource introspection (environment context determines which deployed instance to introspect)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.