IoT Edge role management changes for your Azure Stack Edge device
For Azure IoT Edge role management for your Azure Stack Edge device, use the updated version of the API, SDK, and Azure PowerShell, which is scheduled for January 2021 release.
This article describes in detail the changes that you need to make when you use this newest version.
The January 2021 update will be available only for Azure Stack Edge Pro - GPU, Azure Stack Edge Pro R, and Azure Stack Edge Mini R devices. The information in this article applies only to these devices.
Note
You're not required to upgrade to the January 2021 version. If you choose to continue using your current version, there is no impact on IoT Edge role management. However, to take advantage of the new features and to help reduce any security risks, we recommend that you install the newer version.
IoT Edge role management changes
After you install the optional January 2021 update on your Azure Stack Edge device, you'll need to use the latest version of the API, SDK, and PowerShell cmdlets for IoT Edge role management.
The following changes are required only if you apply the January 2021 update:
- If you're currently using the Role Management API version 2019-08-01, upgrade to the API version that will be released in January 2021.
- If you're currently using role management via SDK version 1.0.0, upgrade to the version that will be released in January 2021.
- If you're using role management with the Azure PowerShell cmdlets (Preview), such as
Get-AzStackEdgeRole,New-AzStackEdgeRole,Set-AzStackEdgeRole, orRemove-AzStackEdgeRole, wait for the new cmdlets to be released in February 2021.
API usage
If you're currently performing IoT Edge role management via API, you should use the new API version 2020-12-01, which will be published later. If you're using the current Role API, after you install the upcoming device software version, you must move to the PUT, GET, or DELETE Kubernetes role, followed by the PUT IoT Add-on API.
For the PUT method
The current HTTP request
The API calls are made at this URI: 'https://management.azure.com/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/testedgedevice/roles/IoTRole1?api-version=2019-08-01'
The request body looks like this:
{ "kind": "IOT", "properties": { "hostPlatform": "Linux", "ioTDeviceDetails": { "deviceId": "iotdevice", "ioTHostHub": "iothub.azure-devices.net", "ioTHostHubId": "/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub", "authentication": { "symmetricKey": { "connectionString": { "value": "Encrypted<<HostName=iothub.azure-devices.net;DeviceId=iotDevice;SharedAccessKey=2C750FscEas3JmQ8Bnui5yQWZPyml0/UiRt1bQwd8=>>", "encryptionCertThumbprint": "348586569999244", "encryptionAlgorithm": "AES256" } } } }, "ioTEdgeDeviceDetails": { "deviceId": "iotEdge", "ioTHostHub": "iothub.azure-devices.net", "ioTHostHubId": "/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub", "authentication": { "symmetricKey": { "connectionString": { "value": "Encrypted<<HostName=iothub.azure-devices.net;DeviceId=iotEdge;SharedAccessKey=2C750FscEas3JmQ8Bnui5yQWZPyml0/UiRt1bQwd8=>>", "encryptionCertThumbprint": "1245475856069999244", "encryptionAlgorithm": "AES256" } } } }, "shareMappings": [], "roleStatus": "Enabled" } }
The upcoming HTTP request
The API calls for the Kubernetes role are made at the following URI:
'https://management.azure.com/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/testedgedevice/roles/KubernetesRole1?api-version=2020-12-01'
The request body will look like this:
{ "kind": "Kubernetes", "properties": { "hostPlatform": "Linux", "kubernetesClusterInfo": { "version": "v1.17.3" }, "kubernetesRoleResources": { "storage": { "endpoints": [] }, "compute": { "vmProfile": "DS1_v2" } } } }The API calls for the IoT Edge add-on are made at the following URI:
'https://management.azure.com/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/testedgedevice/roles/KubernetesRole1/addons/iotaddon?api-version=2020-12-01'
The request body will look like this:
{ "kind": "IoT", "properties": { "ioTDeviceDetails": { "deviceId": "iotdevice", "ioTHostHub": "iothub.azure-devices.net", "ioTHostHubId": "/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub", "authentication": { "symmetricKey": { "connectionString": { "value": "Encrypted<<HostName=iothub.azure-devices.net;DeviceId=iotDevice;SharedAccessKey=2C750FscEas3JmQ8Bnui5yQWZPyml0/UiRt1bQwd8=>>", "encryptionCertThumbprint": "348586569999244", "encryptionAlgorithm": "AES256" } } } }, "ioTEdgeDeviceDetails": { "deviceId": "iotEdge", "ioTHostHub": "iothub.azure-devices.net", "ioTHostHubId": "/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub", "authentication": { "symmetricKey": { "connectionString": { "value": "Encrypted<<HostName=iothub.azure-devices.net;DeviceId=iotEdge;SharedAccessKey=2C750FscEas3JmQ8Bnui5yQWZPyml0/UiRt1bQwd8=>>", "encryptionCertThumbprint": "1245475856069999244", "encryptionAlgorithm": "AES256" } } } } } }
For the GET method
The current HTTP response
The API calls are made at the following URI:
'https://management.azure.com/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/testedgedevice/roles/IoTRole1?api-version=2019-08-01'
The response body looks like this:
"kind": "IOT", "properties": { "hostPlatform": "Linux", "ioTDeviceDetails": { "deviceId": "iotdevice", "ioTHostHub": "iothub.azure-devices.net", "ioTHostHubId": "/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub", "authentication": { "symmetricKey": {} } }, "ioTEdgeDeviceDetails": { "deviceId": "iotEdge", "ioTHostHub": "iothub.azure-devices.net", "ioTHostHubId": "/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub", "authentication": { "symmetricKey": {} } }, "shareMappings": [], "roleStatus": "Enabled" }, "id": "/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/testedgedevice/roles/IoTRole1", "name": "IoTRole1", "type": "dataBoxEdgeDevices/roles" }
The upcoming HTTP response
The API calls are made at the following URI:
'https://management.azure.com/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/testedgedevice/roles/KubernetesRole1/addons/iotaddon?api-version=2020-12-01'
The response body looks like this:
{ "kind": "IoT", "properties": { "provisioningState": "Creating", "ioTDeviceDetails": { "deviceId": "iotdevice", "ioTHostHub": "iothub.azure-devices.net", "ioTHostHubId": "/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub", "authentication": { "symmetricKey": {} } }, "ioTEdgeDeviceDetails": { "deviceId": "iotEdge", "ioTHostHub": "iothub.azure-devices.net", "ioTHostHubId": "/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub", "authentication": { "symmetricKey": {} } }, "version": "0.1.0-beta10" }, "id": "/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/res1/roles/kubernetesRole/addons/iotName", "name": " iotName", "type": "Microsoft.DataBoxEdge/dataBoxEdgeDevices/roles/addon", }
For the DELETE method
The current API calls
The API calls are made at the following URI:
'https://management.azure.com/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/testedgedevice/roles/IoTRole1?api-version=2019-08-01'
The upcoming API calls
The API calls are made at the following URI:
'https://management.azure.com/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/testedgedevice/roles/KubernetesRole1/addons/iotaddon?api-version=2020-12-01'
SDK usage
If you're using the SDK, after you've installed the January 2021 update, you'll need to change the way you set up the IoT Edge role, as shown in the following sample. You'll then download and install the upcoming NuGet package to move to the new SDK, as shown here.
The current SDK sample
var iotRoleStatus = "Enabled";
var iotHostPlatform = "Linux";
var id = $@"/subscriptions/546ec571-2d7f-426f-9cd8-0d695fa7edba/resourceGroups/resourceGroup/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/deviceName/roles/iotrole";
var name = "iotrole";
var type = "Microsoft.DataBoxEdge/dataBoxEdgeDevices/role";
var iotRoleName = "iotrole";
var ioTDeviceDetails = new IoTDeviceInfo(...);
var ioTEdgeDeviceDetails = new IoTDeviceInfo(...);
var ioTEdgeAgentInfo = new IoTEdgeAgentInfo(...);
var shareMappings = new List<MountPointMap>(...);
var role = new IoTRole(roleStatus,
hostPlatform,
shareMappings,
ioTDeviceDetails,
ioTEdgeDeviceDetails,
ioTEdgeAgentInfo,
id,
name,
type);
DataBoxEdgeManagementClient.Roles.CreateOrUpdate(deviceName, iotRoleName, role, resourceGroup);
The new SDK sample
var k8sRoleStatus = "Enabled";
var k8sHostPlatform = "Linux";
var k8sId = $@"/subscriptions/546ec571-2d7f-426f-9cd8-0d695fa7edba/resourceGroups/resourceGroup/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/deviceName/roles/KubernetesRole";
var k8sRoleName = "KubernetesRole";
var k8sClusterVersion = "v1.17.3"; //Final values will be updated here around January 2021
var k8sVmProfile = "DS1_v2"; //Final values will be updated here around January 2021
var type = "Microsoft.DataBoxEdge/dataBoxEdgeDevices/role";
var k8sRole = new KubernetesRole(
roleStatus,
hostPlatform,
shareMappings,
k8sClusterVersion,
k8sVmProfile,
k8sId,
k8sRoleName,
type
);
DataBoxEdgeManagementClient.Roles.CreateOrUpdate(deviceName, k8sRoleName, k8sRole, resourceGroup); //Final usage will be updated here around January 2021
var ioTId = $@"/subscriptions/546ec571-2d7f-426f-9cd8-0d695fa7edba/resourceGroups/resourceGroup/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/deviceName/roles/KubernetesRole/addons/iotaddon";
var ioTAddonName = "iotaddon";
var ioTAddonType = "Microsoft.DataBoxEdge/dataBoxEdgeDevices/roles/addons";
var addon = new IoTAddon(
ioTDeviceDetails,
ioTEdgeDeviceDetails,
ioTEdgeAgentInfo,
ioTId,
ioTAddonName,
ioTAddonType);
DataBoxEdgeManagementClient.AddOns.CreateOrUpdate(deviceName, k8sRoleName, addonName, addon, resourceGroup); //Final usage will be updated here around January 2021
Cmdlet usage
If you're currently using the Get-AzStackEdgeRole, New-AzStackEdgeRole, Set-AzStackEdgeRole, or Remove-AzStackEdgeRole cmdlet, you'll need to wait for the new version that's planned for the February 2021 release.
Frequently asked questions
I'm using Azure Stack Edge Pro - FPGA. Does the January 2021 update affect the FPGA model?
No. The January 2021 update applies only to Azure Stack Edge Pro - FPGA, Azure Stack Edge Pro R, and Azure Stack Edge Mini R devices. Azure Stack Edge Pro - FPGA isn't affected by this update and doesn't require any changes to IoT Edge role management.
After I update Azure Stack Edge Pro - GPU to the new device software in January 2021, are any of the existing services affected?
No. Your configured services won't be affected after you install the January 2021 device update.
What are the high-level changes to the IoT Edge management API, SDK, or cmdlet?
IoT Edge is an add-on under the Kubernetes role, which implies that you'll first need to ensure that Kubernetes is configured and then perform the IoT Edge configuration.
Next steps
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for