次の方法で共有

Azure Kubernetes Service (AKS) でサービス コネクタを使用する方法

  • [アーティクル]

Azure Kubernetes Service (AKS) は、サービス コネクタでサポートされているコンピューティング サービスの 1 つです。 この記事は、次の理解に役立つことを目的にしています。

  • サービス接続の作成時にクラスターで行われる操作。
  • サービス コネクタが作成する Kubernetes リソースを使用する方法。
  • AKS クラスター内のサービス コネクタのログをトラブルシューティングして表示する方法。

前提条件

サービス コネクタがクラスターで行う操作

サービス コネクタは、サービス接続の作成時に選択されたさまざまなターゲット サービスと認証の種類に応じて、AKS クラスターに対して異なる操作を行います。 サービス コネクタで行われる可能性がある操作の一覧を次に示します。

サービス コネクタの Kubernetes 拡張機能を追加する

サービス接続が初めて作成されるときに、sc-extension という名前の Kubernetes 拡張機能がクラスターに追加されます。 後で、サービス接続要求がサービス コネクタに送信されるたびに、この拡張機能がユーザーのクラスターに Kubernetes リソースを作成するのに役立ちます。 AKS クラスターの拡張機能は、Azure portal の [拡張機能とアプリケーション] メニューで確認できます。

Azure portal のスクリーンショット。AKS 拡張機能を表示しています。

拡張機能は、クラスター接続メタデータが格納される場所でもあります。 拡張機能をアンインストールすると、クラスター内のすべての接続が使用できなくなります。 拡張演算子は、クラスター名前空間 sc-system でホストされます。

Kubernetes リソースを作成する

サービス コネクタは、サービス接続の作成時にユーザーが指定した名前空間に Kubernetes リソースをいくつか作成します。 Kubernetes リソースには接続情報が格納されます。これは、ユーザーのワークロード定義またはアプリケーション コードがターゲット サービスと通信するために必要です。 認証の種類に応じて、異なる Kubernetes リソースが作成されます。 Connection String と Service Principal の認証の種類には、Kubernetes シークレットが作成されます。 Workload Identity の認証の種類には、Kubernetes シークレットに加えて Kubernetes サービス アカウントも作成されます。

サービス コネクタが各サービス接続に対して作成した Kubernetes リソースは、Azure portal の Kubernetes リソースの [サービス コネクタ] メニューで確認できます。

Azure portal のスクリーンショット。サービス コネクタによって作成された Kubernetes リソースを表示しています。

サービス接続を削除しても、関連付けられている Kubernetes リソースは削除されません。 必要に応じて、kubectl delete コマンドなどを使用して、リソースを手動で削除してください。

azureKeyvaultSecretsProvider アドオンを有効にする

ターゲット サービスが Azure Key Vault であり、かつサービス接続の作成時にシークレット ストア CSI ドライバーが有効になっている場合、サービス コネクタはクラスターに対して azureKeyvaultSecretsProvider アドオンを有効にします。

Azure portal のスクリーンショット。接続の作成時に Key Vault に対して CSI ドライバーを有効にしています。

CSI ドライバーを使用して Azure Key Vault に接続するチュートリアルに従って、シークレット ストア CSI ドライバーを使用して Azure Key Vault への接続をセットアップします。

ワークロード ID と OpenID Connect (OIDC) 発行者を有効にする

サービス接続の作成時に認証の種類が Workload Identity である場合、サービス コネクタはクラスターのワークロード ID と OIDC 発行者を有効にします。

Azure portal のスクリーンショット。ワークロード ID を使用して接続を作成しています。

認証の種類が Workload Identity のとき、フェデレーション ID 資格情報を作成するには、ユーザー割り当てマネージド ID が必要です。 「ワークロード ID」で詳細を参照するか、チュートリアルに従って、ワークロード ID を使用して Azure Storage への接続をセットアップします。

サービス コネクタが作成した Kubernetes リソースを使用する方法

ターゲット サービスの種類や認証の種類が異なるときは、異なる Kubernetes リソースが作成されます。 以降のセクションでは、サービス コネクタが作成した Kubernetes リソースをクラスター ワークロード定義とアプリケーション コードで使用する方法について説明します。

Kubernetes シークレット

認証の種類が Connection String または Service Principal のときは、Kubernetes シークレットが作成されます。 クラスター ワークロード定義は、シークレットを直接参照できます。 例を次のスニペットに示します。

apiVersion: batch/v1
kind: Job
metadata:
  namespace: default
  name: sc-sample-job
spec:
  template:
    spec:
      containers:
      - name: raw-linux
        image: alpine
        command: ['printenv']
        envFrom:
          - secretRef:
              name: <SecretCreatedByServiceConnector>
      restartPolicy: OnFailure

これで、アプリケーション コードが、環境変数のシークレット内の接続文字列を使用できます。 サンプル コードを参照して、環境変数の名前と、それらをアプリケーション コードで使用してさまざまなターゲット サービスに対して認証する方法の詳細を確認できます。

Kubernetes サービス アカウント

認証の種類が Workload Identity のときは、Kubernetes サービス アカウントとシークレットの両方が作成されます。 クラスター ワークロード定義は、サービス アカウントとシークレットを参照して、ワークロード ID を使用して認証できます。 例を次のスニペットに示します。

apiVersion: batch/v1
kind: Job
metadata:
  namespace: default
  name: sc-sample-job
  labels:
    azure.workload.identity/use: "true"
spec:
  template:
    spec:
      serviceAccountName: <ServiceAccountCreatedByServiceConnector>
      containers:
      - name: raw-linux
        image: alpine
        command: ['printenv']
        envFrom:
          - secretRef:
              name: <SecretCreatedByServiceConnector>
      restartPolicy: OnFailure

チュートリアルで、ワークロード ID を使用して Azure Storage に接続する方法を学習できます。

トラブルシューティングとログの表示の方法

サービス接続の作成時にエラーが発生し、再試行しても軽減できなかった場合は、次の方法を使用してトラブルシューティングのための詳細情報を収集できます。

サービス コネクタの Kubernetes 拡張機能を調べる

サービス コネクタの Kubernetes 拡張機能は、Azure Arc 対応 Kubernetes クラスター拡張機能上に構築されています。 次のコマンドを使用して、拡張機能のインストールまたは更新中にエラーが発生したかどうかを調べます。

  1. k8s-extension Azure CLI 拡張機能をインストールします。
az extension add --name k8s-extension
  1. サービス コネクタ拡張機能の状態を取得します。 コマンド出力の statuses プロパティを調べて、エラーがあるかどうかを確認します。
az k8s-extension show \
    --resource-group MyClusterResourceGroup \
    --cluster-name MyCluster \
    --cluster-type managedClusters \
    --name sc-extension

Kubernetes クラスター ログを調べる

拡張機能のインストール中にエラーが発生し、かつ statuses プロパティのエラー メッセージが発生内容についての十分な情報を提供しない場合は、次の手順で Kubernetes ログをさらに調べることができます。

  1. AKS クラスターに接続します。

    az aks get-credentials \
    --resource-group MyClusterResourceGroup \
    --name MyCluster

  2. サービス コネクタ拡張機能は、Helm チャートを使用して名前空間 sc-system にインストールされているため、次のコマンドを使用して名前空間と Helm リリースを調べます。

    • 名前空間が存在することを確認します。
    kubectl get ns
    • Helm リリースの状態を確認します。
    helm list -n sc-system

  3. 拡張機能のインストールまたは更新中に、sc-job という Kubernetes ジョブが、サービス接続用の Kubernetes リソースを作成します。 通常、ジョブの実行が失敗すると拡張機能が失敗します。 次のコマンドを実行して、ジョブの状態を確認します。 sc-system 名前空間に sc-job が存在しない場合は、正常に実行されているはずです。 このジョブは、正常に実行された後に自動的に削除されるように設計されています。

    • ジョブが存在することを確認します。
    kubectl get job -n sc-system
    • ジョブの状態を取得します。
    kubectl describe job/sc-job -n sc-system
    • ジョブ ログを表示します。
    kubectl logs job/sc-job -n sc-system

一般的なエラーと軽減策

Conflict

エラー メッセージ:Operation returned an invalid status code: Conflict.

理由: このエラーは、通常、AKS (Azure Kubernetes Service) クラスターが更新中の状態のときにサービス接続を作成しようとすると発生します。 サービス接続の更新が、進行中の更新と競合しています。

軽減策: 作成を再試行する前に、クラスターが "成功" 状態であることを確認してください。 これにより、競合に関連するほとんどのエラーが解決されます。

タイムアウト

エラー メッセージ:

  • Long running operation failed with status 'Failed'. Unable to get a response from the Agent in time
  • Timed out waiting for the resource to come to a ready/completed state

理由: このエラーは、リソース制限などの問題が原因で、サービス コネクタのクラスター拡張機能を作成または更新する際に使用する Kubernetes ジョブのスケジューリングに失敗した場合によく発生します。

軽減策: 「Kubernetes クラスター ログを調べる」を参照し、詳細な理由を確認して解決してください。 一般的な問題は、プリエンプションのためにノードが使用できないことです。 この場合は、ノードを追加するか、ノードの自動スケーリングを有効にすることを検討してください。

未承認のリソース アクセス

エラー メッセージ:You do not have permission to perform ... If access was recently granted, please refresh your credentials.

理由: サービス コネクタには、ユーザーに代わって接続操作を実行するために、接続先の Azure リソースを操作するためのアクセス許可が必要になります。 このエラーは、一部の Azure リソースに対する必要なアクセス許可がないことを示しています。

軽減策: このエラー メッセージに示されている Azure リソースに対するアクセス許可を確認してください。 必要なアクセス許可を取得して、作成を再試行してください。

その他の問題

上記の軽減策で問題が解決しない場合は、サービス コネクタのクラスター拡張機能を削除してリセットしてから、作成を再試行してください。 この方法により、サービス コネクタのクラスター拡張機能に関連するほとんどの問題が解決すると予想されます。

拡張機能をリセットするには、次の CLI コマンドを使用します。

az extension add --name k8s-extension

az k8s-extension delete \
    --resource-group <MyClusterResourceGroup> \
    --cluster-name <MyCluster> \
    --cluster-type managedClusters \
    --name sc-extension

次のステップ

さまざまなターゲット サービスを統合する方法を学習し、その構成設定と認証方法についてお読みください。

ストレージ BLOBを統合する方法について学習します