Sync diff from MS Docs and fix some bugs (#977)
This commit is contained in:
Yonghui Ye
GitHub
Родитель
8453f15711
Коммит
aa7a6cded1
|
|
@ -11,5 +11,7 @@
|
|||
}
|
||||
],
|
||||
"timeout": "20s",
|
||||
"aliveStatusCodes": [200]
|
||||
"aliveStatusCodes": [200],
|
||||
"retryOn429": true,
|
||||
"retryCount": 5
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,34 +1,44 @@
|
|||
|
||||
[appendix]
|
||||
== Configuration Properties
|
||||
[#global_proeprties]
|
||||
=== Global Properties
|
||||
include::_configuration-properties-global.adoc[]
|
||||
=== Azure Active Directory Properties
|
||||
include::_configuration-properties-azure-active-directory.adoc[]
|
||||
=== Azure Active Directory B2C Properties
|
||||
include::_configuration-properties-azure-active-directory-b2c.adoc[]
|
||||
[#azure_app_configuration_proeprties]
|
||||
=== Azure App Configuration Properties
|
||||
include::_configuration-properties-azure-app-configuration.adoc[]
|
||||
[#azure_cosmos_proeprties]
|
||||
=== Azure Cosmos Properties
|
||||
include::_configuration-properties-azure-cosmos-db.adoc[]
|
||||
[#azure_event_hubs_proeprties]
|
||||
=== Azure Event Hubs Properties
|
||||
include::_configuration-properties-azure-event-hubs.adoc[]
|
||||
=== Azure Key Vault Properties
|
||||
include::_configuration-properties-azure-key-vault.adoc[]
|
||||
[#azure_key_vault_secrets_proeprties]
|
||||
=== Azure Key Vault Secrets Properties
|
||||
include::_configuration-properties-azure-key-vault-secrets.adoc[]
|
||||
[#azure_key_vault_certificates_proeprties]
|
||||
=== Azure Key Vault Certificates Properties
|
||||
include::_configuration-properties-azure-key-vault-certificates.adoc[]
|
||||
[#azure_service_bus_proeprties]
|
||||
=== Azure Service Bus Properties
|
||||
include::_configuration-properties-azure-service-bus.adoc[]
|
||||
=== Azure Service Bus JMS Properties
|
||||
include::_configuration-properties-azure-service-bus-jms.adoc[]
|
||||
=== Azure Storage Properties
|
||||
include::_configuration-properties-azure-storage.adoc[]
|
||||
[#azure_storage_blob_proeprties]
|
||||
=== Azure Storage Blob Properties
|
||||
include::_configuration-properties-azure-storage-blob.adoc[]
|
||||
[#azure_storage_file_share_proeprties]
|
||||
=== Azure Storage File Share Properties
|
||||
include::_configuration-properties-azure-storage-file-share.adoc[]
|
||||
[#azure_storage_queue_proeprties]
|
||||
=== Azure Storage Queue Properties
|
||||
include::_configuration-properties-azure-storage-queue.adoc[]
|
||||
=== All Configuration Properties
|
||||
|
|
@ -37,6 +47,12 @@ include::_configuration-properties-all.adoc[]
|
|||
[appendix]
|
||||
include::_migration-guide-for-4.0.adoc[]
|
||||
|
||||
[appendix]
|
||||
include::create-and-configure-managed-identity.adoc[]
|
||||
|
||||
[appendix]
|
||||
include::deploy-applications-to-azure-hosting-environments.adoc[]
|
||||
|
||||
[appendix]
|
||||
include::_known-issues.adoc[]
|
||||
|
||||
|
|
|
|||
|
|
@ -60,37 +60,37 @@ Spring Cloud Azure unifies configuration properties' prefixes to `spring.cloud.a
|
|||
|
||||
|Azure App Configuration
|
||||
|spring.cloud.azure.*appconfiguration*
|
||||
|link:appendix.html#_azure_app_configuration_proeprties[App Configuration Properties]
|
||||
|link:appendix.html#azure_app_configuration_proeprties[App Configuration Properties]
|
||||
|
||||
|Azure Cosmos DB
|
||||
|spring.cloud.azure.*cosmos*
|
||||
|link:appendix.html#_azure_cosmos_proeprties[Cosmos Properties]
|
||||
|link:appendix.html#azure_cosmos_proeprties[Cosmos Properties]
|
||||
|
||||
|Azure Event Hubs
|
||||
|spring.cloud.azure.*eventhubs*
|
||||
|link:appendix.html#_azure_event_hubs_proeprties[Event Hubs Properties]
|
||||
|link:appendix.html#azure_event_hubs_proeprties[Event Hubs Properties]
|
||||
|
||||
|Azure Key Vault Certificates
|
||||
|spring.cloud.azure.*keyvault.certificate*
|
||||
|link:appendix.html#_azure_key_vault_certificates_proeprties[Key Vault Certificates Properties]
|
||||
|link:appendix.html#azure_key_vault_certificates_proeprties[Key Vault Certificates Properties]
|
||||
|
||||
|Azure Key Vault Secrets
|
||||
|spring.cloud.azure.*keyvault.secret*
|
||||
|link:appendix.html#_azure_key_vault_secrets_proeprties[Key Vault Secrets Properties]
|
||||
|link:appendix.html#azure_key_vault_secrets_proeprties[Key Vault Secrets Properties]
|
||||
|
||||
|Azure Service Bus
|
||||
|spring.cloud.azure.*servicebus*
|
||||
|link:appendix.html#_azure_service_bus_proeprties[Service Bus Properties]
|
||||
|link:appendix.html#azure_service_bus_proeprties[Service Bus Properties]
|
||||
|
||||
|Azure Storage Blob
|
||||
|spring.cloud.azure.*storage.blob*
|
||||
|link:appendix.html#_azure_storage_blob_proeprties[Storage Blob Properties]
|
||||
|link:appendix.html#azure_storage_blob_proeprties[Storage Blob Properties]
|
||||
|
||||
|Azure Storage File Share
|
||||
|spring.cloud.azure.*storage.fileshare*
|
||||
|link:appendix.html#_azure_storage_file_share_proeprties[Storage File Share Properties]
|
||||
|link:appendix.html#azure_storage_file_share_proeprties[Storage File Share Properties]
|
||||
|
||||
|Azure Storage Queue
|
||||
|spring.cloud.azure.*storage.queue*
|
||||
|link:appendix.html#_azure_storage_queue_proeprties[Storage Queue Properties]
|
||||
|link:appendix.html#azure_storage_queue_proeprties[Storage Queue Properties]
|
||||
|===
|
||||
|
|
|
|||
|
|
@ -0,0 +1,30 @@
|
|||
[#create-and-configure-a-managed-identity-on-azure-hosting-services]
|
||||
== Create and configure a managed identity on Azure hosting services
|
||||
|
||||
There are two types of managed identities: **system-assigned** and **user-assigned**.
|
||||
|
||||
For more information about Azure managed identities, see link:https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/[Azure AD-managed identities for Azure resources].
|
||||
|
||||
For more information about Azure Active Directory, see link:https://docs.microsoft.com/azure/active-directory/fundamentals/active-directory-whatis[What is Azure Active Directory].
|
||||
|
||||
=== Create and configure a system-assigned managed identity
|
||||
|
||||
The following list provides references on how to create and configure system-assigned managed identity on various Azure hosting services.
|
||||
|
||||
- Azure VM. For more information, see link:https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm[Configure managed identities for Azure resources on a VM using the Azure portal].
|
||||
- Azure App Service and Azure Functions. For more information, see link:https://docs.microsoft.com/azure/app-service/overview-managed-identity[How to use managed identities for App Service and Azure Functions].
|
||||
- Azure Containers Instances. For more information, see link:https://docs.microsoft.com/azure/container-instances/container-instances-managed-identity[How to use managed identities with Azure Container Instances].
|
||||
- Azure Kubernetes Service(AKS). For more information, see link:https://docs.microsoft.com/azure/aks/use-managed-identity[Use a managed identity in Azure Kubernetes Service].
|
||||
- Azure Spring Apps. For more information, see link:https://docs.microsoft.com/azure/spring-cloud/how-to-enable-system-assigned-managed-identity?tabs=azure-portal&pivots=sc-standard-tier[Enable system-assigned managed identity for an application in Azure Spring Apps].
|
||||
|
||||
=== Create and configure a user-assigned managed identity
|
||||
|
||||
For instructions on how to create a user-assigned managed identity, see link:https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp[Manage user-assigned managed identities].
|
||||
|
||||
The following list provides references on how to configure a user-assigned managed identity on various Azure hosting services.
|
||||
|
||||
- Azure VM. For more information, see link:https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm[Configure managed identities for Azure resources on a VM using the Azure portal].
|
||||
- Azure App Service and Azure Functions. For more information, see link:https://docs.microsoft.com/azure/app-service/overview-managed-identity[How to use managed identities for App Service and Azure Functions].
|
||||
- Azure Containers instances. For more information, see link:https://docs.microsoft.com/azure/container-instances/container-instances-managed-identity[How to use managed identities with Azure Container Instances].
|
||||
- Azure Kubernetes Service(AKS). For more information, see link:https://docs.microsoft.com/azure/aks/use-managed-identity#bring-your-own-control-plane-mi[Use a managed identity in Azure Kubernetes Service].
|
||||
- Azure Spring Apps. For more information, see link:https://docs.microsoft.com/azure/spring-cloud/how-to-manage-user-assigned-managed-identities?tabs=azure-portal&pivots=sc-standard-tier[Manage user-assigned managed identities for an application in Azure Spring Apps].
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
[#deploy-application-to-azure-hosting-services]
|
||||
== Deploy application to Azure hosting services
|
||||
|
||||
The following list provides references on how to deploy applications to various Azure hosting services.
|
||||
|
||||
- Azure Virtual Machines (VMs). For more information, see the link:https://docs.microsoft.com/azure/virtual-machines/linux/tutorial-manage-vm#connect-to-vm[Connect to VM] section of link:https://docs.microsoft.com/azure/virtual-machines/linux/tutorial-manage-vm[Tutorial: Create and Manage Linux VMs with the Azure CLI]. After you connect to the VM, you have to install and configure your applications yourself.
|
||||
|
||||
- Azure App Service. For more information, see link:https://docs.microsoft.com/azure/app-service/deploy-best-practices[Azure App Service deployment].
|
||||
|
||||
- Azure Functions. For more information, see link:https://docs.microsoft.com/azure/azure-functions/functions-deployment-technologies[Deployment technologies in Azure Functions].
|
||||
|
||||
- Azure Containers Instances. For more information, see link:https://docs.microsoft.com/azure/container-instances/container-instances-quickstart[Quickstart: Deploy a container instance in Azure using the Azure CLI].
|
||||
|
||||
- Azure Kubernetes Service (AKS). For more information, see link:https://docs.microsoft.com/azure/developer/java/spring-framework/deploy-spring-boot-java-app-on-kubernetes[Deploy Spring Boot Application to the Azure Kubernetes Service].
|
||||
|
||||
- Azure Spring Apps. For more information, see link:https://docs.microsoft.com/azure/spring-cloud/quickstart-deploy-apps?tabs=Azure-CLI&pivots=programming-language-java[Quickstart: Build and deploy apps to Azure Spring Apps].
|
||||
|
|
@ -30,4 +30,5 @@ include::configuration-properties.adoc[]
|
|||
=== link:appendix.html##configuration-properties[Configuration properties]
|
||||
=== link:appendix.html#migration-guide-for-4-0[Migration guide for 4.0]
|
||||
=== link:appendix.html#known-issues[Known issues]
|
||||
|
||||
=== link:appendix.html#create-and-configure-a-managed-identity-on-azure-hosting-services[Create and configure a managed identity on Azure hosting services]
|
||||
=== link:appendix.html#deploy-application-to-azure-hosting-services[Deploy application to Azure hosting services]
|
||||
|
|
|
|||
|
|
@ -1,10 +1,253 @@
|
|||
[#kafka-support]
|
||||
== Kafka Support
|
||||
|
||||
Connect to Azure Event Hubs (link:https://azure.microsoft.com/pricing/details/event-hubs/#explore-pricing-options[Basic pricing tier is not supported]) using Spring Kafka libraries. There are two approaches to connect to Azure Event Hubs for Kafka, the first one is to provide the Azure Event Hubs connection string directly, the other is to use Azure Resource Manager to retrieve the connection string.
|
||||
From version 4.3.0, Spring Cloud Azure for Kafka supports various types of credentials to authenticate and connect to Azure Event Hubs.
|
||||
|
||||
=== Supported Kafka version
|
||||
|
||||
The current version of the starter should be compatible with Apache Kafka Clients 2.0.0 using Java 8 or above.
|
||||
|
||||
=== Supported authentication types
|
||||
|
||||
The following authentication types are supported:
|
||||
|
||||
* Plain connection string authentication
|
||||
** Direct connection string authentication
|
||||
** ARM-based connection string authentication
|
||||
* OAuth credential authentication
|
||||
** Managed identity authentication
|
||||
** Username/password authentication
|
||||
** Service principal authentication
|
||||
** `DefautlAzureCredential` authentication
|
||||
|
||||
=== How it works
|
||||
|
||||
==== OAuth credential authentication
|
||||
|
||||
This section describes the overall workflow of Spring Cloud Azure OAuth authentication.
|
||||
|
||||
Spring Cloud Azure will first build one of the following types of credentials depending on the application authentication configuration:
|
||||
|
||||
- `ClientSecretCredential`
|
||||
- `ClientCertificateCredential`
|
||||
- `UsernamePasswordCredential`
|
||||
- `ManagedIdentityCredential`
|
||||
|
||||
If none of these types of credentials are found, the credential chain via `DefaultAzureTokenCredential` will be used to obtain credentials from application properties, environment variables, managed identity, or IDEs. For detailed information, see the link:index.html#authentication[Authentication] section.
|
||||
|
||||
==== Plain connection string authentication
|
||||
|
||||
For the connection string authentication mode, you can use connection string authentication directly or use the Azure Resource Manager to retrieve the connection string. For more information about the usage, see the link:#basic-usage-connection-string[Basic usage for connection string authentication] section.
|
||||
|
||||
NOTE: Since version of 4.3.0, connection string authentication is deprecated in favor of OAuth authentications.
|
||||
|
||||
=== Configuration
|
||||
|
||||
==== Configurable properties when using Kafka support with OAuth authentication
|
||||
|
||||
Spring Cloud Azure for Kafka supports the following two levels of configuration options:
|
||||
|
||||
1. The global authentication configuration options of `credential` and `profile` with prefixes of `spring.cloud.azure`.
|
||||
2. Kafka-specific level configurations. The Kafka-level configurations are also available for Spring Boot and Spring Cloud Stream binders for `common`, `consumer`, `producer`, or `admin` scopes, which have different prefixes.
|
||||
|
||||
The global properties are exposed via `com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties`. The Kafka-specific properties are exposed via `org.springframework.boot.autoconfigure.kafka.KafkaProperties` (Spring Boot) and `org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties` (Spring Cloud Stream binder).
|
||||
|
||||
The following list shows all supported configuration options.
|
||||
|
||||
* The Spring Cloud Azure global authentication configuration options
|
||||
|
||||
** Prefix: `spring.cloud.azure`
|
||||
** Supported options: `spring.cloud.azure.credential.*`, `spring.cloud.azure.profile.*`
|
||||
|
||||
For the full list of global configuration options, see the link:appendix.html#global_proeprties[Global properties] section.
|
||||
|
||||
* Spring Boot Kafka common configuration
|
||||
|
||||
** Prefix: `spring.kafka.properties.azure`
|
||||
** Example: `spring.kafka.properties.azure`.credential.*
|
||||
|
||||
* Spring Kafka consumer configuration options
|
||||
|
||||
** Prefix: `spring.kafka.consumer.properties.azure`
|
||||
** Example: `spring.kafka.consumer.properties.azure`.credential.*
|
||||
|
||||
* Spring Kafka producer configuration options
|
||||
|
||||
** Prefix: `spring.kafka.producer.properties.azure`
|
||||
** Example: `spring.kafka.producer.properties.azure`.credential.*
|
||||
|
||||
* Spring Kafka admin configuration options
|
||||
|
||||
** Prefix: `spring.kafka.admin.properties.azure`
|
||||
** Example: `spring.kafka.admin.properties.azure`.credential.*
|
||||
|
||||
* Spring Cloud Stream Kafka Binder common configuration
|
||||
|
||||
** Prefix: `spring.cloud.stream.kafka.binder.configuration.azure`
|
||||
** Example: `spring.cloud.stream.kafka.binder.configuration.azure`.credential.*
|
||||
|
||||
* Spring Cloud Stream Kafka Binder consumer configuration
|
||||
|
||||
** Prefix: `spring.cloud.stream.kafka.binder.consumer-properties.azure`
|
||||
** Example: `spring.cloud.stream.kafka.binder.consumer-properties.azure`.credential.*
|
||||
|
||||
* Spring Cloud Stream Kafka Binder producer configuration
|
||||
|
||||
** Prefix: `spring.cloud.stream.kafka.binder.producer-properties.azure`
|
||||
** Example: `spring.cloud.stream.kafka.binder.producer-properties.azure`.credential.*
|
||||
|
||||
* Spring Cloud Stream Kafka Binder admin configuration
|
||||
|
||||
** Prefix: Not supported, should use Spring Boot Kafka common or admin configuration.
|
||||
|
||||
.Spring Boot Kafka common configuration options
|
||||
[cols="2*", options="header"]
|
||||
|===
|
||||
|Property
|
||||
|Description
|
||||
| spring.kafka.properties.azure.credential.client-certificate-password | Password of the certificate file.
|
||||
| spring.kafka.properties.azure.credential.client-certificate-path | Path of a PEM certificate file to use when performing service principal authentication with Azure.
|
||||
| spring.kafka.properties.azure.credential.client-id | Client ID to use when performing service principal authentication with Azure. This is a legacy property.
|
||||
| spring.kafka.properties.azure.credential.client-secret | Client secret to use when performing service principal authentication with Azure. This is a legacy property.
|
||||
| spring.kafka.properties.azure.credential.managed-identity-enabled | Whether to enable managed identity to authenticate with Azure. If *true* and the `client-id` is set, will use the client ID as user assigned managed identity client ID. The default value is *false*.
|
||||
| spring.kafka.properties.azure.credential.password | Password to use when performing username/password authentication with Azure.
|
||||
| spring.kafka.properties.azure.credential.username | Username to use when performing username/password authentication with Azure.
|
||||
| spring.kafka.properties.azure.profile.environment.active-directory-endpoint | The Azure Active Directory endpoint to connect to.
|
||||
| spring.kafka.properties.azure.profile.tenant-id | Tenant ID for Azure resources.
|
||||
|===
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
The configuration options in different levels apply the following rules. The more specific configuration options have higher priority than the common ones. For example:
|
||||
|
||||
- Spring Kafka common configuration options supersede the global options.
|
||||
- Spring Kafka consumer configuration options supersede the common options.
|
||||
- Spring Kafka producer configuration options supersede the common options.
|
||||
- Spring Kafka admin configuration options supersede the common options.
|
||||
- The Spring Cloud Stream Kafka Binder options are just like the above.
|
||||
====
|
||||
|
||||
==== Configurable properties when using Kafka support with plain connection string authentication
|
||||
|
||||
|
||||
.Spring Boot Event Hubs for Kafka common configuration options
|
||||
[cols="2*", options="header"]
|
||||
|===
|
||||
|Property
|
||||
|Description
|
||||
| **spring.cloud.azure.eventhubs**.kafka.enabled | Whether to enable the Azure Event Hubs Kafka support. The default value is *true*.
|
||||
| **spring.cloud.azure.eventhubs**.connection-string | Azure Event Hubs connection string. Provide this value when you want to provide the connection string directly.
|
||||
| **spring.cloud.azure.eventhubs**.namespace | Azure Event Hubs namespace. Provide this value when you want to retrieve the connection information through Azure Resource Manager.
|
||||
| **spring.cloud.azure.eventhubs**.resource.resource-group | The resource group of Azure Event Hubs namespace. Provide this value when you want to retrieve the connection information through Azure Resource Manager.
|
||||
| **spring.cloud.azure**.profile.subscription-id | The subscription ID. Provide this value when you want to retrieve the connection information through Azure Resource Manager.
|
||||
|===
|
||||
|
||||
=== Dependency Setup
|
||||
|
||||
Add the following dependency to your project. This will automatically include the `spring-boot-starter` dependency in your project transitively.
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>com.azure.spring</groupId>
|
||||
<artifactId>spring-cloud-azure-starter</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
NOTE: Remember to add the BOM `spring-cloud-azure-dependencies` along with the above dependency. For details, see the link:index.html#starter-dependencies[Getting started] section.
|
||||
|
||||
=== Basic usage
|
||||
|
||||
The following sections show the classic Spring Boot application usage scenarios.
|
||||
|
||||
==== Use OAuth authentication
|
||||
|
||||
When you use the OAuth authentication provided by Spring Cloud Azure for Kafka, you can configure the specific credentials using the above configurations. Alternatively, you can choose to configure nothing about credentials, in which case Spring Cloud Azure will load the credentials from the environment. This section describes the usages that load the credentials from the Azure CLI environment or the Azure Spring Apps hosting environment.
|
||||
|
||||
NOTE: If you choose to use a security principal to authenticate and authorize with Azure Active Directory for accessing an Azure resource, see the link:index.html#authorize-access-with-azure-active-directory[Authorize access with Azure Active Directory] section to make sure the security principal has been granted the sufficient permission to access the Azure resource.
|
||||
|
||||
The following section describes the scenarios using different Spring ecosystem libraries with OAuth authentication.
|
||||
|
||||
===== Spring Kafka application support
|
||||
|
||||
This section describes the usage scenario for Spring Boot application using Spring Kafka or Spring Integration Kafka library.
|
||||
|
||||
====== Dependency setup
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>com.azure.spring</groupId>
|
||||
<artifactId>spring-cloud-azure-starter</artifactId>
|
||||
</dependency>
|
||||
<!-- Using Spring Kafka library only-->
|
||||
<dependency>
|
||||
<groupId>org.springframework.kafka</groupId>
|
||||
<artifactId>spring-kafka</artifactId>
|
||||
<version>{version}</version><!--Need to be set, for example:2.8.6-->
|
||||
</dependency>
|
||||
<!-- Using Spring Integration library only -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.integration</groupId>
|
||||
<artifactId>spring-integration-kafka</artifactId>
|
||||
<version>{version}</version><!--Need to be set, for example:5.5.12-->
|
||||
</dependency>
|
||||
----
|
||||
|
||||
[#spring-kafka-configuraiton-setup]
|
||||
====== Configuration update
|
||||
|
||||
To use the OAuth authentication, just specify the Event Hubs endpoint, as shown in the following example:
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
spring.kafka.bootstrap-servers=<NAMESPACENAME>.servicebus.windows.net:9093
|
||||
----
|
||||
|
||||
===== Spring Cloud Stream binder Kafka application support
|
||||
|
||||
This section describes the usage scenario for Spring Boot applications using the Spring Cloud Stream binder Kafka library.
|
||||
|
||||
====== Dependency setup
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>com.azure.spring</groupId>
|
||||
<artifactId>spring-cloud-azure-starter</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-stream-kafka</artifactId>
|
||||
<version>{version}</version><!--Need to be set, for example:3.2.3-->
|
||||
</dependency>
|
||||
----
|
||||
|
||||
====== Configuration
|
||||
|
||||
To use the OAuth authentication, just specify the Event Hubs endpoint and `com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration`, as shown in the following example:
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
spring.cloud.stream.kafka.binder.brokers=<NAMESPACENAME>.servicebus.windows.net:9093
|
||||
spring.cloud.stream.binders.kafka.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration
|
||||
----
|
||||
|
||||
NOTE: Set `com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration` to enable the whole OAuth authentication workflow.
|
||||
|
||||
====== Samples
|
||||
|
||||
See the link:https://github.com/Azure-Samples/azure-spring-boot-samples/tree/spring-cloud-azure_{project-version}[azure-spring-boot-samples] repository on GitHub.
|
||||
|
||||
[#basic-usage-connection-string]
|
||||
==== Use connection string authentication
|
||||
|
||||
You can use connection string authentication directly or use the Azure Resource Manager to retrieve the connection string.
|
||||
|
||||
NOTE: Since version of 4.3.0, connection string authentication is deprecated in favor of OAuth authentications.
|
||||
|
||||
===== Dependency setup
|
||||
|
||||
Add the following dependencies if you want to migrate your Apache Kafka application to use Azure Event Hubs for Kafka.
|
||||
|
||||
[source,xml]
|
||||
|
|
@ -15,7 +258,7 @@ Add the following dependencies if you want to migrate your Apache Kafka applicat
|
|||
</dependency>
|
||||
----
|
||||
|
||||
If you want to retrieve the connection string using Azure Resource Manager, please also add below dependency
|
||||
If you want to retrieve the connection string using Azure Resource Manager, add the following dependency:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
|
|
@ -25,52 +268,24 @@ If you want to retrieve the connection string using Azure Resource Manager, plea
|
|||
</dependency>
|
||||
----
|
||||
|
||||
=== Configuration
|
||||
===== Configuration
|
||||
|
||||
NOTE: If you choose to use a security principal to authenticate and authorize with Azure Active Directory for accessing an Azure resource, please refer to link:index.html#authorize-access-with-azure-active-directory[Authorize access with Azure AD] to make sure the security principal has been granted the sufficient permission to access the Azure resource.
|
||||
====== Use Event Hubs connection string directly
|
||||
|
||||
.Configurable properties when using Kafka support
|
||||
[cols="2*", options="header"]
|
||||
|===
|
||||
|Property
|
||||
|Description
|
||||
|*spring.cloud.azure.eventhubs*.kafka.enabled
|
||||
|Whether to enable the Azure Event Hubs Kafka support, default to true.
|
||||
|*spring.cloud.azure.eventhubs*.connection-string
|
||||
|Azure Event Hubs connection string. Should be provided when want to provide the connection string directly.
|
||||
|*spring.cloud.azure.eventhubs*.namespace
|
||||
|Azure Event Hubs namespace. Should be provided when want to retrieve the connection information through Azure Resource Manager.
|
||||
|*spring.cloud.azure.eventhubs*.resource.resource-group
|
||||
|The resource group of Azure Event Hubs namespace. Should be provided when want to retrieve the connection information through Azure Resource Manager.
|
||||
|*spring.cloud.azure*.profile.subscription-id
|
||||
| The subscription id. Should be provided when want to retrieve the connection information through Azure Resource Manager.
|
||||
|===
|
||||
The simplest way to connect to Event Hubs for Kafka is with the connection string. Just add the following property.
|
||||
|
||||
NOTE: Authentication information is also required for authenticating for Azure Resource Manager. The credential related configurations of Resource Manager should be configured under prefix `spring.cloud.azure`. For more information, see the link:index.html#authentication[Authentication] section.
|
||||
|
||||
=== Basic Usage
|
||||
|
||||
|
||||
==== Use Event Hubs Connection String
|
||||
|
||||
The simplest way to connect to Event Hubs for Kafka is with the connection string.
|
||||
|
||||
Add the following properties and you are good to go.
|
||||
|
||||
[source,yaml]
|
||||
[source,properties]
|
||||
----
|
||||
spring:
|
||||
cloud:
|
||||
azure:
|
||||
eventhubs:
|
||||
connection-string: ${AZURE_EVENTHUBS_CONNECTION_STRING}
|
||||
spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
|
||||
----
|
||||
|
||||
==== Use Azure Resource Manager to Retrieve Connection String
|
||||
====== Use Azure Resource Manager to retrieve connection string
|
||||
|
||||
If you don't want to configure connection string in your application, it's also possible to use Azure Resource Manager to retrieve the connection string. And you could use credentials stored in Azure CLI or other local development tool, like Visual Studio Code or Intellij IDEA to authenticate with Azure Resource Manager. Or Managed Identity if your application is deployed to Azure Cloud. Just make sure the principal have sufficient permission to read resource metadata.
|
||||
If you don't want to configure the connection string in your application, you can use Azure Resource Manager to retrieve the connection string. To authenticate with Azure Resource Manager, you can also use credentials stored in Azure CLI or another local development tool such as Visual Studio Code or Intellij IDEA. Alternately, you can use Managed Identity if your application is deployed to Azure Cloud. Just be sure the principal has sufficient permission to read resource metadata.
|
||||
|
||||
Add the following properties and you are good to go.
|
||||
NOTE: If you choose to use a security principal to authenticate and authorize with Azure Active Directory for accessing an Azure resource, see the link:index.html#authorize-access-with-azure-active-directory[Authorize access with Azure Active Directory] section to be sure the security principal has been granted the sufficient permission to access the Azure resource.
|
||||
|
||||
To use Azure Resource Manager to retrieve the connection string, just add the following property.
|
||||
|
||||
[source,yaml]
|
||||
----
|
||||
|
|
@ -87,5 +302,6 @@ spring:
|
|||
|
||||
=== Samples
|
||||
|
||||
See link:https://github.com/Azure-Samples/azure-spring-boot-samples/tree/spring-cloud-azure_{project-version}[azure-spring-boot-samples] for more details.
|
||||
See the link:https://github.com/Azure-Samples/azure-spring-boot-samples/tree/spring-cloud-azure_{project-version}[azure-spring-boot-samples] repository on GitHub.
|
||||
|
||||
include::remove-credentials-from-spring-kafka-applications.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,108 @@
|
|||
|
||||
=== Remove credentials from Spring Kafka applications
|
||||
|
||||
==== Overview
|
||||
|
||||
You can use the Event Hubs Kafka endpoint in your Spring Kafka application. From Spring Cloud Azure 4.3.0, you can configure and run your application without credentials. This article is a migration guide for removing credentials from Spring Kafka applications.
|
||||
|
||||
==== Update dependencies
|
||||
|
||||
First, add the `spring-cloud-azure-dependencies` BOM, as shown in the following example:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>com.azure.spring</groupId>
|
||||
<artifactId>spring-cloud-azure-dependencies</artifactId>
|
||||
<version>${version.spring.cloud.azure}</version><!-- The version for spring-cloud-azure-dependencies is 4.3.0+.-->
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
----
|
||||
|
||||
Then, add the Spring Cloud Azure starter, as shown in the following example:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>com.azure.spring</groupId>
|
||||
<artifactId>spring-cloud-azure-starter</artifactId>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
----
|
||||
|
||||
==== Update configuration
|
||||
|
||||
If you're using Spring Kafka, remove the following options if you have customized values:
|
||||
|
||||
- `spring.kafka.security.protocol`
|
||||
- `spring.kafka.security.properties.sasl.mechanism`
|
||||
- `spring.kafka.security.properties.sasl.jaas.config`
|
||||
|
||||
The final configuration should look like the following example:
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
spring.kafka.bootstrap-servers=<NAMESPACENAME>.servicebus.windows.net:9093
|
||||
----
|
||||
|
||||
If you're using Spring Cloud Stream Binder Kafka, remove the following options if you have customized values:
|
||||
|
||||
- `spring.kafka.security.protocol`
|
||||
- `spring.kafka.security.properties.sasl.mechanism`
|
||||
- `spring.kafka.security.properties.sasl.jaas.config`
|
||||
- `spring.cloud.stream.kafka.configuration.security.protocol`
|
||||
- `spring.cloud.stream.kafka.configuration.sasl.mechanism`
|
||||
- `spring.cloud.stream.kafka.configuration.sasl.jaas.config`
|
||||
|
||||
Then, add the following option:
|
||||
|
||||
- `spring.cloud.stream.binders.kafka.environment.spring.main.sources`
|
||||
|
||||
The final configuration should look like the following example:
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
spring.cloud.stream.kafka.binder.brokers=<NAMESPACENAME>.servicebus.windows.net:9093
|
||||
spring.cloud.stream.binders.kafka.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration
|
||||
----
|
||||
|
||||
|
||||
NOTE: The `spring.cloud.stream.binders.kafka.environment.spring.main.sources` option is used to specify the additional configuration of `KafkaBinderConfigurationPropertiesBeanPostProcessor` specifying the OAuth security parameters for the particular binder.
|
||||
|
||||
==== Run locally
|
||||
|
||||
===== Grant permissions
|
||||
|
||||
With Azure AD, you can use Azure role-based access control (Azure RBAC) to grant permissions to a security principal, which may be a user or an application service principal.
|
||||
|
||||
Because Azure Event Hubs supports Azure role-based access control, you need to assign the corresponding data plane roles to the security principal you use when you want to read or write data to it. In this article, you'll use an Azure CLI credential to connect to Azure Event Hubs, so you need to assign roles to an Azure CLI account. For more information about assigning access roles, see link:https://docs.microsoft.com/azure/event-hubs/authorize-access-azure-active-directory[Authorize access to Event Hubs resources using Azure Active Directory].
|
||||
|
||||
NOTE: For data access, set the data plane access role: Azure Event Hubs Data Sender and Azure Event Hubs Data Receiver.
|
||||
|
||||
===== Sign in to your Azure account
|
||||
|
||||
To use the Azure CLI credential, first use the Azure CLI command `az login` to sign in. Then, build and test your application.
|
||||
|
||||
NOTE: If you want to use other local environment credentials, for example with IntelliJ, see link:index.html#authentication[Authentication] for details.
|
||||
|
||||
==== Deploy to Azure Spring Apps
|
||||
|
||||
This section describes how to run the application locally. In production, you can deploy the application to Azure hosting environments like Azure Spring Apps.
|
||||
|
||||
===== Create and configure managed identity
|
||||
|
||||
To connect with managed identities, enable the managed identity on Azure Spring Apps and grant the access permissions. For more information, see link:appendix.html#create-and-configure-a-managed-identity-on-azure-hosting-services[Create and configure a managed identity on Azure hosting services].
|
||||
|
||||
For information on how to assign roles to the managed identity, see link:https://docs.microsoft.com/azure/role-based-access-control/role-assignments-portal[Assign Azure roles using the Azure portal].
|
||||
|
||||
NOTE: For data access, set the data plane access role: Azure Event Hubs Data Sender and Azure Event Hubs Data Receiver.
|
||||
|
||||
===== Deploy to Azure Spring Apps
|
||||
|
||||
For more information, see link:appendix.html#deploy-application-to-azure-hosting-services[Deploy application to Azure hosting services].
|
||||
|
|
@ -511,9 +511,9 @@ By doing this, when access `/app-role1` endpoint, the following claims in access
|
|||
====== Use JWT Client Authentication
|
||||
|
||||
1. Read link:https://docs.microsoft.com/azure/active-directory/develop/active-directory-certificate-credentials#register-your-certificate-with-microsoft-identity-platform[MS docs about Register your certificate with Microsoft identity platform].
|
||||
1. Upload a *.pem* certificate to application registered in Azure Portal.
|
||||
2. Configure certificate path and password of a **.PFX* or **.P12* certificate.
|
||||
3. Add property `spring.cloud.azure.active-directory.authorization-clients.azure.client-authentication-method=private_key_jwt` configuration to client that wants to be authenticated through JWT Client Authentication.
|
||||
2. Upload a *.pem* certificate to application registered in Azure Portal.
|
||||
3. Configure certificate path and password of a **.PFX* or **.P12* certificate.
|
||||
4. Add property `spring.cloud.azure.active-directory.authorization-clients.azure.client-authentication-method=private_key_jwt` configuration to client that wants to be authenticated through JWT Client Authentication.
|
||||
|
||||
Below is an example configuration file for a Web Application scenario, certificate information is configured in global properties:
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче