ventx/terraform-aws-stackx-cluster
Explore the diagrams »

Report a Bug · Request a Feature · Ask a Question

Table of Contents

• About
  • Built With
• Getting Started
  • Prerequisites
  • Quickstart
• Usage
• Support
• Project assistance
• Contributing
• Authors & contributors
• Security
• License
• Acknowledgements
• Roadmap

---

About

Terraform cluster module which deploys a Kubernetes (EKS) cluster control-plane to AWS. Supports logs ingested to CloudWatch via KMS encryption. Deploys EKS Add-Ons "aws-vpc-cni" and "kube-proxy" with matching EKS control-plane version. Creates an IAM OIDC provider to be used with EKS IRSA authentication mechanism. -- Part of stackx.

ℹ️ Architecture Diagrams

Placeholder	Rover

Built With

Getting Started

Prerequisites

• AWS credentials
• Terraform
• VPC network and subnets

Quickstart

To get started, clone the projects, check all configurable Inputs and deploy everything with make.

git clone https://github.com/ventx/stackx-terraform-aws-cluster.git
make all # init, validate, plan, apply

Usage

You can run this module in conjunction with other stackx components (recommended) or as single-use (build your own).

Deployment time around (with dependency modules): 15 minutes

  --- PASS: TestAwsCluster (958.78s)

stackx (RECOMMENDED)

This is just a bare minimum example of how to use the module. See all available stackx modules here: https://github.com/ventx

  module "aws-network" {
    source = "ventx/stackx-network/aws"
    version     = "0.1.0"
  }

  module "aws-cluster" {
    source          = "ventx/stackx-cluster/aws"
    version         = "0.3.1" // Pinned and tested version, generated by {x-release-please-version}
    cluster_version = "1.23"
    subnet_ids      = module.aws_network.private_subnet_ids
  }

Single-Use

  module "aws-cluster" {
    source = "ventx/stackx-cluster/aws"
    version     = "0.3.1" // Pinned and tested version, generated by {x-release-please-version}
    cluster_version = "1.22"
    subnet_ids = ["subnet-1", "subnet-2", "subnet-3"]
  }

Terraform

Features

• Simple and easy to use, just the bare minimum
• Control-Plan logs ingested to CloudWatch via KMS encryption
• EKS Add-Ons "aws-vpc-cni" and "kube-proxy"
• IAM OIDC provider to be used with EKS IRSA
• EKS Fargate Profile support (disabled by default)

Resources

• EKS
• EKS Fargate Profile
• CloudWatch Log Group
• IAM OIDC provider
• IAM Policies
• IAM Roles
• SecurityGroup
• SecurityGroup rules
• KMS Key
• KMS Key Alias

Opinions

Our Terraform modules are are highly opionated:

• Keep modules small, focused, simple and easy to understand
• Prefer simple code over complex code
• Prefer KISS > DRY
• Set some sane default values for variables, but do not set a default value if user input is strictly required

These opinions can be seen as some "soft" rules but which are not strictly required.

Requirements

Name	Version
terraform	>= 1.0.0
aws	>= 3.45.0
local	>= 2.1.0
null	>= 3.1.0
tls	>= 3.1.0

Providers

Name	Version
aws	5.22.0
tls	4.0.4

Modules

No modules.

Resources

Name	Type
aws_cloudwatch_log_group.eks_cluster	resource
aws_ec2_tag.cluster_security_group	resource
aws_eks_addon.kube_proxy	resource
aws_eks_addon.vpc_cni	resource
aws_eks_cluster.cluster	resource
aws_eks_fargate_profile.this	resource
aws_iam_openid_connect_provider.irsa	resource
aws_iam_policy.vpc_cni_ipv6	resource
aws_iam_role.eks_cluster	resource
aws_iam_role.fargate	resource
aws_iam_role.vpc_cni	resource
aws_iam_role_policy_attachment.attach	resource
aws_iam_role_policy_attachment.example	resource
aws_iam_role_policy_attachment.this	resource
aws_kms_alias.eks_secrets_encryption	resource
aws_kms_key.eks_secrets_encryption	resource
aws_security_group_rule.ingress_worker_cluster	resource
aws_security_group_rule.worker_cluster_ingress	resource
aws_caller_identity.current	data source
aws_eks_addon_version.kube_proxy	data source
aws_eks_addon_version.vpc_cni	data source
aws_eks_cluster_auth.cluster	data source
aws_iam_policy_document.eks_secrets_encryption	data source
aws_iam_policy_document.fargate_assume_role_policy	data source
aws_iam_policy_document.tr	data source
aws_iam_policy_document.vpc_cni	data source
aws_iam_policy_document.vpc_cni_ipv6	data source
aws_iam_session_context.current	data source
aws_partition.current	data source
aws_region.current	data source
tls_certificate.oidc	data source

Inputs

Name	Description	Type	Default	Required
cluster_cw_retention	Specifies the number of days you want to retain log events in the log group for EKS Cluster events (e.g. 90 => 90 days)	number	1	no
cluster_tags	Add additional tags to the EKS created main/primary cluster Security Group - will be merged with var.tags and Karpenter discovery tag	map(string)	{}	no
cluster_version	Kubernetes master major version (e.g. 1.28) (https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html)	string	"1.27"	no
cw_kms_arn	KMS Key ARN for CloudWatch encryption - if not set, your EKS control plane logs will be ingested unencrypted	string	""	no
eks_api_access_cidrs	IP CIDRs which are allowed to access the EKS API Public endpoint)	list(string)	[ "0.0.0.0/0" ]	no
eks_cluster_log_types	Log types to enable for EKS Cluster (Master) - Valid values: api, audit, authenticator, controllerManager, scheduler	list(string)	[ "api", "audit", "authenticator", "controllerManager", "scheduler" ]	no
eks_kms_admin_arns	Additional ARNs to be added in EKS KMS Key Policy for administrative access (default: current context)	list(string)	[]	no
eks_kms_arn	KMS Key ARN for EKS secrets encryption-at-rest	string	null	no
eks_kms_key_deletion_window	The waiting period, specified in number of days (between 7 and 30), until the AWS KMS Key will be finally deleted.	number	7	no
enable_addon_kube_proxy	Enable / Disable EKS Addon kube-proxy	bool	true	no
enable_addon_vpc_cni	Enable / Disable EKS Addon vpc-cni	bool	true	no
endpoint_private_access	Enable / Disable private EKS API endpoint	bool	true	no
endpoint_public_access	Enable / Disable private EKS API endpoint	bool	true	no
fargate	Enable / Disable use of Fargate profile	bool	false	no
fargate_iam_role_arn	Existing IAM Role ARN to be used for Fargate Execution Role	string	""	no
fargate_selectors	List of selector for Kubernetes Pods to execute with the Fargate Profile (Default to a K8s Namespace: fargate)	any	[ { "namespace": "fargate" } ]	no
ip_family	IP Family for EKS cluster - ipv4 or ipv6	string	"ipv4"	no
name	Base Name for all resources (preferably generated by terraform-null-label)	string	"stackx-cluster"	no
subnet_ids	Subnet IDs to create EKS Cluster into	list(string)	n/a	yes
tag_cluster_sg	Add tags to EKS created Cluster Security Group	bool	true	no
tags	User specific Tags / Labels to attach to resources (will be merged with module tags)	map(string)	{}	no
tf_eks_cluster_timeouts	(Optional) Updated Terraform resource management timeouts. Applies to aws_eks_cluster in particular to permit resource management times	map(string)	{ "create": "30m", "delete": "15m", "update": "60m" }	no
tf_eks_fargate_profile_timeouts	(Optional) Updated Terraform resource management timeouts. Applies to aws_eks_fargate_profile in particular to permit resource management times	map(string)	{ "create": "5m", "delete": "10m" }	no
worker_sg_id	SecurityGroup ID of Worker nodes	string	null	no

Outputs

Name	Description
api_cidrs	EKS Public API endpoint allowed CIDRs
cluster_ca	EKS Cluster certificate authority
cluster_endpoint	EKS Cluster endpoint
cluster_name	EKS Cluster name
cluster_role_arn	ARN of the EKS cluster IAM role
cluster_security_group_id	EKS Cluster Security Group ID created by Amazon EKS
cluster_version	EKS Cluster K8s Version
eni_sg_ids	EKS Cluster cross-account ENIs Security Group IDs
k8s_version	EKS Cluster K8s Version
oidc_issuer	Issuer URL of EKS Cluster OIDC
oidc_issuer_arn	OIDC Identity issuer ARN for the EKS cluster (IRSA)
platform_version	EKS Cluster Platform Version
sg_id	EKS Cluster Security Group ID created by Amazon EKS (convenience output)
vpc_id	EKS Cluster VPC ID

Support

If you need professional support directly by the maintainers of the project, don't hesitate to contact us:

• GitHub issues
• Contact options listed on this GitHub profile

Project assistance

If you want to say thank you or/and support active development of terraform-aws-stackx-cluster:

• Add a GitHub Star to the project.
• Tweet about the terraform-aws-stackx-cluster.
• Write interesting articles about the project on Dev.to, Medium or your personal blog.

Together, we can make terraform-aws-stackx-cluster better!

Contributing

First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please read our contribution guidelines, and thank you for being involved!

Security

terraform-aws-stackx-cluster follows good practices of security, but 100% security cannot be assured. terraform-aws-stackx-cluster is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the Apache 2.0 license.

See LICENSE for more information.

Acknowledgements

• All open source contributors who made this possible

Roadmap

See the open issues for a list of proposed features (and known issues).

• Top Feature Requests (Add your votes using the 👍 reaction)
• Top Bugs (Add your votes using the 👍 reaction)
• Newest Bugs