Entidades de servicio con Azure Kubernetes Service (AKS)Service principals with Azure Kubernetes Service (AKS)

  • Tiempo de lectura: 6 minutos

Para interactuar con las API de Azure, un clúster de AKS requiere una entidad de servicio de Azure Active Directory (AD) o una identidad administrada.To interact with Azure APIs, an AKS cluster requires either an Azure Active Directory (AD) service principal or a managed identity. Estos elementos se necesitan para crear y administrar dinámicamente otros recursos de Azure, como Azure Load Balancer o Container Registry.A service principal or managed identity is needed to dynamically create and manage other Azure resources such as an Azure load balancer or container registry (ACR).

En este artículo se muestra cómo crear y usar una entidad de servicio para los clústeres de AKS.This article shows how to create and use a service principal for your AKS clusters.

Antes de empezarBefore you begin

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.To create an Azure AD service principal, you must have permissions to register an application with your Azure AD tenant, and to assign the application to a role in your subscription. Si no tiene los permisos necesarios, es posible que tenga 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.If you don't have the necessary permissions, you might need to ask your Azure AD or subscription administrator to assign the necessary permissions, or pre-create a service principal for you to use with the AKS cluster.

Si usa una entidad de servicio de otro inquilino de Azure AD, hay consideraciones adicionales en torno a los permisos disponibles al implementar el clúster.If you are using a service principal from a different Azure AD tenant, there are additional considerations around the permissions available when you deploy the cluster. Puede que no tenga los permisos adecuados para leer y escribir datos del directorio.You may not have the appropriate permissions to read and write directory information. Para obtener más información, consulte ¿Cuáles son los permisos de usuario predeterminados en Azure Active Directory?For more information, see What are the default user permissions in Azure Active Directory?

También es preciso que esté instalada y configurada la versión 2.0.59 de la CLI de Azure u otra versión posterior.You also need the Azure CLI version 2.0.59 or later installed and configured. Ejecute az --version para encontrar la versión.Run az --version to find the version. Si necesita instalarla o actualizarla, vea Instalación de la CLI de Azure.If you need to install or upgrade, see Install Azure CLI.

Creación y uso de una entidad de servicio automáticamenteAutomatically create and use a service principal

Cuando crea un clúster de AKS en Azure Portal o mediante el comando az aks create, Azure puede generar automáticamente una entidad de servicio.When you create an AKS cluster in the Azure portal or using the az aks create command, Azure can automatically generate a service principal.

En el siguiente ejemplo de la CLI de Azure, no se especifica una entidad de servicio.In the following Azure CLI example, a service principal is not specified. En este escenario, la CLI de Azure crea un entidad de servicio para el clúster de AKS.In this scenario, the Azure CLI creates a service principal for the AKS cluster. Para completar esta operación correctamente, la cuenta debe tener los derechos apropiados para crear una entidad de servicio.To successfully complete the operation, your Azure account must have the proper rights to create a service principal.

az aks create --name myAKSCluster --resource-group myResourceGroup

Creación manual de una entidad de servicioManually create a service principal

Para crear manualmente una entidad de servicio con la CLI de Azure, use el comando az ad sp create-for-rbac.To manually create a service principal with the Azure CLI, use the az ad sp create-for-rbac command. En el ejemplo siguiente, el parámetro --skip-assignment impide la asignación de asignaciones predeterminadas adicionales:In the following example, the --skip-assignment parameter prevents any additional default assignments being assigned:

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

La salida será similar al del ejemplo siguiente:The output is similar to the following example. Tome nota de sus valores appId y password.Make a note of your own appId and password. Se usan al crear un clúster de AKS en la sección siguiente.These values are used when you create an AKS cluster in the next section.

{
  "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 AKSSpecify a service principal for an AKS cluster

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:To use an existing service principal when you create an AKS cluster using the az aks create command, use the --service-principal and --client-secret parameters to specify the appId and password from the output of the az ad sp create-for-rbac command:

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.If you're using an existing service principal with customized secret, ensure the secret is no longer than 190 bytes.

Si implementa un clúster de AKS mediante Azure Portal, en la página autenticación del cuadro de diálogo Creación de un clúster de Kubernetes, elija Configurar la entidad de servicio.If you deploy an AKS cluster using the Azure portal, on the Authentication page of the Create Kubernetes cluster dialog, choose to Configure service principal. Seleccione Usar existente y especifique los valores siguientes:Select Use existing, and specify the following values:

  • Id. de cliente de la entidad de servicio es su appIdService principal client ID is your appId
  • Secreto del cliente de la entidad de servicio es el valor de contraseñaService principal client secret is the password value

Imagen de la exploración hasta Azure Vote

Delegación del acceso a otros recursos de AzureDelegate access to other Azure resources

La entidad de servicio del clúster de AKS se puede utilizar para acceder a otros recursos.The service principal for the AKS cluster can be used to access other resources. 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.For example, if you want to deploy your AKS cluster into an existing Azure virtual network subnet or connect to Azure Container Registry (ACR), you need to delegate access to those resources to the service principal.

Para delegar permisos, cree una asignación de roles mediante el comando az role assignment create.To delegate permissions, create a role assignment using the az role assignment create command. Asigne el elemento appId a un ámbito determinado, como un grupo de recursos o un recurso de red virtual.Assign the appId to a particular scope, such as a resource group or virtual network resource. Un rol define qué permisos tiene la entidad de servicio en el recurso, como se muestra en el ejemplo siguiente:A role then defines what permissions the service principal has on the resource, as shown in the following example:

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/myVnetThe --scope for a resource needs to be a full resource ID, such as /subscriptions/<guid>/resourceGroups/myResourceGroup or /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.If you have removed the Contributor role assignment from the node resource group, the operations below may fail.

Las secciones siguientes detallan las delegaciones comunes que es posible que deba realizar.The following sections detail common delegations that you may need to make.

Azure Container RegistryAzure 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.If you use Azure Container Registry (ACR) as your container image store, you need to grant permissions to the service principal for your AKS cluster to read and pull images. 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.Currently, the recommended configuration is to use the az aks create or az aks update command to integrate with a registry and assign the appropriate role for the service principal. Para ver los pasos detallados, consulte Autenticación con Azure Container Registry desde Azure Kubernetes Service.For detailed steps, see Authenticate with Azure Container Registry from Azure Kubernetes Service.

RedesNetworking

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.You may use advanced networking where the virtual network and subnet or public IP addresses are in another resource group. Asigne el rol integrado Colaborador de la red en la subred dentro de la red virtual.Assign the Network Contributor built-in role on the subnet within the virtual network. Como alternativa, puede crear un rol personalizado con permisos para tener acceso a los recursos de red de ese grupo de recursos.Alternatively, you can create a custom role with permissions to access the network resources in that resource group. Consulte permisos del servicio AKS para obtener más información.See AKS service permissions for more details.

StorageStorage

Es posible que necesite acceder a los recursos de disco existentes en otro grupo de recursos.You may need to access existing Disk resources in another resource group. Asigne uno de los siguientes conjuntos de permisos de rol:Assign one of the following set of role permissions:

Azure Container InstancesAzure 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 AKS debe tener concedidos los permisos de Colaborador en el grupo de recursos de ACI.If you use Virtual Kubelet to integrate with AKS and choose to run Azure Container Instances (ACI) in resource group separate to the AKS cluster, the AKS service principal must be granted Contributor permissions on the ACI resource group.

Consideraciones adicionalesAdditional considerations

Cuando use entidades de servicio de AKS y Azure AD, tenga en cuenta lo siguiente.When using AKS and Azure AD service principals, keep the following considerations in mind.

  • La entidad de servicio para Kubernetes forma parte de la configuración del clúster.The service principal for Kubernetes is a part of the cluster configuration. Sin embargo, no use la identidad para implementar el clúster.However, don't use the identity to deploy the cluster.
  • De forma predeterminada, las credenciales de la entidad de servicio son válidas durante un año.By default, the service principal credentials are valid for one year. Puede actualizar o rotar las credenciales de la entidad de servicio en cualquier momento.You can update or rotate the service principal credentials at any time.
  • Cada entidad de servicio está asociada a una aplicación de Azure AD.Every service principal is associated with an Azure AD application. 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 ).The service principal for a Kubernetes cluster can be associated with any valid Azure AD application name (for example: https://www.contoso.org/example). La dirección URL de la aplicación no tiene por qué ser un punto de conexión real.The URL for the application doesn't have to be a real endpoint.
  • Al especificar el identificador de cliente, utilice el valor de appId.When you specify the service principal Client ID, use the value of the 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.On the agent node VMs in the Kubernetes cluster, the service principal credentials are stored in the file /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.When you use the az aks create command to generate the service principal automatically, the service principal credentials are written to the file ~/.azure/aksServicePrincipal.json on the machine used to run the command.
  • Si no pasa específicamente una entidad de servicio en comandos adicionales de la CLI de AKS, se usa la entidad de servicio predeterminada ubicada en ~/.azure/aksServicePrincipal.json.If you do not specifically pass a service principal in additional AKS CLI commands, the default service principal located at ~/.azure/aksServicePrincipal.json is used.
  • Opcionalmente, también puede quitar el archivo aksServicePrincipal.json y AKS creará una entidad de servicio.You can also optionally remove the aksServicePrincipal.json file, and AKS will create a new service principal.
  • Al eliminar un clúster de AKS creado mediante az aks create, no se elimina la entidad de servicio que se ha creado automáticamente.When you delete an AKS cluster that was created by az aks create, the service principal that was created automatically is not deleted.

    • Para eliminar la entidad de servicio, consulte el clúster servicePrincipalProfile.clientId y, después, elimínelo con az ad sp delete.To delete the service principal, query for your cluster servicePrincipalProfile.clientId and then delete with az ad sp delete. Reemplace los nombres de clúster y del grupo de recursos siguientes con los suyos propios.Replace the following resource group and cluster names with your own values:

      az ad sp delete --id $(az aks show -g myResourceGroup -n myAKSCluster --query servicePrincipalProfile.clientId -o tsv)

Solución de problemasTroubleshoot

La CLI de Azure almacena en caché las credenciales de la entidad de servicio para un clúster de AKS.The service principal credentials for an AKS cluster are cached by the Azure CLI. Si estas credenciales han expirado, encontrará errores al implementar clústeres de AKS.If these credentials have expired, you encounter errors deploying AKS clusters. 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é:The following error message when running az aks create may indicate a problem with the cached service principal credentials:

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 el comando siguiente:Check the age of the credentials file using the following command:

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.The default expiration time for the service principal credentials is one year. Si el archivo aksServicePrincipal.json tiene más de un año, elimine el archivo e intente volver a implementar un clúster de AKS.If your aksServicePrincipal.json file is older than one year, delete the file and try to deploy an AKS cluster again.

Pasos siguientesNext steps

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.For more information about Azure Active Directory service principals, see Application and service principal objects.

Para obtener información sobre cómo actualizar las credenciales, vea Actualizar o rotar las credenciales de una entidad de servicio en AKS.For information on how to update the credentials, see Update or rotate the credentials for a service principal in AKS.