Framework documentation

# Framework Documentation

[Contribute on GitHub](https://github.com/kbst/terraform-kubestack)[Join #kubestack on Slack](https://slack.k8s.io/)

Topics

-   [Introduction](/documentation/)
-   [Platform Architecture](/documentation/platform-architecture/)
-   [GitOps Process](/documentation/gitops-process/)
-   [Inheritance Model](/documentation/inheritance-model/)
-   [Repository layout](/documentation/repository-layout/)
-   [Module Types](/documentation/module-types/)
-   [Clusters](/documentation/clusters/)
-   [Node-Pools](/documentation/node-pools/)
-   [Platform Features](/documentation/platform-features/)
-   [Extending Kubestack](/documentation/extending-kubestack/)

## 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](https://registry.terraform.io/providers/kbst/kustomization/latest). Platform feature modules are local modules in your repository. Your agent scaffolds them from upstream Helm charts or YAML manifests following the [Kubestack skill](https://www.kubestack.com/SKILL.md), see [platform features](/documentation/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](/documentation/inheritance-model/) all modules implement is a key enabler for Kubestack's reliable [GitOps automation](/documentation/gitops-process/).

These conventions are also what the [Kubestack skill](https://www.kubestack.com/SKILL.md) 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](https://opentofu.org/docs/language/modules/sources/).

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](/documentation/platform-features/#configuration) 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](/documentation/inheritance-model/#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](/documentation/clusters/#configuration).

**Amazon**

EKS requires the cluster module and a `aws` provider alias to configure the desired region. The alias attribute is used to pass a [specific provider into a specific module](https://www.terraform.io/docs/configuration/providers.html#alias-multiple-provider-instances).

```
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](/documentation/node-pools/#configuration).

**Amazon**

```
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](/documentation/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](/documentation/platform-features/#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.

**Amazon**

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

[PreviousRepository layout](/documentation/repository-layout/ "Repository layout")[NextClusters](/documentation/clusters/ "Clusters")

On this page

-   [Module Types](#module-types)
-   [Introduction](#introduction)
-   [Naming Conventions](#naming-conventions)
-   [Common Module Attributes](#common-module-attributes)
-   [Examples](#examples)

For your agent

-   [SKILL.md](/SKILL.md)
-   [This page as Markdown](/documentation/module-types/index.md)