az iot du device deployment

  • Reference

Note

This reference is part of the azure-iot extension for the Azure CLI (version 2.37.0 or higher). The extension will automatically install the first time you run an az iot du device deployment command. Learn more about extensions.

Device deployment management.

Deployments will apply a desired compatible update against a target device group distributing the update across device classes within the group. Cloud-initiated rollback policy can be optionally configured.

Commands

Name Description Type Status
az iot du device deployment cancel

Cancel a device class subgroup deployment.

 Extension GA
az iot du device deployment create

Create a deployment for a device group. The deployment will be multi-cast against every device class subgroup within the target group.

 Extension GA
az iot du device deployment delete

Delete a deployment by device group or device class subgroup.

 Extension GA
az iot du device deployment list

List deployments for a device group or device class subgroup.

 Extension GA
az iot du device deployment list-devices

List devices in a device class subgroup deployment along with their state. Useful for getting a list of failed devices.

 Extension GA
az iot du device deployment retry

Retry a device class subgroup deployment.

 Extension GA
az iot du device deployment show

Show a deployment for a device group or device class subgroup including status which details a breakdown of how many devices in the deployment are in progress, completed, or failed.

 Extension GA

az iot du device deployment cancel

Cancel a device class subgroup deployment.

az iot du device deployment cancel --account
                                   --cid
                                   --deployment-id
                                   --gid
                                   --instance
                                   [--resource-group]

Examples

Cancel the target device class subgroup deployment.

az iot du device deployment cancel -n {account_name} -i {instance_name} --deployment-id {deployment_id} --group-id {device_group_id} --class-id {device_class_id}

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account=<name>.

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain '&', '^', '[', ']', '{', '}', '|', '<', '>', forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance=<name>.

Optional Parameters

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--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.

az iot du device deployment create

Create a deployment for a device group. The deployment will be multi-cast against every device class subgroup within the target group.

az iot du device deployment create --account
                                   --deployment-id
                                   --gid
                                   --instance
                                   --un
                                   --up
                                   --update-version
                                   [--failed-count]
                                   [--failed-percentage]
                                   [--rbun]
                                   [--rbup]
                                   [--rbuv]
                                   [--resource-group]
                                   [--start-time]

Examples

Create a device group deployment scheduled to start immediately (with respect to UTC time).

az iot du device deployment create -n {account_name} -i {instance_name} --group-id {device_group_id} --deployment-id {deployment_id} --update-name {update_name} --update-provider {update_provider} --update-version {update_version}

Create a device group deployment scheduled to start on a desired iso-8601 compliant datetime.

az iot du device deployment create -n {account_name} -i {instance_name} --group-id {device_group_id} --deployment-id {deployment_id} --update-name {update_name} --update-provider {update_provider} --update-version {update_version} --start-time "2022-12-20T01:00:00"

Create a device group deployment scheduled to start immediately with a defined cloud-initiated rollback policy. The cloud rollback is initiated when failed count or failed percentage targets are met.

az iot du device deployment create -n {account_name} -i {instance_name} --group-id {device_group_id} --deployment-id {deployment_id} --update-name {update_name} --update-provider {update_provider} --update-version {update_version} --failed-count 10 --failed-percentage 5 --rollback-update-name {rollback_update_name} --rollback-update-provider {rollback_update_provider} --rollback-update-version {rollback_update_version}

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account=<name>.

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain '&', '^', '[', ']', '{', '}', '|', '<', '>', forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance=<name>.

--un --update-name

The update name.

--up --update-provider

The update provider.

--update-version --uv

The update version.

Optional Parameters

--failed-count --fc

Integer representing the number of failed devices in a deployment before a cloud initated rollback occurs. Required when defining rollback policy.

--failed-percentage --fp

Integer representing the percentage of failed devices in a deployment before a cloud initated rollback occurs. Required when defining rollback policy.

--rbun --rollback-update-name

The rollback update name.

--rbup --rollback-update-provider

The rollback update provider.

--rbuv --rollback-update-version

The rollback update version.

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group=<name>.

--start-time

The iso-8601 compliant start time for deployment. If no value is provided the corresponding value for UTC 'now' will be used.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--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.

az iot du device deployment delete

Delete a deployment by device group or device class subgroup.

az iot du device deployment delete --account
                                   --deployment-id
                                   --gid
                                   --instance
                                   [--cid]
                                   [--resource-group]
                                   [--yes {false, true}]

Examples

Delete the target device group deployment.

az iot du device deployment delete -n {account_name} -i {instance_name} --deployment-id {deployment_id} --group-id {device_group_id}

Delete the target device class subgroup deployment.

az iot du device deployment delete -n {account_name} -i {instance_name} --deployment-id {deployment_id} --group-id {device_group_id} --class-id {device_class_id}

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account=<name>.

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain '&', '^', '[', ']', '{', '}', '|', '<', '>', forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance=<name>.

Optional Parameters

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group=<name>.

--yes -y

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

accepted values: false, true
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--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.

az iot du device deployment list

List deployments for a device group or device class subgroup.

az iot du device deployment list --account
                                 --gid
                                 --instance
                                 [--cid]
                                 [--order-by]
                                 [--resource-group]

Examples

List deployments for a device group.

az iot du device deployment list -n {account_name} -i {instance_name} --group-id {device_group_id}

List deployments for a device group ordering results by startDateTime descending.

az iot du device deployment list -n {account_name} -i {instance_name} --group-id {device_group_id} --order-by "startDateTime desc"

List deployments for a device class subgroup.

az iot du device deployment list -n {account_name} -i {instance_name} --group-id {device_group_id} --class-id {device_class_id}

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account=<name>.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance=<name>.

Optional Parameters

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--order-by

Orders the set of deployments returned. You can order by startDateTime [desc/asc].

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--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.

az iot du device deployment list-devices

List devices in a device class subgroup deployment along with their state. Useful for getting a list of failed devices.

az iot du device deployment list-devices --account
                                         --cid
                                         --deployment-id
                                         --gid
                                         --instance
                                         [--filter]
                                         [--resource-group]

Examples

List devices in a device class subgroup deployment.

az iot du device deployment list-devices -n {account_name} -i {instance_name} --group-id {device_group_id} --class-id {device_class_id} --deployment-id {deployment_id}

List devices in a device class subgroup deployment filtering by deviceId and deviceState.

az iot du device deployment list-devices -n {account_name} -i {instance_name} --group-id {device_group_id} --class-id {device_class_id} --deployment-id {deployment_id} --filter "deviceId eq 'd0' and deviceState eq 'InProgress'"

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account=<name>.

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain '&', '^', '[', ']', '{', '}', '|', '<', '>', forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance=<name>.

Optional Parameters

--filter

Restricts the set of deployment device states returned. You can filter on deviceId and moduleId and/or deviceState.

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--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.

az iot du device deployment retry

Retry a device class subgroup deployment.

az iot du device deployment retry --account
                                  --cid
                                  --deployment-id
                                  --gid
                                  --instance
                                  [--resource-group]

Examples

Retry the target device class subgroup deployment.

az iot du device deployment retry -n {account_name} -i {instance_name} --deployment-id {deployment_id} --group-id {device_group_id} --class-id {device_class_id}

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account=<name>.

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain '&', '^', '[', ']', '{', '}', '|', '<', '>', forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance=<name>.

Optional Parameters

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--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.

az iot du device deployment show

Show a deployment for a device group or device class subgroup including status which details a breakdown of how many devices in the deployment are in progress, completed, or failed.

az iot du device deployment show --account
                                 --deployment-id
                                 --gid
                                 --instance
                                 [--cid]
                                 [--resource-group]
                                 [--status {false, true}]

Examples

Show a deployment for a device group.

az iot du device deployment show -n {account_name} -i {instance_name} --group-id {device_group_id} --deployment-id {deployment_id}

Show the status of a device group deployment.

az iot du device deployment show -n {account_name} -i {instance_name} --group-id {device_group_id} --deployment-id {deployment_id} --status

Show a deployment for a device class subgroup.

az iot du device deployment show -n {account_name} -i {instance_name} --group-id {device_group_id} --class-id {device_class_id} --deployment-id {deployment_id}

Show the status of a device class subgroup deployment.

az iot du device deployment show -n {account_name} -i {instance_name} --group-id {device_group_id} --class-id {device_class_id} --deployment-id {deployment_id} --status

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account=<name>.

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain '&', '^', '[', ']', '{', '}', '|', '<', '>', forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance=<name>.

Optional Parameters

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group=<name>.

--status

Gets the status of a deployment including a breakdown of how many devices in the deployment are in progress, completed, or failed.

accepted values: false, true
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--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.