diff --git a/sdk/spring/azure-spring-boot-samples/azure-spring-cloud-sample-servicebus-queue-multibinders/README.adoc b/sdk/spring/azure-spring-boot-samples/azure-spring-cloud-sample-servicebus-queue-multibinders/README.adoc index 99b4ae04a728..62356c2a0df8 100644 --- a/sdk/spring/azure-spring-boot-samples/azure-spring-cloud-sample-servicebus-queue-multibinders/README.adoc +++ b/sdk/spring/azure-spring-boot-samples/azure-spring-cloud-sample-servicebus-queue-multibinders/README.adoc @@ -36,7 +36,112 @@ spring.cloud.stream.binders.servicebus2.type=servicebus-queue spring.cloud.stream.binders.servicebus2.defaultCandidate=false spring.cloud.stream.binders.servicebus2.environment.spring.cloud.azure.servicebus.connection-string=[servicebus-namespace-2-connection-string] +# Configuration for bindings +spring.cloud.stream.bindings.input.destination=[servicebus-queue-1-name] +spring.cloud.stream.bindings.output.destination=[servicebus-queue-name-same-as-above] +spring.cloud.stream.bindings.input1.destination=[servicebus-queue-2-name] +spring.cloud.stream.bindings.output1.destination=[servicebus-queue-name-same-as-above] +spring.cloud.stream.bindings.input1.binder=servicebus2 +spring.cloud.stream.bindings.output1.binder=servicebus2 +.... + +=== MSI credential based usage + +==== Overview + +https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/[MSI] (Managed Service Identity, aka Managed Identity) for Azure resources provides Azure services with an automatically managed identity in https://docs.microsoft.com/azure/active-directory/fundamentals/active-directory-whatis[Azure AD]. +You can use this identity to authenticate to any service that supports Azure AD authentication without having any credentials in your code. + +==== Prerequisites + +1. Create https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-quickstart-portal[Azure Service Bus]. +Please note `Basic` tier is unsupported. + +2. Create https://docs.microsoft.com/azure/storage/[Azure Storage] for checkpoint use. + +==== Setup Application + +Please note your application should run in VM (Virtual Machine) or App Services on Azure for support of MSI. Choose any of them. + +===== Method 1: Setup VM and assign identity + +1. Create VM in Azure portal. +Please refer to https://docs.microsoft.com/azure/virtual-machines/windows/quick-create-portal[Create a Windows virtual machine in the Azure portal] or https://docs.microsoft.com/azure/virtual-machines/linux/quick-create-portal[Create a Linux virtual machine in the Azure portal]. +Choose any one according to your needs. + +2. Create an user-assigned identity in Azure Portal. +Please refer to https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-to-manage-ua-identity-portal#create-a-user-assigned-managed-identity[Create an user-assigned managed identity]. + +3. Assign the user-assigned identity to the VM. +Please refer to https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm#assign-a-user-assigned-managed-identity-to-an-existing-vm[Assign an user-assigned managed identity to an existing VM]. + +===== Method 2: Setup App Service and assign identity + +- 1. Deploy this sample's Spring Boot JAR file to App Service. + +You can follow https://docs.microsoft.com/java/azure/spring-framework/deploy-spring-boot-java-app-with-maven-plugin?toc=%2Fazure%2Fapp-service%2Fcontainers%2Ftoc.json&view=azure-java-stable[ + Deploy a Spring Boot JAR file to Azure App Service] to deploy the JAR file. + +Another way to deploy an executable JAR is via FTP/S. Follow https://docs.microsoft.com/azure/app-service/deploy-ftp[ +Deploy your app to App Service using FTP/S]. +And the JAR file's name must be `app.jar`. + +- 2. Create a managed identity for App Service. + +If you choose system-assigned identity, follow https://docs.microsoft.com/azure/app-service/overview-managed-identity#adding-a-system-assigned-identity[ + Adding a system assigned identity]. + +If you choose user-assigned identity, follow https://docs.microsoft.com/azure/app-service/overview-managed-identity#adding-a-user-assigned-identity[ + Adding a user assigned identity]. + +==== Add Role Assignment for Resource Group + +- Resource Group: assign `Reader` role for managed identity. + +See https://docs.microsoft.com/azure/role-based-access-control/role-assignments-portal[Add or remove Azure role assignments] to add the role assignment for Resource Group. + +For different built-in role's descriptions, please see https://docs.microsoft.com/azure/role-based-access-control/built-in-roles[Built-in role descriptions]. + +==== Add Role Assignment for Service Bus +- Namespace of Service Bus: assign `Contributor` role for managed identity. + +See https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-managed-service-identity[Managed identities for Azure resources with Service Bus] to add role assignment for Service Bus, Storage Account is similar. + + +==== Add MSI related properties +1. Update link:src/main/resources/application.properties[application.properties] ++ +.... +# Enable MSI +spring.cloud.azure.msi-enabled=true +spring.cloud.azure.resource-group=[resource-group] +spring.cloud.azure.subscription-id=[subscription-id] +spring.cloud.azure.servicebus=[servicebus-namespace-1] +spring.cloud.azure.managed-identity.client-id=[client id of managed identity] + +# Default binder +spring.cloud.stream.bindings.input.destination=[servicebus-queue-1-name] +spring.cloud.stream.bindings.output.destination=[servicebus-queue-1-name-same-as-above] +spring.cloud.stream.servicebus.queue.bindings.input.consumer.checkpoint-mode=MANUAL + +# Another binder for servicebus2 +spring.cloud.stream.binders.servicebus2.type=servicebus-queue +spring.cloud.stream.binders.servicebus2.defaultCandidate=false +spring.cloud.stream.binders.servicebus2.environment.spring.cloud.azure.servicebus.namespace=[servicebus-namespace-2] + +spring.cloud.stream.binders.servicebus2.environment.spring.cloud.azure.msi-enabled=true +spring.cloud.stream.binders.servicebus2.environment.spring.cloud.azure.resource-group=[resource-group] +spring.cloud.stream.binders.servicebus2.environment.spring.cloud.azure.subscription-id=[subscription-id] +spring.cloud.stream.binders.servicebus2.environment.spring.cloud.azure.managed-identity.client-id=[client id of managed identity] + +spring.cloud.stream.bindings.input1.destination=[servicebus-queue-2-name] +spring.cloud.stream.bindings.output1.destination=[servicebus-queue-2-name-same-as-above] +spring.cloud.stream.bindings.input1.binder=servicebus2 +spring.cloud.stream.bindings.output1.binder=servicebus2 + +# Use manual checkpoint mode +spring.cloud.stream.servicebus.queue.bindings.input1.consumer.checkpoint-mode=MANUAL .... [NOTE] @@ -47,23 +152,16 @@ Whether the binder configuration is a candidate for being considered a default b This allows adding binder configurations without interfering with the default processing. ==== +==== Redeploy Application + +If you update the role assignment for services, then redeploy the app again. + === How to run First, we need to ensure that this {instruction}[instruction] is completed before run. 1. Update stream binding related properties in link:src/main/resources/application.properties[application.properties] -+ -[source%nowrap,properties] -.... -spring.cloud.stream.bindings.input.destination=[servicebus-queue-1-name] -spring.cloud.stream.bindings.output.destination=[servicebus-queue-name-same-as-above] - - -spring.cloud.stream.bindings.input1.destination=[servicebus-queue-2-name] -spring.cloud.stream.bindings.output1.destination=[servicebus-queue-name-same-as-above] -.... - -2. Run the `mvn clean spring-boot:run` in the root of the code sample to get the app running. +2. For connection string usage, run the `mvn clean spring-boot:run` in the root of the code sample to get the app running; for MSI usage, deploy or redeploy web application. 3. Send a POST request to test the default binder + @@ -71,6 +169,11 @@ spring.cloud.stream.bindings.output1.destination=[servicebus-queue-name-same-as- $ curl -X POST http://localhost:8080/messages?message=hello .... + +or when the app runs on App Service or VM ++ +.... +$ curl -d -X POST https://[your-app-URL]/messages?message=hello +.... 4. Verify in your app's logs that a similar message was posted: + @@ -85,6 +188,11 @@ $ curl -X POST http://localhost:8080/messages?message=hello $ curl -X POST http://localhost:8080/messages1?message=hello .... + +or when the app runs on App Service or VM ++ +.... +$ curl -d -X POST https://[your-app-URL]/messages1?message=hello +.... 6. Verify in your app's logs that a similar message was posted: +