devops-stack-module-cluster-eks

A DevOps Stack module to deploy a Kubernetes cluster on Amazon Web Services EKS.

This module currently only supports self-managed node groups and not EKS managed nodes. It uses the Terraform module "eks" by AWS to manage the cluster itself.

The node_groups variable is a map of objects. Each value of the map creates a node group referenced by its label. The value object can take any input accepted by the self-managed-node-group submodule.

Here is an example that creates one node group with 3 instances of type r5a.large, attaches them to the main Load Balancer, and customizes the base EBS volume size to 100 GB:

  node_groups = {
    "my-node-group" = {
      instance_type     = "r5a.xlarge"
      min_size          = 3
      max_size          = 3
      desired_size      = 3
      target_group_arns = module.my_cluster.nlb_target_groups

      block_device_mappings = {
        "default" = {
          device_name = "/dev/xvda"
          ebs = {
            volume_size = 100
          }
        }
      }
    },
  }
You can check out available instance types on the official AWS documentation pages.

Depending on the create_public_nlb and create_private_nlb variales, it creates a public and/or public Network Load Balancer(s). The node groups that have the target_group_arns = module.my_cluster.nlb_target_groups value set will be added as backends of the LBs. By default, the LBs only forward traffic on the ports 80 and 443, but you can customize this using the extra_lb_target_groups and extra_lb_http_tcp_listeners variables to add other ports. Look at the lb.tf file in this module for the syntax.

This module needs a Route 53 DNS zone in the same AWS account to create a wildcard CNAME record that points to the Network LB. The DNS zone must be passed in the base_domain variable. This record is used by other DevOps Stack modules as default URLs for their applications.

Technical Reference

Dependencies

Requirements

The following requirements are needed by this module:

Providers

The following providers are used by this module:

Modules

The following Modules are called:

cluster

Source: terraform-aws-modules/eks/aws

Version: ~> 19.0

nlb

Source: terraform-aws-modules/alb/aws

Version: ~> 8.0

nlb_private

Source: terraform-aws-modules/alb/aws

Version: ~> 8.0

Resources

The following resources are used by this module:

Required Inputs

The following input variables are required:

cluster_name

Description: Name of the EKS cluster. Must be unique in the AWS account.

Type: string

private_subnet_ids

Description: List of IDs of private subnets that the EKS instances will be attached to.

Type: list(string)

vpc_id

Description: ID of the VPC where the cluster and nodes will be deployed.

Type: string

Optional Inputs

The following input variables are optional (have default values):

aws_auth_accounts

Description: Additional AWS account numbers to add to the aws-auth configmap.

Type: list(string)

Default: []

aws_auth_roles

Description: Additional IAM roles to add to the aws-auth configmap.

Type:

list(object({
    rolearn  = string
    username = string
    groups   = list(string)
  }))

Default: []

aws_auth_users

Description: Additional IAM users to add to the aws-auth configmap.

Type:

list(object({
    userarn  = string
    username = string
    groups   = list(string)
  }))

Default: []

base_domain

Description: The base domain for the cluster.

This module needs a Route 53 zone matching this variable with permission to create DNS records. It will create a wildcard CNAME record *.apps.<base_domain> that points to an Elastic Load Balancer routing ingress traffic to all cluster nodes. Such urls will be used by default by other DevOps Stack modules for the applications they deploy (e.g. Argo CD, Prometheus, etc).

Type: string

Default: null

cluster_endpoint_public_access_cidrs

Description: List of CIDR blocks which can access the Amazon EKS public API server endpoint.

Type: list(string)

Default:

[
  "0.0.0.0/0"
]

create_private_nlb

Description: Whether to create an internal NLB attached the private subnets

Type: bool

Default: false

create_public_nlb

Description: Whether to create an internet-facing NLB attached to the public subnets

Type: bool

Default: true

extra_lb_http_tcp_listeners

Description: Additional Listeners to attach to Network LBs.

A list of maps describing the HTTP listeners. Required key/values: port, protocol. Optional key/values: target_group_index (defaults to http_tcp_listeners[count.index]).

Type: list(any)

Default: []

extra_lb_target_groups

Description: Additional Target Groups to attach to Network LBs.

A list of maps containing key/value pairs that define the target groups. Required key/values: name, backend_protocol, backend_port.

Type: list(any)

Default: []

kubernetes_version

Description: Kubernetes version for the EKS cluster.

Please check the AWS EKS documentation to find the available versions.

This variable can be changed on an existing cluster to update it. Note that this triggers an "instance refresh" on the nodes' auto scaling group, and so will recreate all pods running on the cluster.

Type: string

Default: "1.25"

nlb_attached_node_groups

Description: List of node_groups indexes that the NLB(s) should be attached to

Type: list(any)

Default: []

node_groups

Description: A map of node group configurations to be created.

Type: any

Default: {}

public_subnet_ids

Description: List of IDs of public subnets the public NLB will be attached to if enabled with 'create_public_nlb'.

Type: list(string)

Default: []

Outputs

The following outputs are exported:

base_domain

Description: The base domain for the cluster.

cluster_name

Description: Name of the EKS cluster.

cluster_oidc_issuer_url

Description: The URL on the EKS cluster for the OpenID Connect identity provider

kubernetes

Description: Kubernetes API endpoint and CA certificate as a structured value.

kubernetes_cluster_ca_certificate

Description: Certificate data required to communicate with the cluster.

kubernetes_host

Description: Endpoint for your Kubernetes API server.

kubernetes_token

Description: Token to use to authenticate with the cluster.

nlb_target_groups

Description: List of ARNs of Network LBs (public and/or private if enabled).

node_groups

Description: Map of attribute maps for all node groups created.

node_security_group_id

Description: ID of the node shared security group

Reference in table format

Show tables

= Requirements

Name Version

terraform

>= 1.0

aws

>= 4

= Providers

Name Version

aws

>= 4

dns

n/a

= Modules

Name Source Version

cluster

terraform-aws-modules/eks/aws

~> 19.0

nlb

terraform-aws-modules/alb/aws

~> 8.0

nlb_private

terraform-aws-modules/alb/aws

~> 8.0

= Resources

Name Type

aws_route53_record.wildcard

resource

aws_eks_cluster_auth.cluster

data source

aws_region.current

data source

aws_route53_zone.this

data source

dns_a_record_set.nlb

data source

= Inputs

Name Description Type Default Required

aws_auth_accounts

Additional AWS account numbers to add to the aws-auth configmap.

list(string)

[]

no

aws_auth_roles

Additional IAM roles to add to the aws-auth configmap.

 
list(object({
    rolearn  = string
    username = string
    groups   = list(string)
  }))

[]

no

aws_auth_users

Additional IAM users to add to the aws-auth configmap.

 
list(object({
    userarn  = string
    username = string
    groups   = list(string)
  }))

[]

no

base_domain

The base domain for the cluster.

This module needs a Route 53 zone matching this variable with permission to create DNS records. It will create a wildcard CNAME record *.apps.<base_domain> that points to an Elastic Load Balancer routing ingress traffic to all cluster nodes. Such urls will be used by default by other DevOps Stack modules for the applications they deploy (e.g. Argo CD, Prometheus, etc).

string

null

no

cluster_endpoint_public_access_cidrs

List of CIDR blocks which can access the Amazon EKS public API server endpoint.

list(string)

 
[
  "0.0.0.0/0"
]

no

cluster_name

Name of the EKS cluster. Must be unique in the AWS account.

string

n/a

yes

create_private_nlb

Whether to create an internal NLB attached the private subnets

bool

false

no

create_public_nlb

Whether to create an internet-facing NLB attached to the public subnets

bool

true

no

extra_lb_http_tcp_listeners

Additional Listeners to attach to Network LBs.

A list of maps describing the HTTP listeners. Required key/values: port, protocol. Optional key/values: target_group_index (defaults to http_tcp_listeners[count.index]).

list(any)

[]

no

extra_lb_target_groups

Additional Target Groups to attach to Network LBs.

A list of maps containing key/value pairs that define the target groups. Required key/values: name, backend_protocol, backend_port.

list(any)

[]

no

kubernetes_version

Kubernetes version for the EKS cluster.

Please check the AWS EKS documentation to find the available versions.

This variable can be changed on an existing cluster to update it. Note that this triggers an "instance refresh" on the nodes' auto scaling group, and so will recreate all pods running on the cluster.

string

"1.25"

no

nlb_attached_node_groups

List of node_groups indexes that the NLB(s) should be attached to

list(any)

[]

no

node_groups

A map of node group configurations to be created.

any

{}

no

private_subnet_ids

List of IDs of private subnets that the EKS instances will be attached to.

list(string)

n/a

yes

public_subnet_ids

List of IDs of public subnets the public NLB will be attached to if enabled with 'create_public_nlb'.

list(string)

[]

no

vpc_id

ID of the VPC where the cluster and nodes will be deployed.

string

n/a

yes

= Outputs

Name Description

base_domain

The base domain for the cluster.

cluster_name

Name of the EKS cluster.

cluster_oidc_issuer_url

The URL on the EKS cluster for the OpenID Connect identity provider

kubernetes

Kubernetes API endpoint and CA certificate as a structured value.

kubernetes_cluster_ca_certificate

Certificate data required to communicate with the cluster.

kubernetes_host

Endpoint for your Kubernetes API server.

kubernetes_token

Token to use to authenticate with the cluster.

nlb_target_groups

List of ARNs of Network LBs (public and/or private if enabled).

node_groups

Map of attribute maps for all node groups created.

node_security_group_id

ID of the node shared security group