dotnet
[New article]: Document deployment state caching for local deployments
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:
- Prompts for provisioning information (subscription ID, resource group name, location)
- Prompts for deployment parameters (e.g., API keys, connection strings)
- Initiates the deployment process
- Saves all prompted values and deployment state to
~/.aspire/deployments/{AppHostSha}/production.json
Subsequent Deployments
On subsequent aspire deploy executions:
- Detects the existing deployment state file at
~/.aspire/deployments/{AppHostSha}/production.json - Notifies the user that settings will be read from the cached file
- Prompts for confirmation to load the cached settings
- Loads the configuration from the cached file into the configuration provider
- 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:
- Prompts for confirmation before deleting the cache for the specified environment
- Deletes the environment-specific deployment state file (e.g.,
~/.aspire/deployments/{AppHostSha}/production.json) - Prompts for all provisioning and parameter information as if deploying for the first time
- Proceeds with deployment
- 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-cacheflag 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
Looking forward to this feature - thanks for the work on it. Presumably secrets will be stored in plain text in this file?
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.
I would like to have an option to re-prompt, but the default values are fetched from the cache. This will give me peace of mind :) , but seriously, an informed deployment is essential. I would even like a complete overview of what will be done with confirmation.
I would like to have an option to re-prompt, but the default values are fetched from the cache.
I'm curious to learn more about what you're thinking about here. Do you want anticipate that you would provide values that different from what waas cached?
if the primary motivation about your second point; seeing what is cached? For example, showing you the contents of the file before we run through the deployment.
5> I'm curious to learn more about what you're thinking about here. Do you want anticipate that you would provide values that different from what waas cached?
I'm curious to learn more about what you're thinking about here. Do you want anticipate that you would provide values that different from what waas cached? - Yes, I would like to see what I have entered earlier, and be able to change if needed. Sometimes, I would like to reuse the same naming (most of situations), but in other cases (when I can't), enter a new one.
It is somewhat spooky for me as an end user to just rerun the deployment without confirmation on values.
if the primary motivation about your second point; seeing what is cached? For example, showing you the contents of the file before we run through the deployment. - not the primary motivation
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.
Would it be an option to save secrets in a vault of a kind ? Something like Powershell does https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.secretmanagement/?view=ps-modules
Keeping them on a filesystem means any process running under the user's account can read them.