/terraform-aws-eks

A Terraform module to create an Elastic Kubernetes (EKS) cluster and associated worker instances on AWS.

Primary LanguageHCLMIT LicenseMIT

terraform-aws-eks

Lint Status LICENSE

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.

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 both kubectl (>=1.10) and aws-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

Testing

This module has been packaged with awspec tests through kitchen and kitchen-terraform. To run them:

  1. Install rvm and the ruby version specified in the Gemfile.

  2. Install bundler and the gems from our Gemfile:

    gem install bundler && bundle install
  3. Ensure your AWS environment is configured (i.e. credentials and region) for test.

  4. 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 by Brandon O'Connor - brandon@atscale.run. Maintained by Max Williams Many thanks to the contributors listed here!

License

MIT Licensed. See LICENSE for full details.

Inputs

Name Description Type Default Required
attach_worker_autoscaling_policy Whether to attach the module managed cluster autoscaling iam policy to the default worker IAM role. This requires manage_worker_autoscaling_policy = true bool "true" no
attach_worker_cni_policy Whether to attach the Amazon managed AmazonEKS_CNI_Policy IAM policy to the default worker IAM role. WARNING: If set false the permissions must be assigned to the aws-node DaemonSet pods via another method or nodes will not be able to join the cluster. bool "true" no
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.14" no
config_output_path Where to save the Kubectl config file (if write_kubeconfig = true). Assumed to be a directory if the value ends with 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_autoscaling_policy Whether to let the module manage the cluster autoscaling iam policy. 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. object [] no
map_users Additional IAM users to add to the aws-auth configmap. See examples/basic/variables.tf for example format. object [] no
permissions_boundary If provided, all IAM roles will be created with this permissions boundary attached. string "null" 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 Name filter for AWS EKS worker AMI. If not provided, the latest official AMI for the specified 'cluster_version' is used. string "" no
worker_ami_name_filter_windows Name filter for AWS EKS Windows worker AMI. If not provided, the latest official AMI for the specified 'cluster_version' is used. string "" no
worker_ami_owner_id The ID of the owner for the AMI to use for the AWS EKS workers. Valid values are an AWS account ID, 'self' (the current account), or an AWS owner alias (e.g. 'amazon', 'aws-marketplace', 'microsoft'). string "602401143452" no
worker_ami_owner_id_windows The ID of the owner for the AMI to use for the AWS EKS Windows workers. Valid values are an AWS account ID, 'self' (the current account), or an AWS owner alias (e.g. 'amazon', 'aws-marketplace', 'microsoft'). string "801119661308" no
worker_create_initial_lifecycle_hooks Whether to create initial lifecycle hooks provided in worker groups. bool "false" 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_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
workers_role_name User defined workers role name. string "" 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_oidc_issuer_url The URL on the EKS cluster OIDC Issuer
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_autoscaling_policy_arn ARN of the worker autoscaling IAM policy if manage_worker_autoscaling_policy = true
worker_autoscaling_policy_name Name of the worker autoscaling IAM policy if manage_worker_autoscaling_policy = true
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