IoT Central を Azure Pipelines に統合して、継続的インテグレーションと継続的デリバリーを実現する

[アーティクル]
06/12/2023

継続的インテグレーションと継続的デリバリー (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 アプリケーションの 1 つのインスタンスに IoT Central 構成を適用するだけのパイプラインを作成します。これらの手順は、ソリューション全体をデプロイし、それを "開発" から "QA"、"QA" から "運用前"、"運用前" から "運用" に昇格させる (途中で必要なすべてのテストを実行する) 大規模なパイプラインに統合する必要があります。

現在、スクリプトは、IoT Central インスタンス間で、ダッシュボード、ビュー、デバイステンプレートのカスタム設定、価格プラン、UX カスタマイズ、アプリケーションイメージ、ルール、スケジュール済みジョブ、保存済みジョブ、登録グループの設定を転送しません。

現在、スクリプトは、ターゲット IoT Central アプリケーションから、構成ファイルに存在しない設定を削除しません。

前提条件

このガイドの手順を完了するには、次の前提条件を満たす必要があります。

2 つの IoT Central アプリケーション - 1 つは開発環境用、もう 1 つは運用環境用。詳細については、「IoT Central アプリケーションを作成する」を参照してください。
2 つの Azure Key Vault - 1 つは開発環境用、もう 1 つは運用環境用。環境ごとに専用の Key Vault を用意することをお勧めします。詳細については、Azure portal を使用した Azure Key Vault の作成に関するページを参照してください。
GitHub アカウント (GitHub)。
Azure DevOps 組織。詳細については、「Azure DevOps 組織の作成」を参照してください。
Windows、Mac、または Linux 用の PowerShell 7。 (PowerShell の入手)。
PowerShell 7 環境にインストールされた Azure Az PowerShell モジュール。詳細については、「Azure Az PowerShell モジュールをインストールする」を参照してください。
PowerShell ファイルと JSON ファイルを編集するための Visual Studio Code またはその他のツール (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 は Key Vault と直接統合できますが、パイプラインには、データエクスポート先のシークレットのフェッチなど、一部の動的 Key Vault 操作のためにサービスプリンシパルが必要です。

サブスクリプションに範囲を絞ったサービスプリンシパルを作成するには:

次のコマンドを実行して、新しいサービスプリンシパルを作成します。

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

password、appId、tenant の値は、後で必要になるためメモします。
サービスプリンシパルのパスワードを SP-Password という名前のシークレットとして運用 Key Vault に追加します。
```
az keyvault secret set --name SP-Password --vault-name {your production key vault name} --value {your service principal password}
```

Key Vault からシークレットを読み取るためのアクセス許可をサービスプリンシパルに付与します。

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 トークンの有効期限は 1 年後です。

開発用と運用用の両方の IoT Central アプリについて、次の手順を実行します。

IoT Central アプリで、[アクセス許可] を選択し、次に [API トークン] を選択します。
[新規] を選択します。
トークンに名前を付け、アプリで最上位レベルの組織を指定し、ロールを [アプリの管理者] に設定します。
開発 IoT Central アプリケーションからの API トークンをメモします。これは、後ほど IoTC-Config.ps1 スクリプトを実行するときに使用します。
運用 IoT Central アプリケーションから生成されたトークンを API-Token という名前のシークレットとして運用 Key Vault に保存します。
```
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 Config options] (IoTC 構成のオプション) メニューが表示されます。このスクリプトでは、既存の IoT Central アプリケーションから構成ファイルを生成し、別の IoT Central アプリケーションに構成を適用できます。
オプション 1 を選択して構成ファイルを生成します。
必要なパラメーターを入力し、Enter キーを押します。
- 開発 IoT Central アプリケーションで生成した API トークン。
- 開発 IoT Central アプリケーションのサブドメイン。
- 構成ファイルとデバイステンプレートを格納するフォルダーとして「..\Config\Dev」と入力します。
- 開発 Key Vault の名前。
スクリプトによって、リポジトリのローカルコピーの Config\Dev フォルダー内に、IoTC Configuration という名前のフォルダーが作成されます。このフォルダーには、構成ファイルと、アプリケーション内のすべてのデバイステンプレート用の Device Models という名前のフォルダーが含まれます。

構成ファイルを変更します

開発 IoT Central アプリケーションインスタンスの設定を表す構成ファイルが作成されたので、運用 IoT Central アプリケーションインスタンスにこの構成を適用する前に、必要な変更を加えます。

前に作成した Dev フォルダーのコピーを作成し、そのコピーに Production という名前を付けます。
テキストエディターを使用して、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": "systemAssignedManagedIdentity",
          "endpointUri": "https://yourstorageaccount.blob.core.windows.net/",
          "containerName": "dataexport"
        },
        "status": "waiting"
      }
    ]
  },
  "file uploads": {
    "connectionString": "FileUpload",
    "container": "fileupload",
    "sasTtl": "PT1H"
  },
  "jobs": {
    "value": []
  }
}

アプリケーションでファイルアップロードが使用されている場合、スクリプトによって、connectionString プロパティで示されている値を使用して、開発 Key Vault 内にシークレットが作成されます。運用ストレージアカウントの接続文字列を含む同じ名前のシークレットを、運用 Key Vault 内に作成します。次に例を示します。
```
az keyvault secret set --name FileUpload --vault-name {your production key vault name} --value '{your production storage account connection string}'
```
アプリケーションでデータエクスポートの宛先にマネージド ID を使用している場合、ユーザーが管理するシークレットはありません。ただし、運用 IoT Central アプリケーションに対してシステム割り当てマネージド ID を有効にし、宛先に書き込むのに必要なアクセス許可を付与する必要があります。
アプリケーションでデータエクスポートの宛先に接続文字列が使用されている場合は、宛先のシークレットを運用キーコンテナーに追加します。構成ファイルには宛先の実際のシークレットは含まれず、シークレットは Key Vault に格納されます。

Key Vault 内のシークレットの名前を持つシークレットを構成ファイル内で更新します。

変換先の型	変更するプロパティ
Service Bus キュー	connectionString
Service Bus トピック	connectionString
Azure Data Explorer	clientSecret
Azure Blob Storage	connectionString
Event Hubs	connectionString
Webhook No Auth	該当なし

次に例を示します。

"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
```

パイプラインを作成する

Web ブラウザーで https://dev.azure.com/{your DevOps organization} に移動して、Azure DevOps 組織を開きます
[新しいプロジェクト] を選択して新しいプロジェクトを作成します。
プロジェクトに名前を付け、必要に応じて説明を入力し、[作成] を選択します。
[プロジェクトへようこそ] ページで、[パイプライン] を選択し、次に [パイプラインを作成] を選択します。
コードの場所として [GitHub] を選択します。
[Authorize AzurePipelines] (Azure Pipelines を承認する) を選択して、Azure Pipelines が GitHub アカウントにアクセスすることを承認します。
[リポジトリの選択] ページで、IoT Central CI/CD GitHub リポジトリのフォークを選択します。
GitHub にログインし、Azure Pipelines がリポジトリにアクセスするためのアクセス許可を指定するように求められたら、[承認してインストール] を選択します。
[パイプラインの構成] ページで、[スタートパイプライン] を選択して作業を開始します。 azure-pipelines.yml が編集のために表示されます。

変数グループを作成する

Key Vault シークレットをパイプラインに統合する簡単な方法は、変数グループを使用することです。変数グループを使用して、デプロイスクリプトで適切なシークレットを使用できるようにします。変数グループを作成するには:

左側のメニューの [パイプライン] セクションで [ライブラリ] を選択します。
[+ Variable group] を選択します。
変数グループの名前として「keyvault」と入力します。
トグルを有効にして、Azure Key Vault 内のシークレットをリンクします。
Azure サブスクリプションを選択して承認します。次に、運用 Key Vault 名を選択します。
[追加] を選択して、グループへの変数の追加を開始します。
次のシークレットを追加します。
- 運用アプリの IoT Central API キー。このシークレットには、作成時に API-Token という名前を付けました。
- 前に作成したサービスプリンシパルのパスワード。このシークレットには、作成時に SP-Password という名前を付けました。
[OK] を選択します。
[保存] を選択して変数グループを保存します。

パイプラインを構成する

次に、IoT Central アプリケーションに構成の変更をプッシュするようにパイプラインを構成します。

左側のメニューの [パイプライン] セクションで [パイプライン] を選択します。

パイプライン YAML の内容を次の YAML に置き換えます。この構成は、運用 Key Vault に次のものが含まれていることを前提としています。

API-Token という名前のシークレット内の運用 IoT Central アプリの API トークン。
SP-Password という名前のシークレット内のサービスプリンシパルパスワード。

-AppName と -KeyVault の値を、運用インスタンスの適切な値に置き換えます。

サービスプリンシパルを作成したときに -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 リポジトリに保存されるため、コミットメッセージを指定し、[保存および実行] をもう一度選択する必要があります。

パイプラインがキューに入れられます。実行されるまでに数分かかる場合があります。

パイプラインを初めて実行するとき、パイプラインがサブスクリプションにアクセスするためのアクセス許可、および Key Vault にアクセスするためのアクセス許可を指定するように求められます。 [許可] を選択し、リソースごとにもう一度 [許可] を選択します。

パイプラインジョブが正常に完了したら、運用 IoT Central アプリケーションにサインインし、構成が想定どおりに適用されたことを確認します。

開発から運用に変更をプロモートする

これで機能するパイプラインを用意できたので、構成の変更を使用して IoT Central インスタンスを直接管理できます。 Device Models フォルダーに新しいデバイステンプレートをアップロードし、構成ファイルを直接変更できます。この方法により、IoT Central アプリケーションの構成を他のコードと同じように扱うことができます。

次のステップ

IoT Central の構成を CI/CD パイプラインに統合する方法について学習したので、次のステップとして、IoT Central アプリケーションを管理および監視する方法について学習することをお勧めします。

次の方法で共有

IoT Central を Azure Pipelines に統合して、継続的インテグレーションと継続的デリバリーを実現する

前提条件

サンプルコードのダウンロード

サービスプリンシパルの作成

IoT Central API トークンを生成する

構成ファイルを生成する

構成ファイルを変更します

パイプラインを作成する

変数グループを作成する

パイプラインを構成する

開発から運用に変更をプロモートする

次のステップ

フィードバック

その他のリソース

次の方法で共有

IoT Central を Azure Pipelines に統合して、継続的インテグレーションと継続的デリバリーを実現する

前提条件

サンプル コードのダウンロード

サービス プリンシパルの作成

IoT Central API トークンを生成する

構成ファイルを生成する

構成ファイルを変更します

パイプラインを作成する

変数グループを作成する

パイプラインを構成する

開発から運用に変更をプロモートする

次のステップ

フィードバック

その他のリソース

サンプルコードのダウンロード

サービスプリンシパルの作成