Built-in vs. custom: How to choose a Konstruct cluster template strategy

If you've ever inherited a cluster that nobody fully understands, or watched two teams solve the same infrastructure problem in completely different ways, you've already felt the cost of not having a template strategy. It's not always dramatic; it starts with a different CNI here, a missing cert-manager version there, but it compounds. Six months later, cluster configuration is tribal knowledge, and the platform team has become the bottleneck.

On 19 August, M R Rishi and I sat down in our Platform Engineering Unplugged series to walk through exactly this problem: why every cluster in an organization looks slightly different, and how Konstruct's cluster template system is designed to fix it without taking autonomy away from the teams who need it.

What is a cluster template in Konstruct?

Every cluster in Konstruct, from the management cluster down to a lightweight virtual cluster, is provisioned from a template. That template defines everything: the platform applications that get installed, the infrastructure definitions, the RBAC and certificates, and the GitOps scaffolding that keeps it all in sync.

Think of a template as the blueprint that turns "create cluster" into a production-ready environment, not a blank node. The goal isn't consistency for its own sake, it's giving every team a cluster that works from minute one, without someone on the platform team having to hold their hand through the setup.

Konstruct's cluster hierarchy looks like this:

1Control Plane Cluster (1 per platform)
2└── Management Clusters (1 per team)
3    ├── Workload Clusters (physical clusters for applications)
4    └── Virtual Clusters (lightweight vcluster-based environments)

Each tier is provisioned from a template. The question is whether to use the ones Konstruct ships out of the box, or to bring your own.

Upstream templates: The built-in option

Upstream templates are the templates that ship with Konstruct. They define the complete set of platform applications for each cluster type and cloud provider, deployed in the right order via Argo CD sync waves. Cert-manager, ingress, secrets management, Crossplane- everything a cluster needs to be useful is already accounted for.

The current upstream templates cover:

• Control Plane: Argo CD, cert-manager, Crossplane, and the full GitOps platform stack (AWS)
• Management Clusters: Per-team management with infrastructure provisioning capabilities (AWS, Civo)
• Workload Clusters: Application clusters with core platform services (AWS, Civo, GCP)
• Virtual Clusters: Lightweight vcluster-based environments sharing a host cluster (AWS)

One thing worth knowing: Civo and AWS workload templates aren't identical. Civo templates use Envoy Gateway instead of NGINX for ingress, and tend to run newer component versions. AWS templates include more infrastructure tooling at the workload level: external-dns, external-secrets, and expanded RBAC. The upstream templates are built to reflect how each provider actually works, not to paper over the differences.

Deployment order is managed through sync-wave annotations on each Argo CD Application. Lower wave numbers deploy first; apps within the same wave deploy concurrently; Argo CD waits for everything in a wave to become healthy before moving to the next. That orchestration is all handled for you.

All upstream templates are open source and maintained in the konstruct-templates repository if you want to see exactly what's in them.

Custom templates: Bringing your own

Custom templates let you replace or extend the upstream templates with your own Terraform modules and GitOps content. They're built for teams that have existing infrastructure patterns, specific networking requirements, compliance tooling, IAM policies, that can't or shouldn't be overridden by a generic default.

Konstruct supports two authoring formats for custom templates:

• Helm chart format (recommended): Your template is a standard Helm chart. Konstruct reads values.yaml to discover input fields, renders the create form dynamically, then Helm-renders the chart with user-supplied values plus Konstruct's built-in values (cluster name, GitOps repo URL, cloud provider, domain, and so on) before committing the result to your GitOps repository. This is the format to use for new templates.
• Token replacement format (legacy): The original v1 format. Flat YAML files with <TOKEN> placeholders defined in a konstruct.yaml file at the template root. Existing templates in this format continue to work, but new templates should use the Helm format.

Konstruct selects the engine automatically: If values.yaml is present, it uses the Helm format; otherwise it falls back to konstruct.yaml.

Custom input variables are a significant part of what makes custom templates useful. You annotate fields in values.yaml with # @input.* comments and Konstruct turns them into form fields in the cluster creation UI, string inputs, dropdowns, boolean toggles, secret fields. Users filling in the form get guided through the configuration your template needs, without having to know the underlying Terraform structure.

Custom templates are available for both workload clusters and team management clusters. The management cluster variant is particularly useful when you need to standardize IAM policies, integrate compliance tooling, or configure organization-specific networking at the team provisioning level.

To get started, the simplest path is to fork the upstream konstruct-templates repository and modify from there, rather than starting from scratch.

Comparing the two approaches

How to choose

Start with upstream. If you're setting up Konstruct for the first time, or if your cloud provider and infrastructure patterns are well-covered by the defaults, upstream templates get you to a working platform without any authoring overhead. They're actively maintained, tested across providers, and reflect real production configurations.

Move to custom when the defaults don't fit. The cases where custom templates make sense tend to be specific: you have an existing Terraform module for cluster infrastructure that encodes years of networking decisions; you need to enforce compliance tooling at provisioning time; you have IAM policies or VPC configurations that can't be expressed through the upstream defaults. Custom templates are designed for exactly those situations, not as a way to diverge from the platform, but as a way to bring your existing standards into it.

The two approaches can also coexist. A platform team might run upstream templates for most workload clusters and use a custom template for a specific team with unusual networking requirements. Konstruct doesn't force a single strategy; it gives you the structure to make either choice deliberately, and to document it in code.

Summary

Cluster configuration being tribal knowledge is a solvable problem. Konstruct's template system, whether you're using upstream defaults or bringing your own, is the foundation for solving it. The choice between built-in and custom isn't about which is better in the abstract; it's about where your organization actually is and what your infrastructure actually needs.

👉 Watch: Why does every cluster in your organization look slightly different?

And if you're ready to dig into the implementation details, the docs cover everything from creating your first management cluster to authoring a Helm-based custom template:

• Cluster management docs
• Upstream template reference
• Custom template guide

Questions or want to talk through what the right template strategy looks like for your platform? Schedule time with me here.