Azure Kubernetes Service (AKS) でのサービス プリンシパル

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

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

開始する前に

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

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

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

サービス プリンシパルを自動的に作成して使用する

Azure portal で、または az aks create コマンドを使用して AKS クラスターを作成すると、Azure によってマネージド ID が作成されます。

次の Azure CLI の例では、サービス プリンシパルは指定されていません。 このシナリオでは、Azure CLI によって、AKS クラスター用のマネージド ID が作成されます。

az aks create --name myAKSCluster --resource-group myResourceGroup

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

Azure CLI を使用して手動でサービス プリンシパルを作成するには、az ad sp create-for-rbac コマンドを使用します。 次の例では、--skip-assignment パラメーターによって、追加の既定の割り当てが行われないようにしています。

az ad sp create-for-rbac --skip-assignment --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 portal を使用して AKS クラスターをデプロイする場合は、 [Create Kubernetes cluster](Kubernetes クラスターの作成) ダイアログ ボックスの [Authentication](認証) ページで、 [Configure service principal](サービス プリンシパルの構成) を選択します。 [既存のものを使用] を選択し、以下の値を指定します。

  • [Service principal client ID](サービス プリンシパルのクライアント ID) は、実際の appId です
  • [Service principal client secret](サービス プリンシパルのクライアント シークレット) は、password の値です

Azure Vote にブラウザーでアクセスしたところ

他の 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 を指定する必要があります。

注意

ノード リソース グループから共同作成者ロールの割り当てを削除した場合、以下の操作が失敗する可能性があります。 システム マネージド 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 で削除します。 次のリソース グループとクラスターの名前は、実際の値に置き換えてください。

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

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