Azure の kubelogin プラグインは、Microsoft Entra 認証を実装する client-go 資格情報プラグインです。 kubelogin プラグインには、kubectl コマンドライン ツールでは使用できない機能が用意されています。 詳細については、「kubelogin の概要」および「kubectl の概要」を参照してください。
この記事では、AKS で推奨されるサポートされているMicrosoft Entra認証方法に kubelogin を使用する方法の概要と例を示します。
AKS での Kubelogin 認証の制限事項
- Microsoft Entra で作成されたグループは、表示名ではなく ObjectID 値によってのみ含まれます。
sAMAccountNameコマンドは、オンプレミスの Windows Server Active Directory から同期されたグループに対してのみ使用できます。
- サービス プリンシパルの認証方法は、従来のMicrosoft Entra ID統合ではなく、マネージド Microsoft Entra ID統合でのみ機能します。
- サービス プリンシパルは、最大 200 個の Microsoft Entra グループ に所属できます。 200 個を超えるグループがある場合は、アプリケーション ロールの使用を検討してください。
- Microsoft Entra テナントに Microsoft Entra 条件付きアクセス ポリシーが設定されている場合、デバイス コード認証方法は機能しません。 そのシナリオでは、代わりに Web ブラウザーの対話型認証を使用します。
- Azure CLI 認証方法は、Microsoft Entra でのみ機能します。
AKS での kubelogin 認証のしくみ
Kubernetes バージョン 1.24 以降を実行している AKS クラスターでは、kubelogin exec プラグイン形式が自動的に使用されます。 1.24 より前のバージョンの Kubernetes を実行しているクラスターでは、この形式に手動で変換する必要があります。
kubelogin とのほとんどの操作では、 convert-kubeconfig サブコマンドを使用します。 サブコマンドは、 --kubeconfig または KUBECONFIG 環境変数で指定した kubeconfig ファイルを使用して、指定された認証方法に基づいて最終的な kubeconfig ファイルを exec 形式に変換します。
kubelogin が実装している認証方法は、Microsoft Entra OAuth 2.0 のトークン許可フローです。 キャッシュの動作は、認証方法によって異なります。 デバイス コード認証、Web ブラウザー対話型認証、およびリソース所有者パスワード資格情報 (ROPC) 認証では、認証レコードが kubelogin のキャッシュ ディレクトリにキャッシュされます。 Azure CLIや Azure Developer CLI などのメソッドでは、kubelogin キャッシュではなく、それぞれのコマンド ライン ツールによって管理されるキャッシュが使用されます。
デバイス コード認証
デバイス コードは、convert-kubeconfig サブコマンドの既定の認証方法です。 この認証方法では、ユーザーがブラウザー セッションからサインインする際に、デバイスコードの入力を求められます。
Note
kubelogin プラグインと exec プラグインが導入される前は、kubectl の Azure 認証方法ではデバイス コード フローのみがサポートされていました。 この方法では、audience クレームにspn: プレフィックスを含むトークンを生成する、以前のバージョンのライブラリが使用されていました。
Microsoft Entra は on-behalf-of (OBO) フローを使用しているため、互換性がありません。
convert-kubeconfig サブコマンドを実行すると、kubelogin によって audience クレームから spn: プレフィックスが削除されます。
デバイス コード認証のパラメーター
次の表は、デバイス コード認証で使用できるパラメーターの概要を示しています。
| パラメーター | Description |
|---|---|
-l devicecode (任意) |
kubelogin 認証方法を指定します。 デバイス コードが既定のメソッドであるため、このパラメーターは省略可能です。 |
--legacy |
レガシー Microsoft Entra ID 統合で構成されたクラスターでは、レガシー動作を使用します。 kubeconfig ファイルがこのようなクラスター用の場合、kubelogin は自動的に --legacy フラグを追加します。 |
--cache-dir |
トークン キャッシュ ディレクトリの既定のパス ( ${HOME}/.kube/cache/kubelogin) をオーバーライドします。 |
Azure CLI 認証
Azure CLI (コマンド: -l azurecli) 認証方法では、Azure CLI が確立したサインイン コンテキストを使用してアクセス トークンを取得します。 トークンは、az login と同じ Microsoft Entra テナントで発行されます。 kubelogin では、トークンは Azure CLI によって既に管理されているため、トークン キャッシュ ファイルに書き込まれません。
Azure CLI 認証のパラメーター
次の表は、Azure CLI 認証で使用できるパラメーターの概要を示しています。
| パラメーター | Description |
|---|---|
-l azurecli |
kubelogin 認証方法を指定します。 |
--azure-config-dir |
Azure CLI 構成ディレクトリを指定します。 既定のディレクトリは ${HOME}/.azure です。 |
Azure にサインインする
az login コマンドを使用してAzureにサインインします。
az login
Web ブラウザーの対話型認証
Web ブラウザーの対話型 (コマンド: -l interactive) 認証方法では、ユーザーをサインインする Web ブラウザーが自動的に開きます。 ユーザーが認証されると、ブラウザーは検証済みの資格情報を使用してローカル Web サーバーにリダイレクトします。 この認証方法は、条件付きアクセス ポリシーに準拠しています。
この認証方法では、ベアラー トークンまたは所有証明 (PoP) トークンを使用できます。
ベアラー トークン認証のパラメーター
次の表は、ベアラー トークン認証で使用できるパラメーターの概要を示しています。
| パラメーター | Description |
|---|---|
-l interactive |
kubelogin 認証方法を指定します。 |
--cache-dir |
トークン キャッシュ ディレクトリの既定のパス ( ${HOME}/.kube/cache/kubelogin) をオーバーライドします。 |
PoP トークン認証のパラメーター
次の表は、PoP トークン認証で使用できるパラメーターの概要を示しています。
| パラメーター | Description |
|---|---|
-l interactive |
kubelogin 認証方法を指定します。 |
--pop-enabled |
PoP トークン認証を有効にします。 |
--pop-claims |
PoP トークン要求をキーと値のペア形式で指定します。 たとえば、「 u=/ARM/ID/OF/CLUSTER 」のように入力します。 |
サービス プリンシパルの認証
サービス プリンシパル (コマンド: -l spn) 認証方法では、サービス プリンシパルを使用してユーザーをサインインします。 環境変数を設定するか、コマンドライン引数で資格情報を指定することで、資格情報を提供できます。 サポートされている資格情報は、パスワードまたは Personal Information Exchange (PFX) クライアント証明書です。
サービス プリンシパル認証のパラメーター
次の表は、サービス プリンシパル認証で使用できるパラメーターの概要を示しています。
| パラメーター | Description |
|---|---|
-l spn |
kubelogin 認証方法を指定します。 |
--client-id |
サービス プリンシパルのアプリケーション ID (クライアント ID)。 |
--client-secret |
サービス プリンシパルのクライアント シークレット。 |
マネージド ID の認証
Microsoft Entra 認証をサポートするリソースに接続するアプリケーションには、 マネージド ID (コマンド: -l msi) 認証方法を使用します。 たとえば、Azure仮想マシン (VM)、Virtual Machine Scale Sets、Azure Cloud ShellなどのAzure リソースへのアクセスなどです。
リソースに割り当てられている既定のマネージド ID または特定のユーザー割り当てマネージド ID を使用できます。
マネージド ID 認証のパラメーター
次の表は、マネージド ID 認証で使用できるパラメーターの概要を示しています。
| パラメーター | Description |
|---|---|
-l msi |
kubelogin 認証方法を指定します。 |
--client-id |
ユーザー割り当てマネージド ID のアプリケーション ID (クライアント ID)。 このパラメーターを指定しない場合は、既定のマネージド ID が使用されます。 |
ワークロード ID 認証
ワークロード ID (コマンド: -l workloadidentity) 認証方法では、Microsoft Entra とフェデレーションされた ID 資格情報を使用して、AKS クラスターへのアクセスを認証します。 この方法では、Microsoft Entra 統合認証が使用されます。 次の環境変数を設定することで動作します。
| Variable | Description |
|---|---|
AZURE_CLIENT_ID |
ワークロード ID とフェデレーションされている Microsoft Entra アプリケーション ID。 |
AZURE_TENANT_ID |
Microsoft Entra テナント ID。 |
AZURE_FEDERATED_TOKEN_FILE |
Kubernetes の投影されたサービス アカウント (JWT) トークンなど、ワークロード ID の署名付きアサーションを含むファイル。 |
AZURE_AUTHORITY_HOST |
Microsoft Entra 認証エンティティのベース URL。 たとえば、「 https://login.microsoftonline.com/ 」のように入力します。 |
ワークロード ID を使用すると、外部システムにサービス プリンシパルの資格情報を格納することなく、GitHubや Argo CD などの CI/CD システムから Kubernetes クラスターにアクセスできます。 GitHub からの OpenID Connect (OIDC) フェデレーションを構成する方法については、OIDC フェデレーションの例 を参照してください。
ワークロード ID 認証のパラメーター
次の表は、ワークロード ID 認証で使用できるパラメーターの概要を示しています。
| パラメーター | Description |
|---|---|
-l workloadidentity |
kubelogin 認証方法を指定します。 |
Azure Developer CLI 認証
Azure Developer CLI (コマンド: -l azd) 認証方法では、Azure Developer CLI が確立するサインイン コンテキストを使用してアクセス トークンを取得します。 トークンは、azd auth login と同じ Microsoft Entra テナントで発行されます。 kubelogin では、Azure Developer CLI によってトークンが管理されるため、トークンはトークン キャッシュに書き込まれません。
この認証方法は、AKS のマネージド Microsoft Entraでのみ機能します。 詳細については、Azure開発者 CLI の概要を参照してください。
Azure Pipelines 認証
Azure Pipelines (コマンド: -l azurepipelines) 認証方法では、Azure Resource Manager サービス接続とパイプラインのシステム アクセス トークンを使用して認証します。 このメソッドは、Azure Pipelinesでのみ機能します。 パイプラインには、Azure Resource Manager サービス接続があり、スクリプトが OAuth トークンにアクセスできるようにする必要があります。
Azure Resource Manager サービス接続でAzureCLI@2 タスクを使用する場合、kubelogin では、環境変数として提供されるテナント ID、クライアント ID、およびサービス接続 ID Azure Pipelines使用できます。 詳細については、Azure Pipelines のサービス接続を参照してください。
Warning
kubelogin では、リソース所有者パスワード資格情報 (ROPC) 認証方法もサポートされています。 Microsoftでは、多要素認証と一部のハイブリッド ID シナリオとの互換性がないため、ROPC を使用しないことをお勧めします。 詳細については、MICROSOFT IDENTITY PLATFORM ROPC ガイダンスを参照してください。
kubeconfig ファイル パスをエクスポートする
convert-kubeconfig サブコマンドを実行する前に、kubeconfig ファイルパスをKUBECONFIG環境変数にエクスポートします。 例えば次が挙げられます。
export KUBECONFIG=/path/to/kubeconfig
kubeconfig ファイルを変換する
convert-kubeconfig サブコマンドを実行して、選択した認証方法に exec プラグインを使用するように kubeconfig ファイルを変換します。
kubelogin convert-kubeconfig
kubelogin convert-kubeconfig -l azurecli
# Bearer token authentication
kubelogin convert-kubeconfig -l interactive
# Proof-of-Possession (PoP) token authentication
kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"
convert-kubeconfigサブコマンドを実行して、exec プラグインを使用するように kubeconfig ファイルを変換します。kubelogin convert-kubeconfig -l spnクライアント ID とクライアント シークレットまたはクライアント証明書の環境変数を設定します。 例えば次が挙げられます。
export AZURE_CLIENT_ID=<service-principal-client-id> export AZURE_CLIENT_SECRET=<service-principal-client-secret>
# Default managed identity authentication
kubelogin convert-kubeconfig -l msi
# Specific managed identity authentication
kubelogin convert-kubeconfig -l msi --client-id <managed-identity-client-id>
kubelogin convert-kubeconfig -l workloadidentity
Azure Developer CLI を使用して kubeconfig ファイルを変換する
Azure Developer CLI を使用してサインインします。
azd auth loginkubeconfig ファイルを変換して、Azure Developer CLI 認証方法を使用します。
kubelogin convert-kubeconfig -l azd
Azure Pipelinesで kubeconfig ファイルを変換する
Azure Resource Manager サービス接続を使用するAzureCLI@2 タスクで、Azure Pipelines認証を使用するように kubeconfig ファイルを変換します。
kubelogin convert-kubeconfig -l azurepipelines
キャッシュされたトークンを削除する
kubelogin remove-cache-dir コマンドを使用して、キャッシュされたトークンを削除します。
kubelogin remove-cache-dir
ノード情報を取得する
kubectl get コマンドを使用してノード情報を取得します。
kubectl get nodes
AKS で kubelogin アプリケーション ID を使用する方法
AKS では、Microsoft Entra のファースト パーティ アプリケーションのペアが使用されます。 これらのアプリケーション ID は、すべての環境で同一です。
| Application | アプリケーション ID (GUID) | 使用される場所 |
|---|---|---|
AKS サーバー アプリケーション (--server-id) |
6dae42f8-4368-4678-94ff-3960e28e3630 |
AKS にアクセスするときにサポートされているすべての kubelogin 認証方法のトークン対象ユーザー。 |
AKS パブリック クライアント アプリケーション (--client-id) |
80faf920-1908-4b52-b5ef-a8e7bedfc67a |
デバイス コード、Web ブラウザー対話型、ROPC 認証。 |
AKS の kubelogin get-token を直接呼び出す場合は、 --server-idを使用して AKS サーバー アプリケーション ID を指定します。 モード固有のパラメーターについては、 kubelogin get-token リファレンスを参照してください。
Note
このセクションの AKS パブリック クライアント アプリケーション ID は、デバイス コード、Web ブラウザーの対話型認証、ROPC 認証の --client-id 値です。 サービス プリンシパルとマネージド ID 認証の場合、 --client-id はサービス プリンシパルまたはユーザー割り当てマネージド ID を代わりに識別します。
たとえば、デバイス コード認証と AKS アプリケーション ID を使用してトークンを取得します。
kubelogin get-token \
--login devicecode \
--server-id 6dae42f8-4368-4678-94ff-3960e28e3630 \
--client-id 80faf920-1908-4b52-b5ef-a8e7bedfc67a \
--tenant-id <microsoft-entra-tenant-id>
関連コンテンツ
- AKS と Microsoft Entra を統合する方法については、 Microsoft Entra 統合 のハウツーに関する記事を参照してください。
- AKS でマネージド ID を使用する方法については、「AKS でマネージド ID を使用する」を参照してください。
- AKS でワークロード ID を使用する方法については、「AKS でワークロード ID を使用する」を参照してください。