Share via

az iot edge devices

  • Reference

Note

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

Commands to manage IoT Edge devices.

Commands

Name Description Type Status
az iot edge devices create

Create and configure multiple edge devices in an IoT Hub.

 Extension Experimental

az iot edge devices create

Experimental

This command is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Create and configure multiple edge devices in an IoT Hub.

This operation accepts inline device arguments or an edge devices configuration file in YAML or JSON format. Inline command args (like '--device-auth') will take precedence and override configuration file properties if they are provided. A sample configuration file can be found here: https://aka.ms/aziotcli-edge-devices-config Review examples and parameter descriptions for details on how to fully utilize this operation.

az iot edge devices create [--auth-type {key, login}]
                           [--cfg]
                           [--clean {false, true}]
                           [--dct]
                           [--dea]
                           [--device]
                           [--device-auth {shared_private_key, x509_thumbprint}]
                           [--hub-name]
                           [--login]
                           [--out]
                           [--rc]
                           [--resource-group]
                           [--rk]
                           [--root-pass]
                           [--vis {false, true}]
                           [--yes {false, true}]

Examples

Create a couple of edge devices using symmetric key auth (default)

az iot edge devices create -n {hub_name} --device id=device_1 --device id=device_2

Create a flat list of edge devices using self-signed certificate authentication with various edge property configurations, using inline arguments.

az iot edge devices create -n {hub_name} --device-auth x509_thumbprint --default-edge-agent "mcr.microsoft.com/azureiotedge-agent:1.4"
--device id=device_1 hostname={FQDN}
--device id=device_2 edge_agent={agent_image}
--device id=parent hostname={FQDN} edge_agent={agent_image} container_auth={path_or_json_string}

Delete all existing device-identities on a hub and create new devices based on a configuration file (with progress bars and visualization output).

az iot edge devices create -n {hub_name} --cfg path/to/config_yml_or_json -c -v

Create a group of nested edge devices with custom module deployments - containing 2 parent devices with 1 child device each, using inline arguments. Also specifies output path for device certificate bundles.

az iot edge devices create -n {hub_name} --out {device_bundle_path}
--device id=parent_1 deployment=/path/to/parentDeployment_1.json
--device id=child_1 parent=parent_1 deployment=/path/to/child_deployment_1.json
--device id=parent_2 deployment=/path/to/parentDeployment_2.json
--device id=child_2 parent=parent_2 deployment=/path/to/child_deployment_2.json

Create a simple nested edge device configuration with an existing root CA, using x509 auth, and specify a custom device bundle output path.

az iot edge devices create -n {hub_name} --out {device_bundle_path}
--root-cert "root_cert.pem" --root-key "root_key.pem" --device-auth x509_thumbprint
--device id=parent1
--device id=child1 parent=parent1

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type={auth-type-value}.

Accepted values: key, login
Default value: key
--cfg --config --config-file

Path to devices configuration file. Sample configuration file: https://aka.ms/aziotcli-edge-devices-config.

--clean -c

Deletes all devices in target hub before creating new devices.

Accepted values: false, true
Default value: False
--dct --device-config-template

Path to IoT Edge config.toml file to use as a basis for edge device configs.

--dea --default-agent --default-edge-agent

Default edge agent for created Edge devices if not specified individually.

--device -d

Space-separated key=value pairs corresponding to properties of the edge device to create. The following key values are supported: id (device_id), deployment (inline json or path to file), hostname, parent (device_id), edge_agent (image URL), and container_auth (inline json or path to file). --device can be used 1 or more times. Review help examples for full parameter usage - these parameters also refer to their corresponding values in our sample configuration file: https://aka.ms/aziotcli-edge-devices-config.

--device-auth --device-auth-type

Device to hub authorization mechanism.

Accepted values: shared_private_key, x509_thumbprint
--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--out --output-path

Directory path to output device configuration bundles. If this value is not specified, no file output will be created.

--rc --root-cert

Path to root public key certificate to sign nested edge device certs.

--resource-group -g

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

--rk --root-key

Path to root private key to sign nested edge device certs.

--root-pass --rp

Root key password.

--vis --visualize -v

Shows visualizations of devices and progress of various tasks (device creation, setting parents, updating configs, etc).

Accepted values: false, true
Default value: False
--yes -y

Do not prompt for confirmation when --clean switch is used to delete existing hub devices.

Accepted values: false, true
Default value: False
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.