Uso de una identidad administrada en Azure Kubernetes Service (AKS)

En este artículo se proporcionan instrucciones paso a paso sobre cómo habilitar y usar una identidad administrada kubelet asignada por el sistema, asignada por el usuario o creada previamente en Azure Kubernetes Service (AKS).

Requisitos previos de la identidad administrada de AKS

Lea la Información general de identidades administradas en Azure Kubernetes Service (AKS) para comprender los distintos tipos de identidades administradas disponibles en AKS y cómo puede usarlos para acceder de forma segura a los recursos de Azure.
Antes de ejecutar los ejemplos de este artículo, establezca la suscripción como la suscripción activa actual mediante el comando .
```
az account set --subscription <subscription-id>
```
Cree un grupo de recursos Azure si aún no tiene uno llamando al comando az group create.
```
az group create \
    --name <resource-group-name> \
    --location <location>
```

Requisitos mínimos de la versión de Azure CLI

Asegúrese de que tiene Azure CLI versión 2.23.0 o posterior instalada. Ejecute para encontrar la versión. Si necesita instalar o actualizar, consulte Install Azure CLI.
Para usar una identidad administrada kubelet creada previamente, necesita tener instalada la versión 2.26.0 o posterior de Azure CLI.
Para actualizar un clúster existente para usar una identidad administrada asignada por el sistema o a identidad administrada asignada por el usuario, necesita Azure CLI versión 2.49.0 o posterior instalada.

Limitaciones

Una vez que crea un clúster con una identidad administrada, no puede volver a usar un principal de servicio.
No se admite el traslado o migración de un clúster habilitado para identidad administrada a otro inquilino.
Si el clúster tiene habilitada la identidad administrada por pods de Microsoft Entra (aad-pod-identity), los pods de Identidad administrada del nodo (NMI) modifican las tablas de IP de los nodos para interceptar las llamadas que se realizan en el punto de conexión de Azure Instance Metadata (IMDS). Esta configuración significa que NMI intercepta cualquier solicitud realizada al punto de conexión IMDS, incluso si un pod determinado no usa .

La definición de recursos personalizados (CRD) de AzurePodIdentityException se puede configurar para especificar que las solicitudes al punto de conexión de IMDS que se originan en etiquetas coincidentes de pod definidas en la CRD se deben procesar en proxy sin ningún procesamiento en NMI. Excluye los pods del sistema con la etiqueta en el espacio de nombres kube-system en configurando la CRD de AzurePodIdentityException. Para obtener más información, consulte Uso de identidades administradas por pods de Microsoft Entra en Azure Kubernetes Service.

Para configurar una excepción, instale el mic-exception YAML.
AKS no admite el uso de una identidad administrada asignada por el sistema cuando se usa una zona DNS privada personalizada.
Las regiones Centro de USDOD, Este de USDOD y USGov Iowa en Azure US Government nube no admiten la creación de un clúster con una identidad administrada asignada por el usuario.

Una identidad kubelet administrada que se haya creado previamente debe ser una identidad administrada asignada a un usuario.
No se admiten las regiones del Este de China y del Norte de China en Microsoft Azure operadas por 21Vianet.

Importante

Todas las características de Microsoft Defender for Cloud se retirarán oficialmente en el Azure de la región de China el 18 de agosto de 2026. Debido a esta próxima retirada, los clientes de Azure en China ya no pueden incorporar nuevas suscripciones al servicio. Una nueva suscripción es cualquier suscripción que aún no se haya incorporado al servicio Microsoft Defender for Cloud antes del 18 de agosto de 2025, la fecha del anuncio de retirada. Para obtener más información sobre la obsolescencia, consulte el Anuncio sobre la retirada de Microsoft Defender for Cloud en Microsoft Azure, operado por 21Vianet.

Los clientes deben trabajar con sus representantes de cuenta para Microsoft Azure operados por 21Vianet para evaluar el impacto de esta retirada en sus propias operaciones.

Consideraciones sobre la actualización del clúster

Al actualizar un clúster, tenga en cuenta la siguiente información:

Una actualización solo funciona si hay una actualización de VHD para consumir. Si ya ejecuta el VHD más reciente, deberá esperar hasta que la siguiente actualización del VHD esté disponible.
El Azure CLI garantiza que el permiso del complemento se establezca correctamente después de la migración. Si no usa el Azure CLI para realizar la operación de migración, debe controlar el permiso de la identidad del complemento por su cuenta. Para obtener un ejemplo con una plantilla de Azure Resource Manager (ARM), consulte Assign Azure roles mediante plantillas de ARM.
Si el clúster usaba --attach-acr para extraer de imágenes de Azure Container Registry (ACR), debe ejecutar el comando az aks update --resource-group <resource-group-name> --name <aks-cluster-name> --attach-acr <acr-resource-id> después de actualizar el clúster para permitir que el kubelet recién creado usado para la identidad administrada obtenga el permiso para extraer de ACR. De lo contrario, no podrá extraer datos desde ACR después de la actualización.

Habilitación de una identidad administrada asignada por el sistema en un clúster de AKS

Habilitación de una identidad administrada asignada por el sistema en un clúster nuevo de AKS

Una identidad administrada asignada por el sistema está habilitada de forma predeterminada al crear un nuevo clúster de AKS.

Cree un clúster de AKS mediante el comando.

az aks create \
    --resource-group <resource-group-name> \
    --name <aks-cluster-name> \
    --generate-ssh-keys

Actualización de un clúster de AKS existente para usar una identidad administrada asignada por el sistema

Actualice un clúster de AKS existente de una entidad de servicio a una identidad administrada asignada por el sistema utilizando el comando con el parámetro .
```
az aks update \
    --resource-group <resource-group-name> \
    --name <aks-cluster-name> \
    --enable-managed-identity
```
Después de actualizar el clúster para usar una identidad administrada asignada por el sistema en lugar de una entidad de servicio, el plano de control y los pods usan la identidad administrada asignada por el sistema para la autorización al acceder a otros servicios en Azure. Kubelet continúa usando una entidad de servicio hasta que actualices también el grupo de agentes. Puede usar el comando en los nodos para actualizar a una identidad administrada. Una actualización del grupo de nodos provoca un tiempo de inactividad para el clúster de AKS, ya que los nodos de los grupos de nodos se acordonan o purgan y se restablece la imagen inicial.

Obtén la ID principal de una identidad administrada asignada por el sistema

Obtenga el ID principal de la identidad administrada asignada por el sistema del clúster usando el comando .

CLIENT_ID=$(az aks show \
    --name <aks-cluster-name> \
    --resource-group <resource-group-name> \
    --query identity.principalId \
    --output tsv)

Incorporación de una asignación de roles para una identidad administrada asignada por el sistema

Asigne un rol de RBAC de Azure a la identidad administrada asignada por el sistema mediante el comando az role assignment create.

En el caso de una red virtual de Azure (VNet), un disco de Azure adjunto, una dirección IP estática o una tabla de rutas que se encuentren fuera del grupo de recursos de nodo de trabajo predeterminado, debe asignar el rol de Network Contributor en el grupo de recursos personalizado.

En el ejemplo siguiente se asigna el rol Colaborador de red a la identidad administrada asignada por el sistema. La asignación de roles se limita al grupo de recursos que contiene la red virtual.
```
az role assignment create \
    --assignee <client-id> \
    --role "Network Contributor" \
    --scope <custom-resource-group-id>
```
Nota:

Los permisos concedidos a la identidad administrada del clúster pueden tardar hasta 60 minutos en propagarse.

Crear una identidad administrada asignada por el usuario

Si aún no tienes un recurso de identidad administrada asignada por el usuario, crea uno mediante el comando .

az identity create \
    --name <identity-name> \
    --resource-group <resource-group-name>

La salida debería ser similar a la salida de ejemplo siguiente:

{                                  
  "clientId": "<client-id>",
  "clientSecretUrl": "<clientSecretUrl>",
  "id": "/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>",
  "location": "<location>",
  "name": "<identity-name>",
  "principalId": "<principal-id>",
  "resourceGroup": "<resource-group-name>",
  "tags": {},
  "tenantId": "<tenant-id>",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Obtención del id. de cliente de la identidad administrada asignada por el usuario

Obtenga el ID principal de la identidad administrada asignada por el usuario mediante el comando .

CLIENT_ID=$(az identity show \
    --name <identity-name> \
    --resource-group <resource-group-name> \
    --query principalId \
    --output tsv)

Obtención del id. de recurso de la identidad administrada asignada por el usuario

Obtenga el identificador de recurso de la identidad administrada asignada por el usuario mediante el comando .

RESOURCE_ID=$(az identity show \
    --name <identity-name> \
    --resource-group <resource-group-name> \
    --query id \
    --output tsv)

Asignación de un rol de RBAC de Azure a la identidad administrada asignada por el usuario

Agregue una asignación de roles para la identidad administrada asignada por el usuario mediante el comando .

En el ejemplo siguiente se asigna el rol Key Vault Secrets User a la identidad administrada asignada por el usuario para concederle permisos para acceder a los secretos en una bóveda de claves. La asignación de roles se limita al recurso del almacén de claves:
```
az role assignment create \
    --assignee <client-id> \
    --role "Key Vault Secrets User" \
    --scope "<keyvault-resource-id>"
```
Nota:

Los permisos concedidos a la identidad administrada del clúster pueden tardar hasta 60 minutos en propagarse.

Habilitación de una identidad administrada asignada por el usuario en un clúster de AKS

Habilitación de una identidad administrada asignada por el usuario en un nuevo clúster de AKS

Cree un clúster de AKS con la identidad administrada asignada por el usuario mediante el comando . Incluye el parámetro y pasa el id. de recurso de la identidad administrada asignada por el usuario:

az aks create \
    --resource-group <resource-group-name> \
    --name <cluster-name> \
    --network-plugin azure \
    --vnet-subnet-id <vnet-subnet-id> \
    --dns-service-ip 10.2.0.10 \
    --service-cidr 10.2.0.0/24 \
    --assign-identity $RESOURCE_ID \
    --generate-ssh-keys

Actualización de un clúster existente para usar una identidad administrada asignada por el usuario

Actualice un clúster existente para usar una identidad administrada asignada por el usuario mediante el comando . Incluye el parámetro y pasa el id. de recurso de la identidad administrada asignada por el usuario:
```
az aks update \
    --resource-group <resource-group-name> \
    --name <cluster-name> \
    --enable-managed-identity \
    --assign-identity $RESOURCE_ID
```
La salida de una actualización correcta del clúster para usar una identidad administrada asignada por el usuario debe ser similar a la del ejemplo siguiente:
```
  "identity": {
    "principalId": null,
    "tenantId": null,
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>": {
        "clientId": "<client-id>",
        "principalId": "<principal-id>"
      }
    }
  },
```
Nota:

Migrar la identidad administrada para el plano de control de "asignada por el sistema" a "asignada por el usuario" no provoca ningún tiempo de inactividad para el plano de control ni los grupos de agentes. Los componentes del plano de control continúan hasta varias horas con la identidad asignada por el sistema anterior hasta la siguiente actualización del token.

Determinación de qué tipo de identidad administrada usa un clúster

Compruebe qué tipo de identidad administrada usa el clúster con el comando .
```
az aks show \
    --name <aks-cluster-name> \
    --resource-group <resource-group-name> \
    --query identity.type \
    --output tsv       
```
Si el clúster usa una identidad administrada, el valor de la propiedad type será SystemAssigned o UserAssigned.

Si el clúster está utilizando una entidad de servicio, el valor de la propiedad type será null. Considere la posibilidad de actualizar el clúster para usar una identidad administrada.

Creación de una identidad administrada de kubelet

Si aún no tiene ninguna identidad administrada de kubelet, cree una mediante el comando .

az identity create \
    --name <kubelet-identity-name> \
    --resource-group <resource-group-name>

La salida debería ser similar a la salida de ejemplo siguiente:

{
  "clientId": "<client-id>",
  "clientSecretUrl": "<clientSecretUrl>",
  "id": "/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<kubelet-identity-name>",
  "location": "<location>",
  "name": "<kubelet-identity-name>",
  "principalId": "<principal-id>",
  "resourceGroup": "<resource-group-name>",
  "tags": {},
  "tenantId": "<tenant-id>",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Asignación de un rol RBAC a la identidad administrada por kubelet

Asigne el rol a la identidad administrada de kubelet mediante el comando .

az role assignment create \
    --assignee <kubelet-client-id> \
    --role "acrpull" \
    --scope "<acr-registry-id>"

Habilitación de una identidad administrada de Kubelet en un clúster de AKS

Habilitación de una identidad administrada de kubelet en un nuevo clúster de AKS

Cree un clúster de AKS con las identidades existentes mediante el comando .

az aks create \
    --resource-group <resource-group-name> \
    --name <aks-cluster-name> \
    --network-plugin azure \
    --vnet-subnet-id <vnet-subnet-id> \
    --dns-service-ip 10.2.0.10 \
    --service-cidr 10.2.0.0/24 \
    --assign-identity <identity-resource-id> \
    --assign-kubelet-identity <kubelet-identity-resource-id> \
    --generate-ssh-keys

Una creación correcta de clústeres de AKS mediante una identidad administrada de kubelet debería generar una salida similar a la siguiente:

  "identity": {
    "principalId": null,
    "tenantId": null,
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>": {
        "clientId": "<client-id>",
        "principalId": "<principal-id>"
      }
    }
  },
  "identityProfile": {
    "kubeletidentity": {
      "clientId": "<client-id>",
      "objectId": "<object-id>",
      "resourceId": "/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<kubelet-identity-name>"
    }
  },

Actualización de un clúster existente para usar una identidad administrada de kubelet

Para actualizar un clúster existente a fin de usar la identidad administrada de kubelet, primero debes obtener la identidad administrada del plano de control actual para el clúster de AKS.

Advertencia

Al actualizar la identidad administrada de kubelet, se producen las actualizaciones de los grupos de nodos del clúster de AKS. Asegúrese de tener configuradas adecuadamente las configuraciones de disponibilidad adecuadas, como los Presupuestos de Disrupción de Pod, antes de ejecutar esto para evitar interrupciones de la carga de trabajo, o hágalo durante una ventana de mantenimiento.

Ejecute el comando para confirmar que el clúster de AKS usa la identidad administrada asignada por el usuario.
```
az aks show \
    --resource-group <resource-group-name> \
    --name <aks-cluster-name> \
    --query "servicePrincipalProfile"
```
Si el clúster utiliza una identidad administrada, la salida le mostrará el elemento con el valor msi. Un clúster que usa una entidad de servicio le mostrará un id. de objeto. Por ejemplo:
```
# The cluster is using a managed identity.
{
  "clientId": "msi"
}
```

Después de comprobar que el clúster usa identidades administradas, podrá encontrar el id. de recurso de la identidad administrada si ejecuta el comando .

az aks show --resource-group <resource-group-name> \
    --name <aks-cluster-name> \
    --query "identity"

Para una identidad administrada asignada por el usuario, la salida debe ser similar a la siguiente salida de ejemplo:

{
  "principalId": null,
  "tenantId": null,
  "type": "UserAssigned",
  "userAssignedIdentities": <identity-resource-id>
      "clientId": "<client-id>",
      "principalId": "<principal-id>"
},

Actualice un clúster de AKS con las identidades existentes mediante el comando . Proporciona el id. de recurso de la identidad administrada asignada por el usuario para el plano de control del argumento . Proporciona el id. de recurso de la identidad administrada de kubelet para el argumento .

az aks update \
    --resource-group <resource-group-name> \
    --name <aks-cluster-name> \
    --enable-managed-identity \
    --assign-identity <identity-resource-id> \
    --assign-kubelet-identity <kubelet-identity-resource-id>

La salida de una actualización correcta del clúster con su propia identidad administrada de kubelet debe ser similar a la siguiente salida de ejemplo:

  "identity": {
    "principalId": null,
    "tenantId": null,
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>": {
        "clientId": "<client-id>",
        "principalId": "<principal-id>"
      }
    }
  },
  "identityProfile": {
    "kubeletidentity": {
      "clientId": "<client-id>",
      "objectId": "<object-id>",
      "resourceId": "/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<kubelet-identity-name>"
    }
  },

Obtención de las propiedades de la identidad administrada de kubelet

Obtenga las propiedades de la identidad administrada de kubelet utilizando el comando y consultando la propiedad .

az aks show \
    --name <aks-cluster-name> \
    --resource-group <resource-group-name> \
    --query "identityProfile.kubeletidentity"

Pasos siguientes

Usa las plantillas de Azure Resource Manager para crear un clúster con identidad administrada habilitada.
Aprenda a usar kubelogin para todos los métodos de autenticación de Microsoft Entra compatibles en AKS.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-03-05