Use una entidad de servicio con Azure Kubernetes Service (AKS)

Artículo
10/25/2023

Un clúster de AKS requiere una entidad de servicio de Microsoft Entra o una identidad administrada para crear y administrar dinámicamente otros recursos de Azure, como Azure Load Balancer o Azure Container Registry (ACR).

Nota:

Las identidades administradas son la manera recomendada de autenticarse en otros recursos en Azure y es el método de autenticación predeterminado para el clúster de AKS. Para más información sobre el uso de una identidad administrada con el clúster, consulte Uso de una identidad administrada asignada por el sistema.

En este artículo se muestra cómo crear y usar una entidad de servicio para los clústeres de AKS.

Antes de empezar

Para crear una entidad de servicio de Microsoft Entra, debe tener permisos suficientes para registrar una aplicación en su inquilino de Microsoft Entra y asignar la aplicación a un rol en su suscripción. Si no tiene los permisos necesarios, tiene que pedir al administrador de Microsoft Entra ID o de la suscripción que asigne los permisos necesarios o bien, crear previamente una entidad de servicio para su uso con el clúster de AKS.

Si usa una entidad de servicio de otro inquilino de Microsoft Entra, hay otras consideraciones en torno a los permisos disponibles al implementar el clúster. Puede que no tenga los permisos adecuados para leer y escribir datos del directorio. Para más información, consulte ¿Cuáles son los permisos de usuario predeterminados en Microsoft Entra ID?

Requisitos previos

Si usa la CLI de Azure, necesita la versión 2.0.59, o posterior. Ejecute az --version para encontrar la versión. Si necesita instalarla o actualizarla, vea Instalación de la CLI de Azure.
Si usa Azure PowerShell, necesita Azure PowerShell versión 5.0.0 o posterior. Ejecute Get-InstalledModule -Name Az para encontrar la versión. Si tiene que instalarla o actualizarla, consulte Instalación del módulo Azure Az PowerShell.

Creación manual de una entidad de servicio

CLI de Azure
Azure PowerShell

Cree una entidad de servicio mediante el comando az ad sp create-for-rbac.

az ad sp create-for-rbac --name myAKSClusterServicePrincipal

La salida debe ser similar a la siguiente salida de ejemplo:

{
  "appId": "559513bd-0c19-4c1a-87cd-851a26afd5fc",
  "displayName": "myAKSClusterServicePrincipal",
  "name": "http://myAKSClusterServicePrincipal",
  "password": "e763725a-5eee-40e8-a466-dc88d980f415",
  "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db48"
}

Copie los valores de appId y password de la salida. Estos se usan al crear un clúster de AKS en la sección siguiente.

Cree una entidad de servicio mediante el comando New-AzADServicePrincipal.

New-AzADServicePrincipal -DisplayName myAKSClusterServicePrincipal -OutVariable sp

La salida debe ser similar a la siguiente salida de ejemplo:

Secret                : System.Security.SecureString
ServicePrincipalNames : {559513bd-0c19-4c1a-87cd-851a26afd5fc, http://myAKSClusterServicePrincipal}
ApplicationId         : 559513bd-0c19-4c1a-87cd-851a26afd5fc
ObjectType            : ServicePrincipal
DisplayName           : myAKSClusterServicePrincipal
Id                    : 559513bd-0c19-4c1a-87cd-851a26afd5fc
Type                  :

Los valores también se almacenan en una variable que se usa al crear un clúster de AKS en la sección siguiente.

Para descifrar el valor almacenado en la cadena segura Secret, ejecute el comando siguiente.

$BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sp.Secret)
[System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)

Especificación de una entidad de servicio para un clúster de AKS

CLI de Azure
Azure PowerShell

Use una entidad de servicio existente para un nuevo clúster de AKS mediante el comando az aks create y use los parámetros --service-principal y --client-secret para especificar el appId y password de la salida que recibió en la sección anterior.
```
az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --service-principal <appId> \
    --client-secret <password>
```
Nota

Si utiliza una entidad de servicio existente con un secreto personalizado, asegúrese de que este no supere los 190 bytes.

Convierta la entidad de servicio ApplicationId y Secret en un objeto PSCredential mediante el siguiente comando.
```
$Cred = New-Object -TypeName System.Management.Automation.PSCredential ($sp.ApplicationId, $sp.Secret)
```
Use una entidad de servicio existente para un nuevo clúster de AKS mediante el comando New-AzAksCluster y especifique el parámetro ServicePrincipalIdAndSecret con el objeto PSCredential creado anteriormente como su valor.
```
New-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -ServicePrincipalIdAndSecret $Cred
```
Nota

Si utiliza una entidad de servicio existente con un secreto personalizado, asegúrese de que este no supere los 190 bytes.

Delegación del acceso a otros recursos de Azure

La entidad de servicio del clúster de AKS se puede utilizar para acceder a otros recursos. Por ejemplo, si quiere implementar el clúster de AKS en una subred de red virtual de Azure o conectarse a Azure Container Registry (ACR), debe delegar el acceso a estos recursos a la entidad de servicio. El permiso concedido a un clúster mediante una identidad administrada asignada por el sistema puede tardar hasta 60 minutos en rellenarse.

CLI de Azure
Azure PowerShell

Cree una asignación de roles con el comando az role assignment create. Asigne el elemento appId a un ámbito determinado, como un grupo de recursos o un recurso de red virtual. El rol define qué permisos tiene la entidad de servicio en el recurso.

Nota

El elemento --scope de un recurso debe ser un id. de recurso completo, como /subscriptions/<guid>/resourceGroups/myResourceGroup o /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet.
```
az role assignment create --assignee <appId> --scope <resourceScope> --role Contributor
```

Cree una asignación de roles con el comando New-AzRoleAssignment. Asigne el elemento ApplicationId a un ámbito determinado, como un grupo de recursos o un recurso de red virtual. El rol define qué permisos tiene la entidad de servicio en el recurso.

Nota

El elemento Scope de un recurso debe ser un identificador de recurso completo, como /subscriptions/<guid>/resourceGroups/myResourceGroup o /subscriptions/<guid >/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet
```
New-AzRoleAssignment -ApplicationId <ApplicationId> -Scope <resourceScope> -RoleDefinitionName Contributor
```

Las secciones siguientes detallan las delegaciones comunes que es posible que deba asignar.

Si usa Azure Container Registry (ACR) como el almacén de imágenes de contenedor, deberá conceder permisos a la entidad de servicio que el clúster de AKS pueda leer y extraer imágenes. Actualmente, se recomienda usar el comando az aks create o az aks update para integrarse en un registro y asignar el rol adecuado a la entidad de servicio. Para ver los pasos detallados, consulte Autenticación con Azure Container Registry desde Azure Kubernetes Service.

Si usa Azure Container Registry (ACR) como el almacén de imágenes de contenedor, deberá conceder permisos a la entidad de servicio que el clúster de AKS pueda leer y extraer imágenes. Actualmente, se recomienda usar el comando New-AzAksCluster o Set-AzAksCluster para integrarse en un registro y asignar el rol adecuado a la entidad de servicio. Para ver los pasos detallados, consulte Autenticación con Azure Container Registry desde Azure Kubernetes Service.

Redes

Puede usar redes avanzadas en las que la red virtual y la subred o las direcciones IP públicas se encuentran en otro grupo de recursos. Asigne el rol integrado Colaborador de la red en la subred dentro de la red virtual. Como alternativa, puede crear un rol personalizado con permisos para tener acceso a los recursos de red de ese grupo de recursos. Para obtener más información, consulte los permisos de servicio de AKS.

Almacenamiento

Si necesita acceder a los recursos de disco existentes en otro grupo de recursos, asigne uno de los siguientes conjuntos de permisos de rol:

Cree un rol personalizado y defina los permisos de rol Microsoft.Compute/disks/read y Microsoft.Compute/disks/write.
O bien, asigne el rol integrado Colaborador de la máquina virtual en el grupo de recursos.

Azure Container Instances

Si usa Virtual Kubelet para la integración con AKS y elige ejecutar Azure Container Instances (ACI) en un grupo de recursos separado del clúster de AKS, la entidad de servicio de clúster AKS debe tener concedidos los permisos de Colaborador en el grupo de recursos de ACI.

Otras consideraciones

CLI de Azure
Azure PowerShell

Al usar AKS y una entidad de servicio de Microsoft Entra, tenga en cuenta lo siguiente:

La entidad de servicio de Kubernetes forma parte de la configuración del clúster, pero no usa esta identidad para implementar el clúster.
De forma predeterminada, las credenciales de la entidad de servicio son válidas durante un año. Puede actualizar o rotar las credenciales de la entidad de servicio en cualquier momento.
Cada entidad de servicio está asociada a una aplicación de Microsoft Entra. La entidad de servicio de un clúster de Kubernetes puede asociarse con cualquier nombre de aplicación de Microsoft Entra válido (por ejemplo, https://www.contoso.org/example). La dirección URL de la aplicación no tiene por qué ser un punto de conexión real.
Al especificar el identificador de cliente, utilice el valor de appId.
En las VM del nodo de agente del clúster de Kubernetes, las credenciales de la entidad de servicio se almacenan en el archivo /etc/kubernetes/azure.json.
Al eliminar un clúster de AKS creado mediante el comando az aks create, no se elimina automáticamente la entidad de servicio creada.
- Para eliminar la entidad de servicio, consulte el clúster servicePrincipalProfile.clientId y, después, elimínelo usando el comando az ad sp delete. Reemplace los valores del parámetro -g para el nombre del grupo de recursos y el parámetro -n para el nombre del clúster:
```
az ad sp delete --id $(az aks show -g myResourceGroup -n myAKSCluster --query servicePrincipalProfile.clientId -o tsv)
```

Al usar AKS y una entidad de servicio de Microsoft Entra, tenga en cuenta lo siguiente:

La entidad de servicio de Kubernetes forma parte de la configuración del clúster, pero no usa esta identidad para implementar el clúster.
De forma predeterminada, las credenciales de la entidad de servicio son válidas durante un año. Puede actualizar o rotar las credenciales de la entidad de servicio en cualquier momento.
Cada entidad de servicio está asociada a una aplicación de Microsoft Entra. La entidad de servicio de un clúster de Kubernetes puede asociarse con cualquier nombre de aplicación de Microsoft Entra válido (por ejemplo, https://www.contoso.org/example). La dirección URL de la aplicación no tiene por qué ser un punto de conexión real.
Al especificar el identificador de cliente, utilice el valor de ApplicationId.
En las VM del nodo de agente del clúster de Kubernetes, las credenciales de la entidad de servicio se almacenan en el archivo /etc/kubernetes/azure.json.
Al eliminar un clúster de AKS creado mediante New-AzAksCluster, no se elimina automáticamente la entidad de servicio creada.
- Para eliminar la entidad de servicio, consulte el servicePrincipalProfile.clientId del clúster y, después, elimínelo usando el comando Remove-AzADServicePrincipal. Reemplace los valores del parámetro -ResourceGroupName para el nombre del grupo de recursos y el parámetro -Name para el nombre del clúster:
```
$ClientId = (Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster ).ServicePrincipalProfile.ClientId
Remove-AzADServicePrincipal -ApplicationId $ClientId
```

Solución de problemas

CLI de Azure
Azure PowerShell

La CLI de Azure almacena en caché las credenciales de la entidad de servicio para los clústeres de AKS. Si estas credenciales expiran, se producen errores durante la implementación del clúster de AKS. Si ejecuta el comando az aks create y recibe un mensaje de error similar al siguiente, puede indicar un problema con las credenciales de la entidad de servicio almacenadas en caché:

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'.

Compruebe la fecha de expiración de las credenciales de la entidad de servicio mediante el comando az ad app credential list con la consulta "[].endDateTime".

az ad app credential list --id <app-id> --query "[].endDateTime" -o tsv

El tiempo de expiración predeterminado para las credenciales de la entidad de servicio es de un año. Si las credenciales son anteriores a un año, puede restablecer las credenciales existentes o crear una nueva entidad de servicio.

Solución de problemas a nivel general de la CLI de Azure

La CLI de Azure se puede ejecutar en varios entornos de shell, pero con ligeras variaciones de formato. Si tiene resultados inesperados con comandos de la CLI de Azure, consulte Uso correcto de la CLI de Azure.

Azure PowerShell almacena en caché las credenciales de la entidad de servicio para los clústeres de AKS. Si estas credenciales expiran, se producen errores durante la implementación del clúster de AKS. Si ejecuta el comando New-AzAksCluster y recibe un mensaje de error similar al siguiente, puede indicar un problema con las credenciales de la entidad de servicio almacenadas en caché:

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'.

Compruebe la fecha de expiración de las credenciales de la entidad de servicio mediante el comando Get-AzADAppCredential. La salida le mostrará la StartDateTime de las credenciales.

Get-AzADAppCredential -ApplicationId <ApplicationId>

Pasos siguientes

Para más información sobre las entidades de servicio de Microsoft Entra, consulte Objetos de aplicación y de entidad de servicio.

Para obtener información sobre cómo actualizar las credenciales, vea Actualizar o rotar las credenciales de una entidad de servicio en AKS.