Skip to content

Latest commit

 

History

History
339 lines (236 loc) · 18 KB

README.md

File metadata and controls

339 lines (236 loc) · 18 KB
Raw

Logo

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

Report a Bug · Request a Feature · Ask a Question

Project license

Pull Requests welcome code with love by ventx

Table of Contents

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

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: ventx Contact Us Kontakt

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).