次の方法で共有

kubelogin を使用して Kubernetes クラスターに対する Azure マネージド ID の認証を有効にする

  • [アーティクル]

AKS マネージド Microsoft Entra 統合を使用すると、Microsoft Entra 統合プロセスが簡略化されます。 これまでは、ユーザーがクライアントとサーバー アプリを作成し、Microsoft Entra テナントでディレクトリ リーダー ロールのアクセス許可を付与する必要がありました。 現在、クライアントとサーバー アプリは AKS リソース プロバイダーによって管理されるようになりました。

クラスター管理者は、ユーザーの ID またはディレクトリ グループのメンバーシップに基づいて、Kubernetes のロールベースのアクセス制御 (Kubernetes RBAC) を構成できます。 Microsoft Entra 認証は、OpenID Connect によって AKS クラスターに提供されます。 OpenID Connect は、OAuth 2.0 プロトコル上に構築された ID レイヤーです。 OpenID Connect の詳細については、OpenID Connect のドキュメントを参照してください。

Microsoft Entra 統合フローの詳細については、Microsoft Entra のドキュメントを参照してください。

この記事では、AKS クラスターで Azure リソースのマネージド ID を有効にして使用する方法について詳しく説明します。

制限事項

AKS での Azure マネージド ID の認証の統合には、次のような制約があります。

  • いったん追加した統合を、無効にすることはできません。
  • 統合されたクラスターからレガシの Microsoft Entra ID クラスターへのダウングレードはサポートされていません。
  • Kubernetes RBAC がサポートされていないクラスターには統合を追加できません。

準備

マネージド ID 用の AKS アドオンを適切にインストールするには、次の要件を満たす必要があります。

  • Azure CLI バージョン 2.29.0 以降がインストールおよび構成されていること。 バージョンを確認するには、az --version を実行します。 インストールまたはアップグレードする必要がある場合は、Azure CLI のインストールに関するページを参照してください。
  • kubectl のバージョン 1.18.1 以降か、kubelogin が必要です。 Azure CLI と Azure PowerShell モジュールには、これら 2 つのコマンドが含まれており、自動的に管理されます。 つまり、これらは既定でアップグレードされ、az aks install-cli を実行する必要はなく、推奨されません。 自動パイプラインを使用している場合は、正しいバージョンまたは最新バージョンへのアップグレードを管理する必要があります。 Kubernetes と kubectl のマイナー バージョン間の差は、1 バージョン未満である必要があります。 そうしなければ、バージョンが正しくないために認証の問題が発生します。
  • helm を使用している場合は、最小バージョン helm 3.3 が必要です。
  • この構成では、クラスター用の Microsoft Entra グループが必要です。 このグループは、クラスターの管理アクセス許可を付与する、管理者グループとして登録されます。 既存の Microsoft Entra グループがない場合は、az ad group create コマンドを使って作成できます。

Note

バージョン 1.24 より新しい Kubernetes バージョンを使う Microsoft Entra 統合クラスターには、自動的に kubelogin 形式が使われます。 Kubernetes バージョン 1.24 以降では、Microsoft Entra ID クラスターの clusterUser 資格情報の既定形式は exec です。この場合、実行 PATH に kubelogin バイナリが必要です。 Microsoft Entra 以外のクラスター、または 1.24 より前のバージョンを実行している Microsoft Entra ID クラスターの動作に変更はありません。 既存のダウンロードされた kubeconfig は引き続き動作します。 既定の動作変更を上書きするために、clusterUser 資格情報を取得するときに、オプションのクエリ パラメーター形式が含まれます。 古い kubeconfig 形式を維持する必要がある場合は、明示的に形式を azure に指定できます。

AKS クラスターで統合を有効にする

新しいクラスターを作成する

  1. az group create コマンドを使用して、Azure リソース グループを作成します。

    az group create --name myResourceGroup --location centralus

  2. az aks create コマンドを使って AKS クラスターを作成し、Microsoft Entra グループの管理アクセスを有効にします。

    az aks create \
    --resource-group myResourceGroup \
    --name myManagedCluster \
    --enable-aad \
    --aad-admin-group-object-ids <id> [--aad-tenant-id <id>] \
    --generate-ssh-keys

    AKS マネージド Microsoft Entra ID クラスターが正常に作成されると、応答本文に次のセクションが含まれます。

    "AADProfile": {
    "adminGroupObjectIds": [
    "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
}

既存のクラスターを使用する

az aks update コマンドを使って、既存の Kubernetes RBAC 対応クラスターで AKS マネージド Microsoft Entra 統合を有効にします。 クラスターへのアクセスが維持されるように管理者グループを設定してください。

az aks update --resource-group MyResourceGroup --name myManagedCluster --enable-aad --aad-admin-group-object-ids <id-1>,<id-2> [--aad-tenant-id <id>]

AKS マネージド Microsoft Entra ID クラスターが正常にアクティブ化されると、応答本文に次のセクションが含まれます。

"AADProfile": {
    "adminGroupObjectIds": [
        "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
    }

レガシ クラスターを統合に追加する

クラスターでレガシの Microsoft Entra 統合を使用している場合、az aks update コマンドを使用して AKS マネージド Microsoft Entra 統合にアップグレードできます。

警告

Free レベルのクラスターでは、アップグレード中に API サーバーのダウンタイムが発生する場合があります。 営業時間外の時間帯にアップグレードすることをお勧めします。 アップグレード後、kubeconfig コンテンツが変更されます。 az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name> を実行して、新しい資格情報を kubeconfig ファイルにマージする必要があります。

az aks update --resource-group myResourceGroup --name myManagedCluster --enable-aad --aad-admin-group-object-ids <id> [--aad-tenant-id <id>]

AKS マネージド Microsoft Entra ID クラスターが正常に移行されると、応答本文に次のセクションが含まれます。

"AADProfile": {
    "adminGroupObjectIds": [
        "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
    }

有効化されたクラスターにアクセスする

  1. az aks get-credentials コマンドを使用して、クラスターにアクセスするためのユーザー資格情報を取得します。

    az aks get-credentials --resource-group myResourceGroup --name myManagedCluster

  2. 手順に従ってサインインします。

  3. Azure CLI を使用するように kubelogin を設定します。

    kubelogin convert-kubeconfig -l azurecli

  4. kubectl get nodes コマンドを使用してクラスター内のノードを表示します。

    kubectl get nodes

kubelogin を使用した非対話型サインイン

kubectl がサポートされない非対話型のシナリオがいくつかあります。 このような場合は、kubelogin を使用して、非対話型のサービス プリンシパル資格情報でクラスターに接続し、継続的インテグレーション パイプラインを実行します。

Note

バージョン 1.24 より新しい Kubernetes バージョンを使う Microsoft Entra 統合クラスターには、自動的に kubelogin 形式が使われます。 Kubernetes バージョン 1.24 以降では、Microsoft Entra ID クラスターの clusterUser 資格情報の既定形式は exec です。この場合、実行 PATH に kubelogin バイナリが必要です。 Microsoft Entra 以外のクラスター、または 1.24 より前のバージョンを実行している Microsoft Entra ID クラスターの動作に変更はありません。 既存のダウンロードされた kubeconfig は引き続き動作します。 既定の動作変更を上書きするために、clusterUser 資格情報を取得するときに、オプションのクエリ パラメーター形式が含まれます。 古い kubeconfig 形式を維持する必要がある場合は、明示的に形式を azure に指定できます。

  • clusterUser 資格情報を取得するときに、format クエリ パラメーターを使用して既定の動作を上書きできます。 値を azure に設定すると、元の kubeconfig 形式を使用できます。

    az aks get-credentials --format azure

  • Microsoft Entra 統合クラスターで Kubernetes バージョン 1.24 以前が使っている場合は、kubeconfig 形式を手動で変換する必要があります。

    export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig

Note

error: The Azure auth plugin has been removed. (エラー: Azure 認証プラグインが削除されました) というメッセージが表示された場合は、コマンドkubelogin convert-kubeconfig を実行して kubeconfig 形式を手動で変換する必要があります。

詳細については、「Azure Kubelogin の既知の問題」 を参照してください。

アクセスに関する問題のトラブルシューティング

重要

このセクションで説明する手順では、通常の Microsoft Entra グループ認証と対比される代替認証方法を示します。 このオプションは、緊急時にのみ使用してください。

有効な Microsoft Entra グループへの管理者アクセス権がない場合は、次の回避策のようにできます。 Azure Kubernetes Service クラスター管理者ロールのメンバーであるアカウントを使ってサインインし、グループまたはテナント管理者の資格情報に、クラスターへのアクセスを許可します。

次のステップ