Implantar e configurar a federação de identidades de carga de trabalho no Kubernetes habilitado para Azure Arc (visualização)

Artigo
11/19/2024

Você pode habilitar o recurso de identidade de carga de trabalho em um cluster Kubernetes habilitado para Azure Arc usando a CLI do Azure. O processo segue estas etapas de alto nível:

Habilite o recurso de identidade de carga de trabalho em um cluster Kubernetes habilitado para Arc novo ou existente.
Crie uma identidade gerenciada (ou registro de aplicativo) e uma conta de serviço do Kubernetes.
Configure a identidade gerenciada para federação de tokens.
Configure anotações de conta de serviço e rótulos de pod de aplicativo para usar a identidade da carga de trabalho.
Configure as configurações de identidade da carga de trabalho no cluster do Kubernetes.
Desative a identidade da carga de trabalho no cluster.

Para obter uma visão geral desse recurso, consulte Federação de identidade de carga de trabalho no Kubernetes habilitado para Arco do Azure (visualização).

Importante

O recurso de federação de identidade de carga de trabalho do Azure Arc está atualmente em visualização. Veja Termos de Utilização Complementares da Pré-visualizações do Microsoft Azure para obter os termos legais que se aplicam às funcionalidades do Azure que estão na versão beta, na pré-visualização ou que ainda não foram lançadas para disponibilidade geral.

Gorjeta

Este artigo descreve as etapas necessárias para implantar e configurar a identidade da carga de trabalho em um cluster Kubernetes habilitado para Arc. Para saber como habilitar a identidade da carga de trabalho em outros tipos de clusters, consulte os seguintes artigos:

Pré-requisitos

A identidade da carga de trabalho para clusters Kubernetes habilitados para Azure Arc (visualização) é suportada nas seguintes distribuições Kubernetes:
- Cluster Ubuntu Linux executando K3s
- AKS no Edge Essentials
- AKS em HCI 23H2

Para usar o recurso de identidade de carga de trabalho, você deve ter a CLI do Azure versão 2.64 ou superior e az connectedk8s a versão 1.10.0 ou superior. Certifique-se de atualizar sua versão da CLI do Azure antes de atualizar sua az connectedk8s versão. Se você usar o Azure Cloud Shell, a versão mais recente da CLI do Azure será instalada.

Habilitar a identidade da carga de trabalho no cluster

Siga as etapas apropriadas para habilitar o recurso de identidade de carga de trabalho para um novo cluster Kubernetes habilitado para Arc ou para um existente. Em ambos os casos, certifique-se de substituir o nome e o grupo de recursos pelos seus valores e configure os parâmetros conforme desejado.

Parâmetro	Descrição	Obrigatório
`--enable-oidc-issuer`	Gera e hospeda a URL do emissor OIDC, que é uma URL acessível publicamente que permite que o servidor de API encontre chaves de assinatura públicas para verificar tokens.	Necessário
`--enable-workload-identity`	Instala um webhook de admissão mutante que projeta um token de conta de serviço assinado em um caminho conhecido e injeta variáveis de ambiente relacionadas à autenticação nos pods do aplicativo com base nas configurações da conta de serviço anotada. Para um novo cluster, se esse parâmetro não estiver habilitado, você deverá montar um volume projetado em um caminho conhecido que exponha o token de conta de serviço assinado ao caminho.	Opcional

Definir variáveis de ambiente

Por conveniência, as variáveis de ambiente definidas abaixo são referenciadas nos exemplos deste artigo. Substitua estes valores pelos seus próprios valores:

export RESOURCE_GROUP="myRG"
export LOCATION="eastus"
export CLUSTER_NAME="mycluster"
export SERVICE_ACCOUNT_NAMESPACE="myKubernetesnamespace"
export SERVICE_ACCOUNT_NAME="mysa"
export SUBSCRIPTION="$(az account show --query id --output tsv)"
export USER_ASSIGNED_IDENTITY_NAME="myIdentity"
export FEDERATED_IDENTITY_CREDENTIAL_NAME="myFedIdentity"

Para criar um cluster habilitado para Azure Arc com a identidade de carga de trabalho habilitada, use o seguinte comando:

az connectedk8s connect --name "${CLUSTER_NAME}" --resource-group "${RESOURCE_GROUP}" --enable-oidc-issuer –-enable-workload-identity

Para habilitar a identidade da carga de trabalho em um cluster Kubernetes habilitado para Arc existente, use o update comando.

az connectedk8s update --name "${CLUSTER_NAME}" --resource-group "${RESOURCE_GROUP}" --enable-oidc-issuer --enable-workload-identity

Recuperar o URL do emissor OIDC

Procure o URL do emissor OIDC e salve-o em uma variável ambiental. Este URL do emissor será utilizado no passo seguinte.

export OIDC_ISSUER="$(az connectk8s show --name "${CLUSTER_NAME}" --resource-group "${RESOURCE_GROUP}" \ 
    --query "oidcIssuerProfile.issuerUrl" \  
    --output tsv)"

Para exibir a variável de ambiente, digite echo ${OIDC_ISSUER}. A variável de ambiente deve conter a URL do emissor, semelhante ao exemplo a seguir:

https://northamerica.oic.prod-arc.azure.com/00000000-0000-0000-0000-000000000000/12345678-1234-1234-1234-123456789123/

Por padrão, o emissor é definido para usar a URL https://{region}.oic.prod-arc.azure.com/{tenant_id}/{uuid}base, onde o valor for corresponde ao local onde o cluster Kubernetes habilitado para {region} Arc é criado. O valor {uuid} representa a chave OpenID Connect (OIDC), que é um guid imutável gerado aleatoriamente para cada cluster.

Criar uma identidade gerenciada

Use o comando para criar uma identidade gerenciada atribuída pelo az identity create usuário. Com a identidade de carga de trabalho, uma relação de confiança é estabelecida entre o token da identidade de gerenciamento atribuída pelo usuário e o token de conta de serviço do cluster Kubernetes.

az identity create \ 
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --location "${LOCATION}" \
    --subscription "${SUBSCRIPTION}"

Buscar o ID do cliente da identidade gerenciada e armazenar em uma variável de ambiente.

export USER_ASSIGNED_CLIENT_ID="$(az identity show \ 
    --resource-group "${RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query 'clientId' \
    --output tsv)"

Criar uma conta de serviço do Kubernetes

Crie uma conta de serviço Kubernetes e anote-a com o ID do cliente da identidade gerenciada criada na etapa anterior. Os tokens assinados associados à conta de serviço do Kubernetes serão trocados por um token Microsoft Entra ID depois que a relação de confiança for estabelecida entre os dois.

Aplique o seguinte trecho do YAML para criar uma conta de serviço com anotação de identidade de carga de trabalho adicionada.

apiVersion: v1 
kind: ServiceAccount 
metadata: 
  annotations: 
    azure.workload.identity/client-id: "${USER_ASSIGNED_CLIENT_ID}" 
  name: "${SERVICE_ACCOUNT_NAME}" 
  namespace: "${SERVICE_ACCOUNT_NAMESPACE}"

Criar a credencial de identidade federada

Use o az identity federated-credential create comando para criar a credencial de identidade federada entre a identidade gerenciada, o emissor da conta de serviço e o assunto. Esta etapa estabelece a relação de confiança entre o cluster do Kubernetes e o Microsoft Entra para troca de tokens. Para obter mais informações sobre credenciais de identidade federada no Microsoft Entra, consulte Visão geral das credenciais de identidade federada no Microsoft Entra ID.

az identity federated-credential create \ 
    --name ${FEDERATED_IDENTITY_CREDENTIAL_NAME} \ 
    --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \ 
    --resource-group "${RESOURCE_GROUP}" \ 
    --issuer "${OIDC_ISSUER}" \ 
    --subject system:serviceaccount:"${SERVICE_ACCOUNT_NAMESPACE}":"${SERVICE_ACCOUNT_NAME}" \ 
    --audience api://AzureADTokenExchange

Nota

Depois que a credencial de identidade federal é adicionada, leva alguns segundos para se propagar. Se uma solicitação de token for feita imediatamente após a adição da credencial de identidade federada, a solicitação poderá falhar até que o cache seja atualizado. Para evitar esse problema, adicione um ligeiro atraso em seus scripts depois de adicionar a credencial de identidade federada.

Configurar anotações de conta de serviço e rótulos de pod

As seguintes anotações de conta de serviço e pod estão disponíveis para configurar a identidade da carga de trabalho com base nos requisitos do aplicativo. O rótulo do pod especificado abaixo é obrigatório se –-enable-workload-identity estiver definido como true.

Anotações de conta de serviço

Todas as anotações de conta de serviço são opcionais. Se uma anotação não for especificada, o valor padrão será usado.

Anotação	Description	Predefinido
`azure.workload.identity/client-id`	ID do cliente do aplicativo Microsoft Entra a ser usado com o pod.
`azure.workload.identity/tenant-id`	ID do locatário do Azure onde o aplicativo Microsoft Entra está registrado.	`AZURE_TENANT_ID` variável de ambiente extraída de `azure-wi-webhook-config` ConfigMap.
`azure.workload.identity/service-account-token-expiration`	`expirationSeconds` para o token de conta de serviço projetado. Configure para evitar o tempo de inatividade causado por erros durante a atualização do token da conta de serviço. A expiração do token da conta de serviço do Kubernetes não está correlacionada com os tokens do Microsoft Entra. Os tokens Microsoft Entra expiram 24 horas após serem emitidos.	3600 (o intervalo suportado é 3600-86400)

Rótulos de pod

Anotação	Description	Valor recomendado	Necessário
`azure.workload.identity/use`	Obrigatório na especificação do modelo pod. Se `–-enable-workload-identity` estiver definido como `true`, somente pods com esse rótulo serão mutados pelo webhook de admissão mutante para injetar as variáveis de ambiente específicas do Azure e o volume de token de conta de serviço projetado.	`true`	Sim

Anotações do pod

Todas as anotações pod são opcionais. Se uma anotação não for especificada, o valor padrão será usado.

Anotação	Description	Predefinido
`azure.workload.identity/service-account-token-expiration`	`expirationSeconds` para o token de conta de serviço projetado. Configure para evitar o tempo de inatividade causado por erros durante a atualização do token da conta de serviço. A expiração do token da conta de serviço do Kubernetes não está correlacionada com os tokens do Microsoft Entra. Os tokens Microsoft Entra expiram 24 horas após serem emitidos.	3600 (o intervalo suportado é 3600-86400)
`azure.workload.identity/skip-containers`	Representa uma lista separada por ponto-e-vírgula de contêineres para ignorar a adição do volume de token de conta de serviço projetado. Por exemplo: `container1;container2`.	Por padrão, o volume de token de conta de serviço projetado é adicionado a todos os contêineres se o pod estiver rotulado com `azure.workload.identity/use: true`.

Definir configurações de identidade de carga de trabalho no cluster do Kubernetes

O servidor de API no cluster Kubernetes precisa ser configurado para emitir tokens de conta de serviço que incluam a URL do emissor OIDC acessível publicamente (para que o Entra saiba onde encontrar as chaves públicas para validar o token).

Para configurar as configurações de identidade da carga de trabalho no Ubuntu Linux com K3s, siga as etapas abaixo para concluir a configuração:

Crie o arquivo de configuração do k3s.

Edite /etc/rancher/k3s/config.yaml para adicionar estas configurações:

   `kube-apiserver-arg:  
     - 'service-account-issuer=${OIDC_ISSUER}'
     - 'service-account-max-token-expiration=24h'`

Salve o config.yaml.
Reinicie o servidor de API do k3s usando o comando systemctl restart k3s.

Recomendamos alternar as chaves da conta de serviço com frequência. Para obter mais informações, consulte Rotação de chaves do emissor da conta de serviço.

Desabilitar a identidade da carga de trabalho

Para desabilitar o recurso de identidade de carga de trabalho em um cluster Kubernetes habilitado para Azure Arc, execute o seguinte comando:

az connectedk8s update
    --resource-group "${RESOURCE_GROUP}"
    --name "${CLUSTER_NAME}"
    --disable-workload-identity

Próximos passos

Explore um exemplo para configurar um aplicativo para usar a identidade da carga de trabalho.

Partilhar via