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
Resources
The following resources are used by this module:
-
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)
Required Inputs
The following input variables are required:
private_subnet_ids
Description: List of IDs of private subnets that the EKS instances will be attached to.
Type: list(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: []
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 |
---|---|
>= 1.0 |
|
>= 4 |
= Providers
Name | Version |
---|---|
>= 4 |
|
n/a |
= Modules
Name | Source | Version |
---|---|---|
terraform-aws-modules/eks/aws |
~> 19.0 |
|
terraform-aws-modules/alb/aws |
~> 8.0 |
|
terraform-aws-modules/alb/aws |
~> 8.0 |
= Resources
Name | Type |
---|---|
resource |
|
data source |
|
data source |
|
data source |
|
data source |
= Inputs
Name | Description | Type | Default | Required |
---|---|---|---|---|
Additional AWS account numbers to add to the aws-auth configmap. |
|
|
no |
|
Additional IAM roles to add to the aws-auth configmap. |
|
|
no |
|
Additional IAM users to add to the aws-auth configmap. |
|
|
no |
|
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 |
|
|
no |
|
List of CIDR blocks which can access the Amazon EKS public API server endpoint. |
|
|
no |
|
Name of the EKS cluster. Must be unique in the AWS account. |
|
n/a |
yes |
|
Whether to create an internal NLB attached the private subnets |
|
|
no |
|
Whether to create an internet-facing NLB attached to the public subnets |
|
|
no |
|
Additional Listeners to attach to Network LBs. A list of maps describing the HTTP listeners. Required key/values: |
|
|
no |
|
Additional Target Groups to attach to Network LBs. A list of maps containing key/value pairs that define the target groups. Required key/values: |
|
|
no |
|
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. |
|
|
no |
|
List of node_groups indexes that the NLB(s) should be attached to |
|
|
no |
|
A map of node group configurations to be created. |
|
|
no |
|
List of IDs of private subnets that the EKS instances will be attached to. |
|
n/a |
yes |
|
List of IDs of public subnets the public NLB will be attached to if enabled with 'create_public_nlb'. |
|
|
no |
|
ID of the VPC where the cluster and nodes will be deployed. |
|
n/a |
yes |
= Outputs
Name | Description |
---|---|
The base domain for the cluster. |
|
Name of the EKS cluster. |
|
The URL on the EKS cluster for the OpenID Connect identity provider |
|
Kubernetes API endpoint and CA certificate as a structured value. |
|
Certificate data required to communicate with the cluster. |
|
Endpoint for your Kubernetes API server. |
|
Token to use to authenticate with the cluster. |
|
List of ARNs of Network LBs (public and/or private if enabled). |
|
Map of attribute maps for all node groups created. |
|
ID of the node shared security group |