Tutorial: Use namespace topics to route MQTT messages to Azure Event Hubs (Azure portal)

In this tutorial, you learn how to use a namespace topic to route data from MQTT clients to Azure Event Hubs. Here are the high-level steps:

Prerequisites

  • If you don't have an Azure subscription, create an Azure free account before you begin.
  • If you're new to Event Grid, read the Event Grid overview before you start this tutorial.
  • Register the Event Grid resource provider according to the steps in Register the Event Grid resource provider.
  • Make sure that port 8883 is open in your firewall. The sample in this tutorial uses the MQTT protocol, which communicates over port 8883. This port might be blocked in some corporate and educational network environments.

Create a namespace in the Azure portal

A namespace in Azure Event Grid is a logical container for one or more topics, clients, client groups, topic spaces and permission bindings. It provides a unique namespace, allowing you to have multiple resources in the same Azure region. With an Azure Event Grid namespace you can group now together related resources and manage them as a single unit in your Azure subscription.

Please follow the next sections to create, view and manage an Azure Event Grid namespace.

To create a namespace:

  1. Sign-in to the Azure portal.

  2. In the search box, enter Event Grid Namespaces and select Event Grid Namespaces from the results.

    Screenshot showing Event Grid Namespaces in the search results.

  3. On the Event Grid Namespaces page, select + Create on the toolbar.

    Screenshot showing Event Grid Namespaces page with the Create button on the toolbar selected.

  4. On the Basics page, follow these steps.

    1. Select the Azure subscription in which you want to create the namespace.

    2. Select an existing resource group or create a resource group.

    3. Enter a name for the namespace.

    4. Select the region or location where you want to create the namespace.

    5. Select Review + create at the bottom of the page.

      Screenshot showing the Basics tab of Create namespace page.

  5. On the Review + create tab, review your settings and select Create.

  6. On the Deployment succeeded page, select Go to resource to navigate to your namespace.

Create a namespace topic

  1. If you aren't on the Event Grid Namespace page, follow the create, view, and manage namespaces steps to view the namespace you want to use to create the topic.

  2. On the Event Grid Namespace page, select Topics option in the Eventing section on the left menu.

  3. On the Topics page, select + Topic button on the command bar.

    Screenshot showing Event Grid namespace topic creation.

  4. On the Create Topic page, type the name of the topic you want to create and select Create.

    Screenshot showing Event Grid namespace topic creation basics.

Enable managed identity for the Event Grid namespace

  1. On the Event Grid Namespace page, select Identity under Settings on the left menu.

  2. Turn on the switch to enable a system-assigned managed identity.

  3. Select Save on the toolbar to save the setting.

    Screenshot of a system-assigned identity page for an Event Grid namespace.

  4. Select Yes on the confirmation message.

  5. Confirm that you see the object ID of the system-assigned managed identity and see a link to assign roles.

    Screenshot that shows assigning identity to a namespace is completed.

    Check notifications in the portal to confirm that the managed identity is enabled for the namespace.

Enable MQTT broker for the Event Grid namespace

  1. On the Event Grid Namespace page, select Configuration under Settings on the left menu.

  2. Select the check box next to Enable MQTT broker.

  3. Select Apply at the bottom of the page.

    Screenshot showing Event Grid namespace configuration page to enable MQTT.

    Check notifications in the portal to confirm that the MQTT broker is enabled for the namespace.

In a separate tab of the Web browser or in a separate window, use the Azure portal to create an Event Hubs namespace with an event hub.

Create an Event Hubs namespace

An Event Hubs namespace provides a unique scoping container, in which you create one or more event hubs. To create a namespace in your resource group using the portal, do the following actions:

  1. In the Azure portal, select All services in the left menu, and select star (*) next to Event Hubs in the Analytics category. Confirm that Event Hubs is added to FAVORITES in the left navigational menu.

    Screenshot showing the selection of Event Hubs in the All services page.

  2. Select Event Hubs under FAVORITES in the left navigational menu, and select Create on the toolbar.

    Screenshot showing the selection of Create button on the Event hubs page.

  3. On the Create namespace page, take the following steps:

    1. Select the subscription in which you want to create the namespace.

    2. Select the resource group you created in the previous step.

    3. Enter a name for the namespace. The system immediately checks to see if the name is available.

    4. Select a location for the namespace.

    5. Choose Basic for the pricing tier. If you plan to use the namespace from Apache Kafka apps, use the Standard tier. The basic tier doesn't support Apache Kafka workloads. To learn about differences between tiers, see Quotas and limits, Event Hubs Premium, and Event Hubs Dedicated articles.

    6. Leave the throughput units (for standard tier) or processing units (for premium tier) settings as it is. To learn about throughput units or processing units: Event Hubs scalability.

    7. Select Review + Create at the bottom of the page.

      Screenshot of the Create Namespace page in the Azure portal.

    8. On the Review + Create page, review the settings, and select Create. Wait for the deployment to complete.

  4. On the Deployment page, select Go to resource to navigate to the page for your namespace.

    Screenshot of the Deployment complete page with the link to resource.

  5. Confirm that you see the Event Hubs Namespace page similar to the following example:

    Screenshot of the home page for your Event Hubs namespace in the Azure portal.

Create an event hub

To create an event hub within the namespace, do the following actions:

  1. On the Overview page, select + Event hub on the command bar.

    Screenshot of the selection of Add event hub button on the command bar.

  2. Type a name for your event hub, then select Review + create.

    Screenshot of the Create event hub page.

  3. On the Review + create page, select Create.

  4. You can check the status of the event hub creation in alerts. After the event hub is created, you see it in the list of event hubs.

    Screenshot showing the list of event hubs.

Give Event Grid namespace the access to send events to the event hub

  1. On the Event Hubs Namespace page, select Access control (IAM) on the left menu.

  2. On the Access control page, select + Add on the command bar, and then select Add role assignment.

    Screenshot that shows the Access control page for the Event Hubs namespace.

  3. On the Add role assignment page, select Azure Event Hubs Data Sender from the list of roles, and then select Next at the bottom of the page.

    Screenshot that shows the Add role assignment page with Azure Event Hubs Data Sender selected.

  4. On the Members page, follow these steps:

    1. For the Assign access to field, select Managed identity.

    2. Choose + Select members.

      Screenshot that shows the Add role assignment page with Managed identity selected.

  5. On the Select managed identities page, follow these steps:

    1. Select your Azure subscription.

    2. For Managed identity, select Event Grid Namespace.

    3. Select the managed identity that has the same name as the Event Grid namespace.

    4. Choose Select at the bottom of the page.

      Screenshot that shows the Select managed identities page with the Event Grid namespace's managed identity selected.

  6. On the Add role assignment page, select Review + assign at the bottom of the page.

  7. On the Review + assign page, select Review + assign.

Create an event subscription with Event Hubs as the endpoint

  1. Switch to the tab of your Web browser window that has the Event Grid namespace open.

  2. On the Event Grid Namespace page, select Topics on the left menu.

  3. On the Topics page, select the namespace topic you created earlier.

    Screenshot that shows the Topics page with the namespace topic selected.

  4. On the Event Grid Namespace Topic page, select + Subscription on the command bar at the top.

    Screenshot that shows the Subscriptions page.

  5. On the Create Subscription page, follow these steps:

    1. Enter a name for the event subscription.

    2. For Delivery mode, select Push.

    3. Confirm that Endpoint type is set to Event hub.

    4. Select Configure an endpoint.

      Screenshot that shows the Create Subscription page.

    5. On the Select Event Hub, follow these steps:

      1. Select the Azure subscription that has the event hub.

      2. Select the resource group that has the event hub.

      3. Select the Event Hubs namespace.

      4. Select the event hub in the Event Hubs namespace.

      5. Then, select Confirm selection.

        Screenshot that shows the Select event hub page.

    6. Back on the Create Subscription page, select System Assigned for Managed identity type.

    7. Select Create at the bottom of the page.

      Screenshot that shows the Create Subscription page with Create button selected.

Configure routing in the Event Grid namespace

  1. Navigate back to the Event Grid Namespace page by selecting the namespace in the Essentials section of the Event Grid Namespace Topic page or by selecting the namespace name in the breadcrumb menu at the top.

  2. On the Event Grid Namespace page, select Routing on the left menu in the MQTT broker section.

  3. On the Routing page, select Enable routing.

  4. For Topic type, select Namespace topic.

  5. For Topic, select the Event Grid namespace topic that you created where all MQTT messages will be routed.

  6. Select Apply.

    Screenshot that shows the Routing page with the namespace topic selected.

    Check notifications to confirm that the namespace is enabled with the routing information.

Create clients, topic space, and permission bindings

Follow steps in the quickstart: Publish and subscribe on an MQTT topic to:

  1. Create a client. You can create the second client if you want to, but it's optional.

  2. Create a topic space.

  3. Create publisher and subscriber permission bindings.

  4. Use MQTTX to send a few messages.

  5. Verify that the event hub received those messages on the Overview page for your Event Hubs namespace.

    Screenshot that shows the Overview page of the event hub with incoming message count.

View routed MQTT messages in Event Hubs by using a Stream Analytics query

Navigate to the Event Hubs instance (event hub) within your event subscription in the Azure portal. Process data from your event hub by using Stream Analytics. For more information, see Process data from Azure Event Hubs using Stream Analytics - Azure Event Hubs | Microsoft Learn. You can see the MQTT messages in the query.

Screenshot that shows the MQTT messages data in Event Hubs by using the Stream Analytics query tool.

Next steps

For code samples, go to this GitHub repository.