View a markdown version of this page

Amazon EKS Hybrid Nodes gateway configuration reference - Amazon EKS
Helm chart valuesAuto Mode vs. managed node group configurationLeader election tuningRelated topics

Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Amazon EKS Hybrid Nodes gateway configuration reference

This page documents all configurable parameters for the Amazon EKS Hybrid Nodes gateway. For installation instructions, see Get started with EKS Hybrid Nodes gateway. For an overview of the gateway, see Amazon EKS Hybrid Nodes gateway.

Helm chart values

The following table lists all values in the eks-hybrid-nodes-gateway Helm chart. You can set these values using --set flags or a custom values.yaml file during helm install or helm upgrade.

Value Type Default Required Description

image.repository

string

public.ecr.aws/eks/eks-hybrid-nodes-gateway

No

Container image repository for the gateway image. Defaults to the public Amazon ECR registry.

image.tag

string

Chart appVersion

No

Image tag. Defaults to the appVersion defined in Chart.yaml.

image.pullPolicy

string

IfNotPresent

No

Image pull policy. Valid values: Always, IfNotPresent, Never.

replicas

integer

2

No

Number of gateway pod replicas. Two replicas is the recommended configuration for high availability in production environments.

nodeLabel

string

hybrid-gateway-node

No

Node label key used to select gateway nodes. Nodes must have this label set to "true".

vpcCIDR

string

""

Yes

VPC CIDR block used for Cilium VTEP configuration. Example: 10.0.0.0/16.

podCIDRs

string

""

Yes

Comma-separated list of pod CIDRs used by Cilium on hybrid nodes. Example: 10.85.0.0/16,10.86.0.0/16.

routeTableIDs

string

""

Yes

Comma-separated list of VPC route table IDs to program with hybrid pod routes. Example: rtb-0123456789abcdef0,rtb-0123456789abcdef1.

autoMode.enabled

boolean

true

No

Enable EKS Auto Mode integration. When true, the chart adds an eks.amazonaws.com/compute-type: auto node selector and uses a zero-downtime rolling update strategy. Set to false for managed node groups or self-managed nodes.

Example install commands

EKS Auto Mode (default):

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:

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

Auto Mode vs. managed node group configuration

The autoMode.enabled Helm value controls two behaviors in the Deployment template:

Behavior autoMode.enabled=true (default) autoMode.enabled=false

Node selector

Adds eks.amazonaws.com/compute-type: auto in addition to the gateway node label.

Uses only the gateway node label (hybrid-gateway-node: "true").

Rolling update strategy

maxSurge: 1, maxUnavailable: 0 — ensures zero downtime during upgrades by starting a new pod before terminating the old one.

maxSurge: 0, maxUnavailable: 1 — terminates the old pod before starting a new one, because node capacity is pre-provisioned.

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. For the required YAML, see Get started with EKS Hybrid Nodes gateway. When using managed node groups or self-managed nodes, you must provision and label the nodes yourself before installing the chart.

For all deployment targets, the Deployment uses hostNetwork: true and requires the NET_ADMIN capability. Pod anti-affinity ensures that the two gateway pods run on separate nodes.

Leader election tuning

The gateway uses Kubernetes Lease-based leader election to maintain an active-standby model. The default parameters are tuned for fast failover:

Parameter Default Description

--leader-election-lease-duration

3s

How long a non-leader waits after the last observed lease renewal before trying to acquire the lease. Lower values detect leader failure faster but increase the risk of false failovers during transient network issues.

--leader-election-renew-deadline

2s

Maximum time the active leader spends trying to renew the lease before giving up leadership. Must be less than the lease duration.

--leader-election-retry-period

1s

How frequently candidates retry acquiring or renewing the lease.

With the default values, the expected failover time when the active gateway fails is approximately 3–5 seconds. This includes the time for the standby to detect the lease expiration, acquire the lease, and run the leader setup sequence (VPC route table updates and Cilium VTEP configuration).

When to adjust leader election parameters

  • Increase lease duration if you observe frequent leader transitions caused by transient network latency between gateway pods and the Kubernetes API server.

  • Decrease lease duration if you need faster failover detection and your network between gateway nodes and the API server is reliable and low-latency.

  • Increase retry period to reduce API server load from leader election in large clusters.

Note

The --leader-election-renew-deadline must always be less than --leader-election-lease-duration. If the renew deadline exceeds the lease duration, the leader may lose the lease before it can renew.