Azure Event Hubs binding spec

Detailed documentation on the Azure Event Hubs binding component

Component format

To setup an Azure Event Hubs binding, create a component of type bindings.azure.eventhubs. See this guide on how to create and apply a binding configuration.

See this for instructions on how to set up an Event Hub.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: <NAME>
  5. spec:
  6.   type: bindings.azure.eventhubs
  7.   version: v1
  8.   metadata:
  9.     # Hub name ("topic")
  10.     - name: eventHub
  11.       value: "mytopic"
  12.     - name: consumerGroup
  13.       value: "myapp"
  14.     # Either connectionString or eventHubNamespace is required
  15.     # Use connectionString when *not* using Azure AD
  16.     - name: connectionString
  17.       value: "Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"
  18.     # Use eventHubNamespace when using Azure AD
  19.     - name: eventHubNamespace
  20.       value: "namespace"
  21.     - name: enableEntityManagement
  22.       value: "false"
  23.     # The following four properties are needed only if enableEntityManagement is set to true
  24.     - name: resourceGroupName
  25.       value: "test-rg"
  26.     - name: subscriptionID
  27.       value: "value of Azure subscription ID"
  28.     - name: partitionCount
  29.       value: "1"
  30.     - name: messageRetentionInDays
  31.       value: "3"
  32.     # Checkpoint store attributes
  33.     - name: storageAccountName
  34.       value: "myeventhubstorage"
  35.     - name: storageAccountKey
  36.       value: "112233445566778899"
  37.     - name: storageContainerName
  38.       value: "myeventhubstoragecontainer"
  39.     # Alternative to passing storageAccountKey
  40.     - name: storageConnectionString
  41.       value: "DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<account-key>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

FieldRequiredBinding supportDetailsExample
eventHubYInput/OutputThe name of the Event Hubs hub (“topic”). Required if using Azure AD authentication or if the connection string doesn’t contain an EntityPath valuemytopic
connectionStringYInput/OutputConnection string for the Event Hub or the Event Hub namespace.
Mutally exclusive with eventHubNamespace field.
 Required when not using Azure AD Authentication		“Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}” or “Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key}”
eventHubNamespaceYInput/OutputThe Event Hub Namespace name.
Mutally exclusive with connectionString field.
Required when using Azure AD Authentication		“namespace”
enableEntityManagementNInput/OutputBoolean value to allow management of the EventHub namespace and storage account. Default: false“true”, “false”
resourceGroupNameNInput/OutputName of the resource group the Event Hub namespace is part of. Required when entity management is enabled“test-rg”
subscriptionIDNInput/OutputAzure subscription ID value. Required when entity management is enabled“azure subscription id”
partitionCountNInput/OutputNumber of partitions for the new Event Hub namespace. Used only when entity management is enabled. Default: “1”“2”
messageRetentionInDaysNInput/OutputNumber of days to retain messages for in the newly created Event Hub namespace. Used only when entity management is enabled. Default: “1”“90”
consumerGroupYInputThe name of the Event Hubs Consumer Group to listen on“group1”
storageAccountNameYInputStorage account name to use for the checkpoint store.“myeventhubstorage”
storageAccountKeyYInputStorage account key for the checkpoint store account.
When using Azure AD, it’s possible to omit this if the service principal has access to the storage account too.		“112233445566778899”
storageConnectionStringYInputConnection string for the checkpoint store, alternative to specifying storageAccountKey“DefaultEndpointsProtocol=https;AccountName=myeventhubstorage;AccountKey=<account-key>”
storageContainerNameYInputStorage container name for the storage account name.“myeventhubstoragecontainer”

Azure Active Directory (AAD) authentication

The Azure Event Hubs pub/sub component supports authentication using all Azure Active Directory mechanisms. For further information and the relevant component metadata fields to provide depending on the choice of AAD authentication mechanism, see the docs for authenticating to Azure.

Binding support

This component supports output binding with the following operations:

  • create: publishes a new message to Azure Event Hubs

Input Binding to Azure IoT Hub Events

Azure IoT Hub provides an endpoint that is compatible with Event Hubs, so Dapr apps can create input bindings to read Azure IoT Hub events using the Event Hubs bindings component.

The device-to-cloud events created by Azure IoT Hub devices will contain additional IoT Hub System Properties, and the Azure Event Hubs binding for Dapr will return the following as part of the response metadata:

System Property NameDescription & Routing Query Keyword
iothub-connection-auth-generation-idThe connectionDeviceGenerationId of the device that sent the message. See IoT Hub device identity properties.
iothub-connection-auth-methodThe connectionAuthMethod used to authenticate the device that sent the message.
iothub-connection-device-idThe deviceId of the device that sent the message. See IoT Hub device identity properties.
iothub-connection-module-idThe moduleId of the device that sent the message. See IoT Hub device identity properties.
iothub-enqueuedtimeThe enqueuedTime in RFC3339 format that the device-to-cloud message was received by IoT Hub.
message-idThe user-settable AMQP messageId.

For example, the headers of a HTTP Read() response would contain:

  1. {
  2.   'user-agent': 'fasthttp',
  3.   'host': '127.0.0.1:3000',
  4.   'content-type': 'application/json',
  5.   'content-length': '120',
  6.   'iothub-connection-device-id': 'my-test-device',
  7.   'iothub-connection-auth-generation-id': '637618061680407492',
  8.   'iothub-connection-auth-method': '{"scope":"module","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}',
  9.   'iothub-connection-module-id': 'my-test-module-a',
  10.   'iothub-enqueuedtime': '2021-07-13T22:08:09Z',
  11.   'message-id': 'my-custom-message-id',
  12.   'x-opt-sequence-number': '35',
  13.   'x-opt-enqueued-time': '2021-07-13T22:08:09Z',
  14.   'x-opt-offset': '21560',
  15.   'traceparent': '00-4655608164bc48b985b42d39865f3834-ed6cf3697c86e7bd-01'
  16. }

Last modified February 2, 2023: Apply suggestions from code review (5f8ee9e6)