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

  • Artículo
  • Tiempo de lectura: 10 minutos

Para acceder con otros recursos de Azure Active Directory (Azure AD), un clúster de AKS requiere una entidad de servicio de Azure Active Directory (AD) o una identidad administrada. Estos elementos se necesitan para crear y administrar dinámicamente otros recursos de Azure, como Azure Load Balancer o Container Registry.

Las identidades administradas son la manera recomendada de autenticarse en otros recursos y es el método de autenticación predeterminado para el clúster 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 Azure AD, es preciso tener los permisos suficientes para registrar una aplicación en un inquilino de Azure AD y asignarle un rol en una suscripción. Si no tiene los permisos necesarios, tiene que pedir al administrador de Azure AD o de la suscripción que asigne los permisos necesarios o 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 Azure AD, 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 obtener más información, consulte ¿Cuáles son los permisos de usuario predeterminados en Azure Active Directory?

Prerrequisitos

CLI de Azure, 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.

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

Para crear manualmente una entidad de servicio con la CLI de Azure, use el comando az ad sp create-for-rbac.

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

La salida será similar al del ejemplo siguiente: Copie los valores de appId y password. Se usan al crear un clúster de AKS en la sección siguiente.

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

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

Para usar una entidad de servicio existente al crear un clúster de AKS mediante el comando az aks create, use los parámetros --service-principal y --client-secret para especificar los valores appId y password a partir del resultado del comando az ad sp create-for-rbac:

az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --service-principal <appId> \
    --client-secret <password>

Nota

Si utiliza una entidad de servicio existente con secreto personalizado, asegúrese de que este no supera 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.

Para delegar permisos, cree una asignación de roles mediante 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. Un rol define qué permisos tiene la entidad de servicio en el recurso, como se muestra en el ejemplo siguiente:

az role assignment create --assignee <appId> --scope <resourceScope> --role Contributor

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

Nota

Si ha quitado la asignación del rol Colaborador del grupo de recursos del nodo, se pueden producir errores en las siguientes operaciones. El permiso concedido a un clúster mediante una identidad administrada asignada por el sistema puede tardar hasta 60 minutos en rellenarse.

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

Azure Container Registry

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, la configuración recomendada es usar el comando az aks create o az aks update para integrarse con 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:

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

Al usar AKS y una entidad de servicio de Azure AD, tenga en cuenta lo siguiente:

  • La entidad de servicio para Kubernetes forma parte de la configuración del clúster. Sin embargo, no use 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 Azure AD. La entidad de servicio de un clúster de Kubernetes puede asociarse con cualquier nombre de aplicación de Azure AD 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.
  • Cuando use el comando az aks create para generar la entidad de servicio automáticamente, sus credenciales se escriben en el archivo ~/.azure/aksServicePrincipal.json de la máquina que se usa para ejecutar el comando.
  • Si no especifica una entidad de servicio principal de la CLI de AKS, se usa la entidad de servicio predeterminada ubicada en ~/.azure/aksServicePrincipal.json.
  • Opcionalmente, puede quitar el archivo aksServicePrincipal.json, y AKS crea una nueva entidad de servicio.
  • Al eliminar un clúster de AKS creado mediante az aks create, no se elimina la entidad de servicio creada automáticamente.

    • Para eliminar la entidad de servicio, consulte el clúster servicePrincipalProfile.clientId y después elimínelo con 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)

Solución de problemas

La CLI de Azure almacena en caché las credenciales de la entidad de servicio para un clúster de AKS. Si estas credenciales han expirado, se producen errores durante la implementación del clúster de AKS. El siguiente mensaje de error al ejecutar az aks create 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 antigüedad del archivo de credenciales con la ejecución del comando siguiente:

ls -la $HOME/.azure/aksServicePrincipal.json

El tiempo de expiración predeterminado para las credenciales de la entidad de servicio es de un año. Si el archivo aksServicePrincipal.json tiene más de un año, elimine el archivo e implementar el clúster de AKS.

Pasos siguientes

Para obtener más información sobre las entidades de servicio de Azure Active Directory, 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.