AzureIoTEdge@2 - Azure IoT Edge v2 task

Use this task to build and deploy images quickly and efficiently to Azure IoT Edge.

This task supports custom variables. If you're not familiar with how to use variables in Pipelines, see define variables.

Note

This task does not support Azure Resource Manager authentication with workflow identity federation.

Syntax

# Azure IoT Edge v2
# Build and deploy an Azure IoT Edge image.
- task: AzureIoTEdge@2
  inputs:
    action: 'Build module images' # 'Build module images' | 'Push module images' | 'Generate deployment manifest' | 'Deploy to IoT Edge devices'. Required. Action. Default: Build module images.
    #deploymentFilePath: '$(System.DefaultWorkingDirectory)/config/deployment.json' # string. Required when action == Deploy to IoT Edge devices. Deployment file. Default: $(System.DefaultWorkingDirectory)/config/deployment.json.
    #azureSubscription: # string. Alias: connectedServiceNameARM. Required when action == Deploy to IoT Edge devices. Azure subscription contains IoT Hub. 
    #iothubname: # string. Required when action == Deploy to IoT Edge devices. IoT Hub name. 
    #deviceOption: # 'Single Device' | 'Multiple Devices'. Required when action == Deploy to IoT Edge devices. Choose single/multiple device. 
    #deviceId: # string. Required when deviceOption == Single Device. IoT Edge device ID. 
    #targetcondition: # string. Required when deviceOption == Multiple Devices. IoT Edge device target condition. 
    #containerregistrytype: 'Azure Container Registry' # 'Azure Container Registry' | 'Generic Container Registry'. Required when action = Push module images. Container registry type. Default: Azure Container Registry.
    #dockerRegistryConnection: # string. Alias: dockerRegistryEndpoint. Required when containerregistrytype = Generic Container Registry. Docker Registry Connection. 
    #azureSubscriptionEndpoint: # string. Optional. Use when containerregistrytype = Azure Container Registry. Azure subscription. 
    #azureContainerRegistry: # string. Required when containerregistrytype = Azure Container Registry. Azure Container Registry. 
    #templateFilePath: 'deployment.template.json' # string. Required when action = Build module images || action = Push module images || action = Generate deployment manifest. .template.json file. Default: deployment.template.json.
    #defaultPlatform: 'amd64' # 'amd64' | 'windows-amd64' | 'arm32v7' | 'arm64v8'. Required when action = Build module images || action = Push module images || action = Generate deployment manifest. Default platform. Default: amd64.
    #fillRegistryCredential: 'true' # 'true' | 'false'. Required when action = Push module images. Add registry credential to deployment manifest. Default: true.
    #deploymentManifestOutputPath: '$(System.DefaultWorkingDirectory)/config/deployment.json' # string. Required when action == Generate deployment manifest. Output path. Default: $(System.DefaultWorkingDirectory)/config/deployment.json.
    #validateGeneratedDeploymentManifest: 'false' # 'true' | 'false'. Required when action = Generate deployment manifest. Validate the schema of generated deployment manifest. Default: false.
  # Advanced
    #deploymentid: '$(System.TeamProject)-devops-deployment' # string. Required when action = Deploy to IoT Edge devices. IoT Edge deployment ID. Default: $(System.TeamProject)-devops-deployment.
    #priority: '0' # string. Required when action = Deploy to IoT Edge devices. IoT Edge deployment priority. Default: 0.
  # Advanced
    #bypassModules: # string. Optional. Use when action = Push module images. Bypass module(s).

Inputs

action - Action
string. Required. Allowed values: Build module images, Push module images, Generate deployment manifest, Deploy to IoT Edge devices. Default value: Build module images.

Selects an Azure IoT Edge action.

Build module images only builds modules (you can use it to check compilation errors).

Push module images pushes modules to the container registry.

Deploy to IoT Edge devices deploys the generated deployment file to IoT Hub. (We recommend putting the Deploy task in the release pipeline.)

deploymentFilePath - Deployment file
string. Required when action == Deploy to IoT Edge devices. Default value: $(System.DefaultWorkingDirectory)/config/deployment.json.

Selects the deployment json file. If this task is in release pipeline, you need to set the location of the deployment file in artifact. (The default value works for most conditions.) If this task is in a build pipeline, you must specify the deployment manifest output path.

azureSubscription - Azure subscription contains IoT Hub
Input alias: connectedServiceNameARM. string. Required when action == Deploy to IoT Edge devices.

Selects an Azure subscription that contains IoT Hub.

iothubname - IoT Hub name
string. Required when action == Deploy to IoT Edge devices.

Selects the IoT Hub.

deploymentid - IoT Edge deployment ID
string. Required when action = Deploy to IoT Edge devices. Default value: $(System.TeamProject)-devops-deployment.

Inputs the IoT Edge Deployment ID. If the ID already exists, it will be overridden. This has up to 128 lowercase letters and numbers, and the following characters are allowed: -:+%_#*?!(),=@;'. For more information, see Azure IoT Edge deployment.

priority - IoT Edge deployment priority
string. Required when action = Deploy to IoT Edge devices. Default value: 0.

Sets the priority to a positive integer to resolve deployment conflicts. When this task is targeted by multiple deployments, a device will use the one with the highest priority or, in the case of two deployments with the same priority, the latest creation time. For more information, see Azure IoT Edge deployment.

deviceOption - Choose single/multiple device
string. Required when action == Deploy to IoT Edge devices. Allowed values: Single Device, Multiple Devices.

According to tags, chooses to deploy to single or multiple devices.

deviceId - IoT Edge device ID
string. Required when deviceOption == Single Device.

Inputs the IoT Edge device ID.

targetcondition - IoT Edge device target condition
string. Required when deviceOption == Multiple Devices.

Inputs the target condition of devices you would like to deploy. Do not use double quotes. Example: tags.building=9 and tags.environment='test'. For more information, see Azure IoT Edge deployment.

containerregistrytype - Container registry type
string. Required when action = Push module images. Allowed values: Azure Container Registry, Generic Container Registry. Default value: Azure Container Registry.

Selects a Container Registry Type. Azure Container Registry is for ACR, and Generic Container Registry is for generic registries including docker hub.

dockerRegistryConnection - Docker Registry Connection
Input alias: dockerRegistryEndpoint. string. Required when containerregistrytype = Generic Container Registry.

Selects a generic Docker registry connection. This is required for build and push.

azureSubscriptionEndpoint - Azure subscription
string. Optional. Use when containerregistrytype = Azure Container Registry.

Selects an Azure subscription.

azureContainerRegistry - Azure Container Registry
string. Required when containerregistrytype = Azure Container Registry.

Specifies an Azure Container Registry. This value should be specified in json format.

azureContainerRegistry: '{"loginServer": "contoso.azurecr.io"}

templateFilePath - .template.json file
string. Required when action = Build module images || action = Push module images || action = Generate deployment manifest. Default value: deployment.template.json.

The path of Azure IoT Edge solution .template.json. This file defines the modules and routes in Azure IoT Edge solution. The file name must end with .template.json.

defaultPlatform - Default platform
string. Required when action = Build module images || action = Push module images || action = Generate deployment manifest. Allowed values: amd64, windows-amd64, arm32v7, arm64v8. Default value: amd64.

In your .template.json, you can leave the modules platform unspecified. For these modules, the default platform will be used.

fillRegistryCredential - Add registry credential to deployment manifest
string. Required when action = Push module images. Allowed values: true, false. Default value: true.

Adds the registry credential for pushing docker images to the deployment manifest.

deploymentManifestOutputPath - Output path
string. Required when action == Generate deployment manifest. Default value: $(System.DefaultWorkingDirectory)/config/deployment.json.

The output path of the generated deployment manifest.

validateGeneratedDeploymentManifest - Validate the schema of generated deployment manifest
string. Required when action = Generate deployment manifest. Allowed values: true, false. Default value: false.

Fail this step if the generated deployment manifest does not pass schema validation. Search Azure IoT Edge deployment in JSON Schema Store to find latest schema.

bypassModules - Bypass module(s)
string. Optional. Use when action = Push module images.

Selects the module(s) that you do not need to build or push in .template.json, specifies the module names, and separates them with commas. Example: if you have SampleModule1 and SampleModule2 in your .template.json and you want to only build or push SampleModule1, then you set the bypass modules as SampleModule2. Leave this empty if you would like to build all the modules in .template.json.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

This task defines the following output variables, which you can consume in downstream steps, jobs, and stages.

DEPLOYMENT_FILE_PATH
This is the path of generated deployment file.

Remarks

Use this task to build, test, and deploy applications quickly and efficiently to Azure IoT Edge.

This task supports custom variables. If you're not familiar with how to use variables in Pipelines, see Define variables.

Examples

Build module images

The following YAML example builds module images:

- task: AzureIoTEdge@2
  displayName: AzureIoTEdge - Build module images
  inputs:
    action: Build module images
    templateFilePath: deployment.template.json
    defaultPlatform: amd64  

Push module images

The following YAML example pushes module images:

variables:
  azureSubscriptionEndpoint: Contoso
  azureContainerRegistry: contoso.azurecr.io

steps:    
- task: AzureIoTEdge@2
  displayName: AzureIoTEdge - Push module images
  inputs:
    action: Push module images
    containerregistrytype: Azure Container Registry
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureContainerRegistry: {"loginServer":"$(azureContainerRegistry)"}
    templateFilePath: deployment.template.json
    defaultPlatform: amd64
    fillRegistryCredential: true

Generate deployment manifest

The following YAML example creates a deployment manifest based on the template file:

steps:    
- task: AzureIoTEdge@2
  displayName: AzureIoTEdge - Generate deployment manifest
  inputs:
    action: Generate deployment manifest
    templateFilePath: deployment.template.json
    defaultPlatform: amd64
    deploymentManifestOutputPath: $(System.DefaultWorkingDirectory)/config/deployment.json
    validateGeneratedDeploymentManifest: false

Deploy to IoT Edge devices

The following YAML example deploys module images:

steps:
- task: AzureIoTEdge@2
  displayName: 'Azure IoT Edge - Deploy to IoT Edge devices'
  inputs:
    action: 'Deploy to IoT Edge devices'
    deploymentFilePath: $(System.DefaultWorkingDirectory)/config/deployment.json
    azureSubscription: $(azureSubscriptionEndpoint)
    iothubname: iothubname
    deploymentid: '$(System.TeamProject)-devops-deployment'
    priority: '0'
    deviceOption: 'Single Device'
    deviceId: deviceId

More examples

For step-by-step examples of how to use these actions in Azure Pipelines, see the following articles:

• Continuous integration and continuous deployment to Azure IoT Edge devices (YAML)
• Continuous integration and continuous deployment to Azure IoT Edge devices (classic editor)

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	Any
Settable variables	Any
Agent version	All supported agent versions.
Task category	Build