KubestackKubestack

Kubestack catalog deprecationThe registry at kbst.xyz is deprecated and will be shut down on December 31, 2026, read the migration guide 

Framework Tutorial

Contribute on GithubJoin #kubestack on Slack

Design Platform

Overview

In this first part of the Kubestack tutorial you will:

  1. Decide on platform architecture and base configuration
  2. Scaffold your OpenTofu repository including a first cluster

Choose your architecture and base configuration

When scaffolding your platform there are two main decisions to take. First, what base_domain and name_prefix to use. And second, how many environments to bootstrap.

  1. base_domain and name_prefix

    • base_domain

      First, you have to select the base_domain to use for your platform. It will be part of the fully qualified domain name (FQDN) for each cluster. For the tutorial we use kubestack.example.com. You must replace example.com with a domain you control. The base_domain is a good option to brand your platform.

    • name_prefix

      You also have to choose a name_prefix for the first cluster. You can use the name prefix to designate a cluster to a specific type of workload, a single tenant or add some creativity to the names. Below examples, use gc0 as the name prefix. Where gc stands for general compute and 0 is there so you can add gc1 if you outgrow the capacity of a single cluster in a region.

  2. Environments

    By default your agent scaffolds a repository with two environments named ops and apps. Each environment will be a complete, separate copy of your entire platform and all its components.

    The ops environment is internal to the platform team, and is used to preview proposed changes and to validate them before they are promoted to apps. All platform users would run both non-prod and prod application enviroments in the external apps enviroment.

    If you prefer non-prod and prod application environments to be separated, the two most common approaches are to:

    • either have separate node pools for non-prod and prod attached to the cluster,
    • or add a third environment, e.g. named apps-prod, to run prod workloads on an entire third copy of your platform

    To have three environments tell your agent to use the environment names apps-prod, apps and ops. Should you want to customize the environment names, order them from mission critial external environment, to internal environment.

Kubestack supports a large number of different platform architectures using different combinations of name prefixes and environments. The platform architecture documentation page explains use-cases and provides examples.

Initialize your repository

Now, ask your agent to initialize your OpenTofu code and repository. Select the tab for the cloud you want to start with.

Your agent knows the required repository structure and module configuration from the skill. It writes the files locally, so you can review every change with git status. If any decision is still open, your agent asks you before writing the files.

AmazonAzureGoogle

Alongside the base domain and name prefix, select a region to use for your fist EKS cluster.

Initialize a new Kubestack repository with a first EKS cluster
in the eu-west-1 region, using gc0 as name_prefix and
kubestack.example.com as base_domain

Your agent may ask you to confirm additional details, like the availability zones to use for the cluster.

Your agent creates the repository in your current working directory, records all decisions in the README.md of the new repository, and saves the skill itself as AGENTS.md in the repository. This way every future agent session can pick the repository up without having to learn the skill again. The remote state configuration is created later in the tutorial, once the state storage exists.

Next

Let's continue the tutorial and provision the cloud infrastructure.

previousnext