Skip to content

Requisitos previos ​

< Tabla de contenido | Siguiente: Configuración de red >

Versiones compatibles: EKS 1.31+, nodeadm 0.1+ Última actualización: February 23, 2026

Este documento cubre los requisitos del sistema para nodos on-premises, servidores GPU e infraestructura de red necesarios para implementar EKS Hybrid Nodes.

Descripción general de los requisitos previos de red ​

El siguiente diagrama muestra los requisitos previos de red para conectar nodos on-premises a un clúster de EKS, incluida la configuración de VPC, Transit Gateway/Virtual Private Gateway y los requisitos de CIDR.

Diagrama de requisitos previos de nodos híbridos que relaciona las configuraciones RemoteNodeNetwork y RemotePodNetwork del clúster con las tablas de rutas tanto en VPC como en el entorno on-premises.

Diagrama de requisitos previos de nodos híbridos que relaciona las configuraciones RemoteNodeNetwork y RemotePodNetwork del clúster con las tablas de rutas tanto en VPC como en el entorno on-premises.Abrir a pantalla completa ↗

Requisitos de los nodos on-premises ​

Sistemas operativos compatibles ​

Sistema operativoVersiónArquitectura
Ubuntu LTS20.04, 22.04, 24.04x86_64, arm64
RHEL8, 9x86_64, arm64
Amazon Linux2023x86_64, arm64
Bottlerocketv1.37.0 y posteriores (solo variantes VMware)Solo x86_64

Nota sobre Bottlerocket: Solo las variantes VMware de Bottlerocket son compatibles con EKS Hybrid Nodes, y se requiere Kubernetes v1.28 o superior. Bottlerocket incluye automáticamente todas las dependencias necesarias, por lo que no se requiere la CLI nodeadm. La arquitectura ARM no es compatible con Bottlerocket.

Notas sobre la arquitectura ARM:

  • Los nodos ARM requieren ARMv8.2 o posterior con extensión Crypto (para kube-proxy v1.31+)
  • Raspberry Pi (anteriores a Pi 5) no es compatible — solo admite ARMv8.0, que carece de la extensión Crypto
  • Pi 5 (ARMv8.2) y posteriores son compatibles

Runtime de contenedores ​

bash
# Check containerd version
containerd --version
# Required version: 1.6.x or higher

# Check Docker Engine version (includes containerd)
docker --version
# Required version: 20.10.10 or higher

Notas de containerd específicas del sistema operativo:

  • Ubuntu 24.04: Requiere containerd v1.7.19 o posterior, o cambios en la configuración del perfil AppArmor
  • RHEL: --containerd-source distro no es válido. Debe usar --containerd-source docker
  • Ubuntu 20.04 / RHEL 8: El kernel predeterminado es anterior a 5.10, que es necesario para Cilium v1.18.x

Especificaciones mínimas de hardware ​

RecursoMínimo (oficial de AWS)Recomendado
CPU1 vCPU4 núcleos o más
RAM1 GiB8 GB o más
DiscoSSD de 50 GBSSD NVMe de 100 GB
Red100 Mbps10 Gbps o más

Nota: El mínimo oficial de AWS es 1 vCPU / 1 GiB, pero se recomiendan 2 núcleos / 4 GB o más para ejecutar cargas de trabajo reales.

Verificación de la configuración del sistema ​

bash
# Verify swap is disabled
free -h
# Swap should be 0

# Disable swap
sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

# Load required kernel modules
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

# Set kernel parameters
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sudo sysctl --system

Creación de imágenes de nodos con plantillas AWS Packer ​

AWS proporciona plantillas de Packer de ejemplo para crear imágenes de nodos para EKS Hybrid Nodes. Estas plantillas admiten formatos de salida OVA (vSphere), Qcow2 y Raw.

Requisitos previos de Packer ​

HerramientaVersión mínima
Packerv1.11.0+
Complemento de VMware vSpherev1.4.0+
Complemento de QEMUMás reciente

Variables de entorno ​

VariableDescripciónPredeterminado
PKR_SSH_PASSWORDContraseña SSH-
ISO_URLURL de imagen ISO del SO-
ISO_CHECKSUMSuma de comprobación de ISO-
CREDENTIAL_PROVIDERProveedor de credenciales (ssm o iam)ssm
K8S_VERSIONVersión de Kubernetes-
NODEADM_ARCHArquitectura (amd64 o arm64)amd64

Variables específicas de RHEL:

VariableDescripción
RH_USERNAMENombre de usuario de suscripción de Red Hat
RH_PASSWORDContraseña de suscripción de Red Hat

Variables específicas de vSphere:

VariableDescripción
VSPHERE_SERVERDirección del servidor vCenter
VSPHERE_USERNombre de usuario de vCenter
VSPHERE_PASSWORDContraseña de vCenter
VSPHERE_DATACENTERNombre del Datacenter
VSPHERE_CLUSTERNombre del clúster
VSPHERE_DATASTORENombre del Datastore
VSPHERE_NETWORKNombre de la red

Comandos de compilación ​

bash
# Build vSphere OVA (Ubuntu 22.04)
packer build -only=general-build.vsphere-iso.ubuntu22 template.pkr.hcl

# Build QEMU image (RHEL 9)
packer build -only=general-build.qemu.rhel9 template.pkr.hcl

# Build Amazon Linux 2023
packer build -only=general-build.qemu.al2023 template.pkr.hcl

Nota: Establecer la variable de entorno CREDENTIAL_PROVIDER en iam crea una imagen para IAM Roles Anywhere. El valor predeterminado es ssm.

Requisitos del servidor GPU (opcional) ​

Controlador NVIDIA ​

bash
# Check NVIDIA driver version
nvidia-smi --query-gpu=driver_version --format=csv,noheader
# Required version: 550.x or higher

# Check CUDA version
nvcc --version
# Recommended version: CUDA 12.x

Modelos de GPU compatibles ​

Modelo de GPUVRAMUso principal
NVIDIA H10080 GBEntrenamiento/inferencia de LLM a gran escala
NVIDIA H200141 GBModelos muy grandes
NVIDIA A10040/80 GBUso general de AI/ML
NVIDIA L40S48 GBOptimizada para inferencia

Instalación del controlador GPU ​

Ubuntu 22.04 LTS (recomendado):

bash
# Install kernel headers
sudo apt-get install -y linux-headers-$(uname -r)

# Add NVIDIA driver repository
distribution=$(. /etc/os-release;echo $ID$VERSION_ID | sed -e 's/\.//g')
wget https://developer.download.nvidia.com/compute/cuda/repos/$distribution/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update

# Install driver
sudo apt-get install -y cuda-drivers-550

# Install NVIDIA Container Toolkit
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Update containerd configuration
sudo nvidia-ctk runtime configure --runtime=containerd
sudo systemctl restart containerd

RHEL 9:

bash
# Install kernel development packages
sudo dnf install -y kernel-devel-$(uname -r) kernel-headers-$(uname -r)

# Add NVIDIA driver repository
sudo dnf config-manager --add-repo https://developer.download.nvidia.com/compute/cuda/repos/rhel9/x86_64/cuda-rhel9.repo

# Install driver
sudo dnf module install -y nvidia-driver:550-dkms

# Install NVIDIA Container Toolkit
curl -s -L https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo | \
  sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repo
sudo dnf install -y nvidia-container-toolkit

# Update containerd configuration
sudo nvidia-ctk runtime configure --runtime=containerd
sudo systemctl restart containerd

Requisitos de red ​

Ancho de banda y latencia ​

ElementoMínimoRecomendado
Ancho de banda100 Mbps10 Gbps o más
Latencia200 ms RTT o menos5 ms o menos
Pérdida de paquetes0.1% o menos0.01% o menos
MTU15009000 (Jumbo Frame)

Configuración de Jumbo Frame ​

bash
# Check MTU setting
ip link show eth0 | grep mtu

# Set MTU to 9000 (temporary)
sudo ip link set dev eth0 mtu 9000

# Permanent configuration (Amazon Linux 2023 - NetworkManager)
sudo nmcli connection modify "System eth0" 802-3-ethernet.mtu 9000
sudo nmcli connection up "System eth0"

# Verify configuration
nmcli connection show "System eth0" | grep mtu

Configuración del proveedor de credenciales IAM ​

EKS Hybrid Nodes requiere uno de dos proveedores de credenciales para autenticar nodos on-premises con AWS.

Opción A: SSM Hybrid Activations ​

SSM Hybrid Activations es la opción más sencilla y no requiere infraestructura PKI.

bash
# Create IAM role for hybrid nodes
aws iam create-role \
  --role-name EKSHybridNodeRole \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ssm.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

# Attach required policies
aws iam attach-role-policy \
  --role-name EKSHybridNodeRole \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKSWorkerNodeMinimalPolicy

aws iam attach-role-policy \
  --role-name EKSHybridNodeRole \
  --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

# Create SSM Hybrid Activation
aws ssm create-activation \
  --default-instance-name "eks-hybrid-node" \
  --iam-role EKSHybridNodeRole \
  --registration-limit 100 \
  --region ap-northeast-2

Opción B: IAM Roles Anywhere ​

IAM Roles Anywhere utiliza certificados X.509 de su PKI existente, ideal para entornos air-gap.

bash
# 1. Create Trust Anchor with your CA certificate
aws rolesanywhere create-trust-anchor \
  --name "eks-hybrid-trust-anchor" \
  --source "sourceType=CERTIFICATE_BUNDLE,sourceData={x509CertificateData=$(cat ca.pem)}" \
  --enabled

# 2. Create Profile that maps to an IAM Role
aws rolesanywhere create-profile \
  --name "eks-hybrid-profile" \
  --role-arns arn:aws:iam::123456789012:role/EKSHybridNodeRole \
  --enabled

# 3. Issue X.509 certificate for each node (using your CA)
openssl req -new -key node.key -out node.csr -subj "/CN=hybrid-node-001"
openssl x509 -req -in node.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out node.crt -days 365

# 4. Distribute cert and key to node
sudo mkdir -p /etc/iam/pki
sudo cp node.crt /etc/iam/pki/server.pem
sudo cp node.key /etc/iam/pki/server.key

Configuración de IAM basada en CloudFormation ​

En lugar de la CLI, puede utilizar CloudFormation para configurar roles IAM y recursos relacionados.

Plantilla de CloudFormation para SSM:

bash
# Download template
curl -OL 'https://raw.githubusercontent.com/aws/eks-hybrid/refs/heads/main/example/hybrid-ssm-cfn.yaml'

# Create parameter file
cat > cfn-ssm-parameters.json << 'EOF'
[
  {"ParameterKey": "RoleName", "ParameterValue": "EKSHybridNodeRole"},
  {"ParameterKey": "SSMDeregisterConditionTagKey", "ParameterValue": "EKSClusterARN"},
  {"ParameterKey": "SSMDeregisterConditionTagValue", "ParameterValue": "arn:aws:eks:ap-northeast-2:123456789012:cluster/my-hybrid-cluster"}
]
EOF

# Deploy stack
aws cloudformation create-stack \
  --stack-name eks-hybrid-ssm-role \
  --template-body file://hybrid-ssm-cfn.yaml \
  --parameters file://cfn-ssm-parameters.json \
  --capabilities CAPABILITY_NAMED_IAM

Plantilla de CloudFormation para IAM Roles Anywhere:

bash
# Download template
curl -OL 'https://raw.githubusercontent.com/aws/eks-hybrid/refs/heads/main/example/hybrid-ira-cfn.yaml'

# Create parameter file
cat > cfn-iamra-parameters.json << 'EOF'
[
  {"ParameterKey": "RoleName", "ParameterValue": "EKSHybridNodeRole"},
  {"ParameterKey": "CertAttributeTrustPolicy", "ParameterValue": "CN"},
  {"ParameterKey": "CABundleCert", "ParameterValue": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"}
]
EOF

# Deploy stack
aws cloudformation create-stack \
  --stack-name eks-hybrid-iamra-role \
  --template-body file://hybrid-ira-cfn.yaml \
  --parameters file://cfn-iamra-parameters.json \
  --capabilities CAPABILITY_NAMED_IAM

Detalles de las políticas IAM ​

Detalles de las políticas IAM requeridas para el rol de nodo híbrido.

Políticas administradas requeridas:

PolíticaPropósito
AmazonEC2ContainerRegistryPullOnlyObtener imágenes de contenedores desde ECR
AmazonSSMManagedInstanceCoreFuncionalidad principal del agente SSM (al usar SSM)

Políticas opcionales:

PolíticaPropósito
eks-auth:AssumeRoleForPodIdentityCompatibilidad con EKS Pod Identity

Política condicional de desregistro de SSM:

En entornos multiclúster, utilice la etiqueta de condición EKSClusterARN para garantizar que los nodos solo puedan desregistrarse de clústeres específicos:

json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ssm:DeregisterManagedInstance",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "ssm:resourceTag/EKSClusterARN": "arn:aws:eks:ap-northeast-2:123456789012:cluster/my-hybrid-cluster"
        }
      }
    }
  ]
}

Detalles de la política de confianza de IAM Roles Anywhere ​

La configuración de la política de confianza es crítica al usar IAM Roles Anywhere.

Mapeo de x509Subject/CN:

El CN (Common Name) del certificado debe coincidir con el nombre del nodo. Esto se utiliza para el seguimiento de auditoría y la identificación del nodo.

json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "rolesanywhere.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession",
        "sts:SetSourceIdentity"
      ],
      "Condition": {
        "StringEquals": {
          "aws:PrincipalTag/x509Subject/CN": "${aws:RequestTag/x509Subject/CN}"
        },
        "ArnEquals": {
          "aws:SourceArn": "arn:aws:rolesanywhere:ap-northeast-2:123456789012:trust-anchor/TRUST_ANCHOR_ID"
        }
      }
    }
  ]
}

Componentes clave:

ComponenteDescripción
sts:SetSourceIdentityEstablece la identidad de origen para el seguimiento de auditoría
sts:RoleSessionNameNombre de sesión vinculado al CN del certificado
x509Subject/CNEl CN del certificado debe coincidir con nodeName

Comparación de duración de credenciales ​

AspectoSSMIAM Roles Anywhere
Duración predeterminada1 hora (fija)1 hora (configurable)
Duración máxima1 hora12 horas
RotaciónAutomática por AWSAutomática, respeta durationSeconds
MaxSessionDurationN/AEl valor del rol IAM debe superar el durationSeconds del perfil
ConfiguraciónNo configurableSe establece mediante el parámetro durationSeconds del perfil

Nota: Al utilizar IAM Roles Anywhere, el MaxSessionDuration del rol IAM debe ser mayor que el valor durationSeconds del perfil. De lo contrario, se producirá un error al obtener las credenciales.

Preparación de acceso al clúster ​

Los nodos híbridos requieren entradas de acceso adecuadas para unirse al clúster de EKS.

Entrada de acceso HYBRID_LINUX (recomendada) ​

El tipo de entrada de acceso HYBRID_LINUX está diseñado específicamente para nodos híbridos:

bash
aws eks create-access-entry \
  --cluster-name my-hybrid-cluster \
  --principal-arn arn:aws:iam::123456789012:role/EKSHybridNodeRole \
  --type HYBRID_LINUX

Este comando establece automáticamente:

  • Nombre de usuario: system:node:{{SessionName}}
  • Grupos de Kubernetes: system:bootstrappers, system:nodes

Alternativa con ConfigMap aws-auth ​

Al utilizar el modo de autenticación API_AND_CONFIG_MAP, puede usar el ConfigMap aws-auth como alternativa:

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-auth
  namespace: kube-system
data:
  mapRoles: |
    - groups:
      - system:bootstrappers
      - system:nodes
      rolearn: arn:aws:iam::123456789012:role/EKSHybridNodeRole
      username: system:node:{{SessionName}}
bash
kubectl apply -f aws-auth-cm.yaml

Nota: El método ConfigMap aws-auth es un enfoque heredado. Para clústeres nuevos, se recomienda utilizar la entrada de acceso HYBRID_LINUX.

Requisitos de configuración de VPC ​

La VPC del clúster de EKS debe estar configurada correctamente para admitir la conectividad de Hybrid Nodes.

Configuración de la tabla de rutas ​

Las tablas de rutas de VPC deben incluir rutas para los CIDR on-premises:

DestinoObjetivoPropósito
10.0.0.0/16 (VPC CIDR)localTráfico interno de VPC
10.80.0.0/16 (Remote Node CIDR)TGW/VGWRuta a nodos on-premises
10.85.0.0/16 (Remote Pod CIDR)TGW/VGWRuta a Pods on-premises

Requisitos de Security Group ​

EKS crea automáticamente reglas de entrada cuando se especifican RemoteNodeNetwork / RemotePodNetwork. Las reglas de salida adicionales deben configurarse manualmente:

DirecciónProtocoloPuertoOrigen/destinoPropósito
Entrada (automática)TCP443Remote Node CIDRKubelet → API Server
Entrada (automática)TCP443Remote Pod CIDRPod → API Server
Entrada (automática)TCP10250Remote Node CIDRAPI Server → Kubelet
Salida (manual)TCP10250Remote Node CIDRAPI Server → Kubelet
Salida (manual)TCPPuertos de WebhookRemote Pod CIDRAPI Server → Webhooks

Nota: Hay un límite de 60 reglas de entrada por Security Group. Verifique los recuentos de reglas al utilizar varios CIDR.

Modos de acceso al endpoint de API Server ​

ModoRuta de KubeletCaso de uso
PúblicoInternet → endpoint de API de EKSConfiguración sencilla; se requiere Internet desde on-premises
PrivadoVPN/DX → VPC ENI → API ServerAir-gap, máxima seguridad (recomendado)

Advertencia: NO use el modo "Público y privado" con nodos híbridos. En este modo, los nodos híbridos resuelven el endpoint de API de EKS únicamente en IP públicas, lo que provoca que fallen las conexiones VPN/Direct Connect privadas. Esto hace que los nodos no puedan unirse al clúster. Debe elegir Público o Privado, no ambos.

Recomendación: Use acceso al endpoint Privado para entornos híbridos de producción.

Creación de clústeres de EKS para Hybrid Nodes ​

Al crear un clúster de EKS compatible con nodos híbridos, se aplican los siguientes requisitos:

  • Modo de autenticación: Debe usar API o API_AND_CONFIG_MAP
  • Familia de direcciones IP: Debe usar IPv4
  • Conectividad de endpoint: Debe usar solo Público O Privado ("Público y privado" no compatible — provoca errores al unir nodos híbridos)
  • Redes remotas: Especifique los CIDR RemoteNodeNetwork y RemotePodNetwork

Uso de eksctl ​

yaml
# cluster-config.yaml
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: my-hybrid-cluster
  region: ap-northeast-2
  version: "1.31"

remoteNetworkConfig:
  iam:
    provider: ssm  # or 'ira' for IAM Roles Anywhere
  vpcGatewayID: tgw-0123456789abcdef0
  remoteNodeNetworks:
    - cidrs: ["10.80.0.0/16"]
  remotePodNetworks:
    - cidrs: ["10.85.0.0/16"]
bash
eksctl create cluster -f cluster-config.yaml

Uso de AWS CLI ​

bash
aws eks create-cluster \
    --name my-hybrid-cluster \
    --region ap-northeast-2 \
    --kubernetes-version 1.31 \
    --role-arn arn:aws:iam::123456789012:role/myAmazonEKSClusterRole \
    --resources-vpc-config subnetIds=subnet-xxx,subnet-yyy,securityGroupIds=sg-zzz,endpointPrivateAccess=true,endpointPublicAccess=false \
    --access-config authenticationMode=API_AND_CONFIG_MAP \
    --remote-network-config '{"remoteNodeNetworks":[{"cidrs":["10.80.0.0/16"]}],"remotePodNetworks":[{"cidrs":["10.85.0.0/16"]}]}'

Actualizar kubeconfig ​

bash
aws eks update-kubeconfig --name my-hybrid-cluster --region ap-northeast-2

# Verify cluster access
kubectl get svc

Add-ons compatibles con Hybrid Nodes ​

No todos los add-ons de EKS son compatibles con nodos híbridos. Amazon VPC CNI no es compatible.

Add-ons de AWS ​

Add-onVersión mínima compatible
kube-proxyv1.25.14-eksbuild.2+
CoreDNSv1.9.3-eksbuild.7+
ADOT (OpenTelemetry)v0.102.1-eksbuild.2+
CloudWatch Observabilityv2.2.1-eksbuild.1+
EKS Pod Identity Agentv1.3.3-eksbuild.1+
Node monitoring agentv1.2.0-eksbuild.1+
CSI snapshot controllerv8.1.0-eksbuild.1+

Add-ons de la comunidad ​

Add-onVersión mínima compatible
Kubernetes Metrics Serverv0.7.2-eksbuild.1+
cert-managerv1.17.2-eksbuild.1+
Prometheus Node Exporterv1.9.1-eksbuild.2+
kube-state-metricsv2.15.0-eksbuild.4+
External DNSv0.19.0-eksbuild.1+

< Tabla de contenido | Siguiente: Configuración de red >

Pregunta a la documentación

Enter envía, Shift+Enter añade una línea.