Prepare um anfitrião e identidade de nó flexível (pré-visualização)

Importante

As funcionalidades de pré-visualização do AKS estão disponíveis num regime de autosserviço e de adesão voluntária. As visualizações prévias são fornecidas "como estão" e "conforme disponíveis" e são excluídas dos contratos de nível de serviço e da garantia limitada. As versões de pré-visualização do AKS são apenas parcialmente abrangidas pelo suporte ao cliente, na medida do possível. Assim sendo, estas funcionalidades não se destinam ao uso em produção. Para obter mais informações, consulte os seguintes artigos de suporte:

Antes de anexar um host Linux como nó flex, prepare o host, configure a identidade que selecionou durante o planeamento e conceda a essa identidade acesso ao cluster do Azure Kubernetes Service (AKS).

Neste artigo, você:

  • Revise os requisitos do host e depois provisione ou selecione o host Linux e a sua identidade Azure.
  • Prepare e inspecione o host, e registre os valores usados pelo fluxo de trabalho de anexos.
  • Atribui o acesso à identidade no âmbito do cluster AKS e verifica essa identidade.

Execute os comandos de gestão deste artigo num ambiente Bash compatível com Linux, que tenha as ferramentas necessárias e acesso à rede. Este artigo chama a esse ambiente o teu ambiente Bash. A máquina separada que se junta ao cluster é o anfitrião flex node; executa comandos lá apenas quando um step te indicar explicitamente para.

Antes de começares

Carregar o ambiente de implementação

Inicie uma nova sessão Bash, identifique o ficheiro de ambiente do artigo de planeamento 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 ficheiro de ambiente fornece os valores partilhados de implementação que este artigo lê, incluindo WORK_DIR, o diretório no seu ambiente Bash onde este artigo armazena os downloads e ficheiros gerados. Por padrão, WORK_DIR é ~/.local/share/aksflexnode/<deployment-name>. O artigo deriva quaisquer outras variáveis que necessite. Se ainda não criaste o ficheiro de ambiente, conclui primeiro Planear a implementação dos teus Flex Nodes.

Se o ficheiro não for encontrado ou não puder ser carregado, pare e volte ao artigo de planeamento antes de continuar.

Defina a subscrição 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

Continuar quando o ID do recurso coincidir com AKS_RESOURCE_ID e o estado de provisionamento for Succeeded.

1. Rever os requisitos do anfitrião

Use um alojamento dedicado que cumpra os seguintes requisitos:

  • Um host AMD64 ou ARM64 a correr Ubuntu 24.04 LTS, Azure Linux 3.x ou Red Hat Enterprise Linux (RHEL) 9 ou 10.
  • Um nome de host único que seja um subdomínio DNS válido. O agente converte-o para minúsculas quando regista o nó.
  • Pelo menos quatro vCPUs e pelo menos 8 GiB livres sob /var/lib.
  • Uma conta SSH com acesso root ou sem sudo palavra-passe no host.
  • Acesso de rede ao servidor da API do AKS, ao Azure Resource Manager, ao Microsoft Entra ID, à versão do nó flex selecionado e ao espelho de artefactos correspondente, bem como aos registos de contentores necessários.
  • Conectividade existente da Camada 3 entre a rede anfitriã de nós flexíveis e a rede de nós gerida pelo AKS. O host e o cluster AKS não têm de estar na mesma região do Azure.

O teu ambiente Bash também deve conseguir ligar-se ao anfitrião flex node através de SSH. Um endereço IP público não é necessário quando tens outro caminho de gestão aprovado.

2. Aprovisionar ou selecionar o anfitrião e a identidade

Preencha apenas a secção da opção de identidade selecionada em Conceitos de identidade e acesso para nós Flex. Não configures mais do que um modo de identidade Azure durável para o mesmo host.

Tip

Ligar uma máquina fora do Azure? Use uma identidade gerida do Azure Arc se a máquina já estiver habilitada para o Arc, ou use um principal de serviço. Utilize a identidade gerida da VM do Azure apenas quando o anfitrião 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 anfitrião. FLEX_HOST_SSH_TARGET é o endereço usado pelo teu ambiente Bash. FLEX_HOST_PRIVATE_IP é o endereço do host acessível a partir da rede de nós gerida pelo AKS. Confirme junto do seu administrador de rede que FLEX_HOST_PRIVATE_IP pertence a FLEX_HOST_SUBNET_CIDR e que é o endereço alcançável a partir da rede de nós gerida pelo AKS. Não utilize um endereço público separado ou um endereço exclusivamente para gestão como endereço do nó Flex.

Utilize uma identidade gerida do Azure Arc

Utilize esta opção para um anfitrião que já esteja conectado ao Azure Arc. Se necessário, siga Ligar máquinas híbridas a servidores com Azure Arc.

Defina os valores dos recursos Arc e os endereços do anfitrião:

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>"

Recuperar o ID do recurso, o estado da ligação e o 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 for Connected e PrincipalId estiver preenchido.

Verifique o agente da Máquina Conectada e o Serviço de Metadados de Instância Híbrida no host:

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

Confirme que azcmagent show reporta o mesmo ID de subscrição, grupo de recursos e nome da máquina que ARC_RESOURCE_ID, ARC_RESOURCE_GROUP, e ARC_MACHINE_NAME. Confirma também que himdsd está ativa. Se o recurso não corresponder, pare e corrija os valores do recurso Arc antes de atribuir acesso.

Registar o Arco e os valores 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 um principal de serviço

Use esta opção para outra máquina virtual suportada ou para um host bare-metal. Prefira uma credencial baseada em certificado em vez de um segredo de cliente de longa duração. Os passos seguintes criam um responsável dedicado para a aplicação e o serviço com um certificado auto-assinado para avaliação. Eles não criam um cliente secreto nem atribuem um papel no Azure. Concedes acesso ao cluster AKS alvo no passo 4.

Antes de continuares:

  • Instale o OpenSSL no seu ambiente Bash e use um CLI do Azure up-to-date que suporte az login --certificate.
  • Inicie sessão com uma conta que possa registar aplicações e criar princípios de serviço no tenant Microsoft Entra associado à subscrição alvo. A propriedade por subscrição do Azure por si só não concede estas permissões de diretório. Se o seu inquilino restringir o registo da candidatura, peça ajuda ao administrador do seu inquilino. Consulte Criar um principal de serviço do Azure com a CLI do Azure.
  • Confirme que a sua organização permite certificados auto-assinados para avaliação. Para uma identidade aprovada existente, utilize o seu ID de inquilino, ID de cliente de aplicação, ID de objeto principal de serviço e ficheiro PEM protegido, e salte para Registar os valores principal de serviço e host.

Não guarde a credencial, a chave privada ou o caminho da credencial no ficheiro do ambiente partilhado. Não imprimas o ficheiro PEM nem o incluas no controlo de versão. O ficheiro PEM contém uma chave privada não encriptada para que o agente possa autenticar-se sem necessidade de um pedido interativo de palavra-passe. Proteja-o com permissões de ficheiros e controlos de acesso aprovados do anfitrião.

Crie um princípio de serviço baseado em certificados

Executa estes comandos no teu ambiente Bash enquanto estás ligado com a tua conta de operador.

  1. Confirme a subscrição, o inquilino e a conta iniciada.

    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 subscrição e o tenant forem os alvos pretendidos.

  2. Escolha um nome de exibição único para a aplicação e crie um diretório de credenciais protegidas.

    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 ficheiro 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 que as permissões PEM são 600. A validade de 30 dias é para avaliação, não para uma política de rotação. Substitua a credencial através do seu processo aprovado antes de esta expirar, se o host permanecer associado.

  4. Crie a aplicação e a entidade principal 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 bem-sucedido e devolver um ID de cliente da aplicação. O comando pode reportar 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ções posterior está limitada ao cluster AKS. Não execute novamente a criação numa aplicação existente para renovar as suas credenciais.

  5. Recupere o ID do objeto principal do serviço e inspecione as credenciais registadas.

    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 que o ID do objeto principal do serviço está preenchido, ambos os IDs de cliente coincidem SP_CLIENT_ID, PasswordCredentials é 0, e que exatamente um certificado está registado com a expiração esperada. Se a replicação de diretórios atrasar a consulta, espere brevemente e tente novamente a pesquisa em vez de criar outra aplicação.

Para um teste só de credenciais, execute apenas a verificação da autenticação por certificado em Verificar um principal de serviço. Não precisas de atribuir um papel no Azure nem preparar um host para essa verificação. Quando o teste estiver concluído, elimine a aplicação dedicada ao teste e a credencial local.

Registe os valores de service principal e de host

Defina os endereços do servidor. Se selecionou uma identidade existente, primeiro defina SP_TENANT_ID, SP_CLIENT_ID, e SP_OBJECT_ID aos 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 é o ID do objeto da aplicação Enterprise, também chamado ID do objeto principal do serviço. Não é o ID do objeto do registo da App. Confirme que SP_CLIENT_ID, SP_OBJECT_ID e o certificado pertencem ao mesmo principal de serviço.

Bootstrap associa SP_TENANT_ID e SP_CLIENT_ID a azure.servicePrincipal.tenantId e azure.servicePrincipal.clientId na configuração do agente gerado. SP_OBJECT_IDé usado para a atribuição de funções do Azure, não como ID de cliente do agente. Para o campo do ficheiro de certificado, a forma completa da configuração censurada e os comandos de verificação segura, veja Inspecionar a configuração do principal de serviço renderizado.

Guarde o ficheiro PEM protegido para verificação de identidade e arranque inicial do anfitrião. Torne-a disponível no servidor através do seu processo de gestão de credenciais aprovado antes da associação. Regista a sua localização através do teu processo aprovado de gestão de credenciais, não no ficheiro do ambiente partilhado. Continue com a opção Preparar e inspecionar o host e, em seguida, atribua a função do AKS.

Use uma identidade gerida por máquina virtual do Azure

Use esta opção para uma VM Azure. Crie uma VM seguindo o Quickstart: Crie uma máquina virtual Linux com a CLI do Azure, ou selecione uma VM existente. Coloque a VM na rede anfitriã de nó flexível planeada para esta implementação. Não precisas de um endereço IP público quando o teu ambiente Bash tem 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 o 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 devolvido 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 que seja acessível a partir da rede de nós gerida pelo AKS. Se o Azure devolver mais do que um endereço, defina FLEX_HOST_PRIVATE_IP o endereço do nó flexível planeado antes de continuar.

Se a VM não tiver endereço IP público, ou se o seu ambiente Bash chegar ao host através de outro caminho de gestão aprovado, defina FLEX_HOST_SSH_TARGET o endereço ou nome do host que o seu ambiente Bash pode alcançar.

Preencha uma das seguintes opções de identidade gerida.

Identidade gerenciada atribuída ao sistema

Ativar a identidade gerida atribuída ao sistema:

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

Recuperar o seu ID principal de objeto:

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 geridas atribuídas pelos utilizadores usando a CLI do Azure.

Defina os valores de identidade:

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

Recuperar 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

Atribuir 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.

Registar a identidade da VM

Registar a VM e os valores de 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 a máquina anfitriã

Liga-te ao anfitrião:

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

No host, inspecione o sistema operativo, arquitetura, nome do host, CPU e 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 do anfitrião no passo 1. Resolva qualquer diferença antes de continuar.

O script de arranque requer curl, jq e tar no anfitrião e é interrompido se algum deles estiver em falta. O agente flex do nó instala os restantes pacotes de execução durante o arranque inicial.

Instala qualquer um dos três que a tua 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

Sair da sessão anfitriã:

exit

Leia o nome real do host Linux no 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 devolver o nome do anfitrião esperado.

Obtenha o FQDN do servidor da API do AKS e verifique a resolução de nome e a conectividade HTTPS a partir do anfitrião:

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 ligação TCP falharem, corriga o DNS, o encaminhamento ou os controlos de rede antes de continuar. Um cluster público de AKS utiliza a sua API pública FQDN. Para um cluster AKS privado, o seu ambiente Bash e a rede do anfitrião dos nós flex têm de conseguir resolver e encaminhar tráfego para o FQDN da API privada.

Regista os valores do anfitrião. O ficheiro do ambiente partilhado armazena caminhos e identificadores não secretos, não conteúdos de chave ou credenciais.

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 do AKS

O fluxo de trabalho de pré-visualização atual utiliza o Azure Kubernetes Service Contributor Role no âmbito exato do cluster AKS. As três opções de identidade utilizam um ID de objeto principal de serviço para controlo de acesso baseado em funções no Azure. Use uma identidade de host dedicada e remova esta atribuição quando remover o host conforme descrito em Gerenciar e remover os nós flex no AKS.

Mostrar o ID do objeto principal selecionado:

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 principal de serviço.

Verifique se a tarefa 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 devolver linha, 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

Executa novamente o comando de lista. Continue quando o ID principal e o âmbito coincidem com a identidade selecionada e AKS_RESOURCE_ID. A propagação de atribuição de funções pode demorar vários minutos.

5. Verificar a identidade selecionada

Antes de bootstrapar o host, confirme que a identidade selecionada pode autenticar e ler exatamente o cluster AKS alvo. Preencha apenas a secção correspondente à sua opção de identidade.

Verificar uma identidade gerida do Azure Arc

No seu ambiente Bash, passe o ID de recurso AKS não secreto para o servidor habilitado com 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, peça um token Azure Resource Manager ao Hybrid Instance Metadata Service (HIMDS) e use-o para ler o recurso AKS. A leitura do token do desafio requer privilégios de root ou pertença 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 sair da sessão do servidor habilitada pelo Azure Arc.

Verificar um service principal

No seu ambiente Bash, utilize o ficheiro PEM combinado obtido nos passos de preparação do principal de serviço. Se iniciou uma nova sessão ou selecionou uma identidade existente, defina novamente o seu caminho protegido:

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

Pare se o ficheiro não existir ou estiver vazio. Não adicione este caminho ao ficheiro de ambiente partilhado.

Primeiro, verifique a autenticação do certificado com um perfil isolado do CLI do Azure. O subshell remove a cache temporária do token mesmo quando um comando falha e não altera o seu login normal na 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 que Tenant corresponde a SP_TENANT_ID e que o testemunho não expirou. Este comando imprime apenas o tenant e a expiração, não o token de acesso. --allow-no-subscriptionspermite testar a autenticação antes de conceder acesso ao Azure. A autenticação bem-sucedida não prova permissão para ler ou registar no cluster AKS.

Depois de a atribuição de funções AKS no passo 4 ter sido propagada, verifique o acesso ao cluster alvo 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 identificador do recurso devolvido coincidir com AKS_RESOURCE_ID e o estado de provisionamento for Succeeded. Se a autenticação for bem-sucedida mas o pedido do cluster for negado, verifique o ID do objeto principal do serviço, o âmbito exato de atribuição de funções e a propagação antes de tentar novamente. Esta verificação prova que o principal do serviço e o seu certificado conseguem ler o cluster alvo. O host utiliza a credencial preparada em Anexar um nó flex a um cluster AKS.

Verifique uma identidade gerida de uma VM do Azure

No seu ambiente Bash, passe o ID de recurso AKS não secreto e o ID de identidade do cliente 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 do Azure, solicite um token do Azure Resource Manager utilizando a identidade gerida selecionada e utilize-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 utilizador, o pedido usa o mesmo HOST_IDENTITY_CLIENT_ID que o fluxo de trabalho de anexo passa para --msi-client-id. Execute exit para sair da sessão da VM do Azure.

O fluxo de trabalho de anexação realiza a verificação final de ponta a ponta quando o anfitrião utiliza a identidade selecionada para registar o seu recurso Azure Machine.

Passo seguinte

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

  • Última atualização a