+++
title = "Azure Event Hubs"
availability = "v1.0+"
maintainer = "Microsoft"
description = "Scale applications based on Azure Event Hubs."
go_file = "azure_eventhub_scaler"
+++

### Trigger Specification

This specification describes the `azure-eventhub` trigger for Azure Event Hubs.

```yaml
triggers:
- type: azure-eventhub
  metadata:
    connectionFromEnv: EVENTHUB_CONNECTIONSTRING_ENV_NAME
    storageConnectionFromEnv: STORAGE_CONNECTIONSTRING_ENV_NAME
    consumerGroup: $Default
    unprocessedEventThreshold: '64'
    blobContainer: 'name_of_container'
```

**Parameter list:**

- `connectionFromEnv` - Name of the environment variable your deployment uses to get the connection string appended with `EntityPath=<event_hub_name>`.
- `storageConnectionFromEnv` - Name of the environment variable that provides connection string for Azure Storage Account to store checkpoint. As of now the Event Hub scaler only reads from Azure Blob Storage.
- `consumerGroup` - Consumer group of Azure Event Hub consumer. (default: `$default`)
- `unprocessedEventThreshold` - Average target value to trigger scaling actions. (Default: `64`, Optional)
- `blobContainer` - Container name to store checkpoint. This is needed for every `checkpointStrategy` except of `AzureFunction`. With Azure Functions the `blobContainer` is autogenerated and cannot be overridden.
- `checkpointStrategy` - configure the checkpoint behaviour of different Event Hub SDKs. (default: `""`)
    - `azureFunction` - Suitable for Azure Functions & Azure WebJobs SDK. This is the default setting, when `blobcontainer` is not specified.
    - `blobMetadata` - For all implementations that store checkpoint information on blob metadata such as current C#, Python, Java and JavaScript Event Hub SDKs.
    - `goSdk` - For all implementations using the [Golang SDK](https://github.com/Azure/azure-event-hubs-go)'s checkpointing, for example Dapr.
    - When no checkpoint strategy is specified, the Event Hub scaler will use backwards compatibility and able to scale older implementations of C#, Python or Java Event Hub SDKs. (see "Legacy checkpointing"). If this behaviour should be used, `blobContainer` is also required.

> 💡 Learn more about the checkpointing behaviour in this [section](#checkpointing-behaviour).

> 💡 The Azure Storage connection string is not compatible with connection string created from a Shared Access Signature.

### Authentication Parameters

You can authenticate by using pod identity or connection string authentication.

**Connection String Authentication:**

- `connection` - Connection string for the Azure Event Hubs Namespace.
  
  The following formats are supported.
  
  - With **SharedAccessKey** - `Endpoint=sb://<sb>.servicebus.windows.net/;SharedAccessKeyName=<key name>;SharedAccessKey=<key value>;EntityPath=<hub-name>`.

- `storageConnection` - Connection string for the Azure Storage Account used to store checkpoint information.

> 💡 When providing `connection`, `EntityPath` is optional. If it is not provided, then `eventHubName` must be used to provide the name of the Azure Event Hub instance to use inside the namespace.

**Pod identity based authentication:**

[Azure AD Pod Identity](https://docs.microsoft.com/en-us/azure/aks/use-azure-ad-pod-identity) or [Azure AD Workload Identity](https://azure.github.io/azure-workload-identity/docs/) providers can be used.

```yaml
apiVersion: keda.sh/v1alpha1
kind: TriggerAuthentication
metadata:
  name: nameOfTriggerAuth
  namespace: default
spec:
  podIdentity:
    provider: Azure
```

When you do so, the Event Hub scaler will depend on the existence of two configurations you have to provide: `eventHubNamespace` and `eventHubName`.

### Checkpointing Behaviour

The list of available checkpointing strategies can be found in the trigger specification [section](#trigger-specification). The way checkpoints are stored
has changed with updates to the EventHub SDKs.

* **Legacy behaviour:** The older implementations are based on the `EventProcessorHost` client, which stores the checkpoint information as contents of
the storage blob. This is the default behaviour when no `checkpointStrategy` is specified.
This is applicable for the following scenarios:
  - .NET applications using `Microsoft.Azure.EventHubs` NuGet package.
  - Java applications using `azure-eventhubs-eph` package.
  - Python applications using `azure-eventhub` package below v5.

* **Current behaviour:** The newer implementations are based on the `EventProcessorClient`, which stores the checkpoint information as metadata on
the storage blob. This is the behaviour when `checkpointStrategy` is set to `blobMetadata`.
This is applicable for the following scenarios:
  - .NET applications using `Azure.Messaging.EventHubs` NuGet package.
  - Python applications using `azure-eventhub` v5.
  - .NET Azure Functions using `Microsoft.Azure.WebJobs.Extensions.EventHubs` v5.
  - Azure Functions in other languages using `Microsoft.Azure.Functions.ExtensionBundle` v3.

> 💡 `blobContainer` name is required for applications following legacy behaviour.

> 💡 Users should set `blobContainer` to `azure-webjobs-eventhub` for Azure Functions using `blobMetadata` as `checkpointStrategy`.

### Example

```yaml
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: azure-eventhub-scaledobject
  namespace: default
spec:
  scaleTargetRef:
    name: azureeventhub-function
  triggers:
  - type: azure-eventhub
    metadata:
      # Required
      storageConnectionFromEnv: AzureWebJobsStorage
      # Required if not using Pod Identity
      connectionFromEnv: EventHub
      # Required if using Pod Identity
      eventHubNamespace: AzureEventHubNameSpace
      eventHubName: NameOfTheEventHub
# Optional
      consumerGroup: $Default # default: $Default
      unprocessedEventThreshold: '64' # default 64 events.
      blobContainer: ehcontainer
```