Skip to main content
Version: 2.10 (Next)

Custom Cluster Templates

Summary​

Starting in Kubefirst Pro 2.9, you can bring your own workload 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.

Prerequisites​

See Custom Cluster Templates Prerequisites.

Using Custom Templates​

Create a Custom Template​

A workload cluster template is a git directory with the GitOps content that will be used to create a workload cluster. The template allows <TOKENS> to be used as variables for input during cluster provision. Kubefirst comes with many available tokens automatically, but allows you to add your own as well.

Define Input Variables​

  1. In your template repository root directory, create a kubefirst.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 in your Terraform files or GitOps yaml content where values should be replaced.
  4. Commit and push the changes to your repository.

Create a Cluster with your Custom Template​

  1. Select Create Cluster.
  2. Choose Custom Template from the template dropdown.
  3. Provide the URL for your custom template and provide a PAT if private.
  4. Complete the prompted variables:
    • Each input defined in kubefirst.yaml appears as a form field
    • The prompt text guides you on what to enter
    • Tips provide example values
  5. Complete standard cluster options (name, region, nodes).
  6. Select Create Cluster.

Connect to a custom cluster template

Workload Cluster Template Requirements​

Your custom workload cluster template must follow these conventions:

Directory Structure​

The kubefirst.yaml file is required in the template folder root.

your-template-repo/any-template-folder/
├── kubefirst.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/

Using Tokens in your Template​

Tokens defined in kubefirst.yaml will be replaced in your Terraform or GitOps files when your cluster is created:

# variables.tf example
variable "vpc_cidr" {
  description = "VPC CIDR block"
  default     = "<WORKLOAD_CIDR>"
}

variable "business_unit" {
  description = "Business unit for tagging"
  default     = "<BUSINESS_UNIT>"
}
# argo cd application example
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "10"
  name: kubefirst
  namespace: argocd
spec:
  destination:
    name: in-cluster
    namespace: kubefirst
  project: default
  source:
    chart: kubefirst-pro
    repoURL: https://charts.konstruct.io
    targetRevision: "<MY_CUSTOM_VERSION_TOKEN>"
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true