Framework Documentation

Module Types

TL;DR:

• Kubestack provides modules for clusters, node-pools and platform features.
• Modules have common inputs and implement the Kubestack configuration inheritance.
• All platform components are fully integrated into the OpenTofu plan/apply lifecycle.

Introduction

Kubestack provides OpenTofu modules for the different platform components. There are three types of modules. Cluster modules, node-pool modules and platform feature modules.

1. Cluster modules provision managed Kubernetes clusters and their required infrastructure dependencies using the respective cloud's OpenTofu provider.
2. Node-Pool modules provision and attach Node-Pools to clusters provisioned by cluster modules.
3. Platform feature modules provision Kubernetes resources on top of Kubernetes clusters using the Kubestack maintained Kustomization provider. Platform feature modules are local modules in your repository. Your agent scaffolds them from upstream Helm charts or YAML manifests following the Kubestack skill, see platform features.

Ultimately, all Kubestack modules are just OpenTofu modules that implement standard Kubestack inputs and outputs. This provides a unified developer experience and makes for seamless integration between the different platform components.

The Kubestack specific inheritance based configuration all modules implement is a key enabler for Kubestack's reliable GitOps automation.

These conventions are also what the Kubestack skill teaches your AI coding agent. Whatever the task, adding a cluster, a node pool or a platform feature, the agent follows the same module pattern every time.

Naming Conventions

Module identifiers and file names by convention reflect the cluster that the module provisions. Node-pool and platform feature binding files are prefixed with the cluster they belong to.

Cluster modules implement a unified naming scheme to support multi-cluster, multi-region and multi-cloud platform architectures. Names are unique for:

• one or more clusters
• in one or more regions
• on a single or multiple different cloud providers
• across multiple infrastructure environments

Common Module Attributes

Kubestack OpenTofu modules accept the following attributes:

source and version (required)

Source and version of the module as required by OpenTofu.

Cluster and node-pool modules are available from GitHub and include the version using the ?ref parameter in the source. Versions for cluster and node-pool modules are the framework version.

# source for a fictitious cluster module
source = "github.com/kbst/terraform-kubestack//example/cluster?ref=v0.1.0"

# source for a fictitious node-pool module
source = "github.com/kbst/terraform-kubestack//example/cluster/node-pool?ref=v0.1.0"

Platform feature modules live in your repository under modules/<feature_name>/. The module's main.tf contains the kustomization overlay module from the framework, referenced with the ?ref parameter set to the framework version.

# source for the overlay module in modules/<feature_name>/main.tf
source = "github.com/kbst/terraform-kubestack//kustomization/overlay?ref=v0.1.0"

Each cluster the feature is deployed to gets a binding file that references the local module directory.

# source for a cluster's binding file
source = "./modules/<feature_name>"

configuration (required)

Map of per environment configuration objects. Following Kubestack's inheritance model. The configuration attributes are specific to the module type and for cluster and node-pool modules also specific to the provider. All platform feature modules support the same configuration attributes.

configuration = {
  apps = {
    # module specific configuration attributes
  }

  ops = {
    # inherits from apps
  }
}

configuration_base_key (optional)

Name of the key in the configuration map all others inherit from. Key must exist in configuration map. Defaults to apps.

configuration_base_key = "apps-prod"
configuration = {
  apps-prod = {
    # every environment inhertis from apps-prod
    # because configuration_base_key is set to apps-prod
  }

  apps-stage = {
    # inherits from apps-prod
  }

  ops = {
    # inherits from apps-prod
  }
}

Examples

Kubestack modules are regular OpenTofu modules and are used the same way. Below examples show general examples how to use cluster, node-pool and platform feature modules.

Cluster Module Examples

The configuration attributes for cluster modules are cloud provider specific. Available attributes are documented as part of the cluster module configuration.

provider "aws" {
  alias = "eks_gc0_eu-west-1"

  region = "eu-west-1"
}

module "eks_gc0_eu-west-1" {
  providers = {
    aws = aws.eks_gc0_eu-west-1
  }

  source = "github.com/kbst/terraform-kubestack//aws/cluster?ref=<version>"

  configuration = {
    apps = {
      base_domain                = var.base_domain
      name_prefix                = "gc0"
      cluster_availability_zones = ["eu-west-1a", "eu-west-1b", "eu-west-1c"]

      default_node_pool = {
        instance_types   = ["t3a.xlarge"]
        desired_capacity = 3
        min_size         = 3
        max_size         = 9
      }
    }
    ops = {}
  }
}

Node-Pool Module Examples

The configuration attributes for node-pool modules are cloud provider specific. Available attributes are documented as part of the node-pool module configuration.

module "eks_gc0_eu-west-1_node_pool_extra" {
  providers = {
    aws = aws.eks_gc0_eu-west-1
  }

  source = "github.com/kbst/terraform-kubestack//aws/cluster/node-pool?ref=<version>"

  cluster          = module.eks_gc0_eu-west-1.cluster
  cluster_metadata = module.eks_gc0_eu-west-1.current_metadata

  configuration = {
    apps = {
      name             = "extra"
      instance_types   = ["t3a.xlarge"]
      desired_capacity = 3
      max_size         = 9
      min_size         = 3
    }
    ops = {}
  }
}

Platform Feature Module Example

Platform feature modules live in your repository, see platform features. The module's main.tf calls the kustomization overlay module and holds the per environment configuration. Available attributes are documented as part of the platform feature module configuration.

# modules/nginx/main.tf
module "nginx" {
  providers = {
    kustomization = kustomization
  }

  # use the framework version that all other modules use
  source = "github.com/kbst/terraform-kubestack//kustomization/overlay?ref=<version>"

  configuration = {
    apps = {
      resources = [
        "${path.module}/manifests/upstream.yaml",
      ]
    }
    ops  = {}
  }
}

Each cluster the feature is deployed to gets a binding file, referencing the local module directory with the cluster's aliased kustomization provider.

provider "kustomization" {
  alias = "eks_gc0_eu-west-1"

  kubeconfig_raw = module.eks_gc0_eu-west-1.kubeconfig
}

module "eks_gc0_eu-west-1_feature_nginx" {
  providers = {
    kustomization = kustomization.eks_gc0_eu-west-1
  }

  source = "./modules/nginx"
}