az iot adr ns link

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 command. Learn more about extensions.

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

Manage links between a Device Registry namespace and downstream resources.

Link a DPS first, then link your IoT Hubs. Use update to change a link's inbound identity or retry a Failed endpoint with its saved identity and settings. Use show, list and wait to inspect linkingState. Links belong to the namespace. To unlink, delete the linked resource first, then run link hub/dps/su remove to remove its endpoint from the namespace. Remove does not delete or check the linked resource and does not wait for unlink completion. Add/update wait for the link to succeed (--timeout default 600 seconds, --interval 30). After --no-wait, use link hub/dps/su wait to track completion.

Commands

Name	Description	Type	Status
az iot adr ns link add	Link DPS first, then a Hub, to a Device Registry namespace.	Extension	Preview
az iot adr ns link dps	Manage DPS links (provisioning endpoints) on a Device Registry namespace.	Extension	Preview
az iot adr ns link dps add	Link a Device Provisioning Service (DPS) to a Device Registry namespace.	Extension	Preview
az iot adr ns link dps list	List DPS provisioning endpoints on a Device Registry namespace.	Extension	Preview
az iot adr ns link dps remove	Remove a DPS endpoint from a Device Registry namespace.	Extension	Preview
az iot adr ns link dps show	Show a single DPS provisioning endpoint on a Device Registry namespace.	Extension	Preview
az iot adr ns link dps update	Update an existing DPS provisioning endpoint on a Device Registry namespace.	Extension	Preview
az iot adr ns link dps wait	Wait for a DPS endpoint to link successfully.	Extension	Preview
az iot adr ns link hub	Manage IoT Hub links (messaging endpoints) on a Device Registry namespace.	Extension	Preview
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 su	Manage Software Updates links (updating endpoints) on a Device Registry namespace.	Extension	Preview
az iot adr ns link su add	Link an Update Instance to a Device Registry namespace.	Extension	Preview
az iot adr ns link su list	List Software Updates updating endpoints on a Device Registry namespace.	Extension	Preview
az iot adr ns link su remove	Remove a Software Updates instance endpoint from a Device Registry namespace.	Extension	Preview
az iot adr ns link su show	Show a single Software Updates updating endpoint on a Device Registry namespace.	Extension	Preview
az iot adr ns link su update	Update an existing Software Updates updating endpoint on a Device Registry namespace.	Extension	Preview
az iot adr ns link su wait	Wait for a Software Updates endpoint to link successfully.	Extension	Preview
az iot adr ns link wait	Wait for selected or all namespace links to succeed.	Extension	Preview

az iot adr ns link add

Preview

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

Link DPS first, then a Hub, to a Device Registry namespace.

Validates both targets, endpoint names, identity selections, and required RBAC before changing namespace endpoints. Submits a DPS-only namespace update and waits for the exact DPS endpoint to reach linkingState Succeeded before submitting a separate Hub update. --no-wait still waits for this DPS dependency; it skips waiting only for the final Hub operation. Both waited stages recover only confirmed AdrMiNotAuthorized on the unchanged endpoint after verifying required service-role assignments. Recovery uses endpoint update, never another add. --timeout (600 seconds) is one shared mutation/recovery budget for both stages after initial RBAC preflight, including RPCs, polling and bounded 30/60/120-second backoff. --interval defaults to 30 seconds. Both must be positive. No delay is added when authorization already works. With --no-wait, use link hub wait to track the Hub stage. Rejected if the namespace already has a linked DPS. A DPS failure or timeout prevents Hub submission. Partial completion is not rolled back. Inspect failed endpoints with link dps show or link hub show and repair persisted failures with the corresponding link update, preserving the existing identity. After DPS succeeds, use link hub add only if the Hub endpoint is absent; use link hub wait if pending. Do not rerun combined link add when the DPS endpoint already exists. Required service-to-service roles: namespace outbound MI -> Contributor on DPS; DPS selected inbound MI -> Contributor on namespace; namespace system-assigned MI -> Azure Device Registry Administrator on namespace; 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.

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

Examples

Link both a Hub and a DPS using system-assigned identity for both inbound callers

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

Link both resources without configuring a Hub inbound caller identity

az iot adr ns link add --ns myNamespace -g myResourceGroup \
  --hub-endpoint-name primary-hub --hub-id <hub-id> \
  --dps-endpoint-name primary-dps --dps-id <dps-id> --dps-system-assigned-mi

Link both with custom Hub availability and weight

az iot adr ns link add --ns myNamespace -g myResourceGroup \
  --hub-endpoint-name primary-hub --hub-id <hub-id> --hub-system-assigned-mi \
  --hub-availability Available --hub-allocation-weight 1 \
  --dps-endpoint-name primary-dps --dps-id <dps-id> --dps-system-assigned-mi

Wait for DPS, submit the Hub without waiting, then observe the Hub link

az iot adr ns link add --ns myNamespace -g myResourceGroup \
  --hub-endpoint-name primary-hub --hub-id <hub-id> \
  --dps-endpoint-name primary-dps --dps-id <dps-id> --dps-system-assigned-mi --no-wait
az iot adr ns link hub wait -n primary-hub --ns myNamespace -g myResourceGroup

Required Parameters

--den --dps-endpoint-name

Logical name of the DPS provisioning endpoint entry on the namespace.

Property	Value
Parameter group:	DPS Arguments

--dps-id --dps-resource-id

Azure resource ID of the Device Provisioning Service to link.

Property	Value
Parameter group:	DPS Arguments

--hen --hub-endpoint-name

Logical name of the Hub messaging endpoint entry on the namespace.

Property	Value
Parameter group:	Hub Arguments

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

Azure resource ID of the IoT Hub to link.

Property	Value
Parameter group:	Hub Arguments

--namespace --ns

Name of the Device Registry namespace that will own both new links.

--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

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

Use the linked DPS resource's system-assigned identity as its inbound caller identity.

Property	Value
Parameter group:	DPS Arguments
Default value:	False
Accepted values:	false, true

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

User-assigned identity resource ID attached to the linked DPS resource.

Property	Value
Parameter group:	DPS Arguments

--hub-allocation-weight --hub-weight

Hub messaging endpoint allocation weight.

Property	Value
Parameter group:	Hub Arguments

--hub-availability

Hub messaging endpoint availability.

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

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

Use the linked IoT Hub's system-assigned identity as its inbound caller identity.

Property	Value
Parameter group:	Hub Arguments
Default value:	False
Accepted values:	false, true

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

User-assigned identity resource ID attached to the linked IoT Hub.

Property	Value
Parameter group:	Hub Arguments

--interval

Polling interval in seconds. Must be greater than zero.

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

--no-wait

Wait for DPS linking to succeed, then return without waiting for the final Hub operation.

Property	Value
Default value:	False

--timeout

Positive shared mutation/recovery budget in seconds for DPS and Hub 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 wait

Preview

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

Wait for selected or all namespace links to succeed.

Without an explicit wait predicate, waits until every selected endpoint has linkingState Succeeded and fails immediately if any reaches Failed. Scope the wait with --hub-endpoint-name, --dps-endpoint-name, and/or --su-endpoint-name. If none is supplied, all currently configured Hub, DPS, and Software Updates links are included. Explicit Azure CLI wait predicates inspect the namespace resource and retain their standard behavior.

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

Examples

Wait until all configured namespace links succeed

az iot adr ns link wait --ns myNamespace -g myResourceGroup

Wait for the Hub and DPS created by combined DPS-first link add

az iot adr ns link wait --ns myNamespace -g myResourceGroup \
  --hub-endpoint-name primary-hub --dps-endpoint-name primary-dps

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>.

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

--den --dps-endpoint-name

DPS endpoint to include in the wait scope.

--exists

Wait until the resource exists.

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

--hen --hub-endpoint-name

Hub endpoint to include in the wait scope.