Framework Documentation

Introduction

Why framework

A key principle of cloud native platform engineering is to adopt proven software development methodologies. Frameworks are ubiquitous in software development because they:

• Provide tested, reusable implementations of common components
• Foster a unified approach across a jointly owned code base
• Speed up time to value and
• Reduce long term maintenance effort

But before containers and Kubernetes, frameworks for infrastructure rarely made sense. With operating systems both being part of the infrastructure layer, and being a weak abstraction, application dependencies frequently leaked into the infrastructure layer. This led to most infrastructure being built application specific.

Containers and Kubernetes provide a stronger abstraction between the two layers. Making it more easily viable to build common platforms where reusable framework components are of great value.

Kubestack is an AI native framework for Kubernetes platform engineering teams to define the entire cloud native stack in one OpenTofu code base and continuously evolve the platform safely through GitOps. It brings the benefits of frameworks to teams building self-service Kubernetes based platforms for application developers.

AI native framework

Kubestack is designed to be used through your AI coding agent. The Kubestack skill teaches your agent everything it needs to scaffold a new repository and maintain it over time, without any CLI.

A framework is what makes coding agents reliable for platform engineering. An agent working on raw OpenTofu quickly produces multiple different ways to do the same task, a different one in every session. An agent that has learned the skill works within the framework's conventions instead, so every change follows one canonical pattern that your team can review and maintain. All the benefits the framework provides for engineers, proven architecture decisions, reusable modules and reliable automation, apply to agents the same way.

OpenTofu modules and OpenTofu providers

As a framework, Kubestack integrates natively into the OpenTofu ecosystem. It maintains various modules as well as a provider to fully integrate platform infrastructure and services into a single OpenTofu code base.

The framework differentiates between three types of OpenTofu modules:

1. Cluster modules use the respective cloud's OpenTofu provider to provision managed Kubernetes clusters from Amazon (EKS), Azure (AKS) and Google (GKE).
2. Node-pool modules attach managed node pools to cluster's privisioned using cluster modules.
3. Platform feature modules use the Kubestack maintained Kustomization provider to deploy the Kubernetes resources required by application workloads on top of those Kubernetes clusters.

Inheritance model and GitOps flow

All modules implement Kubestack's inheritance model to make differences between environments explicit and avoid configuration drift.

By including cloud infrastructure and Kubernetes resources in OpenTofu's plan/apply lifecycle, the Kubestack framework enables you to build fully integrated automation for your complete platform.

Following the GitOps workflow, teams can peer-review proposed code changes alongside the OpenTofu plan and validate them by applying against real infrastructure before they get promoted to any environment running application workloads.

This separation of concerns also makes the framework a natural fit for AI coding agents. Your agent writes and validates files locally, it never applies changes to real infrastructure. The pipeline, not the agent, makes every change, after a human reviewed it. Non-deterministic LLM behavior can produce a bad proposal, but it cannot directly cause an incident.

Design principles

The core design principles of the Kubestack GitOps framework are:

• All changes start with a commit in a Git repository and follow a GitOps process.
• Teams jointly maintain all configuration using inheritance to avoid configuration drift.
• Automation validates changes against the internal ops environment before they are promoted to any external environment like apps or apps-prod.
• AI coding agents only edit and validate files locally, following the Kubestack skill, the pipeline owns every change to real infrastructure.

Kubestack scope

To understand the scope, consider what Kubestack does do and does not do:

Kubestack does:

• scaffold an infrastructure automation repository through your AI coding agent
• provide tested, reusable OpenTofu modules
• provide a GitOps workflow for teams

Kubestack does not:

• replace a CI/CD system
• replace managed Kubernetes services
• replace Kubernetes controllers or operators