Preparar um host e uma identidade de nó flex (versão prévia)

Importante

As funcionalidades em versão preliminar do AKS estão disponíveis de forma optativa e por autoatendimento. As versões prévias são fornecidas “no estado em que se encontram” e “conforme disponíveis” e são excluídas dos contratos de nível de serviço e da garantia limitada. As versões prévias do AKS são parcialmente cobertas pelo suporte ao cliente em uma base de melhor esforço. Dessa forma, esses recursos não são destinados ao uso em produção. Para obter mais informações, consulte os seguintes artigos:

Antes de adicionar um host Linux como um nó flex, prepare o host, configure a identidade selecionada durante o planejamento e conceda a essa identidade acesso ao cluster do AKS (Serviço de Kubernetes do Azure).

Neste artigo você:

  • Examine os requisitos de host e, em seguida, provisione ou selecione o host Linux e sua identidade de Azure.
  • Prepare e inspecione o host e registre os valores usados pelo fluxo de trabalho do anexo.
  • Atribua o acesso à identidade no escopo do cluster do AKS e verifique essa identidade.

Execute os comandos de gerenciamento neste artigo em um ambiente Bash compatível com Linux que tenha as ferramentas necessárias e o acesso à rede. Este artigo se refere a esse ambiente como seu ambiente Bash. A máquina separada que ingressa no cluster é o host do nó flex; execute comandos nela somente quando uma etapa instruir você explicitamente a fazer isso.

Antes de começar

Carregar o ambiente de implantação

Inicie uma nova sessão bash, identifique o arquivo de ambiente do artigo de planejamento e carregue-o. Substitua <deployment-name> pelo rótulo de implantação.

export FLEXNODE_DEPLOYMENT="<deployment-name>"
export FLEXNODE_ENV_FILE="${HOME}/.config/aks-flexnode/${FLEXNODE_DEPLOYMENT}.env"
test -s "${FLEXNODE_ENV_FILE}"
source "${FLEXNODE_ENV_FILE}"

O arquivo de ambiente fornece os valores de implantação compartilhados que este artigo lê, incluindo WORK_DIR, o diretório em seu ambiente Bash em que este artigo armazena downloads e arquivos gerados. Por padrão, WORK_DIR é ~/.local/share/aksflexnode/<deployment-name>. O artigo deriva todas as outras variáveis necessárias. Se você ainda não criou o arquivo de ambiente, conclua Planejar a implantação dos nós flexíveis primeiro.

Se o arquivo não for encontrado ou não puder ser carregado, pare e retorne ao artigo de planejamento antes de continuar.

Defina a assinatura ativa e confirme o cluster selecionado:

az account set --subscription "${SUBSCRIPTION_ID}"

az aks show \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --query "{Name:name,ResourceId:id,ProvisioningState:provisioningState}" \
    --output table

Continue quando o ID do recurso corresponder a AKS_RESOURCE_ID e o estado de provisionamento for Succeeded.

1. Examine os requisitos do host

Use um host dedicado que atenda aos seguintes requisitos:

  • Um host AMD64 ou ARM64 executando o Ubuntu 24.04 LTS, Azure Linux 3.x ou RHEL (Red Hat Enterprise Linux) 9 ou 10.
  • Um nome de host exclusivo que é um nome de subdomínio DNS válido. O agente o converte para minúsculas quando registra o nó.
  • Pelo menos quatro vCPUs e pelo menos 8 GiB gratuitos em /var/lib.
  • Uma conta SSH com acesso raiz ou sem sudo senha no host.
  • Acesso de rede ao servidor da API do AKS, ao Azure Resource Manager, ao Microsoft Entra ID, à versão do nó flexível selecionada, ao espelho de artefatos e aos registros de contêineres necessários.
  • Conectividade de Camada 3 existente entre a rede do host do nó flex e a rede de nós gerenciada pelo AKS. O host e o cluster do AKS não precisam estar na mesma região Azure.

Seu ambiente Bash também deve conseguir se conectar ao host do nó flex via SSH. Um endereço IP público não é necessário quando você tem outro caminho de gerenciamento aprovado.

2. Provisionar ou selecionar o host e a identidade

Preencha apenas a seção correspondente à opção de identidade selecionada em Conceitos de identidade e acesso para nós flex. Não configure mais de um modo de identidade de Azure durável para o mesmo host.

Dica

Conectando uma máquina fora do Azure? Use uma identidade gerenciada do Azure Arc se o computador já estiver habilitado para o Arc, ou use uma entidade de serviço. Use identidade gerenciada da VM do Azure somente quando o host do nó flex for uma VM do Azure.

Defina os caminhos de chave SSH usados por cada opção de identidade:

export SSH_PRIVATE_KEY_PATH="<path-to-private-key>"
export SSH_PUBLIC_KEY_PATH="<path-to-public-key>"

Cada opção de identidade também estabelece dois endereços de host. FLEX_HOST_SSH_TARGET é o endereço usado pelo seu ambiente bash. FLEX_HOST_PRIVATE_IP é o endereço de host acessível da rede de nós gerenciada pelo AKS. Confirme com o administrador de rede que FLEX_HOST_PRIVATE_IP pertence a FLEX_HOST_SUBNET_CIDR e é o endereço que pode ser acessado a partir da rede de nós gerenciada pelo AKS. Não use um endereço público separado ou um endereço apenas para gerenciamento como endereço do nó flex.

Usar uma identidade gerenciada Azure Arc

Use esta opção para um host que já esteja conectado ao Azure Arc. Se necessário, siga Conectar máquinas híbridas com servidores habilitados para Azure Arc.

Defina os valores de recurso do Arc e os endereços de host:

export ARC_RESOURCE_GROUP="<arc-machine-resource-group>"
export ARC_MACHINE_NAME="<arc-machine-name>"
export FLEX_HOST_SSH_TARGET="<admin-user>@<reachable-host-address>"
export FLEX_HOST_PRIVATE_IP="<private-ip-reachable-from-aks>"

Recupere a ID do recurso, o status da conexão e a ID do objeto principal:

ARC_RESOURCE_ID="/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${ARC_RESOURCE_GROUP}/providers/Microsoft.HybridCompute/machines/${ARC_MACHINE_NAME}"
export ARC_RESOURCE_ID

HOST_PRINCIPAL_OBJECT_ID="$(az resource show \
    --ids "${ARC_RESOURCE_ID}" \
    --query identity.principalId \
    --output tsv)"
export HOST_PRINCIPAL_OBJECT_ID

az resource show \
    --ids "${ARC_RESOURCE_ID}" \
    --query "{Name:name,Status:properties.status,IdentityType:identity.type,PrincipalId:identity.principalId}" \
    --output yaml

Continue quando Status estiver Connected e PrincipalId estiver preenchido.

Verifique o agente do Computador Conectado e o Serviço de Metadados da Instância Híbrida no host:

ssh -i "${SSH_PRIVATE_KEY_PATH}" "${FLEX_HOST_SSH_TARGET}" \
    'sudo azcmagent show && systemctl is-active himdsd'

Confirme se azcmagent show informa a mesma ID da assinatura, o mesmo grupo de recursos e o mesmo nome da máquina que ARC_RESOURCE_ID, ARC_RESOURCE_GROUP e ARC_MACHINE_NAME. Confirme também se himdsd está ativo. Se o recurso não corresponder, interrompa e corrija os valores de recurso do Arc antes de atribuir acesso.

Registre os valores de Arc e de identidade:

set_flexnode_env ARC_RESOURCE_GROUP "${ARC_RESOURCE_GROUP}"
set_flexnode_env ARC_MACHINE_NAME "${ARC_MACHINE_NAME}"
set_flexnode_env ARC_RESOURCE_ID "${ARC_RESOURCE_ID}"
set_flexnode_env FLEX_HOST_SSH_TARGET "${FLEX_HOST_SSH_TARGET}"
set_flexnode_env FLEX_HOST_PRIVATE_IP "${FLEX_HOST_PRIVATE_IP}"
set_flexnode_env HOST_PRINCIPAL_OBJECT_ID "${HOST_PRINCIPAL_OBJECT_ID}"
set_flexnode_env HOST_IDENTITY_CLIENT_ID ""

Usar uma entidade de serviço

Use essa opção para outra máquina virtual com suporte ou host bare-metal. Prefira uma credencial de certificado em vez de um segredo de cliente de longa duração. As etapas a seguir criam um aplicativo dedicado e uma entidade de serviço com um certificado autoassinado para avaliação. Eles não criam um segredo do cliente nem atribuem uma função Azure. Você concede acesso ao cluster AKS de destino na etapa 4.

Antes de continuar:

  • Instale o OpenSSL em seu ambiente Bash e use uma CLI do Azure atualizada que dê suporte a az login --certificate.
  • Entre com uma conta que possa registrar aplicativos e criar entidades de serviço no locatário Microsoft Entra associado à assinatura de destino. A propriedade de uma assinatura do Azure, por si só, não concede essas permissões de diretório. Se o locatário restringir o registro de aplicativo, peça ajuda ao administrador do locatário. Consulte Criar uma entidade de serviço Azure com o CLI do Azure.
  • Confirme se sua organização permite certificados autoassinados para avaliação. Para uma identidade aprovada existente, use a ID do locatário, a ID do cliente do aplicativo, a ID do objeto da entidade de serviço e o arquivo PEM protegido e pule para Registrar os valores da entidade de serviço e do host.

Não armazene a credencial, a chave privada ou o caminho da credencial no arquivo de ambiente compartilhado. Não imprima o arquivo PEM ou inclua-o no controle do código-fonte. O arquivo PEM contém uma chave privada não criptografada para que o agente possa se autenticar sem um prompt de senha interativo. Proteja-o com permissões de arquivo e controles de acesso de host aprovados.

Criar entidade de serviço baseada em certificado

Execute esses comandos em seu ambiente Bash enquanto estiver conectado com sua conta de operador.

  1. Confirme a assinatura, o locatário e a conta conectada.

    az account set --subscription "${SUBSCRIPTION_ID}"
az account show \
    --query "{SubscriptionId:id,TenantId:tenantId,Account:user.name}" \
    --output table

SP_TENANT_ID="$(az account show --query tenantId --output tsv)"
export SP_TENANT_ID

    Continue apenas quando a assinatura e o locatário forem os destinos pretendidos.

  2. Escolha um nome de exibição de aplicativo exclusivo e crie um diretório de credencial protegido.

    export SP_DISPLAY_NAME="aks-flexnode-${FLEXNODE_DEPLOYMENT}-$(date -u +%Y%m%dT%H%M%SZ)"
install -d -m 0700 "${WORK_DIR:?Load the deployment environment first.}"
SP_CREDENTIAL_DIR="$(mktemp -d "${WORK_DIR}/sp-credential.XXXXXXXX")"
export SP_CREDENTIAL_DIR
export SP_CLIENT_CERTIFICATE_FILE="${SP_CREDENTIAL_DIR:?Credential directory wasn't created.}/sp-client.pem"

  3. Crie um certificado de 30 dias e um arquivo PEM combinado que contenha o certificado e a chave privada.

    (
    set -e
    umask 077

    openssl req -x509 -newkey rsa:2048 -sha256 -days 30 -nodes \
        -keyout "${SP_CREDENTIAL_DIR}/sp-client.key" \
        -out "${SP_CREDENTIAL_DIR}/sp-client.crt" \
        -subj "/CN=${SP_DISPLAY_NAME}"

    cat "${SP_CREDENTIAL_DIR}/sp-client.crt" \
        "${SP_CREDENTIAL_DIR}/sp-client.key" \
        > "${SP_CLIENT_CERTIFICATE_FILE}"
    chmod 0600 "${SP_CLIENT_CERTIFICATE_FILE}"
    rm -f "${SP_CREDENTIAL_DIR}/sp-client.key"
)

openssl x509 \
    -in "${SP_CREDENTIAL_DIR}/sp-client.crt" \
    -noout -subject -dates
stat -c '%a %n' "${SP_CLIENT_CERTIFICATE_FILE}"

    Interrompa se a criação do certificado falhar. Confirme se as permissões PEM são 600. A validade de 30 dias é para avaliação, não para uma política de rotação. Se o host permanecer conectado, substitua a credencial de acordo com o processo aprovado antes que expire.

  4. Crie o aplicativo e a entidade de serviço carregando apenas o certificado público.

    SP_CLIENT_ID="$(az ad sp create-for-rbac \
    --name "${SP_DISPLAY_NAME}" \
    --cert "@${SP_CREDENTIAL_DIR}/sp-client.crt" \
    --query appId \
    --output tsv)"
export SP_CLIENT_ID

    Continue apenas quando o comando for executado com sucesso e retornar um ID do cliente da aplicação. O comando pode relatar que ajustou a data de término da credencial para corresponder à expiração do certificado. Não adicione --role ou --scopes; a atribuição de função posterior é limitada ao cluster do AKS. Não execute a criação novamente para um aplicativo existente para girar as credenciais.

  5. Recupere a ID do objeto da entidade de serviço e inspecione as credenciais registradas.

    SP_OBJECT_ID="$(az ad sp show \
    --id "${SP_CLIENT_ID}" \
    --query id \
    --output tsv)"
export SP_OBJECT_ID

az ad sp show \
    --id "${SP_CLIENT_ID}" \
    --query "{ClientId:appId,ServicePrincipalObjectId:id}" \
    --output table

az ad app show \
    --id "${SP_CLIENT_ID}" \
    --query "{ClientId:appId,PasswordCredentials:length(passwordCredentials),Certificates:keyCredentials[].{KeyId:keyId,Expires:endDateTime}}" \
    --output json

    Confirme se o ID do objeto do service principal está preenchido, se ambos os IDs de cliente são iguais SP_CLIENT_ID, se PasswordCredentials é 0, e se há exatamente um certificado registrado com a data de expiração esperada. Se a replicação de diretório atrasar a pesquisa, aguarde brevemente e repita a pesquisa em vez de criar outro aplicativo.

Para um teste apenas de credenciais, execute somente a verificação de autenticação por certificado em Verificar um principal de serviço. Você não precisa atribuir uma função Azure ou preparar um host para essa verificação. Quando o teste for concluído, exclua o aplicativo de teste dedicado e a credencial local.

Anote os valores de service principal e do host

Defina os endereços do host. Se você selecionou uma identidade existente, primeiro defina SP_TENANT_ID, SP_CLIENT_ID e SP_OBJECT_ID com seus identificadores.

export FLEX_HOST_SSH_TARGET="<admin-user>@<reachable-host-address>"
export FLEX_HOST_PRIVATE_IP="<private-ip-reachable-from-aks>"

: "${SP_TENANT_ID:?Set the Microsoft Entra tenant ID.}"
: "${SP_CLIENT_ID:?Set the application client ID.}"
: "${SP_OBJECT_ID:?Set the service principal object ID.}"
export HOST_IDENTITY_CLIENT_ID=""
export HOST_PRINCIPAL_OBJECT_ID="${SP_OBJECT_ID}"

set_flexnode_env FLEX_HOST_SSH_TARGET "${FLEX_HOST_SSH_TARGET}"
set_flexnode_env FLEX_HOST_PRIVATE_IP "${FLEX_HOST_PRIVATE_IP}"
set_flexnode_env SP_TENANT_ID "${SP_TENANT_ID}"
set_flexnode_env SP_CLIENT_ID "${SP_CLIENT_ID}"
set_flexnode_env SP_OBJECT_ID "${SP_OBJECT_ID}"
set_flexnode_env HOST_IDENTITY_CLIENT_ID "${HOST_IDENTITY_CLIENT_ID}"
set_flexnode_env HOST_PRINCIPAL_OBJECT_ID "${HOST_PRINCIPAL_OBJECT_ID}"

SP_OBJECT_ID é a ID do objeto do aplicativo empresarial, também chamado de ID do objeto da entidade de serviço. Não é o identificador de objeto do registro de aplicativo. Confirme que SP_CLIENT_ID, SP_OBJECT_ID e o certificado pertencem à mesma entidade de serviço.

Bootstrap mapeia SP_TENANT_ID e SP_CLIENT_ID para azure.servicePrincipal.tenantId e azure.servicePrincipal.clientId na configuração do agente gerado. SP_OBJECT_ID é usado para a atribuição de função do Azure, não como a ID de cliente do agente. Para o campo de arquivo de certificado, a forma de configuração redigida completa e os comandos de verificação segura, confira Inspecionar a configuração da entidade de serviço renderizada.

Mantenha o arquivo PEM protegido para verificação de identidade e inicialização do host. Disponibilize-o no host por meio do processo de gerenciamento de credenciais aprovado antes do anexo. Registre sua localização por meio do processo de gerenciamento de credenciais aprovado, não no arquivo de ambiente compartilhado. Continue com Preparar e inspecionar o host e, em seguida, atribua a função AKS.

Usar uma identidade gerenciada de máquina virtual Azure

Use essa opção para uma VM Azure. Crie uma VM seguindo o Início Rápido: criar uma máquina virtual linux com o CLI do Azure ou selecionar uma VM existente. Coloque a VM na rede de host do nó flex planejada para essa implantação. Você não precisa de um endereço IP público quando seu ambiente bash tiver outro caminho SSH aprovado.

Defina os valores da VM:

export VM_RESOURCE_GROUP="<vm-resource-group>"
export VM_NAME="<vm-name>"
export VM_ADMIN_USER="<vm-admin-user>"

Recupere a ID do recurso da VM e os endereços do host. O destino SSH usa o endereço IP público quando a VM tem um e o endereço privado, caso contrário:

VM_RESOURCE_ID="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query id \
    --output tsv)"
export VM_RESOURCE_ID

FLEX_HOST_PRIVATE_IP="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --show-details \
    --query privateIps \
    --output tsv)"
export FLEX_HOST_PRIVATE_IP

VM_PUBLIC_IP="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --show-details \
    --query publicIps \
    --output tsv)"
export VM_PUBLIC_IP

export FLEX_HOST_SSH_TARGET="${VM_ADMIN_USER}@${VM_PUBLIC_IP:-${FLEX_HOST_PRIVATE_IP}}"

Confirme o endereço privado retornado para a VM:

az vm list-ip-addresses \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query "[0].virtualMachine.{Name:name,PrivateAddresses:network.privateIpAddresses}" \
    --output table

Continue apenas quando FLEX_HOST_PRIVATE_IP contiver um único endereço privado que pertença a FLEX_HOST_SUBNET_CIDR e possa ser acessado pela rede de nós gerenciada pelo AKS. Se Azure retornar mais de um endereço, defina FLEX_HOST_PRIVATE_IP como o endereço do nó flex planejado antes de continuar.

Se a VM não tiver endereço IP público, ou se o seu ambiente Bash acessar o host por meio de outro caminho de gerenciamento aprovado, defina FLEX_HOST_SSH_TARGET como o endereço ou nome do host que o seu ambiente Bash consegue acessar.

Conclua uma das seguintes opções de identidade gerenciada.

Identidade gerenciada atribuída pelo sistema

Habilite a identidade gerenciada atribuída pelo sistema:

az vm identity assign \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --output none

Recupere sua ID de objeto principal:

HOST_PRINCIPAL_OBJECT_ID="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query identity.principalId \
    --output tsv)"
export HOST_PRINCIPAL_OBJECT_ID

export HOST_IDENTITY_CLIENT_ID=""

Identidade gerenciada atribuída pelo usuário

Crie ou selecione uma identidade seguindo Gerenciar identidades gerenciadas atribuídas pelo usuário usando o CLI do Azure.

Defina os valores de identidade:

export USER_ASSIGNED_IDENTITY_RESOURCE_GROUP="<identity-resource-group>"
export USER_ASSIGNED_IDENTITY_NAME="<identity-name>"

Recupere os identificadores de identidade:

USER_ASSIGNED_IDENTITY_RESOURCE_ID="$(az identity show \
    --resource-group "${USER_ASSIGNED_IDENTITY_RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query id \
    --output tsv)"
export USER_ASSIGNED_IDENTITY_RESOURCE_ID

HOST_PRINCIPAL_OBJECT_ID="$(az identity show \
    --resource-group "${USER_ASSIGNED_IDENTITY_RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query principalId \
    --output tsv)"
export HOST_PRINCIPAL_OBJECT_ID

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

Atribua a identidade à VM:

az vm identity assign \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --identities "${USER_ASSIGNED_IDENTITY_RESOURCE_ID}" \
    --output none

Verifique se a VM lista a identidade selecionada:

az vm identity show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query "{Type:type,UserAssignedIdentities:userAssignedIdentities}" \
    --output yaml

Continue quando a saída incluir USER_ASSIGNED_IDENTITY_RESOURCE_ID.

Registrar a identidade da VM

Registre os valores de VM e identidade:

set_flexnode_env VM_RESOURCE_GROUP "${VM_RESOURCE_GROUP}"
set_flexnode_env VM_NAME "${VM_NAME}"
set_flexnode_env VM_ADMIN_USER "${VM_ADMIN_USER}"
set_flexnode_env VM_RESOURCE_ID "${VM_RESOURCE_ID}"
set_flexnode_env VM_PUBLIC_IP "${VM_PUBLIC_IP}"
set_flexnode_env FLEX_HOST_SSH_TARGET "${FLEX_HOST_SSH_TARGET}"
set_flexnode_env FLEX_HOST_PRIVATE_IP "${FLEX_HOST_PRIVATE_IP}"
set_flexnode_env HOST_PRINCIPAL_OBJECT_ID "${HOST_PRINCIPAL_OBJECT_ID}"
set_flexnode_env HOST_IDENTITY_CLIENT_ID "${HOST_IDENTITY_CLIENT_ID}"

3. Preparar e inspecionar o host

Conecte-se ao host:

ssh -i "${SSH_PRIVATE_KEY_PATH}" "${FLEX_HOST_SSH_TARGET}"

No host, inspecione o sistema operacional, a arquitetura, o nome do host, a CPU e o armazenamento disponível:

source /etc/os-release
printf 'Operating system: %s %s\n' "${NAME}" "${VERSION_ID}"
printf 'Architecture: %s\n' "$(uname -m)"
printf 'Host name: %s\n' "$(hostname)"
printf 'vCPUs: %s\n' "$(nproc)"
free -h
df -h /var/lib

Compare os resultados com os requisitos de host na etapa 1. Resolva qualquer diferença antes de continuar.

O script de inicialização requer curl, jqe tar no host e é interrompido se algum deles estiver ausente. O agente do nó flex instala os pacotes restantes de tempo de execução durante a inicialização.

Instale qualquer um dos três que sua imagem ainda não inclui:

# Ubuntu
sudo apt-get update && sudo apt-get install -y curl jq tar

# Azure Linux 3
sudo tdnf install -y curl jq tar

Saia da sessão de host:

exit

Leia o nome real do host Linux em seu ambiente Bash:

FLEX_HOST_NAME="$(ssh \
    -i "${SSH_PRIVATE_KEY_PATH}" \
    "${FLEX_HOST_SSH_TARGET}" \
    hostname)"
export FLEX_HOST_NAME

printf 'Flex host name: %s\n' "${FLEX_HOST_NAME}"

Continue quando o comando retornar o nome do host esperado.

Recupere o FQDN do servidor da API do AKS e verifique a resolução de nomes e a conectividade HTTPS a partir do host:

AKS_API_FQDN="$(az aks show \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --query '(privateFqdn || fqdn)' \
    --output tsv)"
export AKS_API_FQDN

ssh -i "${SSH_PRIVATE_KEY_PATH}" "${FLEX_HOST_SSH_TARGET}" \
    "getent hosts '${AKS_API_FQDN}' && \
    timeout 5 bash -c '</dev/tcp/${AKS_API_FQDN}/443'"

Se a resolução de nomes ou a conexão TCP falhar, corrija o DNS, o roteamento ou os controles de rede antes de continuar. Um cluster público do AKS usa seu FQDN de API pública. Para um cluster AKS privado, o ambiente Bash e a rede do host do nó flex devem resolver e rotear para o FQDN da API privada.

Registre os valores do host. O arquivo de ambiente compartilhado armazena caminhos e identificadores não seguros, não conteúdo de chave ou credencial.

set_flexnode_env SSH_PRIVATE_KEY_PATH "${SSH_PRIVATE_KEY_PATH}"
set_flexnode_env SSH_PUBLIC_KEY_PATH "${SSH_PUBLIC_KEY_PATH}"
set_flexnode_env FLEX_HOST_NAME "${FLEX_HOST_NAME}"

4. Atribuir a função AKS

O fluxo de trabalho de pré-visualização atual usa a função Colaborador do Serviço de Kubernetes do Azure no escopo exato do cluster AKS. Todas as três opções de identidade usam uma ID do objeto da entidade de serviço para o controle de acesso baseado em função do Azure. Use uma identidade de host dedicada e remova essa atribuição quando você remover o host conforme descrito em Gerenciar e remover nós flex no AKS.

Exiba a ID do objeto principal selecionada:

printf 'Principal object ID: %s\n' "${HOST_PRINCIPAL_OBJECT_ID}"

Continue apenas quando o valor estiver preenchido e pertencer à identidade da VM selecionada, à máquina Arc ou à entidade de serviço.

Verifique se a atribuição já existe:

az role assignment list \
    --assignee-object-id "${HOST_PRINCIPAL_OBJECT_ID}" \
    --scope "${AKS_RESOURCE_ID}" \
    --fill-principal-name false \
    --query "[?roleDefinitionName=='Azure Kubernetes Service Contributor Role'].{PrincipalId:principalId,Role:roleDefinitionName,Scope:scope}" \
    --output table

Se o comando não retornar linhas, crie a atribuição:

az role assignment create \
    --assignee-object-id "${HOST_PRINCIPAL_OBJECT_ID}" \
    --assignee-principal-type ServicePrincipal \
    --role "Azure Kubernetes Service Contributor Role" \
    --scope "${AKS_RESOURCE_ID}" \
    --output none

Execute o comando de lista novamente. Continue quando a ID da entidade e o escopo coincidirem com a identidade selecionada e AKS_RESOURCE_ID. A propagação da atribuição de função pode levar vários minutos.

5. Verificar a identidade selecionada

Antes de inicializar o host, confirme se a identidade selecionada pode se autenticar e ter acesso de leitura ao cluster AKS de destino exato. Preencha apenas a seção correspondente à sua opção de identidade.

Verificar uma identidade gerenciada do Azure Arc

No seu ambiente Bash, passe o ID não confidencial do recurso AKS para o servidor habilitado para Azure Arc:

[[ "${AKS_RESOURCE_ID}" == /subscriptions/*/providers/Microsoft.ContainerService/managedClusters/* ]]
printf -v AKS_RESOURCE_ID_QUOTED '%q' "${AKS_RESOURCE_ID}"

ssh -t \
    -i "${SSH_PRIVATE_KEY_PATH}" \
    "${FLEX_HOST_SSH_TARGET}" \
    "export AKS_RESOURCE_ID=${AKS_RESOURCE_ID_QUOTED}; \
    exec bash -l"

No servidor habilitado para Azure Arc, solicite um token Azure Resource Manager do HIMDS (Serviço de Metadados de Instância Híbrida) e use-o para ler o recurso do AKS. A leitura do token de desafio requer acesso root ou pertencer ao grupo himds:

TOKEN_URL="${IDENTITY_ENDPOINT:-http://127.0.0.1:40342/metadata/identity/oauth2/token}?api-version=2019-11-01&resource=https%3A%2F%2Fmanagement.azure.com"

CHALLENGE_TOKEN_PATH="$(curl --silent --show-error \
    --dump-header - \
    --output /dev/null \
    --header Metadata:true \
    "${TOKEN_URL}" |
    sed -n 's/^[Ww][Ww][Ww]-[Aa]uthenticate: Basic realm=//p' |
    tr -d '\r')"

test -n "${CHALLENGE_TOKEN_PATH}"
CHALLENGE_TOKEN="$(sudo cat "${CHALLENGE_TOKEN_PATH}")"

TOKEN="$(curl --fail --silent --show-error \
    --header Metadata:true \
    --header "Authorization: Basic ${CHALLENGE_TOKEN}" \
    "${TOKEN_URL}" |
    jq -r '.access_token // empty')"

test -n "${TOKEN}"

AKS_ARM_HTTP="$(curl --silent --show-error \
    --output /dev/null \
    --write-out '%{http_code}' \
    --header "Authorization: Bearer ${TOKEN}" \
    "https://management.azure.com${AKS_RESOURCE_ID}?api-version=2025-07-01")"

unset CHALLENGE_TOKEN TOKEN
printf 'AKS_ARM_HTTP=%s\n' "${AKS_ARM_HTTP}"

Resultado esperado: AKS_ARM_HTTP=200. Execute exit para deixar a sessão de servidor habilitada para Azure Arc.

Verificar um service principal

Em seu ambiente Bash, use o arquivo PEM combinado gerado nas etapas de preparação da entidade de serviço. Se você iniciou uma nova sessão ou selecionou uma identidade existente, defina seu caminho protegido novamente:

export SP_CLIENT_CERTIFICATE_FILE="<protected-path-to-sp-client.pem>"
test -s "${SP_CLIENT_CERTIFICATE_FILE}"

Pare se o arquivo não existir ou estiver vazio. Não adicione esse caminho ao arquivo de ambiente compartilhado.

Primeiro verifique a autenticação de certificado com um perfil de CLI do Azure isolado. O subshell remove seu cache temporário de token mesmo quando um comando falha e não altera seu login normal no CLI do Azure.

(
    set -e
    SP_AZURE_CONFIG_DIR="$(mktemp -d)"
    chmod 0700 "${SP_AZURE_CONFIG_DIR}"
    trap 'rm -rf -- "${SP_AZURE_CONFIG_DIR}"' EXIT
    export AZURE_CONFIG_DIR="${SP_AZURE_CONFIG_DIR}"

    az login \
        --service-principal \
        --username "${SP_CLIENT_ID}" \
        --certificate "${SP_CLIENT_CERTIFICATE_FILE}" \
        --tenant "${SP_TENANT_ID}" \
        --allow-no-subscriptions \
        --output none

    az account get-access-token \
        --resource https://management.azure.com/ \
        --query "{Tenant:tenant,ExpiresOn:expiresOn}" \
        --output table
)

Confirme se o Tenant corresponde a SP_TENANT_ID e se o token não expirou. Esse comando imprime apenas o locatário e a expiração, não o token de acesso. --allow-no-subscriptionspermite testar a autenticação antes de conceder acesso Azure. A autenticação bem-sucedida não prova a permissão para ler ou registrar-se no cluster do AKS.

Depois que a atribuição de função do AKS na etapa 4 for propagada, verifique o acesso ao cluster de destino exato:

(
    set -e
    SP_AZURE_CONFIG_DIR="$(mktemp -d)"
    chmod 0700 "${SP_AZURE_CONFIG_DIR}"
    trap 'rm -rf -- "${SP_AZURE_CONFIG_DIR}"' EXIT
    export AZURE_CONFIG_DIR="${SP_AZURE_CONFIG_DIR}"

    az login \
        --service-principal \
        --username "${SP_CLIENT_ID}" \
        --certificate "${SP_CLIENT_CERTIFICATE_FILE}" \
        --tenant "${SP_TENANT_ID}" \
        --output none

    az account set --subscription "${SUBSCRIPTION_ID}"

    az aks show \
        --resource-group "${RESOURCE_GROUP}" \
        --name "${CLUSTER_NAME}" \
        --query "{Name:name,ResourceId:id,ProvisioningState:provisioningState}" \
        --output table
)

Continue apenas quando o ID do recurso retornado corresponder a AKS_RESOURCE_ID e o estado de provisionamento for Succeeded. Se a autenticação for bem-sucedida, mas a solicitação ao cluster for negada, verifique o ID do objeto da entidade de serviço, o escopo exato da atribuição de função e a propagação antes de tentar novamente. Essa verificação prova que a entidade de serviço e seu certificado podem ler o cluster de destino. O host utiliza a credencial preparada em Anexar um nó flex a um cluster do AKS.

Verificar uma identidade gerenciada de uma máquina virtual do Azure

Em seu ambiente Bash, passe a ID de recurso AKS não secreta e a ID do cliente de identidade para a VM do Azure:

[[ "${AKS_RESOURCE_ID}" == /subscriptions/*/providers/Microsoft.ContainerService/managedClusters/* ]]
printf -v AKS_RESOURCE_ID_QUOTED '%q' "${AKS_RESOURCE_ID}"
printf -v HOST_IDENTITY_CLIENT_ID_QUOTED '%q' "${HOST_IDENTITY_CLIENT_ID}"

ssh -t \
    -i "${SSH_PRIVATE_KEY_PATH}" \
    "${FLEX_HOST_SSH_TARGET}" \
    "export AKS_RESOURCE_ID=${AKS_RESOURCE_ID_QUOTED}; \
    export HOST_IDENTITY_CLIENT_ID=${HOST_IDENTITY_CLIENT_ID_QUOTED}; \
    exec bash -l"

Na VM Azure, solicite um token Azure Resource Manager da identidade gerenciada selecionada e use-o para ler o recurso do AKS:

TOKEN_URL="http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fmanagement.azure.com%2F"

if [ -n "${HOST_IDENTITY_CLIENT_ID}" ]; then
    ENCODED_CLIENT_ID="$(jq -rn \
        --arg value "${HOST_IDENTITY_CLIENT_ID}" \
        '$value|@uri')"
    TOKEN_URL="${TOKEN_URL}&client_id=${ENCODED_CLIENT_ID}"
fi

TOKEN="$(curl --fail --silent --show-error \
    --header Metadata:true \
    "${TOKEN_URL}" |
    jq -r '.access_token // empty')"

test -n "${TOKEN}"

AKS_ARM_HTTP="$(curl --silent --show-error \
    --output /dev/null \
    --write-out '%{http_code}' \
    --header "Authorization: Bearer ${TOKEN}" \
    "https://management.azure.com${AKS_RESOURCE_ID}?api-version=2025-07-01")"

unset TOKEN
printf 'AKS_ARM_HTTP=%s\n' "${AKS_ARM_HTTP}"

Resultado esperado: AKS_ARM_HTTP=200. Para uma identidade atribuída pelo usuário, a solicitação usa o mesmo HOST_IDENTITY_CLIENT_ID que o fluxo de trabalho de anexação passa para --msi-client-id. Execute exit para sair da sessão de VM Azure.

O fluxo de trabalho de anexo executa a verificação final de ponta a ponta quando o host usa a identidade selecionada para registrar seu recurso Azure Machine.

Próximas etapas

Em seguida, anexe e verifique o host preparado como um Flex Node.

  • Última atualização em