整合 IoT Central 與 Azure Pipelines 以進行持續整合和持續傳遞

文章
01/10/2024

持續整合和持續傳遞（CI/CD）是指使用自動化管線開發及傳遞軟體的程式。本文說明如何自動化IoT Central 應用程式組態的建置、測試和部署。此自動化可讓開發小組更頻繁地提供可靠的版本。

持續整合從將程式代碼認可到原始程式碼存放庫中的分支開始。每個認可都會與其他開發人員的認可合併，以確保不會引入任何衝突。藉由建立組建並針對該組建執行自動化測試，進一步驗證變更。此程式最終會導致成品或部署套件組合部署到目標環境。在此情況下，目標是 Azure IoT Central 應用程式。

如同IoT Central是較大IoT解決方案的一部分，IoT Central是 CI/CD 管線的一部分。 CI/CD 管線應該將整個IoT解決方案和所有組態部署到每個環境，從開發到生產環境：

顯示一般 CI/CD 管線階段的圖表。

IoT Central 是應用程式 平臺即服務 ，其部署需求與 平臺即服務 元件不同。針對IoT Central，您可以部署組態和裝置範本。這些組態和裝置範本會使用 API 來管理並整合至發行管線。

雖然您可以將IoT Central 應用程式建立自動化，但您應該先在每個環境中建立應用程式，再開發 CI/CD 管線。

藉由使用 Azure IoT Central REST API，您可以將 IoT Central 應用程式組態整合到發行管線中。

本指南會逐步引導您建立新的管線，以根據 GitHub 中管理的配置檔來更新 IoT Central 應用程式。本指南有與 Azure Pipelines 整合的特定指示，但可調整為在任何使用 Tekton、Jenkins、GitLab 或 GitHub Actions 等工具所建置的發行管線中包含 IoT Central。

在本指南中，您會建立管線，該管線只會將IoT Central設定套用至IoT Central 應用程式的單一實例。您應該將步驟整合到較大的管線中，以部署整個解決方案，並將它從開發升級至 QA 到生產階段前，一路上執行所有必要的測試。

腳本目前不會在IoT Central實例之間傳輸下列設定：儀錶板、檢視、裝置範本中的自定義設定、定價方案、UX 自定義、應用程式映像、規則、排程工作、已儲存的工作和註冊群組。

腳本目前不會從組態檔中不存在的目標 IoT Central 應用程式移除設定。

必要條件

您需要下列必要條件，才能完成本指南中的步驟：

兩個IoT Central應用程式 - 一個用於您的開發環境，另一個用於生產環境。若要深入瞭解，請參閱建立IoT Central應用程式。
兩個 Azure 金鑰保存庫 - 一個用於您的開發環境，另一個用於生產環境。最佳做法是為每個環境提供專用金鑰保存庫。若要深入瞭解，請參閱使用 Azure 入口網站建立 Azure 金鑰保存庫。
GitHub 帳戶 GitHub。
Azure DevOps 組織。若要深入瞭解，請參閱建立 Azure DevOps 組織。
適用於 Windows、Mac 或 Linux 的 PowerShell 7。取得 PowerShell。
安裝在 PowerShell 7 環境中的 Azure Az PowerShell 模組。若要深入瞭解，請參閱安裝 Azure Az PowerShell 模組。
Visual Studio Code 或其他工具來編輯 PowerShell 和 JSON 檔案。取得 Visual Studio Code。
Git 用戶端。從 Git 下載最新版本 - 下載（git-scm.com）。

在 Azure Cloud Shell 中使用 Bash 環境。如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 登入。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

下載範例程式碼

若要開始使用，請派生IoT Central CI/CD GitHub存放庫，然後將分支複製到本機電腦：

若要派生 GitHub 存放庫，請開啟 IoT Central CI/CD GitHub 存放庫，然後選取 [分支]。
開啟主控台或bash視窗並執行下列命令，將存放庫分支複製到本機電腦。
```
git clone https://github.com/{your GitHub username}/iot-central-CICD-sample
```

建立服務主體

雖然 Azure Pipelines 可以直接與密鑰保存庫整合，但管線需要服務主體來進行某些動態密鑰保存庫互動，例如擷取數據導出目的地的秘密。

若要建立範圍設定為訂用帳戶的服務主體：

執行下列命令以建立新的服務主體：

az ad sp create-for-rbac -n DevOpsAccess --scopes /subscriptions/{your Azure subscription Id} --role Contributor

記下密碼、 appId 和 租用戶 ，因為您稍後需要這些值。

將服務主體密碼新增為名為 SP-Password 的秘密至生產金鑰儲存庫：

az keyvault secret set --name SP-Password --vault-name {your production key vault name} --value {your service principal password}

授與服務主體許可權，以從密鑰保存庫讀取秘密：

az keyvault set-policy --name {your production key vault name} --secret-permissions get list --spn {the appId of the service principal}

產生IoT Central API令牌

在本指南中，您的管線會使用 API 令牌來與您的 IoT Central 應用程式互動。也可以使用服務主體。

注意

IoT Central API 令牌會在一年後到期。

針對您的開發和生產IoT Central應用程式，完成下列步驟。

在您的 IoT Central 應用程式中，選取 [許可權]，然後選取 [API 令牌]。
選取新增。
為令牌指定名稱、指定您應用程式中的最上層組織，並將角色設定為App管理員 istrator。
記下您開發IoT Central 應用程式的 API 令牌。您稍後會在執行 IoTC-Config.ps1 腳本時使用它。

將產生的令牌從生產 IoT Central 應用程式儲存為呼叫 API-Token 至生產密鑰保存庫的秘密：

az keyvault secret set --name API-Token --vault-name {your production key vault name} --value '{your production app API token}'

產生組態檔

這些步驟會根據現有的IoT Central應用程式，為您的開發環境產生 JSON 組態檔。您也會從應用程式下載所有現有的裝置範本。

在 IoT Central CI/CD 存放庫的本機複本中執行下列 PowerShell 7 腳本：
```
cd .\iot-central-CICD-sample\PowerShell\
.\IoTC-Config.ps1
```
請依照指示登入您的 Azure 帳戶。
登入之後，腳本會顯示 [IoTC 組態選項] 功能表。此腳本可以從現有的IoT Central 應用程式產生組態檔，並將設定套用至另一個IoT Central 應用程式。
選取選項 1 以產生組態檔。
輸入必要的參數，然後按 Enter：
- 您為開發IoT Central 應用程式所產生的 API 令牌。
- 開發 IoT Central 應用程式的子域。
- 輸入 ..\Config\Dev 作為儲存組態檔和裝置範本的資料夾。
- 開發金鑰保存庫的名稱。
腳本會在存放庫本機複本的 Config\Dev 資料夾中，建立名為 IoTC 組態的資料夾。此資料夾包含組態檔，以及應用程式中所有裝置範本稱為 「裝置模型 」的資料夾。

修改設定檔

既然您有一個組態檔，代表開發 IoT Central 應用程式實例的設定，請先進行任何必要的變更，再將此組態套用至生產 IoT Central 應用程式實例。

建立先前建立之 Dev 資料夾的複本，並將其呼叫為 Production。
使用文字編輯器，在 [生產] 資料夾中開啟IoTC-Config.json。

檔案有多個區段。不過，如果您的應用程式未使用特定設定，則會從檔案省略該區段：

{
  "APITokens": {
    "value": [
      {
        "id": "dev-admin",
        "roles": [
          {
            "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
          }
        ],
        "expiry": "2023-05-31T10:47:08.53Z"
      }
    ]
  },
  "data exports": {
    "value": [
      {
        "id": "5ad278d6-e22b-4749-803d-db1a8a2b8529",
        "displayName": "All telemetry to blob storage",
        "enabled": false,
        "source": "telemetry",
        "destinations": [
          {
            "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63"
          }
        ],
        "status": "notStarted"
      }
    ]
  },
  "device groups": {
    "value": [
      {
        "id": "66f41d29-832d-4a12-9e9d-18932bee3141",
        "displayName": "MXCHIP Getting Started Guide - All devices"
      },
      {
        "id": "494dc749-0963-4ec1-89ff-e1de2228e750",
        "displayName": "RS40 Occupancy Sensor - All devices"
      },
      {
        "id": "dd87877d-9465-410b-947e-64167a7a1c39",
        "displayName": "Cascade 500 - All devices"
      },
      {
        "id": "91ceac5b-f98d-4df0-9ed6-5465854e7d9e",
        "displayName": "Simulated devices"
      }
    ]
  },
  "organizations": {
    "value": []
  },
  "roles": {
    "value": [
      {
        "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
        "displayName": "Builder"
      },
      {
        "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
        "displayName": "Administrator"
      },
      {
        "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
        "displayName": "Operator"
      }
    ]
  },
  "destinations": {
    "value": [
      {
        "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
        "displayName": "Blob destination",
        "type": "blobstorage@v1",
        "authorization": {
          "type": "connectionString",
          "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourexportaccount;AccountKey=*****;EndpointSuffix=core.windows.net",
          "containerName": "dataexport"
        },
        "status": "waiting"
      }
    ]
  },
  "file uploads": {
    "connectionString": "FileUpload",
    "container": "fileupload",
    "sasTtl": "PT1H"
  },
  "jobs": {
    "value": []
  }
}

如果您的應用程式使用檔案上傳，腳本會在您的開發金鑰保存庫中建立秘密，其中包含屬性中顯示的 connectionString 值。在生產密鑰保存庫中建立具有相同名稱的秘密，其中包含生產記憶體帳戶連接字串。例如：
```
az keyvault secret set --name FileUpload --vault-name {your production key vault name} --value '{your production storage account connection string}'
```
如果您的應用程式使用數據匯出，請將目的地的秘密新增至生產密鑰保存庫。配置檔不包含目的地的任何實際秘密，秘密會儲存在密鑰保存庫中。

使用金鑰保存庫中的秘密名稱更新組態檔中的秘密。

目的地類型	要變更的屬性
服務匯流排佇列	connectionString
服務匯流排主題	connectionString
Azure 資料總管	clientSecret
Azure Blob 儲存體	connectionString
事件中樞	connectionString
Webhook 無驗證	N/A

例如：

"destinations": {
  "value": [
    {
      "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
      "displayName": "Blob destination",
      "type": "blobstorage@v1",
      "authorization": {
        "type": "connectionString",
        "connectionString": "Storage-CS",
        "containerName": "dataexport"
      },
      "status": "waiting"
    }
  ]
}

若要將 Configuration 資料夾上傳至 GitHub 存放庫，請從 IoTC-CICD-howto 資料夾執行下列命令。
```
 git add Config
 git commit -m "Adding config directories and files"
 git push
```

建立管線

移至，在網頁瀏覽器中開啟您的 Azure DevOps 組織 https://dev.azure.com/{your DevOps organization}
選取 [新增專案 ] 以建立新的專案。
為您的專案指定名稱和選擇性描述，然後選取 [ 建立]。
在 [歡迎使用專案] 頁面上，選取 [管線]，然後選取 [建立管線]。
選取 [GitHub ] 作為程序代碼的位置。
選取 [ 授權 AzurePipelines ] 以授權 Azure Pipelines 存取您的 GitHub 帳戶。
在 [ 選取存放庫 ] 頁面上，選取 IoT Central CI/CD GitHub 存放庫的分支。
當系統提示您登入 GitHub 並提供 Azure Pipelines 存取存放庫的許可權時，請選取 [ 核准和安裝]。
在 [設定管線] 頁面上，選取 [入門管線] 以開始使用。隨即 會顯示azure-pipelines.yml 以供編輯。

建立變數群組

將金鑰保存庫秘密整合到管線的簡單方式是透過變數群組。使用變數群組來確保部署腳本可以使用正確的秘密。若要建立變數群組：

在左側功能表的 [管線] 區段中，選取 [連結庫]。
選取 [+ 變數群組]。
輸入 keyvault 作為變數群組的名稱。
啟用切換以從 Azure 金鑰保存庫連結秘密。
選取您的 Azure 訂用帳戶並加以授權。然後選取您的生產金鑰保存庫名稱。
選取 [ 新增 ] 以開始將變數新增至群組。
新增下列秘密：
- 生產應用程式的IoT Central API 金鑰。您在建立秘密時呼叫此秘密 API-Token 。
- 您先前建立之服務主體的密碼。您在建立秘密時呼叫此秘密 SP-Password 。
選取 [確定]。
選取 [ 儲存 ] 以儲存變數群組。

設定您的管線

現在將管線設定為將設定變更推送至 IoT Central 應用程式：

在左側功能表的 [管線] 區段中選取 [管線]。

將管線 YAML 的內容取代為下列 YAML。此群組態假設您的生產金鑰儲存函式庫包含：

生產 IoT Central 應用程式的 API 令牌，其秘密稱為 API-Token。
秘密中的服務主體密碼稱為 SP-Password。

將和 -KeyVault 的值-AppName取代為生產實例的適當值。

您已記-AppId-TenantId下和建立服務主體時。

trigger:
- master
variables:
- group: keyvault
- name: buildConfiguration
  value: 'Release'
steps:
- task: PowerShell@2
  displayName: 'IoT Central'
  inputs:
    filePath: 'PowerShell/IoTC-Task.ps1'
    arguments: '-ApiToken "$(API-Token)" -ConfigPath "Config/Production/IoTC Configuration" -AppName "{your production IoT Central app name}" -ServicePrincipalPassword (ConvertTo-SecureString "$(SP-Password)" -AsPlainText -Force) -AppId "{your service principal app id}" -KeyVault "{your production key vault name}" -TenantId "{your tenant id}"'
    pwsh: true
    failOnStderr:  true

選取儲存並執行。
YAML 檔案會儲存至您的 GitHub 存放庫，因此您需要提供認可訊息，然後選取 [ 儲存並再次執行 ]。

您的管線已排入佇列。執行前可能需要幾分鐘的時間。

第一次執行管線時，系統會提示您授與管線存取訂用帳戶和存取密鑰保存庫的許可權。針對每個資源選取 [允許 ]，然後 再次 [允許 ]。

當管線作業順利完成時，請登入您的生產 IoT Central 應用程式，並確認已如預期般套用設定。

將開發變更升階至生產環境

現在您已有運作中的管線，您可以使用組態變更直接管理 IoT Central 實例。您可以將新的裝置範本上傳至 [裝置模型 ] 資料夾，並直接對組態檔進行變更。此方法可讓您將IoT Central 應用程式的組態與任何其他程式碼相同。

後續步驟

既然您已瞭解如何將IoT Central設定整合到 CI/CD 管線中，建議的下一個步驟是瞭解如何管理及監視IoT Central 應用程式。

分享方式：