Solución de problemas de la CLI agente para Azure Kubernetes Service (AKS) (versión preliminar)

En este artículo se proporcionan instrucciones sobre cómo solucionar problemas comunes con la CLI agente para Azure Kubernetes Service (AKS).

Pasos comunes de solución de problemas

Si tiene algún problema al usar la CLI agente para AKS, pruebe los pasos de solución de problemas siguientes:

  • Si en las respuestas observa solicitudes que reintentan /chat/completions, significa que puede estar limitado por los límites de tokens por minuto (TPM) del LLM. Aumente el límite de TPM o solicite más cuota.
  • Si las salidas varían, puede deberse a la variabilidad de la respuesta LLM o a las conexiones de servidor intermitentes del Protocolo de contexto de modelo (MCP).
  • Asegúrese de que el nombre de implementación sea el mismo que el nombre del modelo en las implementaciones de Azure OpenAI.
  • Si se produce un error en la aks-agent instalación, intente desinstalar la CLI de Azure y vuelva a instalar la versión más reciente.

Error: El demonio de Docker no se está ejecutando

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

  1. Si recibe un error que indica que el demon de Docker no se está ejecutando, inicie el servicio Docker mediante los pasos adecuados para el sistema operativo:

    • macOS/Windows:

      • Inicie Docker Desktop desde las aplicaciones.
      • Espere a que Se inicie Docker.

    • linux:

      • Inicie el servicio docker con los siguientes comandos:

        sudo systemctl start docker
sudo systemctl enable docker  # Enable Docker to start on boot

  2. Compruebe que Docker se está ejecutando con el comando siguiente:

    docker info

Error: Permiso de Docker denegado

Got permission denied while trying to connect to the Docker daemon socket

Para resolver los problemas de permisos de Docker, asegúrese de que su usuario tenga los permisos necesarios para acceder al demonio de Docker usando los pasos correspondientes a su sistema operativo.

  • macOS/Windows:

    • Reinicie Docker Desktop para asegurarse de que tiene los permisos necesarios.

  • linux:

    • Agregue el usuario al grupo de Docker para permitir el acceso no raíz a Docker mediante los siguientes comandos:
    sudo usermod -aG docker $USER
newgrp docker  # Apply group changes immediately

Error: Errores de extracción de imágenes de Docker

Error response from daemon: pull access denied for aks-agent, repository does not exist or may require 'docker login'

Para resolver errores de extracción de imágenes de Docker, pruebe los pasos siguientes:

  • Asegúrese de que tiene conectividad a Internet.
  • Compruebe si los firewalls corporativos bloquean el acceso al registro de Docker.
  • Intente volver a inicializar el agente con az aks agent-init.

Problemas de credenciales de Azure

Error: Error de autenticación de Azure

Para resolver los problemas de autenticación de Azure, asegúrese de que la CLI de Azure está autenticada correctamente y tiene acceso a los recursos necesarios mediante los pasos siguientes:

  1. Compruebe que las credenciales de Azure están configuradas correctamente mediante el az account show comando .

    az account show

  2. Si es necesario, vuelva a iniciar sesión con el az login comando .

    az login

Problemas de cuenta de servicio y RBAC

Error: No se encontró la cuenta de servicio

Error: service account "aks-mcp" not found in namespace "default"

Para resolver los problemas de la cuenta de servicio, asegúrese de que la cuenta de servicio de Kubernetes se crea correctamente y se configura mediante los pasos siguientes:

  1. Compruebe que la cuenta de servicio existe con el comando siguiente:

    kubectl get serviceaccount aks-mcp --namespace $NAMESPACE

  2. Si no se encuentra la cuenta de servicio, cree una mediante los pasos descritos en Creación de una cuenta de servicio y configuración de la identidad de carga de trabajo para la CLI de agente para Azure Kubernetes Service (AKS) (versión preliminar)

Error: Errores de permisos denegados

Error: forbidden: User "system:serviceaccount:<namespace>:aks-mcp" cannot get resource "pods" in API group "" in the namespace "<namespace>"

Para resolver los errores de permiso denegado, asegúrese de que la cuenta de servicio de Kubernetes tiene los permisos de RBAC necesarios mediante los pasos siguientes:

  1. Compruebe que los permisos de RBAC están configurados correctamente mediante los siguientes comandos:

    kubectl get role aks-mcp-role --namespace $NAMESPACE
kubectl get rolebinding aks-mcp-rolebinding --namespace $NAMESPACE

  2. Compruebe que RoleBinding asocia la cuenta de servicio correcta con el rol mediante el siguiente comando:

    kubectl describe rolebinding aks-mcp-rolebinding --namespace $NAMESPACE

Problemas de identidad de carga de trabajo

Error: La identidad de carga de trabajo no está habilitada

Error: workload identity is not enabled on this cluster

Si recibe un error que indica que la identidad de carga de trabajo no está habilitada, compruebe que el clúster de AKS tiene habilitada la identidad de carga de trabajo mediante los pasos siguientes:

  1. Compruebe si la identidad de carga de trabajo está habilitada en el clúster de AKS mediante el az aks show comando .

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

  2. Si la identidad de carga de trabajo no está habilitada, siga los pasos descritos en Creación de una cuenta de servicio y configuración de la identidad de carga de trabajo para la CLI agente para Azure Kubernetes Service (AKS) (versión preliminar) para habilitar la identidad de carga de trabajo en el clúster.

Error: Falta anotación

Error: service account does not have workload identity annotation

Para resolver errores de anotación que faltan, asegúrese de que la cuenta de servicio de Kubernetes tenga la anotación de identidad de carga de trabajo correcta mediante los pasos siguientes:

  1. Compruebe si la anotación existe en la cuenta de servicio mediante el comando siguiente:

    kubectl describe serviceaccount aks-mcp --namespace $NAMESPACE

  2. Si falta la anotación, agréguela mediante el siguiente comando. Asegúrese de reemplazar $CLIENT_ID por el identificador de cliente real de la credencial de identidad federada.

    kubectl annotate serviceaccount aks-mcp --namespace $NAMESPACE azure.workload.identity/client-id="$CLIENT_ID" --overwrite

Error: Retraso de propagación de credenciales federadas

Si recibe errores relacionados con la credencial de identidad federada que no se encuentra o los errores de autenticación, puede deberse a retrasos de propagación después de crear la credencial de identidad federada en Azure. Para resolver este problema, pruebe los siguientes pasos:

  1. Espere unos minutos para que la credencial de identidad federada se propague entre los servicios de Azure.
  2. Compruebe que la credencial de identidad federada existe mediante el az identity federated-credential list comando .
az identity federated-credential list --identity-name $IDENTITY_NAME --resource-group $RESOURCE_GROUP

Problemas de inicialización

Error: No se encontró la extensión

ERROR: The command 'aks agent' is invalid or not supported. Use 'az aks --help' to see available commands

Para resolver errores de extensión no encontrados, asegúrese de que la aks-agent extensión está instalada y cargada correctamente mediante los pasos siguientes:

  1. Instale la extensión aks-agent mediante el comando az extension add.

    az extension add --name aks-agent --debug

  2. Compruebe la instalación correcta mediante el az extension list comando .

    az extension list

    La salida debe incluir una entrada para aks-agent.

Contenido relacionado

  • Last updated on