az iot edge deployment

Manage IoT Edge deployments at scale.

Commands

az iot edge deployment create

Create an IoT Edge deployment in a target IoT Hub.

az iot edge deployment delete

Delete an IoT Edge deployment.

az iot edge deployment list

List IoT Edge deployments in an IoT Hub.

az iot edge deployment show

Get the details of an IoT Edge deployment.

az iot edge deployment show-metric

Evaluate a target system metric defined in an IoT Edge deployment.

az iot edge deployment update

Update specified properties of an IoT Edge deployment.

Use --set followed by property assignments for updating a deployment.

Note: IoT Edge deployment content is immutable. Deployment properties that can be updated are 'labels', 'metrics', 'priority' and 'targetCondition'.

az iot edge deployment create

Create an IoT Edge deployment in a target IoT Hub.

Deployment content is json and in the form of {"modulesContent":{...}} or {"content":{"modulesContent":{...}}}.

Edge deployments can be created with user defined metrics for on demand evaluation. User metrics are json and in the form of {"queries":{...}} or {"metrics":{"queries":{...}}}.

az iot edge deployment create --content
                              --deployment-id
                              [--hub-name]
                              [--lab]
                              [--layered {false, true}]
                              [--login]
                              [--metrics]
                              [--pri]
                              [--resource-group]
                              [--target-condition]

Examples

Create a deployment with labels (bash syntax example) that applies for devices in 'building 9' and the environment is 'test'.

az iot edge deployment create -d {deployment_name} -n {iothub_name} --content modules_content.json --labels '{"key0":"value0", "key1":"value1"}' --target-condition "tags.building=9 and tags.environment='test'" --priority 3

Create a deployment with labels (powershell syntax example) that applies for devices tagged with environment 'dev'.

az iot edge deployment create -d {deployment_name} -n {iothub_name} --content modules_content.json --labels "{'key':'value'}" --target-condition "tags.environment='dev'"

Create a layered deployment that applies for devices tagged with environment 'dev'. Both user metrics and modules content defined inline (powershell syntax example).

az iot edge deployment create -d {deployment_name} -n {iothub_name} --content "{'modulesContent':{'`$edgeAgent':{'properties.desired.modules.mymodule0':{ }},'`$edgeHub':{'properties.desired.routes.myroute0':'FROM /messages/* INTO `$upstream'}}}" --target-condition "tags.environment='dev'" --priority 10 --metrics "{'queries':{'mymetrik':'SELECT deviceId from devices where properties.reported.lastDesiredStatus.code = 200'}}" --layered

Create a layered deployment that applies for devices in 'building 9' and environment 'test'. Both user metrics and modules content defined inline (bash syntax example).

az iot edge deployment create -d {deployment_name} -n {iothub_name} --content '{"modulesContent":{"$edgeAgent":{"properties.desired.modules.mymodule0":{ }},"$edgeHub":{"properties.desired.routes.myroute0":"FROM /messages/* INTO $upstream"}}}' --target-condition "tags.building=9 and tags.environment='test'" --metrics '{"queries":{"mymetrik":"SELECT deviceId from devices where properties.reported.lastDesiredStatus.code = 200"}}' --layered

Create a layered deployment that applies for devices in 'building 9' and environment 'test'. Both user metrics and modules content defined from file.

az iot edge deployment create -d {deployment_name} -n {iothub_name} --content layered_modules_content.json --target-condition "tags.building=9 and tags.environment='test'" --metrics metrics_content.json --layered

Required Parameters

--content -k

IoT Edge deployment content. Provide file path or raw json.

--deployment-id -d

Target deployment name.

Optional Parameters

--hub-name -n

IoT Hub name.

--lab --labels

Map of labels to be applied to target deployment. Use the following format: '{"key0":"value0", "key1":"value1"}'.

--layered

Layered deployments allow you to define desired properties in $edgeAgent, $edgeHub and user modules that will layer on top of a base deployment. For example the routes specified in a layered deployment will merge with routes of the base deployment. Routes with the same name will be overwritten based on deployment priority.

accepted values: false, true
--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.

--metrics -m

IoT Edge deployment metric definitions. Provide file path or raw json.

--pri --priority

Weight of deployment in case of competing rules (highest wins).

--resource-group -g

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

--target-condition --tc -t

Target condition in which an Edge deployment applies to.

az iot edge deployment delete

Delete an IoT Edge deployment.

az iot edge deployment delete --deployment-id
                              [--hub-name]
                              [--login]
                              [--resource-group]

Required Parameters

--deployment-id -d

Target deployment name.

Optional Parameters

--hub-name -n

IoT Hub name.

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

--resource-group -g

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

az iot edge deployment list

List IoT Edge deployments in an IoT Hub.

az iot edge deployment list [--hub-name]
                            [--login]
                            [--resource-group]
                            [--top]

Optional Parameters

--hub-name -n

IoT Hub name.

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

--resource-group -g

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

--top

Maximum number of deployments to return.

default value: 10

az iot edge deployment show

Get the details of an IoT Edge deployment.

az iot edge deployment show --deployment-id
                            [--hub-name]
                            [--login]
                            [--resource-group]

Required Parameters

--deployment-id -d

Target deployment name.

Optional Parameters

--hub-name -n

IoT Hub name.

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

--resource-group -g

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

az iot edge deployment show-metric

Evaluate a target system metric defined in an IoT Edge deployment.

az iot edge deployment show-metric --deployment-id
                                   --metric-id
                                   [--hub-name]
                                   [--login]
                                   [--metric-type {system, user}]
                                   [--resource-group]

Examples

Evaluate the 'appliedCount' system metric

az iot edge deployment show-metric -m appliedCount -d {deployment_name} -n {iothub_name} --mt system

Evaluate the 'myCustomMetric' user metric

az iot edge deployment show-metric -m myCustomMetric -d {deployment_name} -n {iothub_name}

Required Parameters

--deployment-id -d

Target deployment name.

--metric-id -m

Target metric for evaluation.

Optional Parameters

--hub-name -n

IoT Hub name.

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

--metric-type --mt

Indicates which metric collection should be used to lookup a metric.

accepted values: system, user
default value: user
--resource-group -g

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

az iot edge deployment update

Update specified properties of an IoT Edge deployment.

Use --set followed by property assignments for updating a deployment.

Note: IoT Edge deployment content is immutable. Deployment properties that can be updated are 'labels', 'metrics', 'priority' and 'targetCondition'.

az iot edge deployment update --deployment-id
                              [--add]
                              [--force-string]
                              [--hub-name]
                              [--login]
                              [--remove]
                              [--resource-group]
                              [--set]

Examples

Alter the labels and target condition of an existing edge deployment

az iot edge deployment update -d {deployment_name} -n {iothub_name} --set labels='{"purpose":"dev", "owners":"IoTEngineering"}' targetCondition='tags.building=9'

Required Parameters

--deployment-id -d

Target deployment name.

Optional Parameters

--add

Add an object to a list of objects by specifying a path and key value pairs. Example: --add property.listProperty <key=value, string or JSON string>.

--force-string

When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.

--hub-name -n

IoT Hub name.

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

--remove

Remove a property or an element from a list. Example: --remove property.list OR --remove propertyToRemove.

--resource-group -g

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

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=.