Azure IoT Operations のトラブルシューティング

2025-05-07

この記事には、Azure IoT Operations に関するトラブルシューティングのヒントが記載されています。

トラブルシューティングガイダンスは、次の方法で Azure IoT Operations をデプロイ、構成、または実行するときに発生する可能性がある問題を診断して解決するのに役立ちます。

クラスターで実行されている Azure IoT Operations サービスと Azure IoT Operations コンポーネントから診断情報を収集する。
セキュリティアクセス許可の不足、シークレットの不足、正しくない構成設定など、一般的な問題に対する解決策を提供します。

既知の問題と一時的な回避策については、「既知の問題: Azure IoT 操作」を参照してください。

Azure IoT Operations のデプロイのトラブルシューティング

一般的なデプロイと構成のトラブルシューティングでは、Azure CLI IoT Operations check コマンドと support コマンドを使用できます。

Azure CLI バージョン 2.53.0 以降が必要であり、Azure IoT Operations 拡張機能がインストールされている必要があります。

正常性、構成、および使いやすさについて Azure IoT Operations サービスのデプロイを評価するには、 az iot ops check を使用します。 check コマンドは、デプロイと構成の問題を見つけるのに役立ちます。
問題の診断に役立つログとトレースを収集するには、 az iot ops support create-bundle を使用します。 support create-bundle コマンドは、Microsoft サポートに対して確認または提供できる標準サポートバンドル zip アーカイブを作成します。

UnauthorizedNamespaceError エラーメッセージが表示される

次のエラーメッセージが表示された場合は、必要な Azure-arc カスタム場所機能を有効にしなかったか、カスタムの場所 RP OID が正しくないカスタムの場所機能を有効にしました。

Message: Microsoft.ExtendedLocation resource provider does not have the required permissions to create a namespace on the cluster.

この問題を解決するには、このガイダンスに従って、適切な OID でカスタムの場所機能を有効にします。

MissingResourceVersionOnHost エラーメッセージが表示される

このエラーメッセージは、デプロイに関連付けられているカスタムの場所リソースが正しく構成されていないことを示します。カスタムの場所で、クラスターに投影しようとしているリソースの API バージョンが間違っています。

Message: The resource {resource Id} extended location {custom location resource Id} does not support the resource type {IoT Operations resource type} or api version {IoT Operations ARM API}. Please check with the owner of the extended location to ensure the host has the CRD {custom resource name} with group {api group name}.iotoperations.azure.com, plural {custom resource plural name}, and versions [{api group version}] installed.

解決するには、カスタムの場所を含む、以前のデプロイに関連付けられているプロビジョニング済みリソースをすべて削除します。 az iot ops deleteまたは代替メカニズムを使用できます。キャッシュの問題の可能性があるため、削除後数分待ってから AIO を再デプロイするか、 az iot ops create --custom-location を使用してカスタムの場所名を選択することをお勧めします。

LinkedAuthorizationFailed エラーメッセージが表示される

デプロイが "code":"LinkedAuthorizationFailed" エラーで失敗した場合、クラスターを含むリソースグループに必要なアクセス許可がないことを示すメッセージが表示されます。

次のメッセージは、ログインプリンシパルに、リソース同期リソース ID で指定されたリソースグループにリソースをデプロイするために必要なアクセス許可がないことを示しています。

Message: The client {principal Id} with object id {principal object Id} has permission to perform action Microsoft.ExtendedLocation/customLocations/resourceSyncRules/write on scope {resource sync resource Id}; however, it does not have permission to perform action(s) Microsoft.Authorization/roleAssignments/write on the linked scope(s) {resource sync resource group} (respectively) or the linked scope(s) are invalid.

リソース同期規則をデプロイするには、ログインプリンシパルに、リソースがデプロイされているリソースグループに対する Microsoft.Authorization/roleAssignments/write アクセス許可が必要です。エッジからクラウドへのリソースハイドレートによってターゲットリソースグループに新しいリソースが作成されるため、このセキュリティ制約が必要です。

この問題を解決するには、プリンシパルのアクセス許可を昇格するか、リソース同期規則をデプロイしないでください。現在の AIO CLI には、 --enable-rsync フラグを使用してリソース同期規則をデプロイするためのオプトインメカニズムがあります。デプロイされているリソース同期規則を停止するには、フラグを省略します。

注

従来の AIO CLI には、 --disable-rsync-rulesを使用したオプトアウトメカニズムがありました。

MQTT ブローカーのデプロイが失敗する

クラスターに、指定された MQTT ブローカーのカーディナリティとメモリプロファイルに十分なリソースがない場合、デプロイが失敗する可能性があります。この状況を解決するには、レプリカ数、ワーカー、シャーディング、メモリプロファイルの設定をクラスターの適切な値に調整します。

警告

レプリカ数を 1 に設定すると、ノード障害シナリオでデータが失われる可能性があります。

ヒント

シャーディング、ワーカー、またはメモリプロファイルの値を小さく設定すると、メッセージの負荷を処理するブローカーの容量が減ります。運用環境にデプロイする前に、MQTT ブローカー構成を使用してシナリオをテストし、ブローカーが予想される最大負荷を処理できることを確認します。

これらのパラメーターに適した値を選択する方法の詳細については、「高可用性、スケーリング、およびメモリ使用量のためのブローカー設定の構成」を参照してください。

既存のインスタンスでリソース同期規則を有効にする

現時点では、 az iot ops コマンドを使用して、既存のインスタンスでリソース同期規則を有効にすることはできません。この制限を回避するには、次のように az rest コマンドを使用します。

デバイスレジストリルールを作成するには:

次の内容を 含むrsr_device_registry.json という名前のファイルを作成します。 <placeholder>の値を実際の値に置き換えます。

{
    "location": "<custom location region>",
    "properties": {
        "targetResourceGroup": "/subscriptions/<subscription Id>/resourceGroups/<resource group name>",
        "priority": 200,
        "selector": {
            "matchLabels": {
                "management.azure.com/provider-name": "Microsoft.DeviceRegistry"
            }
        }
    }
}

次のコマンドを実行して、デバイスレジストリリソース同期規則を作成します。 <placeholder>の値を実際の値に置き換えます。

az rest --url /subscriptions/<subscription Id>/resourceGroups/<resource group name>/providers/Microsoft.ExtendedLocation/customLocations/<custom location name>/resourceSyncRules/<rule name>?api-version=2021-08-31-preview --method PUT --body "@rsr_device_registry.json"

インスタンスルールを作成するには:

次の内容を 含むrsr_instance.json という名前のファイルを作成します。 <placeholder>の値を独自の値に置き換えます。

{
    "location": "<custom location region>",
    "properties": {
        "targetResourceGroup": "/subscriptions/<subscription Id>/resourceGroups/<resource group name>",
        "priority": 400,
        "selector": {
            "matchLabels": {
                "management.azure.com/provider-name": "microsoft.iotoperations"
            }
        }
    }
}

次のコマンドを実行して、インスタンスリソース同期規則を作成します。 <placeholder>の値を独自の値に置き換えます。

az rest --url /subscriptions/<subscription Id>/resourceGroups/<resource group name>/providers/Microsoft.ExtendedLocation/customLocations/<custom location name>/resourceSyncRules/<rule name>?api-version=2021-08-31-preview --method PUT --body "@rsr_instance.json"

Azure Key Vault シークレット管理のトラブルシューティング

シークレット管理に関連する次のエラーメッセージが表示される場合は、Azure Key Vault の内容を更新します。

rpc error: code = Unknown desc = failed to mount objects, error: failed to get objectType:secret,
objectName:nbc-eventhub-secret, objectVersion:: GET https://aio-kv-888f27b078.vault.azure.net/secrets/nbc-eventhub-secret/--------------------------------------------------------------------------------
RESPONSE 404: 404 Not FoundERROR CODE: SecretNotFound--------------------------------------------------------------------------------{ "error": { "code": "SecretNotFound", "message": "A secret with (name/id) nbc-eventhub-secret was not found in this key vault.
If you recently deleted this secret you may be able to recover it using the correct recovery command.
For help resolving this issue, please see https://go.microsoft.com/fwlink/?linkid=2125182" }

このエラーは、Azure IoT Operations が、Azure Key Vault から存在しないシークレットを同期しようとしたときに発生します。この問題を解決するには、シークレットプロバイダークラスなどのリソースを作成する前に、Azure Key Vault にシークレットを追加します。

OPC UA サーバー接続のトラブルシューティング

コネクタがセキュリティのないエンドポイントのみを公開するサーバーに接続しようとすると、OPC UA サーバー接続が BadSecurityModeRejected エラーで失敗します。この問題を解決するには、次の 2 とおりの方法があります。

資産エンドポイントプロファイルの追加構成で次の値を明示的に設定して、制限を無効にします。

プロパティ価値

securityMode none

securityPolicy http://opcfoundation.org/UA/SecurityPolicy#None
接続を確立するには、OPC UA サーバーにセキュリティで保護されたエンドポイントを追加し、証明書の相互信頼を設定します。

プロパティ	価値
`securityMode`	`none`
`securityPolicy`	`http://opcfoundation.org/UA/SecurityPolicy#None`

OPC PLC シミュレーターのトラブルシューティング

OPC PLC シミュレーターは、その資産エンドポイントを作成した後、MQTT ブローカーにデータを送信しません

この問題を回避するには、次のコマンドを実行して、資産エンドポイントの autoAcceptUntrustedServerCertificates=true を設定します。

ENDPOINT_NAME=<name-of-you-endpoint-here>
kubectl patch AssetEndpointProfile $ENDPOINT_NAME \
-n azure-iot-operations \
--type=merge \
-p '{"spec":{"additionalConfiguration":"{\"applicationName\":\"'"$ENDPOINT_NAME"'\",\"security\":{\"autoAcceptUntrustedServerCertificates\":true}}"}}'

注意事項

運用環境または運用前環境では、この構成を使わないでください。適切な認証なしでクラスターをインターネットに公開すると、未承認アクセスや DDOS 攻撃につながる可能性があります。

次のコマンドを使用して、すべての資産エンドポイントにパッチを適用することができます。

ENDPOINTS=$(kubectl get AssetEndpointProfile -n azure-iot-operations --no-headers -o custom-columns=":metadata.name")
for ENDPOINT_NAME in `echo "$ENDPOINTS"`; do \
kubectl patch AssetEndpointProfile $ENDPOINT_NAME \
   -n azure-iot-operations \
   --type=merge \
   -p '{"spec":{"additionalConfiguration":"{\"applicationName\":\"'"$ENDPOINT_NAME"'\",\"security\":{\"autoAcceptUntrustedServerCertificates\":true}}"}}'; \
done

Azure IoT Layered Network Management のトラブルシューティング (プレビュー)

このセクションのトラブルシューティングガイダンスは、Layered Network Management コンポーネントを使用する場合の Azure IoT Operations に固有のものです。詳細については、「Azure IoT Operations は階層化されたネットワークでどのように機能しますか?」を参照してください。

親レベルで階層ネットワーク管理をインストールすることはできません

階層ネットワーク管理オペレーターのインストールが失敗した場合、またはレイヤードネットワーク管理インスタンスのカスタムリソースを適用できない場合は、次のようにします。

リージョンがサポートされていることを確認します。詳細については、「サポートされているリージョン」を参照してください。
Layered Network Management の Arc 拡張機能のインストールに他のエラーがある場合は、エラーに含まれるガイダンスに従ってください。拡張機能をアンインストールしてインストールしてみてください。
Layered Network Management オペレーターが実行中で準備完了状態であることを確認します。
カスタムリソース kubectl apply -f cr.yaml の適用が失敗した場合、このコマンドの出力にエラーの原因が一覧表示されます。たとえば、CRD のバージョンが一致しない、または CRD のエントリが間違っているなどです。

親レベルのレイヤードネットワーク管理を使用してクラスターを Arc 対応にすることはできません

同じコンピューターでクラスターを繰り返し削除してオンボードすると、入れ子になったレイヤーでクラスターを Arc 対応にするときにエラーが発生する可能性があります。次に例を示します。

Error: We found an issue with outbound network connectivity from the cluster to the endpoints required for onboarding.
Please ensure to meet the following network requirements 'https://docs.microsoft.com/en-us/azure/azure-arc/kubernetes/quickstart-connect-cluster?tabs=azure-cli#meet-network-requirements'
If your cluster is behind an outbound proxy server, please ensure that you have passed proxy parameters during the onboarding of your cluster.

次のコマンドを実行します。

sudo systemctl restart systemd-networkd

ホストマシンを再起動します。

それでもエラーが表示される場合は、次の項目を確認してください。

--debug コマンドの実行時に connectedk8s パラメーターを追加します。
ネットワークパケットトレースをキャプチャして調査します。詳細については、「パケットトレースへのレイヤードネットワーク管理のキャプチャ」を参照してください。

分離クラスターに Azure IoT 操作をインストールすることはできません

入れ子になったレイヤーに Azure IoT Operations コンポーネントをインストールすることはできません。たとえば、レベル 4 の Layered Network Management が実行中の時、レベル 3 では Azure IoT Operations をインストールできないということです。

親レベルで実行されている Layered Network Managment サービスにアクセスできるノードを確認します。たとえば、ノードから実行 ping <IP-ADDRESS-L4-LNM> します。
次のコマンドを使用して、親レベルで実行されている Layered Network Management サービスに DNS クエリが解決されていることを確認します:
```
nslookup management.azure.com
```
DNS は、Layered Network Management サービスの IP アドレスで応答する必要があります。
ドメインが正しく解決されている場合は、ドメインが許可リストに追加されていることを確認します。詳細については、「子レベルの階層ネットワーク管理から Azure IoT Operations サービスに接続できない」を参照してください。
ネットワークパケットトレースをキャプチャして調査します。詳細については、「パケットトレースへのレイヤードネットワーク管理のキャプチャ」を参照してください。

分離されたクラスターに Azure IoT 操作をインストールできますが、ポッドの起動に失敗する

Azure IoT Operations コンポーネントをクラスターにインストールすると、インストールが開始され、続行されます。ただし、1 つまたは少数のコンポーネント (ポッド) の初期化は失敗します。

失敗したポッドを特定する

kubectl get pods -n azure-iot-operations

ポッドの詳細を取得する:

kubectl describe pod [POD NAME] -n azure-iot-operations

コンテナーイメージの関連情報を確認します。イメージのダウンロードが失敗した場合は、ダウンロードパスのドメイン名が許可リストにあるかどうかを確認します。次に例を示します。
```
Warning  Failed  3m14s  kubelet  Failed to pull image "…
```

子レベルの階層ネットワーク管理から Azure IoT Operations サービスに接続することはできません

Layered Network Management は、宛先ドメインが許可リストにない場合、トラフィックをブロックします。子レベルは、許可リスト内のドメインの一覧にアクセスできます。ドメインが含まれているかどうかを確認するには、レイヤードネットワーク管理の許可リストを確認します。ドメインが許可リストにない場合は、許可リストに追加できます。

次のコマンドを実行して、構成マップを一覧表示します。
```
kubectl get cm -n azure-iot-operations
```

出力は次の例のようになります。

NAME                           DATA   AGE
aio-lnm-level4-config          1      50s
aio-lnm-level4-client-config   1      50s

xxx-client-config に許可リストが含まれています。実行:
```
kubectl get cm aio-lnm-level4-client-config -o yaml
```
許可されているすべてのドメインが出力に一覧表示されます。

レイヤードネットワーク管理をパケットトレースにキャプチャする

場合によっては、親レベルの Layered Network Management インスタンスが特定のエンドポイントにネットワークトラフィックを転送していない可能性があります。必要なエンドポイントへの接続により、ノードで実行されているサービスに問題が発生しています。有効にしたサービスが、更新後に新しいエンドポイントに接続しようとしている可能性があります。または、既定の許可リストにないエンドポイントへの接続を必要とする新しい Arc 拡張機能またはサービスをインストールしようとしています。通常、接続エラーを通知するエラーメッセージに情報があるはずです。ただし、不足しているエンドポイントに関する明確な情報がない場合は、詳細なデバッグのために子ノード上のネットワークトラフィックをキャプチャできます。

Windows ホスト
Linux ホスト

Wireshark ネットワークトラフィックアナライザーをホストにインストールします。
Wireshark を実行し、キャプチャを開始します。
インストールまたは接続の失敗を再現します。
キャプチャを停止します。

キャプチャを開始するには、次のコマンドを実行します。
```
sudo tcpdump -W 5 -C 10 -i any -w AIO-deploy -Z root
```
インストールまたは接続の失敗を再現します。
キャプチャを停止します。

Wireshark を使用してトレースファイルを開きます。接続エラーまたは応答しない接続を探します。

ip.addr == [IP address] パラメーターを使用してパケットをフィルター処理します。カスタム DNS サービスアドレスの IP アドレスを入力します。
DNS クエリと応答を確認して、レイヤードネットワーク管理の許可リストにないドメイン名があるかどうかを確認します。

操作エクスペリエンス Web UI へのアクセスのトラブルシューティング

Operations エクスペリエンス Web UI にサインインするには、Kubernetes - Azure Arc インスタンスを含むリソースグループに対する共同作成者以上のアクセス許可を持つ Microsoft Entra ID アカウントが必要です。

次のいずれかのエラーメッセージが表示された場合:

割り当てられていないインスタンスの取得中に問題が発生しました
メッセージ: 要求は認可されていません
コード: PermissionDenied

Microsoft Entra ID アカウントが、Operations エクスペリエンスアクセスの「前提条件」セクションの要件を満たしていることを確認します。

データフローのトラブルシューティング

"グローバルエラー: AllBrokersDown" というエラーメッセージが表示される

データフローログに Global error: AllBrokersDown エラーメッセージが表示される場合は、データフローが約 4 分または 5 分間メッセージを処理していないことを意味します。データフローソースが正しく構成され、メッセージが送信されていることを確認します。たとえば、MQTT ブローカーの正しいトピック名を使用していることを確認します。

次の方法で共有