Principais de serviço com o Serviço Kubernetes do Azure (AKS)Service principals with Azure Kubernetes Service (AKS)

Para interagir com APIs do Azure, um cluster do AKS requer um principal de serviço do Azure Active Directory (AD).To interact with Azure APIs, an AKS cluster requires an Azure Active Directory (AD) service principal. O principal de serviço é necessário para criar e gerir dinamicamente outros recursos do Azure como um balanceador de carga ou registo de contentor do Azure (ACR).The service principal is needed to dynamically create and manage other Azure resources such as an Azure load balancer or container registry (ACR).

Este artigo mostra como criar e utilizar um principal de serviço para os seus clusters do AKS.This article shows how to create and use a service principal for your AKS clusters.

Antes de começarBefore you begin

Para criar um principal de serviço do Azure AD, tem de ter permissões para registar uma aplicação no seu inquilino do Azure AD e para atribuir a aplicação a uma função na sua subscrição.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. Se não tiver as permissões necessárias, poderá ter de pedir ao administrador do Microsoft Azure AD ou da subscrição para atribuir as permissões necessárias ou pré-criar um principal de serviço para utilizar com o cluster do 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.

Se estiver a utilizar um principal de serviço do Azure AD com um diferente de inquilino, existem as considerações adicionais sobre as permissões disponíveis ao implementar o cluster.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. Não pode ter as permissões adequadas para ler e escrever informações de diretório.You may not have the appropriate permissions to read and write directory information. Para obter mais informações, consulte quais são as permissões de usuário padrão no Azure Active Directory?For more information, see What are the default user permissions in Azure Active Directory?

Também precisa da versão 2.0.59 da CLI do Azure ou posterior instalado e configurado.You also need the Azure CLI version 2.0.59 or later installed and configured. Executar az --version para localizar a versão.Run az --version to find the version. Se precisar de instalar ou atualizar, veja instalar a CLI do Azure.If you need to install or upgrade, see Install Azure CLI.

Criar e utilizar um principal de serviço automaticamenteAutomatically create and use a service principal

Quando cria um cluster do AKS no Azure portal ou utilizando o az aks criar comando, o Azure pode gerar automaticamente um principal de serviço.When you create an AKS cluster in the Azure portal or using the az aks create command, Azure can automatically generate a service principal.

No exemplo seguinte da CLI do Azure, não está especificado nenhum principal de serviço.In the following Azure CLI example, a service principal is not specified. Neste cenário, a CLI do Azure cria um principal de serviço para o cluster do AKS.In this scenario, the Azure CLI creates a service principal for the AKS cluster. Para concluir esta operação com êxito, a sua conta do Azure tem de ter os direitos adequados para criar um principal de serviço.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

Criar um principal de serviço manualmenteManually create a service principal

Para criar manualmente um principal de serviço com a CLI do Azure, utilize o az ad sp create-for-rbac comando.To manually create a service principal with the Azure CLI, use the az ad sp create-for-rbac command. No exemplo a seguir, o parâmetro --skip-assignment impede que sejam atribuídas atribuições predefinidas adicionais:In the following example, the --skip-assignment parameter prevents any additional default assignments being assigned:

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

O resultado será semelhante ao seguinte exemplo.The output is similar to the following example. Tome nota do seu appId e password.Make a note of your own appId and password. Estes valores serão utilizados quando criar um cluster do AKS na secção seguinte.These values are used when you create an AKS cluster in the next section.

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

Especificar um principal de serviço para um cluster do AKSSpecify a service principal for an AKS cluster

Para utilizar um principal de serviço existente quando criar um cluster do AKS com o criar az aks comando, utilize o --service-principal e --client-secret parâmetros para especificar o appId e password da saída do az ad sp create-for-rbac comando: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>

Se implementar um cluster do AKS com o portal do Azure, na página Autenticação da caixa de diálogo Criar cluster do Kubernetes, opte por Configurar principal de serviço.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. Selecione Utilizar existente e especifique os seguintes valores:Select Use existing, and specify the following values:

  • O ID de cliente do principal de serviço é o seu appIdService principal client ID is your appId
  • O Segredo do cliente do principal de serviço é o valor da palavra-passeService principal client secret is the password value

Imagem de navegação para o Azure Vote

Delegar o acesso a outros recursos do AzureDelegate access to other Azure resources

O principal de serviço para o cluster do AKS pode ser utilizado para aceder a outros recursos.The service principal for the AKS cluster can be used to access other resources. Por exemplo, se pretender implementar o seu cluster do AKS para uma sub-rede de rede virtual do Azure existente ou ligar para o Azure Container Registry (ACR), terá de delegar o acesso a esses recursos para o principal de serviço.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.

Delegar permissões, criar uma atribuição de função com o criação da atribuição de função de az comando.To delegate permissions, create a role assignment using the az role assignment create command. Atribuir o appId a um âmbito específico, tal como um grupo de recursos ou recurso de rede virtual.Assign the appId to a particular scope, such as a resource group or virtual network resource. Uma função, em seguida, define quais as permissões que o principal de serviço tem no recurso, conforme mostrado no exemplo a seguir: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

O --scope para um recurso tem de ser um ID de recurso completo, como /subscriptions/<guid>/resourceGroups/myResourceGroup ou /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

As secções seguintes detalham as delegações comuns que poderá ter de fazer.The following sections detail common delegations that you may need to make.

Registo de Contentores do AzureAzure Container Registry

Se utilizar o Azure Container Registry (ACR) como arquivo de imagem de contentor, tem de conceder permissões para o seu cluster do AKS ler e solicitar imagens.If you use Azure Container Registry (ACR) as your container image store, you need to grant permissions for your AKS cluster to read and pull images. O principal de serviço do AKS cluster deve ser delegado a leitor função no Registro.The service principal of the AKS cluster must be delegated the Reader role on the registry. Para obter passos detalhados, consulte acesso AKS de concessão para o ACR.For detailed steps, see Grant AKS access to ACR.

RedesNetworking

Pode utilizar as redes avançados em que a rede virtual e sub-rede ou endereços IP públicos são outro grupo de recursos.You may use advanced networking where the virtual network and subnet or public IP addresses are in another resource group. Atribua um conjunto de permissões de função seguinte:Assign one of the following set of role permissions:

  • Criar uma função personalizada e definir as seguintes permissões de função:Create a custom role and define the following role permissions:
    • Microsoft.Network/virtualNetworks/subnets/join/actionMicrosoft.Network/virtualNetworks/subnets/join/action
    • Microsoft.Network/virtualNetworks/subnets/readMicrosoft.Network/virtualNetworks/subnets/read
    • Microsoft.Network/virtualNetworks/subnets/writeMicrosoft.Network/virtualNetworks/subnets/write
    • Microsoft.Network/publicIPAddresses/join/actionMicrosoft.Network/publicIPAddresses/join/action
    • Microsoft.Network/publicIPAddresses/readMicrosoft.Network/publicIPAddresses/read
    • Microsoft.Network/publicIPAddresses/writeMicrosoft.Network/publicIPAddresses/write
  • Ou, atribuir os contribuinte de rede função incorporada na sub-rede na rede virtualOr, assign the Network Contributor built-in role on the subnet within the virtual network

ArmazenamentoStorage

Terá de aceder aos recursos de disco existentes noutro grupo de recursos.You may need to access existing Disk resources in another resource group. Atribua um conjunto de permissões de função seguinte:Assign one of the following set of role permissions:

Azure Container InstancesAzure Container Instances

Se usar o Virtual Kubelet para integrar com o AKS e optar por executar o Azure Container Instances (ACI) no grupo de recursos separados para o cluster do AKS, tem de ser concedido o principal de serviço do AKS contribuinte permissões no recurso do ACI grupo.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.

Considerações adicionaisAdditional considerations

Quando utilizar principais de serviço do AKS e do Microsoft Azure AD, tenha em atenção as seguintes considerações.When using AKS and Azure AD service principals, keep the following considerations in mind.

  • O principal de serviço para Kubernetes faz parte da configuração do cluster.The service principal for Kubernetes is a part of the cluster configuration. No entanto, não utilize a identidade para implementar o cluster.However, don't use the identity to deploy the cluster.
  • Por predefinição, as credenciais do principal de serviço são válidas durante um ano.By default, the service principal credentials are valid for one year. Pode atualizar ou rodar as credenciais do principal de serviço em qualquer altura.You can update or rotate the service principal credentials at any time.
  • Cada principal de serviço está associado a uma aplicação do Azure AD.Every service principal is associated with an Azure AD application. O principal de serviço de um cluster do Kubernetes pode ser associado a qualquer nome de aplicação do Microsoft Azure AD válido (por exemplo: 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). O URL para a aplicação não tem de ser um ponto final real.The URL for the application doesn't have to be a real endpoint.
  • Quando especificar o ID de Cliente do principal de serviço, utilize o valor de appId.When you specify the service principal Client ID, use the value of the appId.
  • No nó de agente VMs no cluster de Kubernetes, as credenciais do principal de serviço são armazenadas no arquivo. /etc/kubernetes/azure.jsonOn the agent node VMs in the Kubernetes cluster, the service principal credentials are stored in the file /etc/kubernetes/azure.json
  • Quando utiliza a criar az aks comandos para gerar o principal de serviço automaticamente, o serviço de credenciais do principal são escritas no ficheiro ~/.azure/aksServicePrincipal.json na máquina utilizada para executar o 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.
  • Ao eliminar um cluster do AKS que foi criado pelo az aks criar, o principal de serviço que foi criado automaticamente não é eliminado.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 o principal de serviço, de consulta para o seu cluster servicePrincipalProfile.clientId e, em seguida, elimine com eliminação do az ad app.To delete the service principal, query for your cluster servicePrincipalProfile.clientId and then delete with az ad app delete. Substitua os seguintes nomes de cluster e de grupo de recursos com seus próprios valores: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)
      

Resolução de problemasTroubleshoot

As credenciais do principal de serviço para um cluster do AKS são colocadas em cache pela CLI do Azure.The service principal credentials for an AKS cluster are cached by the Azure CLI. Se estas credenciais tiverem expirado, encontrar erros ao implementar clusters do AKS.If these credentials have expired, you encounter errors deploying AKS clusters. A seguinte mensagem de erro quando em execução az aks criar pode indicar um problema com as credenciais do principal de serviço em cache: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'.

Verifique a idade do arquivo de credenciais com o seguinte comando:Check the age of the credentials file using the following command:

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

A hora de expiração predefinida para as credenciais do principal de serviço é um ano.The default expiration time for the service principal credentials is one year. Se sua aksServicePrincipal.json ficheiro é mais antigo do que um ano, elimine o ficheiro e tente implementar novamente um cluster do AKS.If your aksServicePrincipal.json file is older than one year, delete the file and try to deploy an AKS cluster again.

Passos seguintesNext steps

Para obter mais informações sobre principais de serviço do Azure Active Directory, consulte aplicativos e objetos de principal de serviço.For more information about Azure Active Directory service principals, see Application and service principal objects.

Para obter informações sobre como atualizar as credenciais, consulte atualizar ou rodar as credenciais para um principal de serviço no AKS.For information on how to update the credentials, see Update or rotate the credentials for a service principal in AKS.