Proposed Pull Request Change
| title | description | services | author | ms.service | ms.topic | ms.date | ms.author | ms.custom |
|---|---|---|---|---|---|---|---|---|
| Azure Stack Edge January 2021 update impact | Microsoft Docs | This article describes the impact of IoT Edge role management on Azure Stack Edge devices after you install the January 2021 update. | databox | alkohli | azure-stack-edge | overview | 10/26/2020 | alkohli | sfi-ropc-nochange |
📄 Document Links
View on GitHub
Raw New Markdown
Generating updated version of doc...
Rendered New Markdown
Generating updated version of doc...
+0
-0
Computing diff...
+0
-0
Computing diff...
---
title: Azure Stack Edge January 2021 update impact | Microsoft Docs
description: This article describes the impact of IoT Edge role management on Azure Stack Edge devices after you install the January 2021 update.
services: databox
author: alkohli
ms.service: azure-stack-edge
ms.topic: overview
ms.date: 10/26/2020
ms.author: alkohli
ms.custom: sfi-ropc-nochange
#Customer intent: As an IT admin, I need to understand what Azure Stack Edge Pro is and how it works so I can use it to process and transform data before sending it to Azure.
---
# 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`, or `Remove-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:
```json
{
"kind": "IOT",
"properties": {
"hostPlatform": "Linux",
"ioTDeviceDetails": {
"deviceId": "iotdevice",
"ioTHostHub": "iothub.azure-devices.net",
"ioTHostHubId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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:
```json
{
"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:
```json
{
"kind": "IoT",
"properties": {
"ioTDeviceDetails": {
"deviceId": "iotdevice",
"ioTHostHub": "iothub.azure-devices.net",
"ioTHostHubId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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:
```json
"kind": "IOT",
"properties": {
"hostPlatform": "Linux",
"ioTDeviceDetails": {
"deviceId": "iotdevice",
"ioTHostHub": "iothub.azure-devices.net",
"ioTHostHubId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub",
"authentication": {
"symmetricKey": {}
}
},
"ioTEdgeDeviceDetails": {
"deviceId": "iotEdge",
"ioTHostHub": "iothub.azure-devices.net",
"ioTHostHubId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub",
"authentication": {
"symmetricKey": {}
}
},
"shareMappings": [],
"roleStatus": "Enabled"
},
"id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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:
```json
{
"kind": "IoT",
"properties": {
"provisioningState": "Creating",
"ioTDeviceDetails": {
"deviceId": "iotdevice",
"ioTHostHub": "iothub.azure-devices.net",
"ioTHostHubId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub",
"authentication": {
"symmetricKey": {}
}
},
"ioTEdgeDeviceDetails": {
"deviceId": "iotEdge",
"ioTHostHub": "iothub.azure-devices.net",
"ioTHostHubId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/GroupForEdgeAutomation/Microsoft.Devices/IotHubs/testrxiothub",
"authentication": {
"symmetricKey": {}
}
},
"version": "0.1.0-beta10"
},
"id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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
```csharp
var iotRoleStatus = "Enabled";
var iotHostPlatform = "Linux";
var id = $@"/subscriptions/bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f/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
```csharp
var k8sRoleStatus = "Enabled";
var k8sHostPlatform = "Linux";
var k8sId = $@"/subscriptions/bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f/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/bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f/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
- [Learn how to apply updates](azure-stack-edge-gpu-install-update.md)
Success! Branch created successfully. Create Pull Request on GitHub
Error: