README.md

Azure Event Hubs Emulator Installer

This repository contains the scripts required to install and run the Azure Event Hubs Emulator.

• Azure Event Hubs
  • Emulator Overview
  • Prerequisites
  • Running Emulator
    • Using Automated Script
    • Using Docker Compose
  • Interacting with Emulator
  • Support
  • License

About Azure Event Hubs

Azure Event Hubs is a cloud native data streaming service that can stream millions of events per second, with low latency, from any source to any destination. Event Hubs is compatible with Apache Kafka, and it enables you to run existing Kafka workloads without any code changes. Read more here.

About Azure Event Hubs Emulator

Azure Event Hubs emulator is designed to offer a local development experience for Azure Event Hubs, enabling you to develop and test code against our services in isolation, free from cloud interference.

Caution

Emulator is intended solely for development and testing scenarios.Any kind of Production use is strictly discouraged. There is no official support provided for Emulator. Any issues/suggestions should be reported via GitHub issues on GitHub project.

Run Azure Event Hubs Emulator

This section summarizes the steps to develop and test locally with Event hubs Emulator. To read more about Event hubs, read here.

Prerequisites

• Docker
  • Docker Desktop
• Minimum hardware Requirements:
  • 2 GB RAM
  • 5 GB of Disk space
• WSL Enablement (Only for Windows):
  • Install Windows Subsystem for Linux (WSL) | Microsoft Learn
  • Configure Docker to use WSL

Note

Before you continue with the subsequent steps, make sure Docker Engine is operational in the background.

Running the Emulator

This section highlights different steps to run Event Hubs Emulator. Details are as follows:

Using Automated Script

Before running automated script, clone the installation repository locally.

Windows

After completing the prerequisites, you can proceed with the following steps to run the Event Hubs Emulator locally.

1. Before executing the setup script, we need to allow execution of unsigned scripts. Run the below command in the PowerShell window:

$>Start-Process powershell -Verb RunAs -ArgumentList 'Set-ExecutionPolicy Bypass –Scope CurrentUser’

2. Execute setup script LaunchEmulator.ps1. Running the script would bring up two containers – Event Hubs Emulator & Azurite (dependency for Emulator)

Linux & macOS

After completing the prerequisites, you can proceed with the following steps to run the Event Hubs Emulator locally.

1. Execute the setup script LaunchEmulator.sh . Running the script would bring up two containers – Event Hubs Emulator & Azurite (dependency for Emulator)

2. Execute the same script LaunchEmulator.sh with the option --compose-down=Y to issue a docker compose down to terminate the containers.

LaunchEmulator.sh --compose-down=Y

Using Docker Compose (Linux Container)

You can also spin up Emulator using Docker Compose file from Microsoft Container Registry. Refer here for details.

Once the steps are successful, Emulator compose set can be found in running in Docker.

Interacting with Emulator

1. You can use the following connection string to connect to Azure Event Hubs Emulator.

"Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

2. With the latest client SDK releases, you can interact with the Emulator in various programming language. For details, refer here

To get started, refer to our GitHub Samples here.

Tip

$Default consumer group is created by default when emulator runs. You can't create $default consumer group with supplied configuration.

Networking options

You can run and connect to Emulator in multiple ways. Use a Connection String from following as per your use-case:

• When the emulator container and interacting application are running natively on local machine:

"Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

• Applications (Containerized/Non-containerized) on the different machine and same local network can interact with Emulator using the IPv4 address of the machine:

"Endpoint=sb://192.168.y.z;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

• Application containers on the same bridge network can interact with Emulator using its alias or IP. Following connection string assumes the name of Emulator has default value i.e."eventhubs-emulator":

Endpoint=sb://eventhubs-emulator;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

• Application containers on the different bridge network can interact with Emulator using the "host.docker.internal" as host:

"Endpoint=sb://host.docker.internal;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

Note If you are using the Kafka protocol, ensure that you update the Bootstrap Servers property with the appropriate host from the options above, based on your use case.

Support

There is no official support provided for Emulator.Any issues/suggestions should be reported via GitHub issues on installation repo.

License

The scripts and documentation in this project are released under the MIT License.

The software (Azure Event Hubs Emulator) that the scripts in this repository install is licensed under separate terms. See the End User License Agreement for the terms governing the software.