ventx/terraform-aws-stackx-worker
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

Minimal Terraform AWS EKS (K8s) Worker nodes module. Creates simple EKS Managed Node Groups which will be used for stackx or other gitOps components. Uses the optimized and hardened AWS Bottlerocket OS and supports regular x86_64 and ARM_64 architectures. Spot or On-Demand instances can be used but for stackx components ondemand is recommended. -- Part of stackx.

ℹ️ Architecture Diagrams

Placeholder	Rover

Built With

Getting Started

Prerequisites

• AWS credentials
• Terraform
• VPC network and subnets
• EKS Cluster

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-worker.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: 10 minutes (with network, cluster, worker)

  make apply 5.81s user 1.12s system 1% cpu 9:57.41 total

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"
  }

  module "aws-cluster" {
    source          = "ventx/stackx-cluster/aws"
    cluster_version = "1.27"
    subnet_ids      = module.aws_network.private_subnet_ids
  }

  module "aws-worker" {
    source          = "ventx/stackx-worker/aws"
    version         = "0.1.0" // Pinned and tested version, generated by {x-release-please-version}
    cluster_name    = module.stackx-cluster.cluster_name
    cluster_version = module.stackx-cluster.cluster_version
    subnet_ids      = module.stackx-network.private_subnet_ids
    vpc_id          = module.stackx-cluster.vpc_id
  }

Single-Use

  module "aws-worker" {
    source = "ventx/stackx-worker/aws"
    version     = "0.1.0" // Pinned and tested version, generated by {x-release-please-version}
    cluster_name    = "existing-eks-cluster
    cluster_version = "1.27"
    subnet_ids      = ["subnet-1", "subnet-2", "subnet-3"]
    vpc_id          = "vpc-123456789"
  }

Terraform

Features

• Simple and easy to use, just the bare minimum
• Uses Bottlerocket AMI for optimized and hardened OS
• Supports x86_64 and ARM_64 architectures
• Supports NVIDIA GPU

Resources

• EKS Node Group
• IAM OIDC provider
• IAM Roles
• SSM Session Manager
• map[OPTIONAL:SSH access]

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
http	>= 3.4.0

Providers

Name	Version
aws	5.22.0
http	3.4.0
random	3.5.1
tls	4.0.4

Modules

No modules.

Resources

Name	Type
aws_autoscaling_group_tag.stateless	resource
aws_eks_node_group.worker	resource
aws_iam_instance_profile.eks_worker	resource
aws_iam_role.eks_worker	resource
aws_iam_role_policy_attachment.attach	resource
aws_key_pair.ssh	resource
aws_secretsmanager_secret.ssh_private	resource
aws_secretsmanager_secret.ssh_public	resource
aws_secretsmanager_secret_version.ssh_private	resource
aws_secretsmanager_secret_version.ssh_public	resource
aws_security_group.ssh	resource
aws_security_group_rule.current_ipv4	resource
aws_ssm_parameter.ssh_private	resource
aws_ssm_parameter.ssh_pub	resource
random_string.random_name	resource
tls_private_key.ssh	resource
aws_iam_policy_document.tr	data source
aws_partition.current	data source
aws_ssm_parameter.eks_ami_release_version	data source
http_http.current_ipv4	data source

Inputs

Name	Description	Type	Default	Required
arch	CPU architecture to use for managed node groups (valid: x86_64, ARM_64)	string	"x86_64"	no
asg_tags	Add additional tags to the EKS Managed Node Group created AutoScalingGroup (in addition to the default cluster-autoscaler capacityType tag)	map(string)	{}	no
aws_key_name	Name of an existing AWS Key Pair name for SSH access to EKS Worker nodes - Leave empty to create new Key Pair	string	""	no
cluster_name	EKS Cluster name	string	"stackx"	no
cluster_version	EKS Cluster version	string	"1.27"	no
desired_size	Number of desired AWS EKS Worker nodes - Managed Node Group. Will be IGNORED after initial deployment	number	3	no
disk_size	EBS disk size in GiB for AWS EKS Worker nodes.	number	80	no
force_update_version	Force update of the version of the Managed Node Group even if PodDisruptionBudgets (PDB) are halting the drain process.	bool	false	no
gpu_ami	Enable / Disable the use of the Bottlerocket AMI for GPU workloads	bool	false	no
instance_types	List of EC2 Instance types of AWS EKS - Managed Node Group for stateless applications (e.g. [t3a.large])	list(string)	[ "c5a.xlarge", "c6a.xlarge" ]	no
key_storage	The AWS service to use to storage the generated SSH Public/Private Key pair for Worker node access	string	"ssm"	no
labels	Labels to add to the EKS Worker nodes	map(string)	{ "app": "stackx" }	no
list_policies_arns	List of additional policy ARNs to attach to EKS Worker Instance Profile role (max. 10)	list(string)	[]	no
max_size	Maximum of AWS EKS Worker nodes - Managed Node Group Stateless (maximum capacity for ASG, e.g. 8)	number	3	no
min_size	Minimum of AWS EKS Worker nodes - Managed Node Group Stateless (minimum capacity for ASG, e.g. 8)	number	3	no
name	Base Name for all resources (preferably generated by terraform-null-label)	string	"stackx-worker"	no
node_role_arn	IAM Role for workers	string	null	no
recovery_window_in_days	Secrets manager recovery window for SSH Public and Private Key for EKS Worker nodes	number	7	no
release_version	EKS AMI release version (get from AWS SSM, eg. /aws/service/bottlerocket/aws-k8s-1.27/x86_64/latest/image_version)	string	null	no
spot	Enable / Disable EC2 spot instances (true or false)	bool	false	no
ssh_allow_workstation	Allow your workstation IPv4 address access via SSH to EKS Worker nodes (var.ssh_allowed_sg_ids must be an empty list and var.vpc_id must be set	bool	true	no
ssh_allowed_sg_ids	List of source Security Group IDs to be allowed for SSH acess to EKS Worker nodes	list(string)	[]	no
subnet_ids	Subnet IDs where to create workers into	list(string)	n/a	yes
tags	User specific Tags to attach to resources (will be merged with module tags)	map(string)	{}	no
taints	List of taints to add to the EKS Worker nodes (e.g. {key = "test", value = "example", effect = "NoSchedule"})	list(map(string))	[ {} ]	no
tf_eks_node_group_timeouts	(Optional) Updated Terraform resource management timeouts. Applies to aws_eks_node_group in particular to permit resource management times	map(string)	{ "create": "40m", "delete": "40m", "update": "60m" }	no
vpc_id	VPC ID of EKS to create SecurityGroup for SSH access (optional)	string	""	no

Outputs

Name	Description
cluster_name	n/a
node_group_arn	n/a
node_group_asg_name	n/a
node_group_role_arn	EKS Worker Managed Node Group IAM Role ARN
node_group_role_name	EKS Worker Managed Node Group IAM Role Name
node_group_ssh_security_group_id	n/a
node_group_subnet_ids	EKS Worker Managed Node Group Subnet IDs
release_version	EKS Managed Node Group release version

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-worker:

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

Together, we can make terraform-aws-stackx-worker 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-worker follows good practices of security, but 100% security cannot be assured. terraform-aws-stackx-worker 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