サービスアカウントを作成し、Azure Kubernetes Service (AKS) のエージェント CLI のワークロード ID を構成する (プレビュー)

この記事では、 必要な サービスアカウントを作成し、 必要に応じて Azure Kubernetes Service (AKS) のエージェント CLI のワークロード ID を構成する方法について説明します。クラスターモードのデプロイではサービスアカウントの作成が必須ですが、ワークロード ID のセットアップは省略可能ですが、Azure リソースにアクセスするときのセキュリティ強化には推奨されます。

[前提条件]

サービスアカウントの作成の前提条件:

Azure CLI バージョン 2.76 以降。 az version コマンドを使用してバージョンを確認します。インストールまたは更新するには、 Azure CLI のインストールに関するページを参照してください。
az account set コマンドを使用して、アクティブな Azure サブスクリプションを設定します。
```
az account set --subscription "your-subscription-id-or-name"
```
Kubernetes サービスアカウント、ロール、ロールバインドを作成および管理するための十分なアクセス許可が必要です。

ワークロード ID 構成の前提条件:

AKS クラスターで有効になっているワークロード ID。
Azure マネージド ID を作成および管理し、フェデレーション ID 資格情報を作成するための十分なアクセス許可が必要です。

変数の定義

まず、環境に必要な変数を設定します。プレースホルダーの値を実際のクラスターと Azure の詳細に置き換えます。

サービスアカウントの作成に必要な変数:

# Cluster information
export RESOURCE_GROUP="<YOUR_RESOURCE_GROUP>"
export CLUSTER_NAME="<YOUR_CLUSTER_NAME>"

# Service account configuration
export SERVICE_ACCOUNT_NAME="aks-mcp"
export SERVICE_ACCOUNT_NAMESPACE="<YOUR_NAMESPACE>"  # e.g., "kube-system" or custom namespace

追加変数 (ワークロード ID を構成する場合のみ):

# Azure information for workload identity
export LOCATION="<YOUR_LOCATION>"
export SUBSCRIPTION="$(az account show --query id --output tsv)"

# Workload identity configuration
export USER_ASSIGNED_IDENTITY_NAME="aks-mcp-identity"
export FEDERATED_IDENTITY_CREDENTIAL_NAME="aks-mcp-fed-identity"

# Generate unique suffix for resource naming
export RANDOM_ID="$(openssl rand -hex 3)"

Kubernetes サービスアカウントを作成し、アクセス許可を割り当てる (必須)

Important

エージェント CLI がクラスターモードで AKS クラスターで認証するには、サービスアカウントが必要です。

サービスアカウントを作成する

次のコマンドを使用して、ターゲット名前空間にサービスアカウントを作成します。

kubectl create serviceaccount "${SERVICE_ACCOUNT_NAME}" --namespace "${SERVICE_ACCOUNT_NAMESPACE}"

RBAC アクセス許可を作成する

aks-mcp トラブルシューティングのための読み取りアクセス権を持つサービスアカウントに必要な Role と RoleBinding を作成します。アクセス要件に基づく 2 つの例を次に示します。

クラスター全体の読み取りアクセス (クラスター管理者に推奨)

この ClusterRoleBinding を使用して、すべての名前空間のシークレットを除くすべての Kubernetes リソースに読み取り専用アクセス権を付与します。このオプションは、クラスター全体の問題を調査してトラブルシューティングする必要があるクラスターレベルの管理者または DevOps エンジニアに推奨されます。
```
cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: aks-mcp-view-rolebinding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: view
subjects:
- kind: ServiceAccount
  name: ${SERVICE_ACCOUNT_NAME}
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
EOF
```

次のコマンドを使用して、リソースが正常に作成されたことを確認します。

kubectl get serviceaccount "${SERVICE_ACCOUNT_NAME}" --namespace "${SERVICE_ACCOUNT_NAMESPACE}"
kubectl get clusterrolebinding aks-mcp-view-rolebinding

名前空間スコープの読み取りアクセス (制限付きアクセスシナリオの場合)

RoleBindings を使用して、特定の名前空間のシークレットのみを除くすべての Kubernetes リソースに読み取り専用アクセス権を付与します。このオプションは、クラスター全体ではなく、特定の名前空間へのアクセスを制限する必要があるチームまたはユーザーに適しています。アクセスを必要とする名前空間ごとに、この RoleBinding を繰り返します。
```
cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: aks-mcp-view-rolebinding
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: view
subjects:
- kind: ServiceAccount
  name: ${SERVICE_ACCOUNT_NAME}
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
EOF
```

次のコマンドを使用して、リソースが正常に作成されたことを確認します。

kubectl get serviceaccount "${SERVICE_ACCOUNT_NAME}" --namespace "${SERVICE_ACCOUNT_NAMESPACE}"
kubectl get rolebinding aks-mcp-view-rolebinding --namespace "${SERVICE_ACCOUNT_NAMESPACE}"

Azure リソースアクセスのワークロード ID を構成する (省略可能)

次の手順は 省略可能 ですが、エージェント CLI がワークロード ID を使用して Azure リソースに安全にアクセスできるようにする場合は推奨されます。

現在のワークロード ID の状態を確認する

az aks show コマンドを使用して、AKS クラスターでワークロード ID が既に有効になっているかどうかを確認します。

az aks show --resource-group "${RESOURCE_GROUP}" --name "${CLUSTER_NAME}" --query "securityProfile.workloadIdentity.enabled"

出力が true場合、ワークロード ID が有効になります。 nullまたはfalse場合は、有効にする必要があります。

ワークロード ID を有効にする

az aks updateフラグと--enable-workload-identity フラグを指定して --enable-oidc-issuer コマンドを使用して、AKS クラスターでワークロード ID を有効にします。

az aks update \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --enable-oidc-issuer \
    --enable-workload-identity

OIDC 発行者 URL を取得する

az aks show コマンドを使用して OIDC 発行者 URL を取得し、環境変数に保存します。

export AKS_OIDC_ISSUER="$(az aks show --name "${CLUSTER_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --query "oidcIssuerProfile.issuerUrl" \
    --output tsv)"

環境変数には、次の例のような発行者 URL が含まれている必要があります。

https://eastus.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/11111111-1111-1111-1111-111111111111/

ユーザー割り当てマネージド ID を作成する

az identity create コマンドを使用して、Azure リソースアクセス用のユーザー割り当てマネージド ID を作成します。

az identity create \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --location "${LOCATION}" \
    --subscription "${SUBSCRIPTION}"

次の出力例は、マネージド ID の正常な作成を示しています:

{
  "clientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroupxxxxxx/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentityxxxxxx",
  "location": "eastus",
  "name": "myIdentityxxxxxx",
  "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "resourceGroup": "myResourceGroupxxxxxx",
  "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

マネージド ID クライアント ID を取得する

az identity showを使用してマネージド ID のクライアント ID を取得し、環境変数に保存します。

export USER_ASSIGNED_CLIENT_ID="$(az identity show \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query 'clientId' \
    --output tsv)"

マネージド ID に必要なロールを割り当てる

az role assignment create コマンドを使用して、マネージド ID に必要なロールを割り当てます。

次の例では、サブスクリプションスコープで "閲覧者" ロールを割り当てます。これにより、エージェント CLI は Azure リソース情報を読み取ることができます。ユースケースに合わせて、必要に応じてロールとスコープを調整します。

az role assignment create --role "Reader" \
    --assignee $USER_ASSIGNED_CLIENT_ID \
    --scope /subscriptions/${SUBSCRIPTION}

Microsoft Entra ID (キーレス認証) で Azure OpenAI を使用している場合は、Azure OpenAI リソースに "Cognitive Services ユーザー" または "Azure AI ユーザー" ロールも割り当てる必要があります。

# Option 1: Assign Cognitive Services User role
az role assignment create \
    --role "Cognitive Services User" \
    --assignee $USER_ASSIGNED_CLIENT_ID \
    --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<openai-resource-name>

# Option 2: Assign Azure AI User role
az role assignment create \
    --role "Azure AI User" \
    --assignee $USER_ASSIGNED_CLIENT_ID \
    --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<openai-resource-name>

<subscription-id>、<resource-group>、および<openai-resource-name>を実際の値に置き換えます。

ワークロード ID を使用してサービスアカウントに注釈を付ける (省略可能)

次のコマンドを使用して、ワークロード ID の注釈を含むようにサービスアカウントを更新します。

kubectl annotate serviceaccount "${SERVICE_ACCOUNT_NAME}" \
    --namespace "${SERVICE_ACCOUNT_NAMESPACE}" \
    azure.workload.identity/client-id="${USER_ASSIGNED_CLIENT_ID}" \
    --overwrite

次のコマンドを使用して、サービスアカウントに正しいワークロード ID 注釈があることを確認します。
```
kubectl describe serviceaccount "${SERVICE_ACCOUNT_NAME}" --namespace "${SERVICE_ACCOUNT_NAMESPACE}"
```

フェデレーション ID 資格情報を作成する (省略可能)

az identity federated-credential create コマンドを使用して、マネージド ID、サービスアカウント発行者、サブジェクトの間にフェデレーション ID 資格情報を作成します。
```
az identity federated-credential create \
    --name "${FEDERATED_IDENTITY_CREDENTIAL_NAME}" \
    --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --issuer "${AKS_OIDC_ISSUER}" \
    --subject "system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME}" \
    --audience api://AzureADTokenExchange
```
注

フェデレーション ID 資格情報が追加された後に反映されるまでに数秒かかります。フェデレーション ID 資格情報を追加した直後にトークン要求が行われると、キャッシュが更新されるまでの間、要求が失敗する可能性があります。このイシューを回避するには、フェデレーション ID 資格情報を追加した後に若干の遅延を追加できます。
フェデレーション ID 資格情報を一覧表示し、 az identity federated-credential list コマンドを使用して作成を確認します。
```
az identity federated-credential list \
    --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --resource-group "${RESOURCE_GROUP}"
```

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-28