terraform-aws-eks
A terraform module to create a managed Kubernetes cluster on AWS EKS. Available through the Terraform registry. Inspired by and adapted from this doc and its source code. Read the AWS docs on EKS to get connected to the k8s dashboard.
Branch | Build status |
---|---|
master |
Assumptions
- You want to create an EKS cluster and an autoscaling group of workers for the cluster.
- You want these resources to exist within security groups that allow communication and coordination. These can be user provided or created within the module.
- You've created a Virtual Private Cloud (VPC) and subnets where you intend to put the EKS resources. The VPC satisfies EKS requirements.
- If
manage_aws_auth = true
, it's required that bothkubectl
(>=1.10) andaws-iam-authenticator
are installed and on your shell's PATH.
Usage example
A full example leveraging other community modules is contained in the examples/basic directory. Here's the gist of using it via the Terraform registry:
module "my-cluster" {
source = "terraform-aws-modules/eks/aws"
cluster_name = "my-cluster"
subnets = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"]
vpc_id = "vpc-1234556abcdef"
worker_groups = [
{
instance_type = "m4.large"
asg_max_size = 5
tags = [{
key = "foo"
value = "bar"
propagate_at_launch = true
}]
}
]
tags = {
environment = "test"
}
}
Other documentation
- Autoscaling: How to enable worker node autoscaling.
- Enable Docker Bridge Network: How to enable the docker bridge network when using the EKS-optimized AMI, which disables it by default.
- Spot instances: How to use spot instances with this module.
Release schedule
Generally the maintainers will try to release the module once every 2 weeks to keep up with PR additions. If particularly pressing changes are added or maintainers come up with the spare time (hah!), release may happen more often on occasion.
Testing
This module has been packaged with awspec tests through kitchen and kitchen-terraform. To run them:
-
Install bundler and the gems from our Gemfile:
gem install bundler && bundle install
-
Ensure your AWS environment is configured (i.e. credentials and region) for test.
-
Test using
bundle exec kitchen test
from the root of the repo.
For now, connectivity to the kubernetes cluster is not tested but will be in the future. Once the test fixture has converged, you can query the test cluster from that terminal session with
kubectl get nodes --watch --kubeconfig kubeconfig
(using default settings config_output_path = "./"
& write_kubeconfig = true
)
Doc generation
Code formatting and documentation for variables and outputs is generated using pre-commit-terraform hooks which uses terraform-docs.
Follow these instructions to install pre-commit locally.
And install terraform-docs
with go get github.com/segmentio/terraform-docs
or brew install terraform-docs
.
Contributing
Report issues/questions/feature requests on in the issues section.
Full contributing guidelines are covered here.
Change log
The changelog captures all important release notes.
Authors
Created and maintained by Brandon O'Connor - brandon@atscale.run. Many thanks to the contributors listed here!
License
MIT Licensed. See LICENSE for full details.
Inputs
Name | Description | Type | Default | Required |
---|---|---|---|---|
cluster_create_security_group | Whether to create a security group for the cluster or attach the cluster to cluster_security_group_id . |
bool | "true" |
no |
cluster_create_timeout | Timeout value when creating the EKS cluster. | string | "15m" |
no |
cluster_delete_timeout | Timeout value when deleting the EKS cluster. | string | "15m" |
no |
cluster_enabled_log_types | A list of the desired control plane logging to enable. For more information, see Amazon EKS Control Plane Logging documentation (https://docs.aws.amazon.com/eks/latest/userguide/control-plane-logs.html) | list(string) | [] |
no |
cluster_endpoint_private_access | Indicates whether or not the Amazon EKS private API server endpoint is enabled. | bool | "false" |
no |
cluster_endpoint_public_access | Indicates whether or not the Amazon EKS public API server endpoint is enabled. | bool | "true" |
no |
cluster_iam_role_name | IAM role name for the cluster. Only applicable if manage_cluster_iam_resources is set to false. | string | "" |
no |
cluster_log_kms_key_id | If a KMS Key ARN is set, this key will be used to encrypt the corresponding log group. Please be sure that the KMS Key has an appropriate key policy (https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html) | string | "" |
no |
cluster_log_retention_in_days | Number of days to retain log events. Default retention - 90 days. | number | "90" |
no |
cluster_name | Name of the EKS cluster. Also used as a prefix in names of related resources. | string | n/a | yes |
cluster_security_group_id | If provided, the EKS cluster will be attached to this security group. If not given, a security group will be created with necessary ingres/egress to work with the workers | string | "" |
no |
cluster_version | Kubernetes version to use for the EKS cluster. | string | "1.13" |
no |
config_output_path | Where to save the Kubectl config file (if write_kubeconfig = true ). Should end in a forward slash / . |
string | "./" |
no |
iam_path | If provided, all IAM roles will be created on this path. | string | "/" |
no |
kubeconfig_aws_authenticator_additional_args | Any additional arguments to pass to the authenticator such as the role to assume. e.g. ["-r", "MyEksRole"]. | list(string) | [] |
no |
kubeconfig_aws_authenticator_command | Command to use to fetch AWS EKS credentials. | string | "aws-iam-authenticator" |
no |
kubeconfig_aws_authenticator_command_args | Default arguments passed to the authenticator command. Defaults to [token -i $cluster_name]. | list(string) | [] |
no |
kubeconfig_aws_authenticator_env_variables | Environment variables that should be used when executing the authenticator. e.g. { AWS_PROFILE = "eks"}. | map(string) | {} |
no |
kubeconfig_name | Override the default name used for items kubeconfig. | string | "" |
no |
local_exec_interpreter | Command to run for local-exec resources. Must be a shell-style interpreter. If you are on Windows Git Bash is a good choice. | list(string) | [ "/bin/sh", "-c" ] |
no |
manage_aws_auth | Whether to apply the aws-auth configmap file. | string | "true" |
no |
manage_cluster_iam_resources | Whether to let the module manage cluster IAM resources. If set to false, cluster_iam_role_name must be specified. | bool | "true" |
no |
manage_worker_iam_resources | Whether to let the module manage worker IAM resources. If set to false, iam_instance_profile_name must be specified for workers. | bool | "true" |
no |
map_accounts | Additional AWS account numbers to add to the aws-auth configmap. See examples/basic/variables.tf for example format. | list(string) | [] |
no |
map_roles | Additional IAM roles to add to the aws-auth configmap. See examples/basic/variables.tf for example format. | list(map(string)) | [] |
no |
map_users | Additional IAM users to add to the aws-auth configmap. See examples/basic/variables.tf for example format. | list(map(string)) | [] |
no |
permissions_boundary | If provided, all IAM roles will be created with this permissions boundary attached. | string | "" |
no |
subnets | A list of subnets to place the EKS cluster and workers within. | list(string) | n/a | yes |
tags | A map of tags to add to all resources. | map(string) | {} |
no |
vpc_id | VPC where the cluster and workers will be deployed. | string | n/a | yes |
worker_additional_security_group_ids | A list of additional security group ids to attach to worker instances | list(string) | [] |
no |
worker_ami_name_filter | Additional name filter for AWS EKS worker AMI. Default behaviour will get latest for the cluster_version but could be set to a release from amazon-eks-ami, e.g. "v20190220" | string | "v*" |
no |
worker_create_security_group | Whether to create a security group for the workers or attach the workers to worker_security_group_id . |
bool | "true" |
no |
worker_groups | A list of maps defining worker group configurations to be defined using AWS Launch Configurations. See workers_group_defaults for valid keys. | any | [] |
no |
worker_groups_launch_template | A list of maps defining worker group configurations to be defined using AWS Launch Templates. See workers_group_defaults for valid keys. | any | [] |
no |
worker_groups_launch_template_mixed | A list of maps defining worker group configurations to be defined using AWS Launch Templates. See workers_group_defaults for valid keys. | any | [] |
no |
worker_security_group_id | If provided, all workers will be attached to this security group. If not given, a security group will be created with necessary ingres/egress to work with the EKS cluster. | string | "" |
no |
worker_sg_ingress_from_port | Minimum port number from which pods will accept communication. Must be changed to a lower value if some pods in your cluster will expose a port lower than 1025 (e.g. 22, 80, or 443). | number | "1025" |
no |
workers_additional_policies | Additional policies to be added to workers | list(string) | [] |
no |
workers_group_defaults | Override default values for target groups. See workers_group_defaults_defaults in local.tf for valid keys. | any | {} |
no |
write_aws_auth_config | Whether to write the aws-auth configmap file. | bool | "true" |
no |
write_kubeconfig | Whether to write a Kubectl config file containing the cluster configuration. Saved to config_output_path . |
bool | "true" |
no |
Outputs
Name | Description |
---|---|
cloudwatch_log_group_name | Name of cloudwatch log group created |
cluster_arn | The Amazon Resource Name (ARN) of the cluster. |
cluster_certificate_authority_data | Nested attribute containing certificate-authority-data for your cluster. This is the base64 encoded certificate data required to communicate with your cluster. |
cluster_endpoint | The endpoint for your EKS Kubernetes API. |
cluster_iam_role_arn | IAM role ARN of the EKS cluster. |
cluster_iam_role_name | IAM role name of the EKS cluster. |
cluster_id | The name/id of the EKS cluster. |
cluster_security_group_id | Security group ID attached to the EKS cluster. |
cluster_version | The Kubernetes server version for the EKS cluster. |
config_map_aws_auth | A kubernetes configuration to authenticate to this EKS cluster. |
kubeconfig | kubectl config file contents for this EKS cluster. |
kubeconfig_filename | The filename of the generated kubectl config. |
worker_iam_instance_profile_arns | default IAM instance profile ARN for EKS worker groups |
worker_iam_instance_profile_names | default IAM instance profile name for EKS worker groups |
worker_iam_role_arn | default IAM role ARN for EKS worker groups |
worker_iam_role_name | default IAM role name for EKS worker groups |
worker_security_group_id | Security group ID attached to the EKS workers. |
workers_asg_arns | IDs of the autoscaling groups containing workers. |
workers_asg_names | Names of the autoscaling groups containing workers. |
workers_default_ami_id | ID of the default worker group AMI |
workers_launch_template_arns | ARNs of the worker launch templates. |
workers_launch_template_ids | IDs of the worker launch templates. |
workers_launch_template_latest_versions | Latest versions of the worker launch templates. |
workers_user_data | User data of worker groups |