az iot adr ns link hub

Preview

Note

This reference is part of the azure-iot extension for the Azure CLI (version 2.73.0 or higher). The extension will automatically install the first time you run an az iot adr ns link hub command. Learn more about extensions.

Command group 'iot adr ns link' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Manage IoT Hub links (messaging endpoints) on a Device Registry namespace.

A namespace must have a linked DPS before a new Hub can be linked or a failed Hub link can be retried (DPS-first ordering). Hub updates preserve existing provisioning settings. Links live on the namespace, not on the IoT Hub resource.

Commands

Name	Description	Type	Status
az iot adr ns link hub add	Link an IoT Hub to a Device Registry namespace.	Extension	Preview
az iot adr ns link hub list	List IoT Hub messaging endpoints on a Device Registry namespace.	Extension	Preview
az iot adr ns link hub remove	Remove a IoT Hub endpoint from a Device Registry namespace.	Extension	Preview
az iot adr ns link hub show	Show a single IoT Hub messaging endpoint on a Device Registry namespace.	Extension	Preview
az iot adr ns link hub update	Update an existing IoT Hub messaging endpoint on a Device Registry namespace.	Extension	Preview
az iot adr ns link hub wait	Wait for an IoT Hub endpoint to link successfully.	Extension	Preview

az iot adr ns link hub add

Preview

Command group 'iot adr ns link hub' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Link an IoT Hub to a Device Registry namespace.

Link a Standard S-tier Hub, such as S1, as a namespace messaging endpoint. Requires the namespace to already have at least one linked DPS (DPS-first ordering). --system-assigned-mi and --user-assigned-mi are optional. When supplied, exactly one may be used to set the inbound caller identity that the Hub will use to call back into the namespace. Required service-to-service roles: namespace outbound MI -> Contributor on HUB; namespace outbound MI -> IoT Hub Data Contributor on HUB; when an inbound identity is selected, HUB selected inbound MI -> Contributor on namespace. The command reuses inherited assignments and creates only missing assignments when run by a caller who can create role assignments (for example Owner, User Access Administrator, or Role Based Access Control Administrator). Otherwise it stops before changing the namespace and prints the exact commands to run. A newly created assignment must become visible within 180 seconds.

az iot adr ns link hub add --en --endpoint-name --name
                           --hub-id --hub-resource-id
                           --namespace --ns
                           --resource-group
                           [--acquire-policy-token]
                           [--allocation-weight --weight]
                           [--availability {Available, Disabled}]
                           [--change-reference]
                           [--interval]
                           [--mi-sa --system-assigned-mi {false, true}]
                           [--mi-ua --user-assigned-mi]
                           [--no-wait]
                           [--timeout]

Examples

Link a Hub using the Hub's system-assigned identity for inbound calls

az iot adr ns link hub add -n primary --ns myNamespace -g myResourceGroup \
  --hub-id /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Devices/IotHubs/<hub> \
  --system-assigned-mi

Link a Hub without configuring an inbound caller identity

az iot adr ns link hub add -n primary --ns myNamespace -g myResourceGroup \
  --hub-id /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Devices/IotHubs/<hub>

Link a Hub with a user-assigned identity and custom availability/weight

az iot adr ns link hub add -n secondary --ns myNamespace -g myResourceGroup \
  --hub-id /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Devices/IotHubs/<hub> \
  --user-assigned-mi /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<id> \
  --availability Available --allocation-weight 1

Required Parameters

--en --endpoint-name --name -n

Logical name of the messaging endpoint entry on the namespace.

--hub-id --hub-resource-id

Azure resource ID of the IoT Hub to link to this namespace.

--namespace --ns

Name of the Device Registry namespace that owns the link.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--allocation-weight --weight

Relative allocation weight used when distributing devices across endpoints.

Property	Value
Parameter group:	Provisioning Arguments

--availability

Whether the endpoint is available for provisioning new devices.

Property	Value
Parameter group:	Provisioning Arguments
Accepted values:	Available, Disabled

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--interval

Positive polling interval in seconds. Default: 30.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	30

--mi-sa --system-assigned-mi

Use the linked IoT Hub's system-assigned identity as the inbound caller identity. The Hub must have that identity enabled.

Property	Value
Parameter group:	Inbound Caller Identity Arguments
Default value:	False
Accepted values:	false, true

--mi-ua --user-assigned-mi

Resource ID of a user-assigned identity attached to the linked IoT Hub.

Property	Value
Parameter group:	Inbound Caller Identity Arguments

--no-wait

Return after submission without observing endpoint readiness or recovering later failures.

Property	Value
Default value:	False

--timeout

Positive mutation/recovery budget in seconds after initial RBAC preflight. Default: 600.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	600

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az iot adr ns link hub list

Preview

Command group 'iot adr ns link hub' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

List IoT Hub messaging endpoints on a Device Registry namespace.

az iot adr ns link hub list --namespace --ns
                            --resource-group

Examples

List all Hub links on a namespace

az iot adr ns link hub list --ns myNamespace -g myResourceGroup

List endpoint names and linking states

az iot adr ns link hub list --ns myNamespace -g myResourceGroup --query "[].{name:name,linkingState:linkingState}"

List failed Hub endpoints

az iot adr ns link hub list --ns myNamespace -g myResourceGroup --query "[?linkingState=='Failed']"

Required Parameters

--namespace --ns

Name of the Device Registry namespace that owns the link.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az iot adr ns link hub remove

Preview

Command group 'iot adr ns link hub' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Remove a IoT Hub endpoint from a Device Registry namespace.

Delete the linked IoT Hub first; this command removes only the namespace endpoint. The namespace outbound identity needs Reader on the linked resource's resource group. A missing grant is created when you can create role assignments; it is kept after unlinking. Keep that resource group until the unlink completes. The command does not wait. Confirm removal with 'az iot adr ns show'. Avoid concurrent namespace updates while this command runs.

az iot adr ns link hub remove --en --endpoint-name --name
                              --namespace --ns
                              --resource-group
                              [--acquire-policy-token]
                              [--change-reference]
                              [--yes {false, true}]

Examples

Remove an endpoint after its linked IoT Hub has been deleted

az iot adr ns link hub remove -n primary --ns myNamespace -g myResourceGroup --yes

Required Parameters

--en --endpoint-name --name -n

Logical name of the messaging endpoint entry on the namespace.

--namespace --ns

Name of the Device Registry namespace that owns the link.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--yes -y

Skip user prompts. Indicates acceptance of action. Used primarily for automation scenarios. Default: false.

Property	Value
Accepted values:	false, true

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az iot adr ns link hub show

Preview

Command group 'iot adr ns link hub' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Show a single IoT Hub messaging endpoint on a Device Registry namespace.

az iot adr ns link hub show --en --endpoint-name --name
                            --namespace --ns
                            --resource-group

Examples

Show a Hub link by endpoint name

az iot adr ns link hub show -n primary --ns myNamespace -g myResourceGroup

Show the endpoint linking state

az iot adr ns link hub show -n primary --ns myNamespace -g myResourceGroup --query linkingState -o tsv

Required Parameters

--en --endpoint-name --name -n

Logical name of the messaging endpoint entry on the namespace.

--namespace --ns

Name of the Device Registry namespace that owns the link.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az iot adr ns link hub update

Preview

Command group 'iot adr ns link hub' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Update an existing IoT Hub messaging endpoint on a Device Registry namespace.

Retry a Failed Hub endpoint without identity options to preserve its saved identity (including no inbound identity) and provisioning settings. A linked DPS is required. To change the inbound identity, pass --system-assigned-mi or --user-assigned-mi. Healthy endpoints require an explicit identity change; target and provisioning settings cannot be changed in place. A Succeeded endpoint remains updateable after DPS deletion. Update checks target existence, region, provisioning-state, Standard SKU, selected identity attachment, namespace outbound principal, and automatic RBAC preflight. Newly created assignments must become visible before namespace mutation. ARM assignment visibility does not guarantee that the linked service already honors access. Waited add/update commands recover only confirmed AdrMiNotAuthorized on the unchanged endpoint, rechecking required assignments and preserving identity and settings. --timeout (600 seconds) bounds mutation, polling and 30/60/120-second propagation backoff after initial RBAC preflight; --interval (30 seconds) controls polling. Success requires endpoint linkingState Succeeded. With --no-wait, use the matching link wait command to track completion. Use update, not add, for a persisted failure. Do not delete the linked Hub to retry it.

az iot adr ns link hub update --en --endpoint-name --name
                              --namespace --ns
                              --resource-group
                              [--acquire-policy-token]
                              [--change-reference]
                              [--interval]
                              [--mi-sa --system-assigned-mi {false, true}]
                              [--mi-ua --user-assigned-mi]
                              [--no-wait]
                              [--timeout]

Examples

Retry a failed Hub link with its saved identity and settings

az iot adr ns link hub update -n primary --ns myNamespace -g myResourceGroup

Switch a Hub link to a system-assigned identity

az iot adr ns link hub update -n primary --ns myNamespace -g myResourceGroup --system-assigned-mi

Required Parameters

--en --endpoint-name --name -n

Logical name of the messaging endpoint entry on the namespace.

--namespace --ns

Name of the Device Registry namespace that owns the link.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--interval

Positive polling interval in seconds. Default: 30.

Property	Value
Parameter group:	Wait Condition Arguments

--mi-sa --system-assigned-mi

Use the linked IoT Hub's system-assigned identity as the inbound caller identity. The Hub must have that identity enabled.

Property	Value
Parameter group:	Inbound Caller Identity Arguments
Default value:	False
Accepted values:	false, true

--mi-ua --user-assigned-mi

Resource ID of a user-assigned identity attached to the linked IoT Hub.

Property	Value
Parameter group:	Inbound Caller Identity Arguments

--no-wait

Return after submission without observing endpoint readiness or recovering later failures.

Property	Value
Default value:	False

--timeout

Positive mutation/recovery budget in seconds after initial RBAC preflight. Default: 600.

Property	Value
Parameter group:	Wait Condition Arguments

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az iot adr ns link hub wait

Preview

Command group 'iot adr ns link hub' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Wait for an IoT Hub endpoint to link successfully.

The endpoint name is required. Without an explicit wait predicate, this command polls that endpoint's linkingState and fails immediately if it reaches Failed.

az iot adr ns link hub wait --en --endpoint-name --name
                            --namespace --ns
                            --resource-group
                            [--acquire-policy-token]
                            [--change-reference]
                            [--created]
                            [--custom]
                            [--deleted]
                            [--exists]
                            [--interval]
                            [--timeout]
                            [--updated]

Examples

Wait until a Hub endpoint reaches linkingState Succeeded

az iot adr ns link hub wait -n primary --ns myNamespace -g myResourceGroup

Required Parameters

--en --endpoint-name --name -n

Logical name of the messaging endpoint entry on the namespace.

--namespace --ns

Name of the Device Registry namespace that owns the link.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--created

Wait until provisioningState is Succeeded.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	False

--custom

Wait until a custom JMESPath expression evaluates to true.

Property	Value
Parameter group:	Wait Condition Arguments

--deleted

Wait until the resource is deleted.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	False

--exists

Wait until the resource exists.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	False

--interval

Polling interval in seconds.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	30

--timeout

Polling budget in seconds, including GET time. An in-flight GET is bounded by transport timeouts and cannot be interrupted by this polling deadline.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	3600

--updated

Wait until provisioningState is Succeeded.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	False

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

Feedback

Was this page helpful?