From a3d8e5cbb22ae72c84eed3fef50f9d9102f4bb49 Mon Sep 17 00:00:00 2001 From: David Fowler Date: Mon, 30 Mar 2026 01:08:22 -0700 Subject: [PATCH 01/23] Reshuffle deployment docs structure - Move pipelines doc from get-started to deployment section - Move manifest-format under deployment/azure with deprecation notice - Create new Deploy to Docker Compose page - Create new Deploy to Kubernetes page - Create new Azure Developer CLI (azd) page (legacy/alternative path) - Create new Customize Azure Container Apps page - Remove stale preview labels (aspire deploy and Docker are GA) - Update Docker package version from preview to 13.1.0 - Remove manifest references from general-purpose docs - Position aspire deploy as primary Azure deployment path - Trim integration pages (Docker, K8s) to link to deployment pages - Update sidebar, redirects, and cross-references - Update stale aspire-8.0.json schema reference Addresses: #354, #331, #335, #358, #359 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- src/frontend/config/redirects.mjs | 2 + .../config/sidebar/deployment.topics.ts | 59 +- src/frontend/config/sidebar/docs.topics.ts | 2 +- .../docs/app-host/container-registry.mdx | 2 +- .../deployment/azure/azure-developer-cli.mdx | 85 ++ .../azure/customize-container-apps.mdx | 122 ++ .../{ => azure}/manifest-format.mdx | 6 +- .../docs/deployment/custom-deployments.mdx | 7 +- .../docs/deployment/docker-compose.mdx | 377 +++++ .../src/content/docs/deployment/index.mdx | 15 +- .../content/docs/deployment/kubernetes.mdx | 183 +++ .../src/content/docs/deployment/overview.mdx | 26 +- .../{get-started => deployment}/pipelines.mdx | 0 src/frontend/src/content/docs/docs.mdx | 2 +- .../docs/fundamentals/external-parameters.mdx | 22 +- .../get-started/deploy-first-app-csharp.mdx | 4 +- .../deploy-first-app-typescript.mdx | 2 +- .../docs/get-started/deploy-first-app.mdx | 1359 ++++++++++++++++- .../src/content/docs/get-started/glossary.mdx | 4 +- .../docs/get-started/what-is-aspire.mdx | 2 +- src/frontend/src/content/docs/index.mdx | 2 +- .../integrations/cloud/azure/overview.mdx | 23 +- .../docs/integrations/compute/docker.mdx | 62 +- .../docs/integrations/compute/kubernetes.mdx | 48 +- .../hosting-integrations.mdx | 6 +- .../docs/reference/cli/commands/aspire-do.mdx | 2 +- .../src/content/docs/whats-new/aspire-13.mdx | 2 +- .../src/content/docs/whats-new/aspire-9-2.mdx | 2 +- 28 files changed, 2181 insertions(+), 247 deletions(-) create mode 100644 src/frontend/src/content/docs/deployment/azure/azure-developer-cli.mdx create mode 100644 src/frontend/src/content/docs/deployment/azure/customize-container-apps.mdx rename src/frontend/src/content/docs/deployment/{ => azure}/manifest-format.mdx (97%) create mode 100644 src/frontend/src/content/docs/deployment/docker-compose.mdx create mode 100644 src/frontend/src/content/docs/deployment/kubernetes.mdx rename src/frontend/src/content/docs/{get-started => deployment}/pipelines.mdx (100%) diff --git a/src/frontend/config/redirects.mjs b/src/frontend/config/redirects.mjs index e49b51812..f5d4541bc 100644 --- a/src/frontend/config/redirects.mjs +++ b/src/frontend/config/redirects.mjs @@ -72,4 +72,6 @@ export const redirects = { '/reference/cli/commands/aspire-mcp-start/': '/reference/cli/commands/aspire-agent-mcp/', '/reference/cli/commands/aspire-exec/': '/reference/cli/commands/aspire-resource/', '/get-started/configure-mcp/': '/get-started/ai-coding-agents/', + '/get-started/pipelines/': '/deployment/pipelines/', + '/deployment/manifest-format/': '/deployment/azure/manifest-format/', }; diff --git a/src/frontend/config/sidebar/deployment.topics.ts b/src/frontend/config/sidebar/deployment.topics.ts index 7e3a39df7..def1ac79d 100644 --- a/src/frontend/config/sidebar/deployment.topics.ts +++ b/src/frontend/config/sidebar/deployment.topics.ts @@ -64,29 +64,8 @@ export const deploymentTopics: StarlightSidebarTopicsUserConfig = { slug: 'deployment/overview', }, { - label: 'Deploy JavaScript apps', - slug: 'deployment/javascript-apps', - }, - { - label: 'Deployment manifest format', - translations: { - da: 'Udrulningsmanifestformat', - de: 'Bereitstellungsmanifestformat', - en: 'Deployment manifest format', - es: 'Formato de manifiesto de despliegue', - fr: 'Format de manifeste de déploiement', - hi: 'तैनाती मैनिफ़ेस्ट प्रारूप', - id: 'Format manifes penyebaran', - it: 'Formato del manifesto di distribuzione', - ja: 'デプロイマニフェスト形式', - ko: '배포 매니페스트 형식', - 'pt-BR': 'Formato de manifesto de implantação', - ru: 'Формат манифеста развертывания', - tr: 'Dağıtım bildirimi biçimi', - uk: 'Формат маніфесту розгортання', - 'zh-CN': '部署清单格式', - }, - slug: 'deployment/manifest-format', + label: 'Pipelines (aspire do)', + slug: 'deployment/pipelines', }, { label: 'Deployment state caching', @@ -130,6 +109,22 @@ export const deploymentTopics: StarlightSidebarTopicsUserConfig = { }, slug: 'deployment/custom-deployments', }, + { + label: 'Deploy JavaScript apps', + slug: 'deployment/javascript-apps', + }, + { + label: 'Deploy to Docker Compose', + slug: 'deployment/docker-compose', + }, + { + label: 'Deploy to Kubernetes', + slug: 'deployment/kubernetes', + }, + { + label: 'Deploy to Kubernetes', + slug: 'deployment/kubernetes', + }, { label: 'Deploy to Azure', collapsed: false, @@ -172,6 +167,24 @@ export const deploymentTopics: StarlightSidebarTopicsUserConfig = { }, slug: 'deployment/azure/aca-deployment-aspire-cli', }, + { + label: 'Azure Developer CLI (azd)', + collapsed: true, + items: [ + { + label: 'Overview', + slug: 'deployment/azure/azure-developer-cli', + }, + { + label: 'Deployment manifest format', + slug: 'deployment/azure/manifest-format', + }, + ], + }, + { + label: 'Customize Azure Container Apps', + slug: 'deployment/azure/customize-container-apps', + }, { label: 'Azure security best practices', translations: { diff --git a/src/frontend/config/sidebar/docs.topics.ts b/src/frontend/config/sidebar/docs.topics.ts index d221912bc..61d3edc20 100644 --- a/src/frontend/config/sidebar/docs.topics.ts +++ b/src/frontend/config/sidebar/docs.topics.ts @@ -548,7 +548,7 @@ export const docsTopics: StarlightSidebarTopicsUserConfig = { uk: 'Розгортання і топологія застосунку', 'zh-CN': '部署与应用拓扑', }, - slug: 'get-started/pipelines', + slug: 'deployment/pipelines', }, { label: 'Understanding resources', diff --git a/src/frontend/src/content/docs/app-host/container-registry.mdx b/src/frontend/src/content/docs/app-host/container-registry.mdx index a53dacfa5..b3771a6b6 100644 --- a/src/frontend/src/content/docs/app-host/container-registry.mdx +++ b/src/frontend/src/content/docs/app-host/container-registry.mdx @@ -629,4 +629,4 @@ The explicit container registry configuration introduced in Aspire 13.1 provides - [Configure Azure Container Apps environments](/integrations/cloud/azure/configure-container-apps/) - [`aspire do` command](/reference/cli/commands/aspire-do/) - [External parameters](/fundamentals/external-parameters/) -- [Pipelines and app topology](/get-started/pipelines/) +- [Pipelines and app topology](/deployment/pipelines/) diff --git a/src/frontend/src/content/docs/deployment/azure/azure-developer-cli.mdx b/src/frontend/src/content/docs/deployment/azure/azure-developer-cli.mdx new file mode 100644 index 000000000..cf8f52835 --- /dev/null +++ b/src/frontend/src/content/docs/deployment/azure/azure-developer-cli.mdx @@ -0,0 +1,85 @@ +--- +title: Azure Developer CLI (azd) +description: Learn how to use the Azure Developer CLI as an alternative deployment path for Aspire applications. +--- + +import { Aside, Steps } from '@astrojs/starlight/components'; + +The Azure Developer CLI (`azd`) is a developer-oriented command-line tool that can provision Azure resources and deploy applications from your local environment or CI/CD pipelines. It integrates with Aspire by consuming the deployment manifest format to understand your app model and automatically provision the corresponding Azure resources. + + + +## When to use azd + +While `aspire deploy` is the recommended path, `azd` remains useful in several scenarios: + +- You have **existing `azd` workflows** and infrastructure templates you want to continue using. +- You need **`azd pipeline config`** for automated CI/CD setup with GitHub Actions or Azure DevOps. +- You want to use **`azd` environment management** features to manage multiple deployment environments. +- You're working with **teams already familiar** with `azd` conventions and tooling. + +## Prerequisites + +- [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) installed +- An active Azure subscription — [create one for free](https://azure.microsoft.com/free/) +- [Aspire CLI](/get-started/install-cli/) installed + +## Basic workflow + + + +1. **Initialize your project** — run `azd init` from your AppHost directory. When prompted, select **Use code in the current directory** so `azd` detects the Aspire app model. + + ```bash title="Initialize azd in the AppHost directory" + azd init + ``` + +2. **Provision and deploy** — run `azd up` to provision the required Azure resources and deploy your application in a single step. This combines the `azd provision` and `azd deploy` commands. + + ```bash title="Provision infrastructure and deploy" + azd up + ``` + +3. **Redeploy without reprovisioning** — after the initial deployment, use `azd deploy` to push code changes without reprovisioning infrastructure. + + ```bash title="Deploy updated code" + azd deploy + ``` + + + +## `aspire deploy` vs `azd` comparison + +| Feature | `aspire deploy` | `azd` | +|---|---|---| +| Azure Container Apps | ✅ | ✅ | +| Azure App Service | ✅ | ❌ | +| Infrastructure provisioning | Built-in | Built-in | +| CI/CD pipeline setup | Manual | `azd pipeline config` | +| Environment management | State caching | `azd env` | +| Manifest dependency | No | Yes | + +## Resource naming + +The `aspire deploy` path and `azd` use different resource naming schemes by default. If you're upgrading from an existing `azd` deployment to `aspire deploy`, use `WithAzdResourceNaming()` to preserve the original naming convention. This avoids creating duplicate Azure resources: + +```csharp title="AppHost.cs" +builder.AddAzureContainerAppEnvironment("env") + .WithAzdResourceNaming(); +``` + +## Deployment manifest + +The `azd` tool relies on the [deployment manifest format](/deployment/azure/manifest-format/) to understand your application topology. The manifest is a JSON document generated from the AppHost that describes resources, bindings, and parameters. It's produced automatically when `azd` invokes the AppHost during deployment. + + + +## See also + +- [Deploy using the Aspire CLI](/deployment/azure/aca-deployment-aspire-cli/) — recommended deployment path +- [Deployment manifest format](/deployment/azure/manifest-format/) +- [Azure Developer CLI documentation](https://learn.microsoft.com/azure/developer/azure-developer-cli/) diff --git a/src/frontend/src/content/docs/deployment/azure/customize-container-apps.mdx b/src/frontend/src/content/docs/deployment/azure/customize-container-apps.mdx new file mode 100644 index 000000000..38aa1487e --- /dev/null +++ b/src/frontend/src/content/docs/deployment/azure/customize-container-apps.mdx @@ -0,0 +1,122 @@ +--- +title: Customize Azure Container Apps +description: Learn how to customize Azure Container Apps deployments for your Aspire applications. +--- + +import { Aside } from '@astrojs/starlight/components'; +import LearnMore from '@components/LearnMore.astro'; + +When you deploy to Azure Container Apps using `aspire deploy`, Aspire provisions infrastructure automatically based on the resources defined in your AppHost. While the defaults work for many scenarios, you often need to customize the generated infrastructure—scaling rules, custom domains, resource groups, role assignments, and more. + +This page covers the most common customization options for Azure Container Apps deployments. For hosting-side configuration of the Container Apps _environment_, see [Configure Azure Container Apps](/integrations/cloud/azure/configure-container-apps/). + +## Customize a Container App with `PublishAsAzureContainerApp` + +Use `PublishAsAzureContainerApp` to customize the generated Container App resource for any project, container, or executable in your AppHost. The callback gives you access to the `AzureResourceInfrastructure` and the `ContainerApp` construct, allowing you to modify any property of the generated resource. + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +builder.AddAzureContainerAppEnvironment("env"); + +builder.AddProject("api") + .PublishAsAzureContainerApp((infrastructure, app) => + { + // Customize the Container App + app.Template.Scale.MinReplicas = 1; + app.Template.Scale.MaxReplicas = 10; + }); + +builder.Build().Run(); +``` + +The `infrastructure` parameter provides access to the overall Azure resource infrastructure, while the `app` parameter represents the `ContainerApp` construct. You can modify scaling, ingress, environment variables, and other settings directly. + + +For more information, see [Publish as Azure Container App](/integrations/cloud/azure/overview/#publish-as-azure-container-app). + + +## Custom domains + +Use `ConfigureCustomDomain` to set up custom domains on Container Apps. This lets you bind a custom DNS name and a managed certificate to your Container App. + +```csharp title="AppHost.cs" +var customDomain = builder.AddParameter("customDomain"); +var certificateName = builder.AddParameter("certificateName"); + +builder.AddProject("api") + .PublishAsAzureContainerApp((infrastructure, app) => + { + ContainerAppExtensions.ConfigureCustomDomain( + app, customDomain, certificateName); + }); +``` + + + +## Existing Azure resources + +When you have Azure resources that already exist—such as a shared Service Bus namespace or a database server—you can reference them instead of having Aspire provision new ones. Aspire provides three APIs for this: + +- `AsExisting` — use the existing resource in both local development and deployment. +- `RunAsExisting` — use the existing resource during local development only. +- `PublishAsExisting` — use the existing resource during deployment only. + +```csharp title="AppHost.cs" +var existingBusName = builder.AddParameter("existingServiceBusName"); + +var serviceBus = builder.AddAzureServiceBus("messaging") + .PublishAsExisting(existingBusName); +``` + +When you reference an existing resource, Aspire skips provisioning for that resource and instead configures your application to connect to the specified instance. + + + +## Resource groups + +By default, all resources deploy to the same resource group. Use `WithResourceGroup` to target a specific resource group for individual resources. This is useful when you need to deploy to a shared resource group managed outside of Aspire: + +```csharp title="AppHost.cs" +builder.AddAzureServiceBus("messaging") + .WithResourceGroup("my-shared-rg"); +``` + +## Role assignments + +Aspire automatically assigns Azure RBAC roles for resources based on how they're referenced. For example, a project that references an Azure Service Bus resource is automatically granted the **Azure Service Bus Data Sender** role. + +To remove the default role assignments for a resource, use `ClearDefaultRoleAssignments`: + +```csharp title="AppHost.cs" +builder.AddAzureServiceBus("messaging") + .ClearDefaultRoleAssignments(); +``` + +Custom role assignments can be configured via `ConfigureInfrastructure`. + + +For more information, see [Manage Azure role assignments](/integrations/cloud/azure/role-assignments/). + + +## Service discovery on Azure Container Apps + +Services deployed to Azure Container Apps use internal DNS for service discovery. HTTP and HTTPS endpoints are both available by default for internal communication between container apps. + +To expose an endpoint externally (outside the Container Apps environment), use `WithExternalHttpEndpoints()`: + +```csharp title="AppHost.cs" +builder.AddProject("api") + .WithExternalHttpEndpoints(); +``` + +## See also + +- [Configure Azure Container Apps](/integrations/cloud/azure/configure-container-apps/) +- [Deploy using the Aspire CLI](/deployment/azure/aca-deployment-aspire-cli/) +- [Manage Azure role assignments](/integrations/cloud/azure/role-assignments/) +- [Azure security best practices](/deployment/azure/azure-security-best-practices/) diff --git a/src/frontend/src/content/docs/deployment/manifest-format.mdx b/src/frontend/src/content/docs/deployment/azure/manifest-format.mdx similarity index 97% rename from src/frontend/src/content/docs/deployment/manifest-format.mdx rename to src/frontend/src/content/docs/deployment/azure/manifest-format.mdx index 15ef3e3ff..e53bed33b 100644 --- a/src/frontend/src/content/docs/deployment/manifest-format.mdx +++ b/src/frontend/src/content/docs/deployment/azure/manifest-format.mdx @@ -13,6 +13,10 @@ import placeholderMappingsLight from '@assets/deployment/placeholder-mappings-li The deployment manifest is a JSON-formatted document generated by Aspire to describe your app's resources and their relationships. This manifest is consumed by deployment tools to provision and configure infrastructure in target cloud environments. + + ## Generate the manifest Create a new Aspire project using the following command: @@ -209,7 +213,7 @@ The final segment of the placeholder string (`url` in this case) is generated by ## Resource types -Each resource has a `type` field. When a deployment tool reads the manifest, it should read the type to verify whether it can correctly process the manifest. During the Aspire preview period, all resource types have a `v0` suffix to indicate that they're subject to change. As Aspire approaches release a `v1` suffix will be used to signify that the structure of the manifest for that resource type should be considered stable (subsequent updates increment the version number accordingly). +Each resource has a `type` field. When a deployment tool reads the manifest, it should read the type to verify whether it can correctly process the manifest. All resource types currently use a `v0` suffix. This format is no longer being actively evolved — for new deployments, use `aspire publish` and `aspire deploy` with compute environment integrations instead. ### Common resource fields diff --git a/src/frontend/src/content/docs/deployment/custom-deployments.mdx b/src/frontend/src/content/docs/deployment/custom-deployments.mdx index 82cfa8599..2b8b111de 100644 --- a/src/frontend/src/content/docs/deployment/custom-deployments.mdx +++ b/src/frontend/src/content/docs/deployment/custom-deployments.mdx @@ -17,10 +17,9 @@ During publishing and deployment, the container image builder is available to cr These APIs give you fine-grained control over the image building process and provide real-time feedback to users during lengthy build operations. -