Tworzenie konta usługi i konfigurowanie tożsamości obciążenia dla interfejsu wiersza polecenia agenta dla usługi Azure Kubernetes Service (AKS) (wersja zapoznawcza)

W tym artykule pokazano, jak utworzyć wymagane konto usługi i opcjonalnie skonfigurować tożsamość obciążenia dla interfejsu wiersza polecenia agenta dla usługi Azure Kubernetes Service (AKS). Tworzenie konta usługi jest obowiązkowe w przypadku wdrożenia trybu klastra, podczas gdy konfiguracja tożsamości obciążenia jest opcjonalna, ale zalecana w celu zapewnienia zwiększonych zabezpieczeń podczas uzyskiwania dostępu do zasobów platformy Azure.

Wymagania wstępne

Wymagania wstępne dotyczące tworzenia konta usługi:

  • CLI platformy Azure w wersji 2.76 lub nowszej. Sprawdź wersję przy użyciu polecenia az version. Aby zainstalować lub zaktualizować, zobacz Instalowanie interfejsu wiersza polecenia platformy Azure.

  • Ustaw aktywną subskrypcję platformy Azure używając polecenia az account set.

    az account set --subscription "your-subscription-id-or-name"
    
  • Potrzebujesz wystarczających uprawnień do tworzenia kont, ról i powiązań ról usługi Kubernetes oraz zarządzania nimi.

Wymagania wstępne dla konfiguracji tożsamości dla obciążeń roboczych

Definiowanie zmiennych

Najpierw skonfiguruj wymagane zmienne dla środowiska. Zastąp wartości zastępcze rzeczywistymi szczegółami dotyczącymi klastra i platformy Azure.

Wymagane zmienne do tworzenia konta usługi:

# 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

Dodatkowe zmienne (tylko w przypadku konfigurowania tożsamości obciążenia):

# 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)"

Tworzenie konta usługi Kubernetes i przypisywanie uprawnień (wymagane)

Ważna

Konto usługi jest wymagane, aby agentowy CLI uwierzytelniał się z klastrem AKS w trybie klastra.

Tworzenie konta usługi

Utwórz konto usługi w docelowej przestrzeni nazw przy użyciu następującego polecenia:

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

Tworzenie uprawnień RBAC

Utwórz niezbędną rolę i powiązanie ról dla konta usługi z dostępem do odczytu na potrzeby rozwiązywania problemów z usługą aks-mcp. Poniżej przedstawiono dwa przykłady na podstawie wymagań dotyczących dostępu:

  1. Użyj tego ClusterRoleBinding, aby przyznać dostęp tylko do odczytu do wszystkich zasobów Kubernetes z wyjątkiem tajemnic we wszystkich przestrzeniach nazw. Ta opcja jest zalecana dla administratorów na poziomie klastra lub inżynierów DevOps, którzy muszą badać i rozwiązywać problemy w całym klastrze.

    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
    
  2. Sprawdź, czy zasoby zostały pomyślnie utworzone przy użyciu następujących poleceń:

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

Dostęp do odczytu w zakresie przestrzeni nazw (w przypadku scenariuszy z ograniczonym dostępem)

  1. Użyj RoleBindings, aby udzielić dostępu tylko do odczytu wszystkim zasobom Kubernetes z wyjątkiem tajemnic w określonych przestrzeniach nazw. Ta opcja jest odpowiednia dla zespołów lub użytkowników, którzy powinni mieć ograniczony dostęp do określonych przestrzeni nazw, a nie całego klastra. Powtórz to powiązanie ról dla każdej przestrzeni nazw, która wymaga dostępu.

    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
    
  2. Sprawdź, czy zasoby zostały pomyślnie utworzone przy użyciu następujących poleceń:

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

Konfigurowanie tożsamości obciążenia na potrzeby dostępu do zasobów platformy Azure (opcjonalnie)

Poniższe kroki są opcjonalne , ale zalecane, jeśli chcesz umożliwić interfejsowi wiersza polecenia agenta bezpieczne uzyskiwanie dostępu do zasobów platformy Azure przy użyciu tożsamości obciążenia.

Sprawdzanie bieżącego stanu tożsamości obciążenia

Sprawdź, czy tożsamość robocza jest już włączona w klastrze usługi AKS przy użyciu polecenia az aks show.

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

Jeśli dane wyjściowe to true, tożsamość obciążenia jest włączona. Jeśli null lub false, musisz to włączyć.

Włączanie tożsamości obciążenia

Włącz tożsamość obciążenia w klastrze AKS za pomocą polecenia az aks update z flagami --enable-workload-identity i --enable-oidc-issuer.

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

Pobierz adres URL wystawcy OIDC

Pobierz adres URL wystawcy OIDC przy użyciu az aks show polecenia i zapisz go w zmiennej środowiskowej.

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

Zmienna środowiskowa powinna zawierać adres URL wystawcy podobny do następującego przykładu:

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

Tworzenie tożsamości zarządzanej przypisanej przez użytkownika

Utwórz tożsamość zarządzaną przypisaną przez użytkownika na potrzeby dostępu do zasobów platformy Azure przy użyciu az identity create polecenia .

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

Poniższy przykład danych wyjściowych przedstawia pomyślne utworzenie tożsamości zarządzanej:

{
  "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"
}

Pobierz identyfikator klienta tożsamości zarządzanej

Pobierz identyfikator klienta tożsamości zarządzanej przy użyciu elementu az identity show i zapisz go w zmiennej środowiskowej.

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

Przypisz niezbędną rolę tożsamości zarządzanej

Przypisz niezbędne role do tożsamości zarządzanej za pomocą polecenia az role assignment create.

Poniższy przykład przypisuje rolę "Czytelnik" w zakresie subskrypcji, co umożliwia agentowemu interfejsowi wiersza polecenia odczytywanie informacji o zasobach Azure. Dostosuj rolę i zakres zgodnie z potrzebami dla twojego przypadku użycia.

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

Jeśli używasz usługi Azure OpenAI z identyfikatorem Entra firmy Microsoft (uwierzytelnianie bez klucza), musisz również przypisać rolę "Użytkownik usług Cognitive Services" lub "Użytkownik usługi Azure AI" w zasobie azure OpenAI:

# 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>

Zastąp <subscription-id>, <resource-group> i <openai-resource-name> rzeczywistymi wartościami.

Dodawanie adnotacji do konta usługi przy użyciu tożsamości obciążenia (opcjonalnie)

  1. Zaktualizuj konto usługi, aby uwzględnić adnotację dla tożsamości zadania roboczego przy użyciu następującego polecenia:

    kubectl annotate serviceaccount "${SERVICE_ACCOUNT_NAME}" \
        --namespace "${SERVICE_ACCOUNT_NAMESPACE}" \
        azure.workload.identity/client-id="${USER_ASSIGNED_CLIENT_ID}" \
        --overwrite
    
  2. Sprawdź, czy konto usługi ma poprawną adnotację tożsamości obciążenia przy użyciu następującego polecenia:

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

Tworzenie poświadczeń tożsamości federacyjnej (opcjonalnie)

  1. Utwórz poświadczenie federacyjnej tożsamości między tożsamością zarządzaną, wystawcą konta usługi i podmiotem, przy użyciu polecenia az identity federated-credential create.

    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
    

    Uwaga / Notatka

    Federacyjne poświadczenia tożsamości potrzebują kilka sekund na propagację po ich dodaniu. Jeśli natychmiast po dodaniu poświadczeń tożsamości federacyjnej zostanie wykonane żądanie tokenu, może się ono zakończyć niepowodzeniem, dopóki pamięć podręczna nie zostanie odświeżona. Aby uniknąć tego problemu, możesz dodać niewielkie opóźnienie po dodaniu poświadczenia tożsamości federacyjnej.

  2. Wyświetl listę poświadczeń tożsamości federacyjnej za pomocą polecenia az identity federated-credential list, aby potwierdzić utworzenie.

    az identity federated-credential list \
        --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \
        --resource-group "${RESOURCE_GROUP}"