Preparación de un host y una identidad de nodo flexible (versión preliminar)

Importante

Las características en versión preliminar de AKS están disponibles en régimen de autoservicio y mediante adhesión voluntaria. Las versiones preliminares se proporcionan "tal cual" y "como están disponibles", y están excluidas de los Acuerdos de nivel de servicio y la garantía limitada. Las versiones preliminares de AKS cuentan con soporte parcial por parte del servicio al cliente en la medida de lo posible. Por lo tanto, estas características no están diseñadas para su uso en producción. Para más información, consulte los siguientes artículos de soporte:

• Directivas de soporte técnico de AKS
• Preguntas más frecuentes sobre el soporte técnico de Azure

Antes de adjuntar un host de Linux como nodo flexible, prepare el host, configure la identidad que seleccionó durante la planeación y conceda a esa identidad acceso al clúster de Azure Kubernetes Service (AKS).

En este artículo, encontrarás:

• Revise los requisitos del host y, a continuación, aprovisione o seleccione el host de Linux y su identidad de Azure.
• Prepare e inspeccione el host, y anote los valores utilizados por el flujo de trabajo de conexión.
• Asigne el acceso de identidad en el ámbito del clúster de AKS y compruebe esa identidad.

Ejecute los comandos de administración de este artículo en un entorno de Bash compatible con Linux que tenga las herramientas necesarias y el acceso a la red. En este artículo, ese entorno se denomina entorno de Bash. La máquina independiente que se une al clúster es el host del nodo flexible; ejecute comandos en ella solo cuando un paso se lo indique explícitamente.

Antes de empezar

• Complete la configuración de red y cree un grupo de nodos flex en AKS.
• Revise Los conceptos de identidad y acceso para los nodos flexibles y seleccione una opción de identidad.
• Use una cuenta de Azure que pueda inspeccionar el recurso host y crear una asignación de roles en el ámbito del clúster de AKS. Role Based Access Control Administrator y User Access Administrator son ejemplos de roles que pueden crear la asignación.
• Instale CLI de Azure y un cliente openSSH en el entorno de Bash.
• Prepare un par de claves SSH aceptado por el host.

Carga del entorno de implementación

Iniciar una nueva sesión de Bash, identificar el archivo del entorno del artículo de planificación y cargarlo. Reemplace <deployment-name> por la etiqueta de despliegue.

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

El archivo de entorno proporciona los valores de implementación compartidos que lee este artículo, incluido WORK_DIR, el directorio del entorno de Bash donde este artículo almacena descargas y archivos generados. De forma predeterminada, WORK_DIR es ~/.local/share/aksflexnode/<deployment-name>. El artículo deriva cualquier otra variable que necesite. Si aún no has creado el archivo de entorno, completa primero Planificar la implementación de los nodos flex.

Si no se encuentra el archivo o no se puede cargar, detenga y vuelva al artículo de planeación antes de continuar.

Establezca la suscripción activa y confirme el clúster seleccionado:

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

Continúe cuando el identificador de recurso coincida AKS_RESOURCE_ID y el estado de aprovisionamiento sea Succeeded.

1. Revisar los requisitos del host

Use un host dedicado que cumpla los siguientes requisitos:

• Un host AMD64 o ARM64 que ejecute Ubuntu 24.04 LTS, Azure Linux 3.x o Red Hat Enterprise Linux (RHEL) 9 o 10.
• Un nombre de host único que es un nombre de subdominio DNS válido. El agente lo convierte en minúsculas cuando registra el nodo.
• Al menos cuatro vCPU y al menos 8 GiB libres en /var/lib.
• Una cuenta SSH con acceso raíz o sin sudo contraseña en el host.
• Acceso de red al servidor de la API de AKS, a Azure Resource Manager, a Microsoft Entra ID, a la versión del nodo flexible seleccionada y al espejo de artefactos, así como a los registros de contenedores necesarios.
• Conectividad de nivel 3 existente entre la red host de nodo flexible y la red de nodos administrados por AKS. El host y el clúster de AKS no tienen que estar en la misma región Azure.

El entorno de Bash también debe poder conectarse al host de nodo flexible a través de SSH. Una dirección IP pública no es necesaria cuando tiene otra ruta de administración aprobada.

2. Aprovisionar o seleccionar el host y la identidad

Complete solo la sección de la opción de identidad seleccionada en Conceptos de identidad y acceso para nodos flexibles. No configure más de un modo de identidad de Azure duradero para el mismo host.

Tip

¿Conectar una máquina fuera de Azure? Utilice una identidad administrada de Azure Arc si el equipo ya está habilitado para Arc, o utilice un entidad de servicio. Use identidad administrada de máquina virtual de Azure solo cuando el host del nodo flexible es una máquina virtual de Azure.

Establezca las rutas de acceso de clave SSH usadas por cada opción de identidad:

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

Cada opción de identidad también establece dos direcciones de host. FLEX_HOST_SSH_TARGET es la dirección que usa el entorno de Bash. FLEX_HOST_PRIVATE_IP es la dirección de host accesible desde la red de nodos administrados por AKS. Confirme con su administrador de red que FLEX_HOST_PRIVATE_IP pertenece a FLEX_HOST_SUBNET_CIDR y que es la dirección a la que se puede acceder desde la red de nodos administrados por AKS. No utilice una dirección pública o solo para administración distinta como dirección del nodo Flex.

Uso de una identidad administrada Azure Arc

Use esta opción para un host que ya esté conectado a Azure Arc. Si es necesario, siga Conexión de máquinas híbridas con servidores habilitados para Azure Arc.

Establezca los valores de recursos de Arc y las direcciones 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 el ID del recurso, el estado de la conexión y el ID del objeto de entidad:

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

Continúe cuando Status es Connected y PrincipalId se rellena.

Compruebe el agente de Connected Machine y el servicio de metadatos de instancia híbrida en el host:

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

Confirme que azcmagent show notifica el mismo identificador de suscripción, grupo de recursos y nombre de equipo que ARC_RESOURCE_ID, ARC_RESOURCE_GROUPy ARC_MACHINE_NAME. Confirme también que himdsd está activo. Si el recurso no coincide, deténgase y corrija los valores del recurso de Arc antes de asignar el acceso.

Anote los valores de Arc y de la identidad:

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

Uso de una entidad de servicio

Utilice esta opción para otra máquina virtual compatible o un host físico compatible. Prefiera una credencial basada en certificado mejor que un secreto de cliente de larga duración. Los siguientes pasos crean una aplicación dedicada y una entidad de servicio con un certificado autofirmado para fines de evaluación. No crean un secreto de cliente ni asignan un rol de Azure. Da acceso al clúster de AKS de destino en el paso 4.

Antes de continuar:

• Instale OpenSSL en el entorno de Bash y use un up-to-date CLI de Azure que admita az login --certificate.
• Inicie sesión con una cuenta que pueda registrar aplicaciones y crear entidades de servicio en el tenant de Microsoft Entra asociado a la suscripción de destino. La propiedad de una suscripción de Azure por sí sola no otorga estos permisos de directorio. Si el inquilino restringe el registro de aplicaciones, pida al administrador de inquilinos ayuda. Consulte Crear una entidad de servicio de Azure con la CLI de Azure.
• Confirme que su organización permite certificados autofirmados para su evaluación. Para una identidad existente ya aprobada, use su ID de inquilino, el ID de cliente de la aplicación, el ID de objeto de la entidad de servicio principal y el archivo PEM protegido, y pase directamente a Registrar los valores de la entidad de servicio principal y del host.

No almacene la credencial, la clave privada ni la ruta de acceso de credencial en el archivo de entorno compartido. No imprima el archivo PEM ni inclúyelo en el control de código fuente. El archivo PEM contiene una clave privada sin cifrar para que el agente pueda autenticarse sin una solicitud de contraseña interactiva. Protéjalo con permisos de archivo y controles de acceso de host aprobados.

Creación de una entidad de servicio basada en certificados

Ejecute estos comandos en el entorno de Bash mientras inició sesión con su cuenta de operador.

1. Confirme la suscripción, el inquilino y la cuenta con la que ha iniciado sesión.

   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
   

   Continúa solo si la suscripción y el inquilino son los destinos previstos.

2. Elija un nombre visible único para la aplicación y cree un directorio protegido para credenciales.

   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. Cree un certificado de 30 días y un archivo PEM combinado que contenga el certificado y la clave 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}"
   

   Detenga si se produce un error en la creación del certificado. Confirme que los permisos PEM son 600. La validez de 30 días es para la evaluación, no una directiva de rotación. Sustituya la credencial siguiendo su proceso aprobado antes de que caduque si el equipo permanece conectado.

4. Crea la aplicación y la entidad de servicio cargando únicamente el 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
   

   Continúe solo cuando el comando se realice correctamente y devuelva un identificador de cliente de aplicación. El comando puede notificar que ha ajustado la fecha de finalización de la credencial para que coincida con la expiración del certificado. No agregue --role ni --scopes; la asignación de roles posterior se limita al clúster de AKS. No vuelva a ejecutar el proceso de creación sobre una aplicación existente para rotar las credenciales.

5. Recupera el ID de objeto de la entidad de servicio y comprueba las credenciales 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 que el identificador de objeto de la entidad de servicio está informado, que ambos identificadores de cliente coinciden con SP_CLIENT_ID, que PasswordCredentials es 0 y que exactamente un certificado está registrado con la fecha de expiración esperada. Si la replicación de directorios retrasa la búsqueda, espere brevemente y vuelva a intentar la búsqueda en lugar de crear otra aplicación.

Para una prueba únicamente de credenciales, ejecute solo la comprobación de autenticación mediante certificado en Verificar una entidad de servicio. No es necesario asignar un rol de Azure ni preparar un host para esa comprobación. Una vez completada la prueba, elimine la aplicación de prueba dedicada y las credenciales locales.

Anota los valores de la entidad de servicio y del host

Establezca las direcciones de host. Si has seleccionado una identidad existente, establece primero SP_TENANT_ID, SP_CLIENT_ID y SP_OBJECT_ID con sus 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 es el ID de objeto de la aplicación empresarial, también denominado ID de objeto de la entidad de servicio. No es el identificador de objeto del registro de aplicación. Confirme que SP_CLIENT_ID, SP_OBJECT_IDy el certificado pertenecen a la misma entidad de servicio.

Bootstrap asigna SP_TENANT_ID y SP_CLIENT_ID a azure.servicePrincipal.tenantId y azure.servicePrincipal.clientId en la configuración del agente generada. SP_OBJECT_IDse usa para la asignación de roles de Azure, no como identificador de cliente del agente. Para obtener información sobre el campo archivo de certificado, la estructura de configuración completa censurada y los comandos de verificación segura, consulta Revisar la configuración de la entidad de servicio generada.

Mantenga el archivo PEM protegido para la comprobación de identidades y el arranque del host. Póngalo a disposición en el host mediante su proceso aprobado de gestión de credenciales antes de adjuntarlo. Registre su ubicación a través del proceso de administración de credenciales aprobado, no en el archivo de entorno compartido. Continúe con Preparar e inspeccionar el host y, a continuación, asigne el rol de AKS.

Uso de una identidad administrada de máquina virtual Azure

Use esta opción para una máquina virtual de Azure. Cree una máquina virtual siguiendo el inicio rápido: Creación de una máquina virtual Linux con el CLI de Azure o selección de una máquina virtual existente. Coloque la máquina virtual en la red de host de nodo flexible planeada para esta implementación. No necesita una dirección IP pública cuando el entorno de Bash tiene otra ruta de acceso SSH aprobada.

Establezca los valores de la máquina virtual:

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

Recupere el identificador de recurso de máquina virtual y las direcciones de host. El destino SSH usa la dirección IP pública cuando la máquina virtual tiene una y la dirección privada de lo contrario:

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 la dirección privada devuelta para la máquina virtual:

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

Continúe solo cuando FLEX_HOST_PRIVATE_IP incluya una única dirección privada que pertenezca a FLEX_HOST_SUBNET_CIDR y sea accesible desde la red de nodos administrados por AKS. Si Azure devuelve más de una dirección, establezca FLEX_HOST_PRIVATE_IP en la dirección de nodo flexible planeada antes de continuar.

Si la máquina virtual no tiene ninguna dirección IP pública o el entorno de Bash llega al host a través de otra ruta de administración aprobada, establezca FLEX_HOST_SSH_TARGET en la dirección o el nombre de host al que puede llegar el entorno de Bash.

Complete una de las siguientes opciones de identidad administrada.

Identidad administrada asignada por el sistema

Habilite la identidad administrada asignada por el sistema:

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

Recupere su identificador 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=""

Identidad administrada asignada por el usuario

Cree o seleccione una identidad siguiendo Administrar identidades administradas asignadas por el usuario mediante el CLI de Azure.

Establezca los valores de identidad:

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

Recupere los identificadores de identidad:

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

Asigne la identidad a la máquina virtual:

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

Compruebe que la máquina virtual muestra la identidad seleccionada:

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

Continúe cuando la salida incluya USER_ASSIGNED_IDENTITY_RESOURCE_ID.

Registro de la identidad de la máquina virtual

Registre los valores de máquina virtual e identidad:

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 inspeccionar el host

Conéctese al host:

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

En el host, inspeccione el sistema operativo, la arquitectura, el nombre de host, la CPU y el almacenamiento disponible:

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 los resultados con los requisitos del host en el paso 1. Resuelva cualquier diferencia antes de continuar.

El script de arranque requiere curl, jqy tar en el host y se detiene si falta alguno de ellos. El agente del nodo flex instala los paquetes de entorno de ejecución restantes durante el arranque.

Instale cualquiera de las tres que la imagen aún no incluye:

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

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

Salga de la sesión de host:

exit

Lee el nombre real del host de Linux en tu entorno de 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}"

Continúe cuando el comando devuelva el nombre de host esperado.

Recupere el FQDN del servidor de API de AKS y compruebe la resolución de nombres y la conectividad HTTPS del 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'"

Si falla la resolución de nombres o la conexión TCP, corrija el DNS, el enrutamiento o los controles de red antes de continuar. Un clúster de AKS público usa su FQDN de API pública. En el caso de un clúster privado de AKS, el entorno de Bash y la red del host del nodo flexible deben poder resolver y enrutar hacia el FQDN de la API privada.

Registre los valores del host. El archivo de entorno compartido almacena rutas de acceso e identificadores no secretos, no el contenido de claves ni de credenciales.

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. Asignar el rol de AKS

El flujo de trabajo de versión preliminar actual usa Azure Kubernetes Service rol de colaborador en el ámbito exacto del clúster de AKS. Las tres opciones de identidad utilizan un identificador de objeto de entidad de servicio para el control de acceso basado en roles de Azure. Use una identidad de host dedicada y quite esta asignación cuando quite el host, tal como se describe en Administración y eliminación de nodos flexibles en AKS.

Muestra el ID del objeto principal seleccionado:

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

Continúe solo cuando se haya especificado el valor y este pertenezca a la identidad de la VM seleccionada, la máquina de Arc o la entidad de servicio.

Compruebe si la asignación ya 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

Si el comando no devuelve ninguna fila, cree la asignación:

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

Vuelva a ejecutar el comando list. Continúe cuando el ID de entidad y el ámbito coincidan con la identidad seleccionada y AKS_RESOURCE_ID. La propagación de la asignación de roles puede tardar varios minutos.

5. Comprobar la identidad seleccionada

Antes de inicializar el host, confirme que la identidad seleccionada puede autenticarse y tener acceso de lectura al clúster de AKS de destino específico. Complete únicamente la sección correspondiente a su opción de identidad.

Verificar una identidad administrada de Azure Arc

En el entorno de Bash, pase el identificador de recurso de AKS no secreto al 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"

En el servidor habilitado para Azure Arc, solicite un token de Azure Resource Manager del servicio de metadatos de instancia híbrida (HIMDS) y úselo para leer el recurso de AKS. Leer el token de desafío requiere ser root o pertenecer al 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. Ejecute exit para dejar la sesión de servidor habilitada para Azure Arc.

Verificar una entidad de servicio

En el entorno de Bash, use el archivo PEM combinado de los pasos de preparación de la entidad de servicio. Si inició una nueva sesión o seleccionó una identidad existente, vuelva a establecer su ruta de acceso protegida:

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

Detenga si el archivo no existe o está vacío. No agregue esta ruta de acceso al archivo de entorno compartido.

En primer lugar, compruebe la autenticación de certificados con un perfil de CLI de Azure aislado. La subshell elimina su caché temporal de tokens incluso cuando un comando falla y no cambia el inicio de sesión habitual en CLI de 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 Inquilino coincide con SP_TENANT_ID y que el token no ha caducado. Este comando muestra solo el tenant y la fecha de expiración, no el token de acceso. --allow-no-subscriptionspermite probar la autenticación antes de conceder Azure acceso. La autenticación correcta no demuestra el permiso de lectura o registro en el clúster de AKS.

Una vez propagada la asignación de roles de AKS en el paso 4, compruebe el acceso al clúster de destino exacto:

(
    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
)

Continúe solo cuando el identificador de recurso devuelto coincida AKS_RESOURCE_ID y el estado de aprovisionamiento sea Succeeded. Si la autenticación se realiza correctamente, pero se deniega la solicitud de clúster, compruebe el identificador de objeto de la entidad de servicio, el ámbito exacto de asignación de roles y la propagación antes de reintentar. Esta comprobación demuestra que la entidad de servicio y su certificado pueden leer el clúster de destino. El host usa la credencial preparada en Asociación de un nodo flexible a un clúster de AKS.

Comprobación de una identidad administrada de máquina virtual de Azure

En el entorno de Bash, pase el identificador de recurso no secreto de AKS y el identificador de cliente de identidad a la máquina virtual de 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"

En la máquina virtual de Azure, solicite un token de Azure Resource Manager de la identidad administrada seleccionada y úselo para leer el recurso de 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. En el caso de una identidad asignada por el usuario, la solicitud utiliza el mismo HOST_IDENTITY_CLIENT_ID que el flujo de trabajo de adjuntos pasa a --msi-client-id. Ejecute exit para dejar la sesión de máquina virtual de Azure.

El flujo de trabajo de adjunto realiza la comprobación final integral de extremo a extremo cuando el host usa la identidad seleccionada para registrar su recurso de Azure Machine.

Paso siguiente

A continuación, adjunte y compruebe el host preparado como un nodo flexible.