diff --git a/docs/azure/integrations-overview.md b/docs/azure/integrations-overview.md index d5499b51e3..3cf913074a 100644 --- a/docs/azure/integrations-overview.md +++ b/docs/azure/integrations-overview.md @@ -1,7 +1,7 @@ --- title: Azure integrations overview description: Overview of the Azure integrations available in the .NET Aspire. -ms.date: 03/07/2025 +ms.date: 03/24/2025 uid: dotnet/aspire/integrations/azure-overview --- @@ -107,7 +107,7 @@ You can query whether a resource is marked as an existing resource, by calling t .NET Aspire provides support for referencing existing Azure resources. You mark an existing resource through the `PublishAsExisting`, `RunAsExisting`, and `AsExisting` APIs. These APIs allow developers to reference already-deployed Azure resources, configure them, and generate appropriate deployment manifests using Bicep templates. -Existing resources referenced with these APIs can be enhanced with role assignments and other customizations that are available with .NET Aspire's [infrastructure as code capabilities](#infrastructure-as-code). These APIs are limited to Azure resources that can be deployed with Bicep templates. +Existing resources referenced with these APIs can be enhanced with [role assignments](role-assignments.md) and other customizations that are available with .NET Aspire's [infrastructure as code capabilities](#infrastructure-as-code). These APIs are limited to Azure resources that can be deployed with Bicep templates. ### Configure existing Azure resources for run mode diff --git a/docs/azure/role-assignments.md b/docs/azure/role-assignments.md new file mode 100644 index 0000000000..e336ab448e --- /dev/null +++ b/docs/azure/role-assignments.md @@ -0,0 +1,261 @@ +--- +title: Manage Azure role assignments +description: Learn how to override Azure role assignments on .NET Aspire resources. +ms.date: 03/31/2025 +--- + +# Manage Azure role assignments + +All .NET Aspire Azure hosting integrations define Azure resources. [These resources](integrations-overview.md#add-azure-resources) come with default role assignments. You can replace these default role assignments with built-in role [or custom role assignments](integrations-overview.md#infrastructure-as-code). In this article, you learn how to manage Azure role assignments on .NET Aspire resources. + +## Default built-in role assignments + +When you add an Azure resource to the [app model](xref:dotnet/aspire/app-host#terminology), it's assigned default roles. If a resource depends on another resource, it inherits the same role assignments as the referenced resource unless explicitly overridden. + +Consider a scenario where an API project resource references an [Azure Search](../azureai/azureai-search-document-integration.md) resource. The API project is given the default role assignments, as shown in the following example: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var search = builder.AddAzureSearch("search"); + +var api = builder.AddProject("api") + .WithReference(search); +``` + +In the example code, the `api` project resource depends on the Azure `search` resource, meaning it references the `search` resource. By default, the `search` resource is assigned the following built-in roles: + +- +- + +These role assignments allow the API project to read and write data to the Azure Search resource, and manage it. However, this behavior might not always be desirable. For instance, you might want to restrict the API project to only read data from the Azure Search resource. + +## Override default role assignments + + + +To override the default role assignment, use the `WithRoleAssignments` API and assign built-in roles as shown in the following example: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var search = builder.AddAzureSearch("search"); + +var api = builder.AddProject("api") + .WithRoleAssignments(search, SearchBuiltInRole.SearchIndexDataReader) + .WithReference(search); +``` + +When you use the `WithRoleAssignments` method, it replaces the default role assignments with the specified ones. This method requires two parameters: the resource to which the role assignment applies and the built-in role to assign. In the preceding example, the `search` resource is assigned the role. + +When you replace the default role assignments with the `SearchIndexDataReader` role, the API project is restricted to only reading data from the Azure Search resource. This ensures the API project can't write data to the Azure Search resource. + +For more information, see [Azure built-in roles](/azure/role-based-access-control/built-in-roles). + +## Built-in role assignment reference + +All built-in roles are defined within the namespaces and are included in the corresponding [📦 Azure.Provisioning.*](https://www.nuget.org/packages?q=Azure.Provisioning) NuGet packages. Each .NET Aspire Azure hosting integration automatically depends on the appropriate provisioning package. For more information, see [Infrastructure as code](integrations-overview.md#infrastructure-as-code). + +The following sections list the built-in roles for each Azure provisioning type that can be used as a parameter to the `WithRoleAssignments` API. + +### Azure App Configuration + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- + + + +### Azure App Container + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- + + + +### Azure Application Insights + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- +- +- +- +- + +For more information, see [Use Application Insights for .NET Aspire telemetry](../deployment/azure/application-insights.md). + +### Azure AI (formerly Cognitive Services) + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +For more information, see [.NET Aspire Azure OpenAI integration (Preview)](../azureai/azureai-openai-integration.md). + +### Azure Cosmos DB + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- + +For more information, see: + +- [.NET Aspire Azure Cosmos DB integration](../database/azure-cosmos-db-integration.md). +- [.NET Aspire Cosmos DB Entity Framework Core integration](../database/azure-cosmos-db-entity-framework-integration.md). + +### Azure Event Hubs + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- +- +- + +For more information, see [.NET Aspire Azure Event Hubs integration](../messaging/azure-event-hubs-integration.md). + +### Azure Key Vault + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +For more information, see [.NET Aspire Azure Key Vault integration](../security/azure-security-key-vault-integration.md). + +### Azure AI Search + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- + +For more information, see [.NET Aspire Azure AI Search integration](../azureai/azureai-search-document-integration.md). + +### Azure Service Bus + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- + +For more information, see [.NET Aspire Azure Service Bus integration](../messaging/azure-service-bus-integration.md). + +### Azure SignalR Service + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- +- +- +- + +For more information, see [.NET Aspire support for Azure SignalR Service](../real-time/azure-signalr-scenario.md). + +### Azure SQL + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- +- +- + + + +### Azure Storage + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +For more information, see: + +- [.NET Aspire Azure Blob Storage integration](../storage/azure-storage-blobs-integration.md) +- [.NET Aspire Azure Data Tables integration](../storage/azure-storage-tables-integration.md) +- [.NET Aspire Azure Queue Storage integration](../storage/azure-storage-queues-integration.md) + +### Azure Web PubSub + +The provisioning resource type is , and the built-in roles are defined in the struct. The built-in roles are: + +- +- +- + +For more information, see [.NET Aspire Azure Web PubSub integration](../messaging/azure-web-pubsub-integration.md). + +## See also + +- [.NET Aspire Azure integrations overview](integrations-overview.md) +- [Azure role-based access control (RBAC)](/azure/role-based-access-control/overview) diff --git a/docs/snippets/azure/AppHost/AppHost.csproj b/docs/snippets/azure/AppHost/AppHost.csproj index 36aa7ab054..6ac9064224 100644 --- a/docs/snippets/azure/AppHost/AppHost.csproj +++ b/docs/snippets/azure/AppHost/AppHost.csproj @@ -14,10 +14,12 @@ + + diff --git a/docs/toc.yml b/docs/toc.yml index ce9a2dbf84..52824fbbd0 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -29,12 +29,12 @@ items: - name: Upgrade to .NET Aspire 9.0 href: get-started/upgrade-to-aspire-9.md -- name: App Host (Orchestration) +- name: App Host (Dev-time orchestration) items: - name: Overview - displayName: orchestration,aspire apphost,aspire app + displayName: orchestration,aspire apphost,aspire app,dev-time,inner-loop href: fundamentals/app-host-overview.md - - name: Orchestrate + - name: Locally orchestrate items: - name: Node.js apps in .NET Aspire href: get-started/build-aspire-apps-with-nodejs.md @@ -136,6 +136,8 @@ items: href: azure/integrations-overview.md - name: Local Azure provisioning href: azure/local-provisioning.md + - name: Manage role assignments + href: azure/role-assignments.md - name: Azure AI Search displayName: azure search,search,azure ai,cognitive search,cognitive services href: azureai/azureai-search-document-integration.md