Skip to main content
EKS Hybrid Nodes are physical or virtual machines outside of AWS that join an EKS cluster. They use the AWS IAM Authenticator together with temporary IAM credentials provisioned by either AWS SSM (the default) or AWS IAM Roles Anywhere. This sub-module creates the IAM role and attached policy that grant those credentials the minimum permissions needed to register and operate as an EKS node. The role ARN is then referenced in the root module’s access_entries variable with type HYBRID_LINUX.

SSM (default)

Hybrid nodes connect via AWS Systems Manager. No certificate infrastructure is required. SSM provisions temporary credentials that assume the hybrid node role.

IAM Roles Anywhere

Hybrid nodes use X.509 certificates and a trust anchor to obtain temporary credentials. Useful when you want PKI-based authentication independent of SSM connectivity.

​
Usage

module "eks" {
  source = "terraform-aws-modules/eks/aws"

  # ...

  access_entries = {
    hybrid-node-role = {
      principal_arn = module.eks_hybrid_node_role.arn
      type          = "HYBRID_LINUX"
    }
  }
}

module "eks_hybrid_node_role" {
  source = "terraform-aws-modules/eks/aws//modules/hybrid-node-role"

  name = "hybrid"

  tags = {
    Environment = "dev"
    Terraform   = "true"
  }
}
The arn output of this module is the value you pass to principal_arn in the root module’s access_entries. This is what allows the hybrid node’s credentials to be recognized by the EKS cluster.

​
Key inputs

​
name
string
default:"EKSHybridNode"
Name of the IAM role (and prefix for the associated policy). When using the role name as a fixed reference, set use_name_prefix = false.
​
use_name_prefix
bool
default:"true"
Use name as a prefix for uniqueness. Set to false when you need the exact role name in tooling or access entry references.
​
enable_ira
bool
default:"false"
Enable IAM Roles Anywhere. When true, the module also creates a Roles Anywhere trust anchor and profile, and an intermediate IAM role used in the credential vending chain.
​
trust_anchor_arns
list(string)
default:"[]"
ARNs of existing IAM Roles Anywhere trust anchors. Required when enable_ira = true and you want to use pre-existing anchors instead of creating a new one.
​
ira_trust_anchor_source_type
string
Source type for the trust anchor. Accepted values: CERTIFICATE_BUNDLE, AWS_ACM_PCA. Required when enable_ira = true and creating a new trust anchor.
​
ira_trust_anchor_x509_certificate_data
string
PEM-encoded X.509 certificate bundle for the trust anchor. Used when ira_trust_anchor_source_type = "CERTIFICATE_BUNDLE".
​
ira_trust_anchor_acm_pca_arn
string
ARN of the ACM Private CA that issued the trust anchor certificate. Used when ira_trust_anchor_source_type = "AWS_ACM_PCA".
​
enable_pod_identity
bool
default:"true"
Allow hybrid nodes to host EKS Pod Identity agent. Adds the necessary trust policy statement so pods running on hybrid nodes can use Pod Identity.
​
cluster_arns
list(string)
default:"['*']"
List of EKS cluster ARNs the node role is allowed to call eks:DescribeCluster on. Defaults to all clusters; scope this down in production.
​
permissions_boundary_arn
string
ARN of a permissions boundary policy to attach to the IAM role.
​
tags
map(string)
default:"{}"
Tags applied to all resources created by this module.

​
Key outputs

OutputDescription
arnARN of the hybrid node IAM role — use this as principal_arn in access_entries
nameName of the hybrid node IAM role
unique_idStable unique identifier for the IAM role
intermediate_role_arnARN of the intermediate IAM role (IAM Roles Anywhere only)
intermediate_role_nameName of the intermediate IAM role

​
How it integrates with the root module

Hybrid nodes are declared via the root module’s remote_network_config variable, which configures the VPC CNI for remote node connectivity. The access entry (created separately in access_entries) is what allows the node role’s credentials to authenticate. 
module "eks" {
  source = "terraform-aws-modules/eks/aws"

  # Remote network configuration for hybrid nodes
  remote_network_config = {
    remote_node_networks = [
      { cidrs = ["172.16.0.0/24"] }
    ]
    remote_pod_networks = [
      { cidrs = ["172.16.1.0/24"] }
    ]
  }

  access_entries = {
    hybrid-nodes = {
      principal_arn = module.eks_hybrid_node_role.arn
      type          = "HYBRID_LINUX"
    }
  }
}

​
Resources created

  • aws_iam_role.this — hybrid node role with SSM trust policy
  • aws_iam_policy.this — EKS hybrid node policy (describe cluster, etc.)
  • aws_iam_role_policy_attachment.this — attaches the policy to the role
  • aws_iam_role.this — hybrid node role
  • aws_iam_policy.this — EKS hybrid node policy
  • aws_iam_role_policy_attachment.this — attaches the policy
  • aws_iam_role.intermediate — intermediate role used in the credential chain
  • aws_iam_policy.intermediate — policy for the intermediate role
  • aws_iam_role_policy_attachment.intermediate — attaches the intermediate policy
  • aws_rolesanywhere_trust_anchor.this — trust anchor (when creating a new one)
  • aws_rolesanywhere_profile.this — Roles Anywhere profile
When using IAM Roles Anywhere, the trust_anchor_arns list must be provided or a new trust anchor must be configured via ira_trust_anchor_source_type. The module will error if enable_ira = true and neither is set.

Build docs developers (and LLMs) love

Get started for freeTalk to us