次の方法で共有

Azure Kubernetes Service (AKS) で Service Connector を使用する

  • [アーティクル]

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

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

前提条件

AKS クラスターに対して Service Connector によって実行される操作

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

Service Connector の Kubernetes 拡張機能の追加

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

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

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

Kubernetes リソースの作成

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

Azure portal での各サービス接続に対して Service Connector によって作成された Kubernetes リソースは、Kubernetes リソースの [Service Connector] メニューで確認できます。

Azure portal のスクリーンショット。Service Connector によって作成された 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 への接続をセットアップします。

Service Connector によって作成された Kubernetes リソースを使用する

ターゲット サービスの種類と認証の種類に応じて、さまざまな Kubernetes リソースが Service Connector によって作成されます。 以降のセクションでは、Service Connector によって作成された 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 に接続する方法を学習します。

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

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

Service Connector の Kubernetes 拡張機能を確認する

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

  1. k8s-extension Azure CLI 拡張機能をインストールします。

    az extension add --name k8s-extension

  2. Service Connector 拡張機能の状態を取得します。 コマンド出力の 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. Service Connector 拡張情報は、Helm チャートを使用して、sc-system 名前空間にインストールされます。 次のコマンドを使用して、名前空間と Helm リリースを確認します。

    • 名前空間が存在することを確認します。

      kubectl get ns

    • Helm リリースの状態を確認します。

      helm list -n sc-system

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

    • ジョブが存在することを確認します。

      kubectl get job -n sc-system

    • ジョブの状態を取得します。

      kubectl describe job/sc-job -n sc-system

    • ジョブ ログを表示します。

      kubectl logs job/sc-job -n sc-system

一般的なエラーと軽減策

拡張機能の作成エラー

エラー メッセージ:

Unable to get a response from the agent in time.

対応策:

「拡張機能の作成エラー」を参照してください

Helm エラー

エラー メッセージ:

  • Timed out waiting for resource readiness
  • Unable to download the Helm chart from the repo URL
  • Helm chart rendering failed with given values
  • Resource already exists in your cluster
  • Operation is already in progress for Helm

対応策:

「Helm エラー」を参照してください

競合

エラー メッセージ:

Operation returned an invalid status code: Conflict.

理由:

このエラーは通常、Azure Kubernetes Service (AKS) クラスターが更新中の状態のときにサービス接続を作成しようとすると発生します。 サービス接続の更新が、進行中の更新と競合しています。 また、このエラーは、サブスクリプションが Microsoft.KubernetesConfiguration リソース プロバイダーに登録されていない場合にも発生します。

対応策:

  1. クラスターが "成功" 状態であることを確認して、作成を再試行してください。

  2. サブスクリプションが Microsoft.KubernetesConfiguration リソース プロバイダーに登録されていることを確認するには、次のコマンドを実行します。

    az provider register -n Microsoft.KubernetesConfiguration

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

エラー メッセージ:

You do not have permission to perform ... If access was recently granted, please refresh your credentials.

理由:

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

対応策:

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

サブスクリプション未登録

エラー メッセージ:

The subscription is not registered to use namespace 'Microsoft.KubernetesConfiguration'

理由:

Service Connector では、Azure Arc 対応 Kubernetes クラスター拡張機能用のリソース プロバイダーである Microsoft.KubernetesConfiguration にサブスクリプションを登録する必要があります。

対応策:

次のコマンドを実行して、Microsoft.KubernetesConfiguration リソース プロバイダーを登録します。 リソース プロバイダーの登録エラーに関する詳細については、「リソース プロバイダーの登録エラーの解決」を参照してください。

az provider register -n Microsoft.KubernetesConfiguration

次のステップ

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

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