Azure Event Hub Plugin

The plugin provides functionality to interact with Event Hub.

Installation

Copy the below line to dependencies section of the project build.gradle file

Please make sure to use the same version for all VIVIDUS dependencies.
Example 1. build.gradle
```
implementation(group: 'org.vividus', name: 'vividus-plugin-azure-event-hub')
```
If the project was imported to the IDE before adding new dependency, re-generate the configuration files for the used IDE and then refresh the project in the used IDE.

Event Hub management

Configuration

Authentication

The authentication process relies on the configuration of the environment variables.

See the official "Azure identity" guide to get more details on what types of authentication could be used.

Azure environment selection

Azure environment could be optionally specified using the property azure.environment (sets the environment for all Azure plugins). The default value is AZURE.

The supported environments are only:

AZURE
AZURE_CHINA
AZURE_GERMANY
AZURE_US_GOVERNMENT

Azure subscription selection

Azure subscription must be configured via AZURE_SUBSCRIPTION_ID environment variable.

Steps

Manage data capturing

Toggles data capturing option (enables or disables it) for the specified Azure Event Hub.

When I $toggle data capturing for event hub `$eventHubName` in namespace `$namespaceName` from resource group `$resourceGroupName`

$toggle - The data capturing toggle: either ENABLE or DISABLE.
$eventHubName - The event hub name.
$namespaceName - The name of the namespace the event hub belongs to.
$resourceGroupName - The resource group name.

The client should have permission to run action Microsoft.EventHub/namespaces/eventhubs/write over scope /subscriptions/{subscription ID}/resourceGroups/{resource group name}/providers/Microsoft.EventHub/namespaces/{event hub namespace}/eventhubs/{event hub name}.

Example 2. Restart data capturing

When I disable data capturing for event hub `sample_event_hub` in namespace `NS-EH` from resource group `RG-EH`
When I enable data capturing for event hub `sample_event_hub` in namespace `NS-EH` from resource group `RG-EH`

Azure Event Hub for Apache Kafka

Azure Event Hubs provides an Apache Kafka endpoint on an event hub, which allows users to connect to the event hub using the Kafka protocol. To achieve this, the following steps should be performed.

Add the Event Hub and Kafka plugins to the project build.gradle

implementation(group: 'org.vividus', name: 'vividus-plugin-azure-event-hub')
implementation(group: 'org.vividus', name: 'vividus-plugin-kafka')

Configure authentication for Kafka Consumer or/and Producer.

During publishing or consuming the Kafka client is trying to access the Event Hubs resources. These resources can be accessed only using an authorized entity. Azure Event Hubs provides 2 options to authorize access to the secure resources:

OAuth 2.0

Example 3. Configure consumer or producer to use OAuth 2.0

kafka.<consumer/producer>.<consumer-or-producer-key>.security.protocol=SASL_SSL
kafka.<consumer/producer>.<consumer-or-producer-key>.sasl.mechanism=OAUTHBEARER
kafka.<consumer/producer>.<consumer-or-producer-key>.sasl.login.callback.handler.class=org.apache.kafka.common.security.oauthbearer.secured.OAuthBearerLoginCallbackHandler
kafka.<consumer/producer>.<consumer-or-producer-key>.sasl.oauthbearer.token.endpoint.url=https://login.microsoftonline.com/<azure-tenant-id>/oauth2/v2.0/token
kafka.<consumer/producer>.<consumer-or-producer-key>.sasl.jaas.config= \
  org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
    clientId='<azure-client-id>' \
    scope='https://<azure-event-hub-namespace>.servicebus.windows.net/.default' \
    clientSecret='<azure-client-secret>';

Shared access signature (SAS)

Example 4. Configure consumer or producer to use SAS

kafka.<consumer/producer>.<consumer-or-producer-key>.security.protocol=SASL_SSL
kafka.<consumer/producer>.<consumer-or-producer-key>.sasl.mechanism=PLAIN
kafka.<consumer/producer>.<consumer-or-producer-key>.sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="$ConnectionString" password="Endpoint=sb://<azure-event-hub-url>/;SharedAccessKeyName=<shared-access-key-name>;SharedAccessKey=<shared-access-key>";