az iot adr ns link su

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 su 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 Software Updates links (updating endpoints) on a Device Registry namespace.

Links a 'Microsoft.DeviceUpdate/updateInstances' resource to the namespace as an updating endpoint under properties.updating.endpoints. Links live on the namespace, not on the Update Instance. Only one Software Updates instance may be linked per namespace. Linking is asynchronous; read-only address fields (serviceAddress, deviceAddress, legacyDeviceAddress) are resolved once linking succeeds.

Commands

Name	Description	Type	Status
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 su add

Preview

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

Link an Update Instance to a Device Registry namespace.

Adds a Software Updates updating endpoint entry under the namespace's properties.updating.endpoints. Only one Software Updates instance may be linked per namespace. If one is already linked, use 'link su update' to modify the existing endpoint. Exactly one of --system-assigned-mi or --user-assigned-mi must be provided to set the inbound caller identity that the update instance will use to call back into the namespace. Required service-to-service roles: namespace outbound MI -> Contributor on SU; namespace outbound MI -> Device Update Administrator on SU; SU selected inbound MI -> Azure Device Registry Contributor on namespace. These are exactly three service-to-service grants. Device Update Administrator enables namespace-initiated ADU data-plane operations, including report generation; ARM Contributor alone does not grant data-plane access. The configured namespace outbound identity and the selected Update Instance inbound identity each support SAMI or an attached UAMI. No ADU first-party service principal or Microsoft Graph lookup is required. Missing assignments are created only when run by a caller who can create role assignments (for example Owner, User Access Administrator, or Role Based Access Control Administrator). A newly created assignment must become visible within 180 seconds. This link workflow never grants the signed-in user Software Updates content roles.

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

Examples

Link an Update Instance using its system-assigned identity for inbound calls

az iot adr ns link su add -n my-su --ns myNamespace -g myResourceGroup \
  --su-id /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.DeviceUpdate/updateInstances/<instance> \
  --system-assigned-mi

Link an Update Instance with a user-assigned identity

az iot adr ns link su add -n my-su --ns myNamespace -g myResourceGroup \
  --su-id /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.DeviceUpdate/updateInstances/<instance> \
  --user-assigned-mi /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<id>

Required Parameters

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

Logical name of the Software Updates endpoint entry.

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

--su-id --su-resource-id

Azure resource ID of the Update Instance to link.

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
Default value:	30

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

Use the linked Update Instance's system-assigned identity. The instance 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 Update Instance.

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

Preview

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

List Software Updates updating endpoints on a Device Registry namespace.

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

Examples

List all Software Updates links on a namespace

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

List endpoint names and linking states

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

List failed Software Updates endpoints

az iot adr ns link su 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 su remove

Preview

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

Remove a Software Updates instance endpoint from a Device Registry namespace.

Delete the linked Software Updates instance 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 su remove --en --endpoint-name --name
                             --namespace --ns
                             --resource-group
                             [--acquire-policy-token]
                             [--change-reference]
                             [--yes {false, true}]

Examples

Remove an endpoint after its linked Software Updates instance has been deleted

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

Required Parameters

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

Logical name of the Software Updates endpoint entry.

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

Preview

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

Show a single Software Updates updating endpoint on a Device Registry namespace.

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

Examples

Show a Software Updates link by endpoint name

az iot adr ns link su show -n my-su --ns myNamespace -g myResourceGroup

Show the endpoint linking state

az iot adr ns link su show -n my-su --ns myNamespace -g myResourceGroup --query linkingState -o tsv

Required Parameters

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

Logical name of the Software Updates endpoint entry.

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

Preview

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

Update an existing Software Updates updating endpoint on a Device Registry namespace.

Retry a Failed endpoint without identity options to reuse its saved inbound identity. Pass --system-assigned-mi or --user-assigned-mi to change that identity. Healthy endpoints require an explicit change. The linked Update Instance cannot be changed in place. Before PATCH, update repeats add's target existence, region, provisioning-state, selected identity attachment, namespace outbound principal, automatic RBAC, and assignment-visibility preflight. This includes Device Update Administrator for the namespace outbound identity on the linked Update Instance, adding the missing grant for links created with older CLI versions. 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. After verifying access and allowing recent assignments to propagate, retry a persisted failed endpoint with update, not add, passing its existing inbound identity. There is no need to delete the linked Update Instance to retry the link.

az iot adr ns link su 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

Rotate to a system-assigned identity on an existing Software Updates link

az iot adr ns link su update -n my-su --ns myNamespace -g myResourceGroup --system-assigned-mi

Required Parameters

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

Logical name of the Software Updates endpoint entry.

--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 Update Instance's system-assigned identity. The instance 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 Update Instance.

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

Preview

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

Wait for a Software Updates 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 su 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 Software Updates endpoint reaches linkingState Succeeded

az iot adr ns link su wait -n my-su --ns myNamespace -g myResourceGroup

Required Parameters

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

Logical name of the Software Updates endpoint entry.

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