Get started with EKS Hybrid Nodes gateway

This page walks you through the prerequisites, environment preparation, installation, verification, and removal of the Amazon EKS Hybrid Nodes gateway. For an introduction to the gateway and its architecture, see Amazon EKS Hybrid Nodes gateway.

Prerequisites

Before you install the Hybrid Nodes gateway, confirm that your environment meets the following requirements:

Prepare gateway nodes

The gateway requires at least two EC2 nodes for high availability. There are two supported node configuration options for the gateway:

EKS Auto Mode (recommended)

When using EKS Auto Mode, you must create a NodePool and NodeClass before installing the Helm chart. The NodePool provisions EC2 instances with the correct labels, taints, and source/destination check configuration. You do not need to manually provision or configure nodes.

Apply the following resources to your cluster, replacing the placeholder values:

apiVersion: eks.amazonaws.com/v1
kind: NodeClass
metadata:
  name: hybrid-gateway
spec:
  advancedNetworking:
    sourceDestCheck: DisabledPrimaryENI
  role: YOUR_NODE_ROLE
  securityGroupSelectorTerms:
    - tags:
        aws:eks:cluster-name: YOUR_CLUSTER_NAME
  subnetSelectorTerms:
    - id: SUBNET_ID_1
    - id: SUBNET_ID_2
---
apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: hybrid-gateway
spec:
  template:
    metadata:
      labels:
        hybrid-gateway-node: "true"
    spec:
      expireAfter: 336h
      nodeClassRef:
        group: eks.amazonaws.com
        kind: NodeClass
        name: hybrid-gateway
      requirements:
        - key: karpenter.sh/capacity-type
          operator: In
          values:
            - on-demand
        - key: eks.amazonaws.com/instance-category
          operator: In
          values:
            - c
            - m
            - r
        - key: eks.amazonaws.com/instance-generation
          operator: Gt
          values:
            - "4"
        - key: kubernetes.io/arch
          operator: In
          values:
            - amd64
        - key: kubernetes.io/os
          operator: In
          values:
            - linux
      taints:
        - key: hybrid-gateway-node
          effect: NoSchedule
      terminationGracePeriod: 24h0m0s
  disruption:
    budgets:
      - nodes: 10%
    consolidateAfter: 30s
    consolidationPolicy: WhenEmptyOrUnderutilized

Key fields in this configuration:

Managed node groups

When using managed node groups, create a dedicated node group for the gateway with the required labels, taints, and a custom launch template that disables source/destination check at launch.

Step 1: Create a launch template

Create a launch template with user data that disables source/destination check on the primary ENI when the instance boots:

# Create the launch template with user data to disable source/dest check
USERDATA=$(cat <<'SCRIPT' | base64 -w 0
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="==BOUNDARY=="

--==BOUNDARY==
Content-Type: text/x-shellscript; charset="us-ascii"

#!/bin/bash
TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 60")
MAC=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/mac)
ENI_ID=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  "http://169.254.169.254/latest/meta-data/network/interfaces/macs/${MAC}/interface-id")
REGION=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/placement/region)

aws ec2 modify-network-interface-attribute \
  --network-interface-id "$ENI_ID" \
  --no-source-dest-check \
  --region "$REGION"

--==BOUNDARY==--
SCRIPT
)

aws ec2 create-launch-template \
  --launch-template-name YOUR_CLUSTER_NAME-gateway-lt \
  --launch-template-data "{\"UserData\":\"${USERDATA}\",\"MetadataOptions\":{\"HttpTokens\":\"required\",\"HttpPutResponseHopLimit\":2}}"

Step 2: Create the managed node group

Create a dedicated managed node group with the gateway label, taint, and the launch template from Step 1:

aws eks create-nodegroup \
  --cluster-name YOUR_CLUSTER_NAME \
  --nodegroup-name YOUR_CLUSTER_NAME-gateway-nodes \
  --subnets SUBNET_ID_1 SUBNET_ID_2 \
  --node-role YOUR_NODE_ROLE_ARN \
  --instance-types INSTANCE_TYPE \
  --ami-type AL2023_x86_64_STANDARD \
  --scaling-config desiredSize=2,maxSize=2,minSize=2 \
  --labels hybrid-gateway-node=true \
  --taints "key=hybrid-gateway-node,effect=NO_SCHEDULE" \
  --launch-template "name=YOUR_CLUSTER_NAME-gateway-lt,version=1"

This creates a 2-node managed node group where:

Use subnets in different Availability Zones for high availability.

Install with Helm

EKS Auto Mode

Run the following command to install the gateway with EKS Auto Mode:

helm install eks-hybrid-nodes-gateway \
  oci://public.ecr.aws/eks/eks-hybrid-nodes-gateway \
  --version 1.0.0 \
  --namespace eks-hybrid-nodes-gateway \
  --create-namespace \
  --set vpcCIDR=VPC_CIDR \
  --set podCIDRs=POD_CIDRS \
  --set routeTableIDs=ROUTE_TABLE_IDS
         

Managed node groups or self-managed nodes

For managed node groups or self-managed nodes, set autoMode.enabled=false:

helm install eks-hybrid-nodes-gateway \
  oci://public.ecr.aws/eks/eks-hybrid-nodes-gateway \
  --version 1.0.0 \
  --namespace eks-hybrid-nodes-gateway \
  --create-namespace \
  --set autoMode.enabled=false \
  --set vpcCIDR=VPC_CIDR \
  --set podCIDRs=POD_CIDRS \
  --set routeTableIDs=ROUTE_TABLE_IDS
         

Required Helm values

The following values are required for all installations:

For a complete list of configurable values, see Amazon EKS Hybrid Nodes gateway configuration reference.

Verify the installation

After installing the gateway, verify that it is running and healthy.

Check pod status

Confirm that two gateway pods are running:

kubectl get pods -n eks-hybrid-nodes-gateway

You should see output similar to:

NAME                                        READY   STATUS    RESTARTS   AGE
eks-hybrid-nodes-gateway-5d4f6a7b8c-abc12   1/1     Running   0          2m
eks-hybrid-nodes-gateway-5d4f6a7b8c-def34   1/1     Running   0          2m

Check leader election

Verify that one pod has acquired the leader election lease:

kubectl get lease -n eks-hybrid-nodes-gateway

The output shows the current leader in the HOLDER column:

NAME                     HOLDER                                      AGE
hybrid-gateway-leader    eks-hybrid-nodes-gateway-5d4f6a7b8c-abc12   2m

Check health endpoint

Verify the health endpoint is responding on the leader pod using port-forwarding:

kubectl port-forward -n eks-hybrid-nodes-gateway LEADER_POD_NAME 8088:8088 &
curl -s http://localhost:8088/healthz

A healthy gateway returns an HTTP 200 response.

Verify VPC route table entries

In the Amazon VPC console or using the AWS CLI, confirm that your VPC route tables contain entries for the hybrid pod CIDRs pointing to the leader gateway instance’s ENI:

aws ec2 describe-route-tables \
  --route-table-ids ROUTE_TABLE_ID \
  --query "RouteTables[].Routes[?DestinationCidrBlock=='[.replaceable]`POD_CIDR`']"

Each hybrid pod CIDR should have a route with the NetworkInterfaceId set to the leader instance’s primary ENI.

Uninstall

To remove the Hybrid Nodes gateway, run:

helm uninstall eks-hybrid-nodes-gateway --namespace eks-hybrid-nodes-gateway

aws ec2 delete-route \
  --route-table-id ROUTE_TABLE_ID \
  --destination-cidr-block POD_CIDR
         

Next steps