Skip to content

azurermIothub

Manages an IotHub

\~> NOTE: Endpoints can be defined either directly on the azurermIothub resource, or using the azurermIothubEndpoint_* resources - but the two ways of defining the endpoints cannot be used together. If both are used against the same IoTHub, spurious changes will occur. Also, defining a azurermIothubEndpoint_* resource and another endpoint of a different type directly on the azurermIothub resource is not supported.

\~> NOTE: Routes can be defined either directly on the azurermIothub resource, or using the azurermIothubRoute resource - but the two cannot be used together. If both are used against the same IoTHub, spurious changes will occur.

\~> NOTE: Enrichments can be defined either directly on the azurermIothub resource, or using the azurermIothubEnrichment resource - but the two cannot be used together. If both are used against the same IoTHub, spurious changes will occur.

\~> NOTE: Fallback route can be defined either directly on the azurermIothub resource, or using the azurermIothubFallbackRoute resource - but the two cannot be used together. If both are used against the same IoTHub, spurious changes will occur.

Example Usage

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as azurerm from "./.gen/providers/azurerm";
/*The following providers are missing schema information and might need manual adjustments to synthesize correctly: azurerm.
For a more precise conversion please use the --provider flag in convert.*/
const azurermResourceGroupExample = new azurerm.resourceGroup.ResourceGroup(
  this,
  "example",
  {
    location: "West Europe",
    name: "example-resources",
  }
);
const azurermStorageAccountExample = new azurerm.storageAccount.StorageAccount(
  this,
  "example_1",
  {
    account_replication_type: "LRS",
    account_tier: "Standard",
    location: azurermResourceGroupExample.location,
    name: "examplestorage",
    resource_group_name: azurermResourceGroupExample.name,
  }
);
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
azurermStorageAccountExample.overrideLogicalId("example");
const azurermStorageContainerExample =
  new azurerm.storageContainer.StorageContainer(this, "example_2", {
    container_access_type: "private",
    name: "examplecontainer",
    storage_account_name: azurermStorageAccountExample.name,
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
azurermStorageContainerExample.overrideLogicalId("example");
const azurermEventhubNamespaceExample =
  new azurerm.eventhubNamespace.EventhubNamespace(this, "example_3", {
    location: azurermResourceGroupExample.location,
    name: "example-namespace",
    resource_group_name: azurermResourceGroupExample.name,
    sku: "Basic",
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
azurermEventhubNamespaceExample.overrideLogicalId("example");
const azurermEventhubExample = new azurerm.eventhub.Eventhub(
  this,
  "example_4",
  {
    message_retention: 1,
    name: "example-eventhub",
    namespace_name: azurermEventhubNamespaceExample.name,
    partition_count: 2,
    resource_group_name: azurermResourceGroupExample.name,
  }
);
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
azurermEventhubExample.overrideLogicalId("example");
const azurermEventhubAuthorizationRuleExample =
  new azurerm.eventhubAuthorizationRule.EventhubAuthorizationRule(
    this,
    "example_5",
    {
      eventhub_name: azurermEventhubExample.name,
      name: "acctest",
      namespace_name: azurermEventhubNamespaceExample.name,
      resource_group_name: azurermResourceGroupExample.name,
      send: true,
    }
  );
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
azurermEventhubAuthorizationRuleExample.overrideLogicalId("example");
const azurermIothubExample = new azurerm.iothub.Iothub(this, "example_6", {
  cloud_to_device: [
    {
      default_ttl: "PT1H",
      feedback: [
        {
          lock_duration: "PT30S",
          max_delivery_count: 15,
          time_to_live: "PT1H10M",
        },
      ],
      max_delivery_count: 30,
    },
  ],
  endpoint: [
    {
      batch_frequency_in_seconds: 60,
      connection_string:
        azurermStorageAccountExample.primaryBlobConnectionString,
      container_name: azurermStorageContainerExample.name,
      encoding: "Avro",
      file_name_format: "{iothub}/{partition}_{YYYY}_{MM}_{DD}_{HH}_{mm}",
      max_chunk_size_in_bytes: 10485760,
      name: "export",
      type: "AzureIotHub.StorageContainer",
    },
    {
      connection_string:
        azurermEventhubAuthorizationRuleExample.primaryConnectionString,
      name: "export2",
      type: "AzureIotHub.EventHub",
    },
  ],
  enrichment: [
    {
      endpoint_names: ["export", "export2"],
      key: "tenant",
      value: "$twin.tags.Tenant",
    },
  ],
  location: azurermResourceGroupExample.location,
  name: "Example-IoTHub",
  resource_group_name: azurermResourceGroupExample.name,
  route: [
    {
      condition: "true",
      enabled: true,
      endpoint_names: ["export"],
      name: "export",
      source: "DeviceMessages",
    },
    {
      condition: "true",
      enabled: true,
      endpoint_names: ["export2"],
      name: "export2",
      source: "DeviceMessages",
    },
  ],
  sku: [
    {
      capacity: "1",
      name: "S1",
    },
  ],
  tags: {
    purpose: "testing",
  },
});
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
azurermIothubExample.overrideLogicalId("example");

Argument Reference

The following arguments are supported:

  • name - (Required) Specifies the name of the IotHub resource. Changing this forces a new resource to be created.

  • resourceGroupName - (Required) The name of the resource group under which the IotHub resource has to be created. Changing this forces a new resource to be created.

  • location - (Required) Specifies the supported Azure location where the resource has to be created. Changing this forces a new resource to be created.

  • sku - (Required) A sku block as defined below.

  • eventHubPartitionCount - (Optional) The number of device-to-cloud partitions used by backing event hubs. Must be between 2 and 128.

  • eventHubRetentionInDays - (Optional) The event hub retention to use in days. Must be between 1 and 7.

  • endpoint - (Optional) An endpoint block as defined below.

  • fallbackRoute - (Optional) A fallbackRoute block as defined below. If the fallback route is enabled, messages that don't match any of the supplied routes are automatically sent to this route. Defaults to messages/events.

\~> NOTE: If fallbackRoute isn't explicitly specified, the fallback route wouldn't be enabled by default.

  • fileUpload - (Optional) A fileUpload block as defined below.

  • identity - (Optional) An identity block as defined below.

  • networkRuleSet - (Optional) A networkRuleSet block as defined below.

  • route - (Optional) A route block as defined below.

  • enrichment - (Optional) A enrichment block as defined below.

  • cloudToDevice - (Optional) A cloudToDevice block as defined below.

  • publicNetworkAccessEnabled - (Optional) Is the IotHub resource accessible from a public network?

  • minTlsVersion - (Optional) Specifies the minimum TLS version to support for this hub. The only valid value is 12. Changing this forces a new resource to be created.

  • tags - (Optional) A mapping of tags to assign to the resource.

A sku block supports the following:

  • name - (Required) The name of the sku. Possible values are b1, b2, b3, f1, s1, s2, and s3.

  • capacity - (Required) The number of provisioned IoT Hub units.

\~> NOTE: Only one IotHub can be on the free tier per subscription.

An endpoint block supports the following:

  • type - (Required) The type of the endpoint. Possible values are azureIotHubStorageContainer, azureIotHubServiceBusQueue, azureIotHubServiceBusTopic or azureIotHubEventHub.

  • name - (Required) The name of the endpoint. The name must be unique across endpoint types. The following names are reserved: events, operationsMonitoringEvents, fileNotifications and $default.

  • authenticationType - (Optional) The type used to authenticate against the endpoint. Possible values are keyBased and identityBased. Defaults to keyBased.

  • identityId - (Optional) The ID of the User Managed Identity used to authenticate against the endpoint.

-> NOTE: identityId can only be specified when authenticationType is identityBased. It must be one of the identityIds of the IoT Hub. If identityId is omitted when authenticationType is identityBased, then the System-Assigned Managed Identity of the IoT Hub will be used.

\~> NOTE: An IoT Hub can only be updated to use the System-Assigned Managed Identity for endpoint since it is not possible to grant access to the endpoint until after creation. The extracted resources azurermIothubEndpoint_* can be used to configure Endpoints with the IoT Hub's System-Assigned Managed Identity without the need for an update.

  • endpointUri - (Optional) URI of the Service Bus or Event Hubs Namespace endpoint. This attribute can only be specified and is mandatory when authenticationType is identityBased for endpoint type azureIotHubServiceBusQueue, azureIotHubServiceBusTopic or azureIotHubEventHub.

  • entityPath - (Optional) Name of the Service Bus Queue/Topic or Event Hub. This attribute can only be specified and is mandatory when authenticationType is identityBased for endpoint type azureIotHubServiceBusQueue, azureIotHubServiceBusTopic or azureIotHubEventHub.

  • connectionString - (Optional) The connection string for the endpoint. This attribute is mandatory and can only be specified when authenticationType is keyBased.

  • batchFrequencyInSeconds - (Optional) Time interval at which blobs are written to storage. Value should be between 60 and 720 seconds. Default value is 300 seconds. This attribute is applicable for endpoint type azureIotHubStorageContainer.

  • maxChunkSizeInBytes - (Optional) Maximum number of bytes for each blob written to storage. Value should be between 10485760(10MB) and 524288000(500MB). Default value is 314572800(300MB). This attribute is applicable for endpoint type azureIotHubStorageContainer.

  • containerName - (Optional) The name of storage container in the storage account. This attribute is mandatory for endpoint type azureIotHubStorageContainer.

  • encoding - (Optional) Encoding that is used to serialize messages to blobs. Supported values are avro, avroDeflate and json. Default value is avro. This attribute is applicable for endpoint type azureIotHubStorageContainer. Changing this forces a new resource to be created.

  • fileNameFormat - (Optional) File name format for the blob. Default format is {iothub}/{partition}/{yyyy}/{mm}/{dd}/{hh}/{mm}. All parameters are mandatory but can be reordered. This attribute is applicable for endpoint type azureIotHubStorageContainer.

  • resourceGroupName - (Optional) The resource group in which the endpoint will be created.

An identity block supports the following:

  • type - (Required) Specifies the type of Managed Service Identity that should be configured on this IoT Hub. Possible values are systemAssigned, userAssigned, systemAssigned,UserAssigned (to enable both).

  • identityIds - (Optional) Specifies a list of User Assigned Managed Identity IDs to be assigned to this IoT Hub.

\~> NOTE: This is required when type is set to userAssigned or systemAssigned,UserAssigned.

A networkRuleSet block supports the following:

  • defaultAction - (Optional) Default Action for Network Rule Set. Possible values are deny, allow. Defaults to deny.

  • applyToBuiltinEventhubEndpoint - (Optional) Determines if Network Rule Set is also applied to the BuiltIn EventHub EndPoint of the IotHub. Defaults to false.

  • ipRule - (Optional) One or more ipRule blocks as defined below.

A ipRule block supports the following:

  • name - (Required) The name of the IP rule.

  • ipMask - (Required) The IP address range in CIDR notation for the IP rule.

  • action - (Optional) The desired action for requests captured by this rule. Possible values are allow. Defaults to allow.

A route block supports the following:

  • name - (Required) The name of the route.

  • source - (Required) The source that the routing rule is to be applied to, such as deviceMessages. Possible values include: invalid, deviceMessages, twinChangeEvents, deviceLifecycleEvents, deviceConnectionStateEvents, deviceJobLifecycleEvents and digitalTwinChangeEvents.

  • condition - (Optional) The condition that is evaluated to apply the routing rule. Defaults to true. For grammar, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-query-language.

  • endpointNames - (Required) The list of endpoints to which messages that satisfy the condition are routed.

  • enabled - (Required) Used to specify whether a route is enabled.

An enrichment block supports the following:

  • key - (Required) The key of the enrichment.

  • value - (Required) The value of the enrichment. Value can be any static string, the name of the IoT Hub sending the message (use $iothubname) or information from the device twin (ex: $twinTagsLatitude)

  • endpointNames - (Required) The list of endpoints which will be enriched.

A fallbackRoute block supports the following:

  • source - (Optional) The source that the routing rule is to be applied to, such as deviceMessages. Possible values include: invalid, deviceMessages, twinChangeEvents, deviceLifecycleEvents, deviceConnectionStateEvents, deviceJobLifecycleEvents and digitalTwinChangeEvents.

  • condition - (Optional) The condition that is evaluated to apply the routing rule. Defaults to true. For grammar, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-query-language.

  • endpointNames - (Optional) The endpoints to which messages that satisfy the condition are routed. Currently only 1 endpoint is allowed.

  • enabled - (Optional) Used to specify whether the fallback route is enabled.

A fileUpload block supports the following:

  • authenticationType - (Optional) The type used to authenticate against the storage account. Possible values are keyBased and identityBased. Defaults to keyBased.

  • identityId - (Optional) The ID of the User Managed Identity used to authenticate against the storage account.

-> NOTE: identityId can only be specified when authenticationType is identityBased. It must be one of the identityIds of the IoT Hub. If identityId is omitted when authenticationType is identityBased, then the System-Assigned Managed Identity of the IoT Hub will be used.

\~> NOTE: An IoT Hub can only be updated to use the System-Assigned Managed Identity for fileUpload since it is not possible to grant access to the endpoint until after creation.

  • connectionString - (Required) The connection string for the Azure Storage account to which files are uploaded.

  • containerName - (Required) The name of the root container where the files should be uploaded to. The container need not exist but should be creatable using the connection_string specified.

  • sasTtl - (Optional) The period of time for which the SAS URI generated by IoT Hub for file upload is valid, specified as an ISO 8601 timespan duration. This value must be between 1 minute and 24 hours. Defaults to pt1H.

  • notifications - (Optional) Used to specify whether file notifications are sent to IoT Hub on upload. Defaults to false.

  • lockDuration - (Optional) The lock duration for the file upload notifications queue, specified as an ISO 8601 timespan duration. This value must be between 5 and 300 seconds. Defaults to pt1M.

  • defaultTtl - (Optional) The period of time for which a file upload notification message is available to consume before it expires, specified as an ISO 8601 timespan duration. This value must be between 1 minute and 48 hours. Defaults to pt1H.

  • maxDeliveryCount - (Optional) The number of times the IoT Hub attempts to deliver a file upload notification message. Defaults to 10.

A cloudToDevice block supports the following:

  • maxDeliveryCount - (Optional) The maximum delivery count for cloud-to-device per-device queues. This value must be between 1 and 100. Defaults to 10.

  • defaultTtl - (Optional) The default time to live for cloud-to-device messages, specified as an ISO 8601 timespan duration. This value must be between 1 minute and 48 hours. Defaults to pt1H.

  • feedback - (Optional) A feedback block as defined below.

A feedback block supports the following:

  • timeToLive - (Optional) The retention time for service-bound feedback messages, specified as an ISO 8601 timespan duration. This value must be between 1 minute and 48 hours. Defaults to pt1H.

  • maxDeliveryCount - (Optional) The maximum delivery count for the feedback queue. This value must be between 1 and 100. Defaults to 10.

  • lockDuration - (Optional) The lock duration for the feedback queue, specified as an ISO 8601 timespan duration. This value must be between 5 and 300 seconds. Defaults to pt60S.

Attributes Reference

The following attributes are exported:

  • id - The ID of the IoTHub.

  • eventHubEventsEndpoint - The EventHub compatible endpoint for events data

  • eventHubEventsNamespace - The EventHub namespace for events data

  • eventHubEventsPath - The EventHub compatible path for events data

  • eventHubOperationsEndpoint - The EventHub compatible endpoint for operational data

  • eventHubOperationsPath - The EventHub compatible path for operational data

-> NOTE: These fields can be used in conjunction with the sharedAccessPolicy block to build a connection string

  • hostname - The hostname of the IotHub Resource.

  • identity - An identity block as documented below.

  • sharedAccessPolicy - One or more sharedAccessPolicy blocks as defined below.

An identity block exports the following:

  • principalId - The Principal ID associated with this Managed Service Identity.

  • tenantId - The Tenant ID associated with this Managed Service Identity.

A sharedAccessPolicy block contains the following:

  • keyName - The name of the shared access policy.

  • primaryKey - The primary key.

  • secondaryKey - The secondary key.

  • permissions - The permissions assigned to the shared access policy.

Timeouts

The timeouts block allows you to specify timeouts for certain actions:

  • create - (Defaults to 30 minutes) Used when creating the IotHub.
  • update - (Defaults to 30 minutes) Used when updating the IotHub.
  • read - (Defaults to 5 minutes) Used when retrieving the IotHub.
  • delete - (Defaults to 30 minutes) Used when deleting the IotHub.

Import

IoTHubs can be imported using the resourceId, e.g.

terraform import azurerm_iothub.hub1 /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mygroup1/providers/Microsoft.Devices/iotHubs/hub1