[New article]: Document deployment state caching for local deployments

[captainsafia]

Proposed topic or title

Local deployment state

Location in table of contents.

/ Publish and Deploy / Azure deployment with Aspire / Local deployment state

Reason for the article

Starting in Aspire 13, we're introducing behavior that caches aspects of deployment state locally on the users machine to make repeated deployments faster. We should document this behavior so users are aware of the functionality.

Article abstract

Aspire Deploy Command: Deployment State Behavior

Overview

The aspire deploy command manages deployment state through cached configuration files stored in ~/.aspire/deployments/{AppHostSha}/{environment}.json. This caching mechanism streamlines repeated deployments by preserving provisioning settings and parameters.

Default Behavior

First Deployment

When running aspire deploy for the first time:

1. Prompts for provisioning information (subscription ID, resource group name, location)
2. Prompts for deployment parameters (e.g., API keys, connection strings)
3. Initiates the deployment process
4. Saves all prompted values and deployment state to ~/.aspire/deployments/{AppHostSha}/production.json

Subsequent Deployments

On subsequent aspire deploy executions:

1. Detects the existing deployment state file at ~/.aspire/deployments/{AppHostSha}/production.json
2. Notifies the user that settings will be read from the cached file
3. Prompts for confirmation to load the cached settings
4. Loads the configuration from the cached file into the configuration provider
5. Proceeds with deployment using the cached values (no re-prompting)

Environment-Specific Deployments

Specifying an Environment

Use the --environment flag to deploy to different environments:

aspire deploy --environment staging

First deployment to a specific environment:

• Prompts for all provisioning and parameter information
• Saves deployment state to ~/.aspire/deployments/{AppHostSha}/{environment}.json (e.g., staging.json)

Subsequent deployments:

• Reads the environment-specific cached file
• Loads configuration from the cached state
• Uses cached values without prompting

Environment Variable Support

The deployment environment can also be specified using the DOTNET_ENVIRONMENT environment variable:

export DOTNET_ENVIRONMENT=staging && aspire deploy

This behaves identically to using the --environment flag, loading the appropriate cached configuration file.

Cache Management

Clearing the Cache

Use the --clear-cache flag to reset deployment state:

aspire deploy --clear-cache

Behavior:

1. Prompts for confirmation before deleting the cache for the specified environment
2. Deletes the environment-specific deployment state file (e.g., ~/.aspire/deployments/{AppHostSha}/production.json)
3. Prompts for all provisioning and parameter information as if deploying for the first time
4. Proceeds with deployment
5. Does not save the prompted values to cache

Environment-Specific Cache Clearing

The --clear-cache flag respects the environment context:

aspire deploy --environment staging --clear-cache

This clears only the staging.json cache file while leaving other environment caches (like production.json) intact.

File Storage Location

• Path pattern: ~/.aspire/deployments/{AppHostSha}/{environment}.json
• Default environment: production
• AppHostSha: A hash value representing the application host configuration, ensuring deployment states are specific to each application configuration

Key Points

• Each environment maintains its own isolated deployment state
• Cached values persist across deployments unless explicitly cleared
• The --clear-cache flag performs a one-time deployment without persisting new values
• Environment selection can be specified via flag or environment variable
• Users are prompted for confirmation when loading cached settings
• Cache files are stored per application (via AppHostSha) and per environment

Relevant searches

No response

[vivaladan]

Looking forward to this feature - thanks for the work on it. Presumably secrets will be stored in plain text in this file?

[captainsafia]

Looking forward to this feature - thanks for the work on it. Presumably secrets will be stored in plain text in this file?

Yep, the generated values that are associated with ParameterResources that are secrets will be stored.

From a security perspective, we follow the same pattern as .NET's user secret manager and save things to a file outside of source code with the primary motivation to mitigate against secret leaks that way.