repository·master·Indexed 20 days ago
https://github.com/kbst/terraform-kubestackAn open-source Terraform framework for Kubernetes Platform Engineering. Kubestack enables teams to define their cloud-native stack in a single codebase and manage platform evolution via a GitOps workflow. It features an inheritance model to prevent configuration drift and provides modules for multiple cloud providers including AWS, Azure, Google, and Scaleway.
Kubestack is an open-source Terraform framework designed for Kubernetes Platform Engineering teams. It allows teams to define their entire cloud-native stack within a single Terraform codebase and evolve the platform safely using GitOps workflows.
Key features include:
The repository is organized by cloud provider and contains specific module patterns:
aws/, azurerm/, google/).common/ directory contains modules used across all providers. Notable modules include:common/metadata: Ensures a consistent naming scheme.kustomization/overlay: Integrates Kustomize into the Terraform apply process for platform features.cluster/: The user-facing module. This interface is intended to be stable and is the primary entry point for users._modules/: Contains the actual implementation details used internally by the cluster module.quickstart/ directory contains the source for zip files used to bootstrap user repositories during the tutorial.tests/ directory contains happy path tests.Kubestack modules may contain 'divergences'—intentional deviations from the project's standard architectural rules (defined in AGENTS.md). These divergences exist because the current implementation cannot yet meet a specific rule due to provider limitations, historical reasons, or planned refactors.
Important for Developers:
Kubestack distinguishes between two types of deviations from its standard module contract:
Kubestack consists of several interconnected components:
kbst CLI tool helps scaffold Terraform code for clusters, node pools, or services. It operates on local files, allowing users to review changes via git status.If automation is unavailable or you are in a disaster recovery scenario, you can run Terraform and cloud CLIs locally using the Kubestack container image. This image bundles all necessary dependencies.
Build the image and run it interactively, mounting your current directory to /infra.
Credentials are cached in the .user directory (which is git-ignored). Use the standard CLI tools for your provider (aws, az, gcloud, or scw) to authenticate.
Select the desired Terraform workspace (ops or apps) and run your commands.
# Build and run the container
docker build -t kubestack .
docker run --rm -ti \
-v `pwd`:/infra \
kubestack
# Authenticate (examples)
aws configure
az login
gcloud init
# Select environment
terraform workspace select ops
# Run commands
terraform init
terraform planTo modify Kubernetes clusters, supporting infrastructure, or Kubernetes services, follow this four-step GitOps workflow. This process ensures changes are validated against the _ops environment before being promoted to the _apps environment.
Create a new branch from main, apply your configuration changes, and push the branch. This triggers a terraform plan against the _ops workspace.
Request a peer review. Reviewers will examine the proposed changes and the Terraform plan. If changes are requested, commit and push them to the same branch.
Once approved, merge the branch into main. This applies the changes to the _ops environment. If successful, the pipeline automatically runs a terraform plan against the _apps environment.
Review the plan for the _apps environment. To promote the changes to the _apps environment, create a Git tag on the merge commit using the prefix apps-deploy- followed by the date and an optional counter.
# 1. Change
git checkout -b examplechange main
git commit
git push origin examplechange
# 2. Review (if changes are needed)
git checkout examplechange
git commit
git push origin examplechange
# 3. Merge
git checkout main
git merge examplechange
git push origin main
# 4. Promote
git checkout main
git pull
git log -1
# Tagging triggers the apps environment pipeline
git tag apps-deploy-$(date -I)-0The recommended way to begin using Kubestack is by following the official Kubestack tutorial. The tutorial guides you through using the framework to build a Kubernetes platform application.
Tutorial Link: https://www.kubestack.com/framework/tutorial/
Some modules have permanent exceptions to the standard contract. For example, the aws/cluster/node-pool module requires cluster_default_node_pool_name and cluster_default_node_pool_subnet_ids to be explicitly provided when provisioning the default node pool itself. This is necessary to break a circular dependency where the node-pool module would otherwise attempt to determine subnets from the default node pool's own subnet IDs.
> **Exception — `aws/cluster/node-pool`:** `cluster_default_node_pool_name` and `cluster_default_node_pool_subnet_ids` — the node-pool module for extra node pools determines subnets from the default node pool's subnet IDs by default; when provisioning the default node pool itself these variables are required to break the circular dependency.The google/cluster/node-pool module has the following deviations:
node_config.labels is merge(cfg.labels, cluster_metadata.labels), which allows metadata labels to override user-supplied labels (the inverse of the required precedence).google_container_node_pool resource sets initial_node_count but lacks a lifecycle { ignore_changes = [initial_node_count] } block, meaning the node count is managed by Terraform state rather than the autoscaler.The aws/cluster module has several known deviations from standard Kubestack patterns:
map_public_ip_on_launch = true when cluster_vpc_subnet_map_public_ip is unset). Standard practice requires private IPs and NAT gateway egress.region configuration attribute; the AWS region is sourced from the provider configuration. The EKS quickstart demonstrates how to alias the provider per cluster.additional_node_tags inside default_node_pool. There is no top-level tags attribute, meaning VPC, subnets, and security groups cannot receive user-supplied tags.cluster_aws_auth_map_roles and cluster_aws_auth_map_users using an in-module kubernetes provider, which is considered an anti-pattern.kubernetes_config_map resource to manage the aws-auth ConfigMap, violating the rule that cluster modules must not contain kubernetes_* resources.aws/cluster/node-pool, the labels attribute is applied to the cloud API but not to the Kubernetes node object's .metadata.labels.