From bca43e4fb0f2ed89fe4caa81717a3300c1c5508c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 13:05:37 +0000 Subject: [PATCH 1/5] Initial plan From fc87103a1d588e5ab1828332172a43241c781b49 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 13:12:26 +0000 Subject: [PATCH 2/5] Add local deployment state documentation Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- docs/cli-reference/aspire-deploy.md | 30 +++++ .../aca-deployment-aspire-cli.md | 2 +- .../aspire-deploy/local-deployment-state.md | 124 ++++++++++++++++++ docs/toc.yml | 3 + 4 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 docs/deployment/aspire-deploy/local-deployment-state.md diff --git a/docs/cli-reference/aspire-deploy.md b/docs/cli-reference/aspire-deploy.md index f35f402d73..c091c9afba 100644 --- a/docs/cli-reference/aspire-deploy.md +++ b/docs/cli-reference/aspire-deploy.md @@ -55,6 +55,14 @@ The following options are available: - [!INCLUDE [option-project](includes/option-project.md)] +- **`-e, --environment`** + + The deployment environment name. Defaults to `production`. Each environment maintains its own isolated deployment state file. + +- **`--clear-cache`** + + Clears the cached deployment state for the specified environment before deploying. When used, the deployment prompts for all values but doesn't save them to cache. + - **`-o, --output-path`** The output path for deployment artifacts. Defaults to a folder named _deploy_ in the current directory. @@ -84,3 +92,25 @@ The following options are available: ```Command aspire deploy --project './projects/apphost/orchestration.AppHost.csproj' -- -fast ``` + +- Deploy to a specific environment: + + ```Command + aspire deploy --environment staging + ``` + +- Clear cached deployment state and deploy: + + ```Command + aspire deploy --clear-cache + ``` + +- Clear cached deployment state for a specific environment: + + ```Command + aspire deploy --environment staging --clear-cache + ``` + +## See also + +- [Local deployment state](../deployment/aspire-deploy/local-deployment-state.md) diff --git a/docs/deployment/aspire-deploy/aca-deployment-aspire-cli.md b/docs/deployment/aspire-deploy/aca-deployment-aspire-cli.md index 3696acba1b..ff886f497c 100644 --- a/docs/deployment/aspire-deploy/aca-deployment-aspire-cli.md +++ b/docs/deployment/aspire-deploy/aca-deployment-aspire-cli.md @@ -139,7 +139,7 @@ Save to user secrets: [y/n] (n): n ``` > [!NOTE] -> The CLI will continuously prompt until all unresolved parameters are provided with values. While Azure deployment is in preview, the CLI will prompt to save values in user secrets but not use them, as [deployment state is not supported](https://github.com/dotnet/aspire/issues/11444). +> The CLI continuously prompts until all unresolved parameters are provided with values. The `aspire deploy` command caches deployment state locally to streamline subsequent deployments. For more information, see [Local deployment state](local-deployment-state.md). Once parameters are collected, Azure infrastructure is provisioned using Bicep templates. This step creates the necessary Azure resources including the Container Apps environment, Container Registry, and any backing services like Redis caches: diff --git a/docs/deployment/aspire-deploy/local-deployment-state.md b/docs/deployment/aspire-deploy/local-deployment-state.md new file mode 100644 index 0000000000..710617a477 --- /dev/null +++ b/docs/deployment/aspire-deploy/local-deployment-state.md @@ -0,0 +1,124 @@ +--- +title: Local deployment state +description: Learn how the aspire deploy command manages deployment state through cached configuration files. +ms.date: 10/17/2025 +ai-usage: ai-assisted +--- + +# Local deployment state + +The `aspire deploy` command manages deployment state through cached configuration files stored locally on your machine. This caching mechanism streamlines repeated deployments by preserving provisioning settings and parameters, making subsequent deployments faster and more efficient. + +## Default behavior + +### First deployment + +When you run `aspire deploy` for the first time, the command: + +1. Prompts for provisioning information (subscription ID, resource group name, location). +1. Prompts for deployment parameters (for example, API keys, connection strings). +1. Initiates the deployment process. +1. Saves all prompted values and deployment state to `~/.aspire/deployments/{AppHostSha}/production.json`. + +### Subsequent deployments + +On subsequent `aspire deploy` executions, the command: + +1. Detects the existing deployment state file at `~/.aspire/deployments/{AppHostSha}/production.json`. +1. Notifies you that settings will be read from the cached file. +1. Prompts for confirmation to load the cached settings. +1. Loads the configuration from the cached file into the configuration provider. +1. Proceeds with deployment using the cached values (no re-prompting). + +## Environment-specific deployments + +### Specify an environment + +Use the `--environment` flag to deploy to different environments: + +```Aspire +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` (for example, `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: + +```bash +export DOTNET_ENVIRONMENT=staging && aspire deploy +``` + +This behaves identically to using the `--environment` flag, loading the appropriate cached configuration file. + +## Cache management + +### Clear the cache + +Use the `--clear-cache` flag to reset deployment state: + +```Aspire +aspire deploy --clear-cache +``` + +**Behavior:** + +1. Prompts for confirmation before deleting the cache for the specified environment. +1. Deletes the environment-specific deployment state file (for example, `~/.aspire/deployments/{AppHostSha}/production.json`). +1. Prompts for all provisioning and parameter information as if deploying for the first time. +1. Proceeds with deployment. +1. **Does not save the prompted values** to cache. + +### Environment-specific cache clearing + +The `--clear-cache` flag respects the environment context: + +```Aspire +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. + +## Security considerations + +The deployment state files are stored locally on your machine in the `~/.aspire/deployments` directory. These files contain provisioning settings and parameter values, including secrets that might be associated with parameter resources. The `aspire deploy` command follows the same security pattern as .NET's user secrets manager: + +- Files are stored outside of source code to mitigate against accidental secret leaks in version control. +- Secrets are stored in plain text in the local file system. +- Any process running under your user account can access these files. + +Consider these security best practices: + +- Ensure your local machine has appropriate security measures in place. +- Be cautious when sharing or backing up files from the `~/.aspire/deployments` directory. +- Use the `--clear-cache` flag when you need to change sensitive parameter values. + +## 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. +- You're prompted for confirmation when loading cached settings. +- Cache files are stored per application (via AppHostSha) and per environment. + +## See also + +- [aspire deploy command reference](../../cli-reference/aspire-deploy.md) +- [Deploy to Azure Container Apps using Aspire CLI](aca-deployment-aspire-cli.md) diff --git a/docs/toc.yml b/docs/toc.yml index ae30c9bd56..88280d6a51 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -498,6 +498,9 @@ items: - name: Deploy to Azure Container Apps using Visual Studio href: deployment/aspire-deploy/aca-deployment-visual-studio.md displayName: azure container apps,vs + - name: Local deployment state + href: deployment/aspire-deploy/local-deployment-state.md + displayName: deployment state,deployment cache,clear-cache,deployment settings - name: Azure security best practices href: deployment/aspire-deploy/azure-security-best-practices.md displayName: azure security,security best practices,container security,managed identity From 4ed162ee05d0effbfc2aa7086e8dfda0ab0bd103 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 21 Oct 2025 15:22:24 +0000 Subject: [PATCH 3/5] Address feedback: Add intros, italicize paths, add CI/CD example Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- .../aspire-deploy/local-deployment-state.md | 65 ++++++++++++++++--- 1 file changed, 56 insertions(+), 9 deletions(-) diff --git a/docs/deployment/aspire-deploy/local-deployment-state.md b/docs/deployment/aspire-deploy/local-deployment-state.md index 710617a477..704a183089 100644 --- a/docs/deployment/aspire-deploy/local-deployment-state.md +++ b/docs/deployment/aspire-deploy/local-deployment-state.md @@ -11,9 +11,11 @@ The `aspire deploy` command manages deployment state through cached configuratio ## Default behavior +The `aspire deploy` command automatically manages deployment state based on whether cached configuration exists for your application and target environment. + ### First deployment -When you run `aspire deploy` for the first time, the command: +When you run `aspire deploy` for the first time, or for the first time in a target `--environment`, the command: 1. Prompts for provisioning information (subscription ID, resource group name, location). 1. Prompts for deployment parameters (for example, API keys, connection strings). @@ -24,7 +26,7 @@ When you run `aspire deploy` for the first time, the command: On subsequent `aspire deploy` executions, the command: -1. Detects the existing deployment state file at `~/.aspire/deployments/{AppHostSha}/production.json`. +1. Detects the existing deployment state file at _~/.aspire/deployments/{AppHostSha}/production.json_. 1. Notifies you that settings will be read from the cached file. 1. Prompts for confirmation to load the cached settings. 1. Loads the configuration from the cached file into the configuration provider. @@ -32,6 +34,8 @@ On subsequent `aspire deploy` executions, the command: ## Environment-specific deployments +Different deployment environments (such as development, staging, and production) typically require different configurations, resource names, and connection strings. The `aspire deploy` command supports environment-specific deployments, ensuring that each environment maintains isolated deployment state. + ### Specify an environment Use the `--environment` flag to deploy to different environments: @@ -43,7 +47,7 @@ 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` (for example, `staging.json`). +- Saves deployment state to _~/.aspire/deployments/{AppHostSha}/{environment}.json_ (for example, _staging.json_). **Subsequent deployments:** @@ -63,6 +67,8 @@ This behaves identically to using the `--environment` flag, loading the appropri ## Cache management +The `aspire deploy` command provides mechanisms to manage cached deployment state, giving you control over when to use cached values and when to start fresh. + ### Clear the cache Use the `--clear-cache` flag to reset deployment state: @@ -74,7 +80,7 @@ aspire deploy --clear-cache **Behavior:** 1. Prompts for confirmation before deleting the cache for the specified environment. -1. Deletes the environment-specific deployment state file (for example, `~/.aspire/deployments/{AppHostSha}/production.json`). +1. Deletes the environment-specific deployment state file (for example, _~/.aspire/deployments/{AppHostSha}/production.json_). 1. Prompts for all provisioning and parameter information as if deploying for the first time. 1. Proceeds with deployment. 1. **Does not save the prompted values** to cache. @@ -87,17 +93,58 @@ 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. +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` +- **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. +## Use deployment state in CI/CD pipelines + +When using the `aspire deploy` command in continuous integration and deployment (CI/CD) pipelines, you might want to persist deployment state across pipeline runs. This approach can be useful for maintaining consistent deployment configurations without manual intervention. + +### GitHub Actions example + +The following example demonstrates how to cache deployment state in a GitHub Actions workflow using the `actions/cache` action: + +```yaml +name: Deploy to Azure + +on: + push: + branches: [ main ] + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Cache Aspire deployment state + uses: actions/cache@v4 + with: + path: ~/.aspire/deployments + key: aspire-deploy-${{ hashFiles('**/AppHost.csproj') }}-${{ github.ref }} + restore-keys: | + aspire-deploy-${{ hashFiles('**/AppHost.csproj') }}- + aspire-deploy- + + - name: Deploy with Aspire CLI + run: aspire deploy --environment production + env: + AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }} +``` + +This workflow caches the _~/.aspire/deployments_ directory, using the AppHost project file hash and branch reference as cache keys. Subsequent workflow runs restore the cached deployment state, allowing automated deployments without re-prompting for configuration values. + +> [!CAUTION] +> When caching deployment state in CI/CD pipelines, ensure that your pipeline has appropriate access controls and secret management practices in place, as the cached state might contain sensitive configuration values. + ## Security considerations -The deployment state files are stored locally on your machine in the `~/.aspire/deployments` directory. These files contain provisioning settings and parameter values, including secrets that might be associated with parameter resources. The `aspire deploy` command follows the same security pattern as .NET's user secrets manager: +The deployment state files are stored locally on your machine in the _~/.aspire/deployments_ directory. These files contain provisioning settings and parameter values, including secrets that might be associated with parameter resources. The `aspire deploy` command follows the same security pattern as .NET's user secrets manager: - Files are stored outside of source code to mitigate against accidental secret leaks in version control. - Secrets are stored in plain text in the local file system. @@ -106,7 +153,7 @@ The deployment state files are stored locally on your machine in the `~/.aspire/ Consider these security best practices: - Ensure your local machine has appropriate security measures in place. -- Be cautious when sharing or backing up files from the `~/.aspire/deployments` directory. +- Be cautious when sharing or backing up files from the _~/.aspire/deployments_ directory. - Use the `--clear-cache` flag when you need to change sensitive parameter values. ## Key points From 5ab8d2948aff73f797a37130304498732057ef47 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 24 Oct 2025 23:50:46 +0000 Subject: [PATCH 4/5] Rename and relocate deployment state doc outside Azure section Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- .openpublishing.redirection.json | 4 ++++ docs/cli-reference/aspire-deploy.md | 2 +- .../deployment/aspire-deploy/aca-deployment-aspire-cli.md | 2 +- ...al-deployment-state.md => deployment-state-caching.md} | 8 ++++---- docs/toc.yml | 6 +++--- 5 files changed, 13 insertions(+), 9 deletions(-) rename docs/deployment/{aspire-deploy/local-deployment-state.md => deployment-state-caching.md} (96%) diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 937c2eef76..31ea8958ed 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -335,6 +335,10 @@ { "source_path_from_root": "/docs/fundamentals/build-container-images.md", "redirect_url": "/dotnet/aspire/fundamentals/custom-deployments" + }, + { + "source_path_from_root": "/docs/deployment/aspire-deploy/local-deployment-state.md", + "redirect_url": "/dotnet/aspire/deployment/deployment-state-caching" } ] } diff --git a/docs/cli-reference/aspire-deploy.md b/docs/cli-reference/aspire-deploy.md index c091c9afba..216f9cc086 100644 --- a/docs/cli-reference/aspire-deploy.md +++ b/docs/cli-reference/aspire-deploy.md @@ -113,4 +113,4 @@ The following options are available: ## See also -- [Local deployment state](../deployment/aspire-deploy/local-deployment-state.md) +- [Deployment state caching](../deployment/deployment-state-caching.md) diff --git a/docs/deployment/aspire-deploy/aca-deployment-aspire-cli.md b/docs/deployment/aspire-deploy/aca-deployment-aspire-cli.md index ff886f497c..be738eeb63 100644 --- a/docs/deployment/aspire-deploy/aca-deployment-aspire-cli.md +++ b/docs/deployment/aspire-deploy/aca-deployment-aspire-cli.md @@ -139,7 +139,7 @@ Save to user secrets: [y/n] (n): n ``` > [!NOTE] -> The CLI continuously prompts until all unresolved parameters are provided with values. The `aspire deploy` command caches deployment state locally to streamline subsequent deployments. For more information, see [Local deployment state](local-deployment-state.md). +> The CLI continuously prompts until all unresolved parameters are provided with values. The `aspire deploy` command caches deployment state locally to streamline subsequent deployments. For more information, see [Deployment state caching](../deployment-state-caching.md). Once parameters are collected, Azure infrastructure is provisioned using Bicep templates. This step creates the necessary Azure resources including the Container Apps environment, Container Registry, and any backing services like Redis caches: diff --git a/docs/deployment/aspire-deploy/local-deployment-state.md b/docs/deployment/deployment-state-caching.md similarity index 96% rename from docs/deployment/aspire-deploy/local-deployment-state.md rename to docs/deployment/deployment-state-caching.md index 704a183089..09fe415459 100644 --- a/docs/deployment/aspire-deploy/local-deployment-state.md +++ b/docs/deployment/deployment-state-caching.md @@ -1,11 +1,11 @@ --- -title: Local deployment state +title: Deployment state caching description: Learn how the aspire deploy command manages deployment state through cached configuration files. ms.date: 10/17/2025 ai-usage: ai-assisted --- -# Local deployment state +# Deployment state caching The `aspire deploy` command manages deployment state through cached configuration files stored locally on your machine. This caching mechanism streamlines repeated deployments by preserving provisioning settings and parameters, making subsequent deployments faster and more efficient. @@ -167,5 +167,5 @@ Consider these security best practices: ## See also -- [aspire deploy command reference](../../cli-reference/aspire-deploy.md) -- [Deploy to Azure Container Apps using Aspire CLI](aca-deployment-aspire-cli.md) +- [aspire deploy command reference](../cli-reference/aspire-deploy.md) +- [Deploy to Azure Container Apps using Aspire CLI](aspire-deploy/aca-deployment-aspire-cli.md) diff --git a/docs/toc.yml b/docs/toc.yml index 88280d6a51..7bfa08de33 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -491,6 +491,9 @@ items: href: deployment/overview.md - name: Building custom deployment pipelines href: fundamentals/custom-deployments.md + - name: Deployment state caching + href: deployment/deployment-state-caching.md + displayName: deployment state,deployment cache,clear-cache,deployment settings,aspire deploy - name: Azure deployment with Aspire items: - name: Deploy to Azure Container Apps using Aspire CLI @@ -498,9 +501,6 @@ items: - name: Deploy to Azure Container Apps using Visual Studio href: deployment/aspire-deploy/aca-deployment-visual-studio.md displayName: azure container apps,vs - - name: Local deployment state - href: deployment/aspire-deploy/local-deployment-state.md - displayName: deployment state,deployment cache,clear-cache,deployment settings - name: Azure security best practices href: deployment/aspire-deploy/azure-security-best-practices.md displayName: azure security,security best practices,container security,managed identity From 2d0bdce56571f55090dabd2877177fd861a1e0bd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 24 Oct 2025 23:56:28 +0000 Subject: [PATCH 5/5] Clarify cache save behavior in GitHub Actions example Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- docs/deployment/deployment-state-caching.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deployment/deployment-state-caching.md b/docs/deployment/deployment-state-caching.md index 09fe415459..0f9988d607 100644 --- a/docs/deployment/deployment-state-caching.md +++ b/docs/deployment/deployment-state-caching.md @@ -137,7 +137,7 @@ jobs: AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }} ``` -This workflow caches the _~/.aspire/deployments_ directory, using the AppHost project file hash and branch reference as cache keys. Subsequent workflow runs restore the cached deployment state, allowing automated deployments without re-prompting for configuration values. +This workflow caches the _~/.aspire/deployments_ directory, using the AppHost project file hash and branch reference as cache keys. The `actions/cache` action automatically restores the cache before the deployment step and saves any updates to the cache after the job completes. Subsequent workflow runs restore the cached deployment state, allowing automated deployments without re-prompting for configuration values. > [!CAUTION] > When caching deployment state in CI/CD pipelines, ensure that your pipeline has appropriate access controls and secret management practices in place, as the cached state might contain sensitive configuration values.