Cluster Templates

Summary

You can bring your own cluster templates and specify custom Terraform modules for cluster infrastructure creation. This feature enables you to define custom input variables that dynamically prompt users during cluster creation.

Custom templates are available for:

• Workload clusters - Development and production application clusters
• Team management clusters - Organization management and control plane clusters (Available in Konstruct 0.2+)

Prerequisites

Git Repository

You need a git repository in your Organization's GitHub org for your custom cluster templates and terraform modules. For a great example starting point, please fork our upstream.

https://github.com/konstructio/konstruct-templates

Terraform Knowledge

• Familiarity with Terraform module structure
• Understanding of provider requirements
• Knowledge of your cloud provider's Terraform resources

Repository Access Setup

Public Repositories

Public repositories work without additional configuration.

Private Repositories

For private repositories, you'll need to provide access credentials when creating the custom template:

1. GitHub: Create a personal access token with repository read permissions.

You'll provide these credentials in the Konstruct UI when configuring your custom template.

Validation Checklist

Before proceeding:

• Git repository created
• Repository access configured

Using Custom Templates

Create a Custom Template

A workload cluster template is a directory in a git repository that has GitOps content used when creating a workload cluster. The template allows you to use <TOKENS> to be used as variables for replacement during cluster provisioning. Konstruct comes with many available tokens automatically, but allows you to add your own tokens as well.

Define Input Variables

1. In your template root directory, create a konstruct.yaml file.
2. Define the cluster type and input variables:

   clusterType: "physical" # physical|virtual|gpu
   inputs:
     - name: "cidr"
       token: "<WORKLOAD_CIDR>"
       prompt: "Enter your workload cluster VPC CIDR block"
       tip: "10.0.0.0/16"
     - name: "business-unit"
       token: "<BUSINESS_UNIT>"
       prompt: "Enter your business unit name"
       tip: "e.g. 'engineering', 'sales', 'marketing'"

3. Use the tokens directly in your GitOps yaml content wherever values should be replaced per instance.
4. Commit and push the new konstruct.yaml file to your git repository.

Create a Cluster with your Custom Template

Connect to your cluster template

1. Select Create Cluster.
2. Choose Custom Template from the template dropdown.
3. Provide the URL for your custom template's git repository
4. Specify the path in that git repository where the workload cluster template folder resides
5. Enter the branch or tag name to define the version of your template
6. Provide a PAT if your git repository is private
7. Click Connect

Complete your cluster creation details

1. Complete standard cluster options (name, region, nodes).
2. Complete the custom prompted variables:
   • Each input defined in konstruct.yaml will appear as a form field
   • The prompt text guides the user on what the field is
   • Tips provide example values
3. Select Create Cluster.

The resulting yaml that gets committed to your gitops repository will have your tokens replaced with the values that were provided by the end user. These values will also be available on your cluster details view.

Workload Cluster Template Requirements

Your custom workload cluster template must follow these conventions:

Directory Structure

The konstruct.yaml file is required in the cluster template's top folder.

your-template-repo/any-template-folder/
├── konstruct.yaml
├── argocd-application-1.yaml
├── argocd-application-2.yaml
└── argocd-application-1/
    ├── application.yaml
    └── external-secret.yaml
└── argocd-application-2/
    ├── application.yaml
    └── external-secret.yaml
└── terraform/
    ├── main.tf
    ├── eks/
    └── vpc/

Here is an example Argo CD application with a custom token

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "10"
  name: konstruct
  namespace: argocd
spec:
  destination:
    name: in-cluster
    namespace: konstruct
  project: default
  source:
    chart: konstruct
    repoURL: https://charts.konstruct.io
    targetRevision: "<MY_CUSTOM_VERSION_TOKEN>"
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

Leveraging Tokens in your Cluster Terraform Module

Your terraform code in your cluster module will use terraform variables just like you always would.

# variables.tf example
variable "vpc_cidr" {
  description = "VPC CIDR block"
}

variable "business_unit" {
  description = "Business unit for tagging"
}

In order to provide input values to these terraform variables, specify your tokens in your workspace as shown here

apiVersion: tf.upbound.io/v1beta1
kind: Workspace
metadata:
  name: <WORKLOAD_CLUSTER_NAME>-infrastructure-bootstrap
spec:
  providerConfigRef:
    name: <WORKLOAD_CLUSTER_NAME>
  forProvider:
    source: Remote
    module: git::https://github.com/konstruct/gitops-template.git//aws-github/terraform/aws/modules/bootstrap?ref=main
    vars:
    - key: cluster_name
      value: "<WORKLOAD_CLUSTER_NAME>"
    - key: vpc_cidr
      value: "<WORKLOAD_CIDR>"

This example shows the use of native konstruct token <WORKLOAD_CLUSTER_NAME> as well as a custom token <WORKLOAD_CIDR>. These values will be replaced by the system and user inputs.

Advanced options

As shown in the example above, it's most common to simply use the module that is specified in your Workspace. If you want to override the default module that your workload cluster template uses however, simply expand the Advanced options, and specify the location of the repository and the path to the module.

Team Management Cluster Templates

Available in Konstruct 0.2+

Platform admins can create custom templates for team management clusters to standardize organization-specific infrastructure patterns.

When to Use Team Management Templates

Use custom team management templates when you need to:

• Customize IAM policies and roles for your organization
• Integrate with existing security and compliance tools
• Add organization-specific monitoring or logging
• Configure custom networking or VPC settings

Creating Team Management Templates

Team management cluster templates follow the same structure as workload cluster templates:

1. Create a konstruct.yaml file in your template directory
2. Define organization-specific input variables
3. Include terraform modules for management cluster infrastructure
4. Add any required ArgoCD applications for management tools

Example konstruct.yaml for team management:

clusterType: "management"
inputs:
  - name: "management-vpc-cidr"
    token: "<MGMT_VPC_CIDR>"
    prompt: "Enter management cluster VPC CIDR block"
    tip: "10.100.0.0/16"
  - name: "compliance-profile"
    token: "<COMPLIANCE_PROFILE>"
    prompt: "Select compliance profile"
    tip: "SOC2, HIPAA, PCI"

Using Custom Team Management Templates

1. Navigate to Organizations > Teams
2. Click Create Team
3. Select Custom Template for the management cluster
4. Provide your custom template repository details
5. Complete the custom input variables
6. Click Create Team

The custom template will be used when provisioning the team's management cluster infrastructure.