Azure Kubernetes Service (AKS) でサービス プリンシパルを使用する

他の Azure Active Directory (Azure AD) リソースにアクセスするには、AKS クラスターには、Azure Active Directory (AD) サービス プリンシパルまたはマネージド ID が必要です。 サービス プリンシパルまたはマネージド ID は、Azure のロード バランサーや Azure Container Registry (ACR) などのその他の Azure リソースを動的に作成および管理するために必要です。

マネージド ID は、Azure の他のリソースで認証を行うための推奨される方法であり、AKS クラスターの既定の認証方法です。 クラスターでのマネージド ID の使用の詳細については、「システム割り当てマネージド ID を使用する」を参照してください。

この記事では、AKS クラスター用のサービス プリンシパルを作成して使用する方法を示します。

開始する前に

Azure AD サービス プリンシパルを作成するには、アプリケーションを Azure AD テナントに登録し、そのアプリケーションをサブスクリプション内のロールに割り当てるためのアクセス許可が必要です。 必要なアクセス許可がない場合は、必要なアクセス許可を割り当てるよう Azure AD またはサブスクリプションの管理者に依頼するか、AKS クラスターで使用するサービス プリンシパルを事前に作成する必要があります。

別の Azure AD テナントのサービス プリンシパルを使用している場合は、クラスターのデプロイ時に使用できるアクセス許可について他の考慮事項があります。 ディレクトリ情報の読み取りと書き込みを行うために適切なアクセス許可がない可能性があります。 詳細については、「Azure Active Directory の既定のユーザー アクセス許可とは」を参照してください。

前提条件

Azure CLI バージョン 2.0.59 以降。 バージョンを確認するには、az --version を実行します。 インストールまたはアップグレードする必要がある場合は、Azure CLI のインストールに関するページを参照してください。

Azure PowerShell バージョン 5.0.0 以降。 バージョンを確認するには、Get-InstalledModule -Name Az を実行します。 インストールまたはアップグレードする必要がある場合は、「Azure Az PowerShell モジュールをインストールする」を参照してください。

手動でサービス プリンシパルを作成する

Azure CLI を使用して手動でサービス プリンシパルを作成するには、az ad sp create-for-rbac コマンドを使用します。

az ad sp create-for-rbac --name myAKSClusterServicePrincipal

出力は次の例のようになります。 appIdpassword の値をコピーします。 これらの値は、次のセクションで AKS クラスターを作成するときに使用します。

{
  "appId": "559513bd-0c19-4c1a-87cd-851a26afd5fc",
  "displayName": "myAKSClusterServicePrincipal",
  "name": "http://myAKSClusterServicePrincipal",
  "password": "e763725a-5eee-40e8-a466-dc88d980f415",
  "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db48"
}

AKS クラスター用のサービス プリンシパルを指定する

az aks create コマンドを使用して AKS クラスターを作成するときに既存のサービス プリンシパルを使用するには、--service-principal パラメーターと --client-secret パラメーターを使用して、az ad sp create-for-rbac コマンドの出力の appIdpassword を指定します。

az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --service-principal <appId> \
    --client-secret <password>

注意

カスタマイズされたシークレットがある既存のサービス プリンシパルを使用する場合は、そのシークレットの長さが 190 バイトを超えていないことを確認します。

他の Azure リソースへのアクセスを委任する

AKS クラスターのサービス プリンシパルは、他のリソースへのアクセスに使用することができます。 たとえば、AKS クラスタを既存の Azure 仮想ネットワーク サブネットに展開したり、Azure Container Registry (ACR) に接続したりする場合、それらのリソースへのアクセスをサービス プリンシパルに委任する必要があります。

アクセス許可を委任するには、az role assignment create コマンドを使用してロールの割り当てを作成します。 リソース グループ、仮想ネットワーク リソースなど、特定のスコープに appId を割り当てます。 さらに、そのサービス プリンシパルが対象のリソースに対して持つアクセス許可がロールによって定義されます。次の例をご覧ください。

az role assignment create --assignee <appId> --scope <resourceScope> --role Contributor

リソースの --scope には、 /subscriptions/<guid>/resourceGroups/myResourceGroup/subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet など、完全なリソース ID を指定する必要があります。

Note

ノード リソース グループから共同作成者ロールの割り当てを削除した場合、以下の操作が失敗する可能性があります。 システム割り当てマネージド ID を使用しているクラスターに付与されたアクセス許可の入力には、最大で 60 分かかる場合があります。

以降の各セクションでは、割り当てる必要が生じることがある一般的な委任について詳しく取り上げます。

Azure Container Registry

Azure Container Registry (ACR) をコンテナーのイメージ ストアとして使用する場合、AKS クラスターがイメージを読み取ってプルするためのアクセス許可を、サービス プリンシパルに与える必要があります。 現在は、az aks create または az aks update コマンドを使用してレジストリと統合し、サービス プリンシパルに適切なロールを割り当てる構成をお勧めします。 詳細な手順については、「Azure Kubernetes Service から Azure Container Registry の認証を受ける」を参照してください。

ネットワーク

仮想ネットワークとサブネットまたはパブリック IP アドレスが別のリソース グループに存在する高度なネットワークを使用することも考えられます。 仮想ネットワーク内のサブネットにネットワーク共同作成者の組み込みロールを割り当てます。 または、そのリソース グループ内のネットワーク リソースにアクセスするためのアクセス許可を持つカスタム ロールを作成することもできます。 詳細については、「AKS サービスの権限」を参照してください。

ストレージ

別のリソース グループ内の既存のディスク リソースにアクセスする必要がある場合は、次のいずれかのロール アクセス許可のセットを割り当てます。

Azure Container Instances

Virtual Kubelet を使用して AKS と統合し、AKS クラスターとは別のリソース グループで Azure Container Instances (ACI) を実行する場合は、AKS クラスター サービス プリンシパルに ACI リソース グループに対する "共同作成者" 権限を与える必要があります。

その他の考慮事項

AKS と Azure AD サービス プリンシパルを使用する場合は、次の点を考慮してください。

  • Kubernetes のサービス プリンシパルは、クラスター構成の一部です。 ただし、クラスターのデプロイにこの ID を使用しないでください。
  • 既定では、このサービス プリンシパル資格情報は 1 年間有効です。 サービス プリンシパルの資格情報はいつでも更新または回転できます。
  • すべてのサービス プリンシパルは、Azure AD アプリケーションに関連付けられています。 Kubernetes クラスターのサービス プリンシパルは、有効な任意の Azure AD アプリケーション名 (たとえば https://www.contoso.org/example) に関連付けることができます。 アプリケーションの URL は、実際のエンドポイントである必要はありません。
  • サービス プリンシパルのクライアント ID を指定するときには、appId の値を使用します。
  • Kubernetes クラスター内のエージェント ノード VM では、サービス プリンシパルの資格情報が /etc/kubernetes/azure.json ファイルに格納されます
  • az aks create コマンドを使用してサービス プリンシパルを自動的に生成すると、サービス プリンシパルの資格情報は、コマンドの実行に使用されたコンピューター上の ~/.azure/aksServicePrincipal.json ファイルに書き込まれます。
  • AKS CLI コマンドでサービス プリンシパルを指定しない場合は、~/.azure/aksServicePrincipal.json にある既定のサービス プリンシパルが使用されます。
  • 必要に応じて、aksServicePrincipal.json ファイルを削除すると、AKS が新しいサービス プリンシパルを作成します。
  • az aks create によって作成された AKS クラスターを削除しても、自動的に作成されたサービス プリンシパルは削除されません。
    • サービス プリンシパルを削除するには、クラスターの servicePrincipalProfile.clientId のクエリを実行してから、az ad sp delete コマンドを使用して削除します。 -g パラメーターの値をリソース グループ名に、-n パラメーターの値をクラスター名に置き換えます。

      az ad sp delete --id $(az aks show -g myResourceGroup -n myAKSCluster --query servicePrincipalProfile.clientId -o tsv)
      

トラブルシューティング

AKS クラスターのサービス プリンシパルの資格情報は、Azure CLI によってキャッシュされます。 これらの資格情報が期限切れになると、AKS クラスターのデプロイ中にエラーが発生します。 az aks create を実行しているときの次のエラー メッセージは、キャッシュされているサービス プリンシパルの資格情報に問題があることを示す可能性があります。

Operation failed with status: 'Bad Request'.
Details: The credentials in ServicePrincipalProfile were invalid. Please see https://aka.ms/aks-sp-help for more details.
(Details: adal: Refresh request failed. Status Code = '401'.

次のコマンドを実行して、資格情報ファイルの有効期限を確認します。

ls -la $HOME/.azure/aksServicePrincipal.json

サービス プリンシパルの資格情報の既定の有効期限は 1 年です。 aksServicePrincipal.json ファイルが 1 年よりも古い場合は、ファイルを削除して AKS クラスターのデプロイを再試行します。

一般的な Azure CLI のトラブルシューティング

Azure CLI は、いくつかのシェル環境で実行できますが、形式には若干の差異があります。 Azure CLI コマンドで予期しない結果が発生した場合は、Azure CLI を正しく使用する方法に関する記事を参照してください。

次のステップ

Azure Active Directory サービス プリンシパルの詳細については、「アプリケーション オブジェクトとサービス プリンシパル オブジェクト」を参照してください。

資格情報の更新方法について詳しくは、「AKS でのサービス プリンシパルの資格情報の更新または回転」を参照してください。