Azure Stack Edge 裝置的 IoT Edge 角色管理變更IoT Edge role management changes for your Azure Stack Edge device

如需 Azure Stack Edge 裝置的 Azure IoT Edge 角色管理,請使用排程於2021 年 1 月發行的 API、SDK 和 Azure PowerShell 更新版本。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.

2021 年 1 月更新僅適用於 Azure Stack Edge Pro - GPU、Azure Stack Edge Pro R,以及 Azure Stack Edge Mini R 裝置。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.

注意

您不需要升級至 2021 年 1 月版本。You're not required to upgrade to the January 2021 version. 如果您選擇繼續使用目前的版本,則 IoT Edge 角色管理將不受影響。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 角色管理變更IoT Edge role management changes

在您的 Azure Stack Edge 裝置上安裝選用的 2021 年 1 月更新後,您必須使用最新版的 API、SDK 和 PowerShell Cmdlet 來管理 IoT Edge 角色。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.

只有在套用 2021 年 1 月更新時,才需要進行下列變更:The following changes are required only if you apply the January 2021 update:

  • 如果您目前使用角色管理 API  2019-08-01 版,請升級至將在 2021 年 1 月發行的 API 版本。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.
  • 如果您目前使用透過 SDK  1.0.0 版取得的角色管理,請升級至將在 2021 年 1 月發行的版本。If you're currently using role management via SDK version 1.0.0, upgrade to the version that will be released in January 2021.
  • 如果您使用角色管理搭配 Azure PowerShell Cmdlet (預覽),例如 Get-AzStackEdgeRoleNew-AzStackEdgeRoleSet-AzStackEdgeRoleRemove-AzStackEdgeRole,請等待即將於 2021 年 2 月發行的新 Cmdlet。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 使用方式API usage

如果您目前透過 API 執行 IoT Edge 角色管理,則應使用即將發行的新 API 版本 2020-12-01。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. 如果您使用目前的角色 API,在安裝即將推出的裝置軟體版本之後,您必須移至 PUT、GET、DELETE Kubernetes 角色,以及 PUT IoT 附加元件 API。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.

PUT 方法For the PUT method

目前的 HTTP 要求The current HTTP request

  • API 呼叫會在此 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 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"
        }
    }
    

即將推出的 HTTP 要求The upcoming HTTP request

  • Kubernetes 角色的 API 呼叫會在下列 URI 上進行: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''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"
                }
            }
        }
    }
    
  • IoT Edge 附加元件的 API 呼叫會在下列 URI 上進行: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''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"
                        }
                    }
                }
            }
        }
    }
    

GET 方法For the GET method

目前的 HTTP 回應The current HTTP response

  • API 呼叫是在下列 URI 上進行: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''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"
    }    
    

即將推出的 HTTP 回應The upcoming HTTP response

  • API 呼叫是在下列 URI 上進行: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''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",
    }
    

DELETE 方法For the DELETE method

目前的 API 呼叫The current API calls

API 呼叫是在下列 URI 上進行: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''https://management.azure.com/subscriptions/4385cf00-2d3a-425a-832f-f4285b1c9dce/resourceGroups/GroupForEdgeAutomation/providers/Microsoft.DataBoxEdge/dataBoxEdgeDevices/testedgedevice/roles/IoTRole1?api-version=2019-08-01'

即將推出的 API 呼叫The upcoming API calls

API 呼叫是在下列 URI 上進行: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''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 使用方式SDK usage

如果您使用 SDK,在安裝 2021 年 1 月更新之後,您必須變更設定 IoT Edge 角色的方式,如下列範例所示。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. 接著,您應下載並安裝即將推出的 NuGet 套件以移至新的 SDK,如下所示。You'll then download and install the upcoming NuGet package to move to the new SDK, as shown here.

目前的 SDK 範例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);

新的 SDK 範例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 使用方式Cmdlet usage

如果您目前使用 Get-AzStackEdgeRoleNew-AzStackEdgeRoleSet-AzStackEdgeRoleRemove-AzStackEdgeRole Cmdlet,則必須等候預計於 2021 年 2 月發行的新版本。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

我目前使用 Azure Stack Edge Pro - FPGA。2021 年 1 月更新是否會影響 FPGA 模型?I'm using Azure Stack Edge Pro - FPGA. Does the January 2021 update affect the FPGA model?

否。No. 2021 年 1 月更新僅適用於 Azure Stack Edge Pro - FPGA、Azure Stack Edge Pro R,以及 Azure Stack Edge Mini R 裝置。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 不會受到此更新的影響,您也無需變更 IoT Edge 角色管理。Azure Stack Edge Pro - FPGA isn't affected by this update and doesn't require any changes to IoT Edge role management.

當我將 Azure Stack Edge Pro - GPU 更新至 2021 年 1 月的新裝置軟體之後,是否有任何現有的服務會受到影響?After I update Azure Stack Edge Pro - GPU to the new device software in January 2021, are any of the existing services affected?

否。No. 在安裝 2021 年 1 月的裝置更新後,您已設定的服務不會受到影響。Your configured services won't be affected after you install the January 2021 device update.

IoT Edge 管理 API、SDK 或 Cmdlet 的高階變更為何?What are the high-level changes to the IoT Edge management API, SDK, or cmdlet?

IoT Edge 是 Kubernetes 角色底下的附加元件,這表示您必須先確定已設定 Kubernetes,再執行 IoT Edge 設定。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