Tutorial

# Framework Tutorial

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

Topics

-   [Get Started](/tutorial/)

## Get Started

### Learn the skill

Kubestack is designed to be used through your AI coding agent. There is no CLI to install. Everything your agent needs to bootstrap a new platform repository and to maintain it over time is captured in the Kubestack skill, published at https://www.kubestack.com/SKILL.md

Ask your agent to learn the skill and bootstrap a new platform:

```
Learn the Kubestack skill at https://www.kubestack.com/SKILL.md and bootstrap a new platform
```

Once learned, your agent keeps the skill in its own native skill storage, so every future session picks it up automatically.

**You stay in control:** Following the skill, your agent only writes local files and verifies them with `tofu validate`. You can review every change with `git status`. Applying changes to cloud infrastructure always remains the job of the GitOps pipeline, where a human reviews and approves every change.

### What your agent will ask you

Before writing any files, your agent confirms the platform decisions with you, in this order:

1.  The cloud provider and region — plus the project for Google Cloud or the resource group for Azure
2.  The `base_domain` for the platform — a domain you own and control
3.  The `name_prefix` for the first cluster, e.g. `gc0`
4.  The environments to bootstrap — `ops` and `apps` by default, optionally a third `apps-prod`
5.  Cluster sizing — instance type, min and max size, and availability zones
6.  Where to host the repository and which CI/CD system to run the pipeline on — GitHub Actions, GitLab CI, Jenkins, CircleCI or Azure DevOps
7.  The remote state backend for OpenTofu

Every answer is recorded in the `README.md` of the new repository, so your agent never has to ask twice.

### What your agent will do

With the decisions recorded, your agent:

1.  Scaffolds the new repository locally: `README.md`, `versions.tf`, `Dockerfile` and the files for the first cluster
2.  Verifies the configuration with `tofu validate`
3.  Hands the bootstrap steps back to you to run: cloud authentication, provisioning the remote state, creating the OpenTofu workspaces and running `tofu apply` for the first time
4.  Writes the pipeline file for your chosen CI/CD system — the skill contains the reference GitHub Actions pipeline plus rules to adapt the [example pipelines](https://github.com/kbst/example-pipelines) for other systems, including running environments in parallel and passing the plan between pipeline steps
5.  From then on works with you through the GitOps workflow: it edits files on branches, the pipeline plans on pull requests, applies to `ops` on merge to main, and applies to `apps` when you push an `apps-deploy-*` tag

**Community Help:** If you have any questions, join the [#kubestack](https://app.slack.com/client/T09NY5SBT/CMBCT7XRQ) channel on the Kubernetes community. To create an account request an [invitation](https://slack.k8s.io/).

On this page

-   [Get Started](#get-started)
-   [Learn the skill](#learn-the-skill)
-   [What your agent will ask you](#what-your-agent-will-ask-you)
-   [What your agent will do](#what-your-agent-will-do)

For your agent

-   [SKILL.md](/SKILL.md)
-   [This page as Markdown](/tutorial/index.md)