Parameters
Template parameters enable customization of virtual cluster templates. Platform administrators define a set of parameters that expose specific fields to users during virtual cluster creation. These parameters allow customization of values like replica counts, image tags, or ingress domains without granting access to the full configuration.
When a user creates a virtual cluster from a parameterized template, the platform presents a form that collects values for each parameter. These values are injected into the rendered configuration using Go templating syntax ({{ .Values.parameterName }}).
This provides some flexibility within defined boundaries. You can adjust some behaviors, such as increasing memory requests or enabling optional apps, while platform teams can still retain control over foundational settings like network configuration, cluster version, and permissions.
Each parameter supports type definitions, validation rules, default values, and allowed value lists. These controls ensure that inputs are valid and align with standards.
Parameters work well for supporting self-service provisioning at scale and also maintain governance, consistency, and operational safety across environments.
Parameter types and validation
When defining parameters in a vCluster template, you must specify the expected input type and optionally enforce validation rules.
Supported parameter types
Templates support basic parameter types for collecting user input during cluster creation:
| Type | Use case |
|---|---|
string | Names, labels, image tags, configuration values |
number | Replica counts, port numbers, resource limits |
boolean | Feature toggles, enable/disable flags |
password | API tokens, secrets, sensitive input values |
multiline | Configuration files, startup scripts, long descriptions |
Validation options
You can apply validation rules to ensure that users provide valid, safe, and expected input when filling out template parameters. These rules improve consistency and reduce configuration errors during virtual cluster creation.
-
Required fields: Mark a parameter as required to prevent users from submitting the form without entering a value. This is useful for mandatory inputs like cluster names or resource sizes.
-
Allowed values: Limit a parameter to a predefined list of options, such as regions, environments, or storage classes. This helps simplify user choices and ensures configuration compliance.
-
Regular expressions: Use regular expression patterns to enforce format requirements for string fields—for example, lowercase-only names or domain-style inputs.
-
Numeric ranges: Set minimum and maximum values for number-type parameters to ensure values like CPU, memory, or replica counts fall within safe limits.
Define parameters using the UI
The platform UI provides an intuitive interface for creating and managing template parameters.
Navigate to your template in the platform UI and click Add parameter in the template editor.
From the Section drop-down list, choose an existing section or create a new one (such as "Environment Settings" or "Resource Configuration"). Sections help organize related parameters and improve the user experience during deployment.
Enter a unique Identifier (variable) name. This becomes the variable key used in your template (for example,
cpu_limitbecomes{{ .Values.cpu_limit }}). Use descriptive names that clearly indicate the parameter's purpose.Select the appropriate Type for your parameter from the drop-down list. Consider what kind of input makes most sense for your use case.
Provide a clear Label that end users can see in the deployment form. Make it descriptive and user-friendly (for example, "CPU Limit" instead of "cpu_limit").
Add a comprehensive Description that explains what the parameter controls and provides guidance on appropriate values. You can include examples when helpful.
Toggle Required if users must provide a value for this parameter before deploying. Before marking a parameter as required, consider whether providing a default value would better support user workflows and reduce friction during cluster creation.
If you want to restrict user choices, use Allowed Options to create a drop-down list. Click + Add option for each allowed value. This is particularly useful for environment names, regions, or configuration presets.
Click Done to save the parameter and add it to your template.
Parameter configuration guidelines
To make your templates intuitive, scalable, and safe to use, follow these best practices when defining parameters.
- Group related parameters: Organize inputs into logical sections such as Resource settings, Network configuration, or Security options.
- Use descriptive names: Choose parameter identifiers that clearly communicate their purpose.
- Use clear descriptions: Include concise guidance, examples, or constraints in the parameter description field to help users enter correct values.
You can also apply advanced parameter options to modify behavior and enforce consistency:
- Default values: Use defaults to reduce manual input and guide users toward standard configurations. For example, you can set a default replica count or enable a common add-on by default.
- Custom validation: Add rules to control input format or range. You can limit values using regular expressions, set minimum or maximum numbers, or define a list of allowed options.
YAML parameter definitions
For templates managed through Git or automated workflows, you can define parameters directly in YAML format.
Basic parameter structure
parameters:
- variable: environment_type
label: Environment Type
description: Select the target environment for this virtual cluster
type: string
required: true
options:
- development
- staging
- production
section: Environment Settings
String parameter with validation
- variable: cluster_name
label: Cluster Name
description: Enter a name for your virtual cluster (3-20 characters, lowercase letters and hyphens only)
type: string
required: true
validation: "^[a-z][a-z0-9-]*[a-z0-9]$"
section: Basic Configuration
Number parameter with range
- variable: replica_count
label: Replica Count
description: Number of application replicas (1-10)
type: number
required: true
min: 1
max: 10
defaultValue: 3
section: Scaling Settings
Boolean parameter for feature toggle
- variable: enable_monitoring
label: Enable Monitoring
description: Install Prometheus and Grafana monitoring stack
type: boolean
defaultValue: true
section: Optional Features
Password parameter for sensitive data
- variable: admin_password
label: Admin Password
description: Password for the admin user (minimum 8 characters)
type: password
required: true
validation: "^.{8,}$"
section: Security Settings
Multiline parameter for configuration
- variable: custom_config
label: Custom Configuration
description: Additional YAML configuration to apply to the virtual cluster
type: multiline
section: Advanced Settings
Complex parameter validation
Use advanced validation patterns to restrict and guide user input when filling out template parameters.
Enum with descriptions
The following example defines a parameter with a fixed list of allowed options, each with a description to help users choose the correct value. This is useful for selecting cluster sizes, environments, or configuration tiers.
- variable: instance_size
label: Instance Size
description: Choose the resource allocation tier for your virtual cluster
type: string
required: true
options:
- value: small
description: 1 CPU, 2GB RAM - suitable for development
- value: medium
description: 2 CPU, 4GB RAM - suitable for testing
- value: large
description: 4 CPU, 8GB RAM - suitable for production workloads
section: Resource Configuration
Access parameter values in templates
After you define parameters, you can access their values in your template using Go template syntax. The platform makes all parameter values available under the .Values object.
Basic parameter access
controlPlane:
replicas: {{ .Values.replica_count }}
Conditional template logic
Use Go template conditionals to create dynamic configurations based on parameter values:
# Set control plane resource limits dynamically based on environment type
controlPlane:
resources:
limits:
cpu: {{- if eq .Values.environment_type "production" }}4000m
{{- else if eq .Values.environment_type "staging" }}2000m
{{- else }}1000m
{{- end }}
memory: {{- if eq .Values.environment_type "production" }}8Gi
{{- else if eq .Values.environment_type "staging" }}4Gi
{{- else }}2Gi
{{- end }}
# Enable persistent volume if requested in values.yaml
{{- if .Values.enable_persistence }}
storage:
persistentVolume:
enabled: true
size: "{{ .Values.storage_size }}"
{{- end }}
# Monitoring should be handled outside of vcluster.yaml. Use Helm subcharts or manifests.
String manipulation and defaults
Use Go template functions for string manipulation and providing fallback values:
metadata:
name: "{{ .Values.cluster_name | lower }}"
labels:
# Use default value if parameter is empty
cost-center: "{{ .Values.cost_center | default "engineering" }}"
# Combine multiple parameters
full-name: "{{ .Values.project_name }}-{{ .Values.environment_type }}"
# Transform string values
normalized-name: "{{ .Values.cluster_name | lower | replace "_" "-" }}"
Available template functions
vCluster templates use Go templates with Helm. This enables dynamic rendering of values using functions like default, lower, and replace. Most functions are mentioned in the Sprig library. The following table summarizes the types of functions that are commonly available.
| Category | Example functions |
|---|---|
| String | trim, lower, upper, title, contains, replace |
| Numbers | add, sub, div, mod, max, min, ceil, floor |
| Logic / Flow | default, ternary, eq, ne, and, or, not |
| Lists / Dicts | merge, hasKey, pluck, keys, values, len |
| Time | now, date, dateInZone |
| Type checks | kindIs, typeIs, isSet, empty |
Some functions are disabled in vCluster templates due to security restrictions.
| Function | Reason |
|---|---|
env | Disabled to prevent env access |
envExpand | Disabled to avoid string injection from env vars |
expandenv | Same as envExpand |
vCluster Platform extends Helm’s function set with custom helpers for working with structured config formats.
| Function | Description |
|---|---|
toYaml | Converts a map or value to YAML |
toToml | Converts a map to TOML format |
toJson | Converts a value to JSON |
fromYaml | Parses a YAML string into a map |
fromYamlArray | Parses a YAML list into an array of maps |
fromJson | Parses a JSON string into a map |
fromJsonArray | Parses a JSON array into an array of maps |
Complex parameter types
Some parameters represent structured values like arrays or objects. You can use these to enable multiple features, set grouped values, or control nested config blocks in your templates.
Array parameters
Use array parameters to allow users to select multiple values, such as feature toggles. You can loop over these in your template to conditionally enable behavior based on which values were selected.
# Parameter definition
- variable: enabled_features
label: Enabled Features
description: Select features to enable
type: array
options:
- ingress
- monitoring
- logging
- backup
section: Features
# Template usage
{{- range .Values.enabled_features }}
{{- if eq . "ingress" }}
networking:
ingress:
enabled: true
{{- end }}
{{- if eq . "monitoring" }}
monitoring:
enabled: true
{{- end }}
{{- end }}
Object parameters
Use object parameters to collect grouped fields, such as a team_config with name and email. You can access these values directly by key using standard dot notation.
# Access nested object values
metadata:
labels:
team: "{{ .Values.team_config.name }}"
contact: "{{ .Values.team_config.email }}"
Parameter validation and error handling
vCluster templates support input validation and error handling to ensure users provide safe, structured, and meaningful values during cluster creation.
Input validation strategies
You can apply format rules, numeric constraints, and other validation checks directly in your parameter definitions.
Format validation with regular expressions
Use a regular expression pattern to enforce formatting for string inputs like Kubernetes versions, domain names, or custom labels.
- variable: kubernetes_version
label: Kubernetes Version
description: Kubernetes version (e.g., 1.28.4, 1.27.8)
type: string
required: true
validation: "^1\.(2[4-9]|[3-9][0-9])\.[0-9]+$"
section: Configuration
Range validation for numbers
Set minimum and maximum values to control numeric inputs such as replica counts, node limits, or storage sizes.
- variable: worker_nodes
label: Worker Nodes
description: Number of worker nodes (1-20)
type: number
required: true
min: 1
max: 20
section: Scaling
Complex validation with multiple constraints
You can combine allowed values and validation patterns to enforce both selection and formatting rules.
- variable: storage_class
label: Storage Class
description: Kubernetes storage class for persistent volumes
type: string
required: true
options:
- fast-ssd
- standard
- archive
validation: "^(fast-ssd|standard|archive)$"
section: Storage
Error handling in templates
You can include conditional logic and error handling in your templates to catch missing values or apply fallback defaults.
# Fail if required parameter is missing
{{- if not .Values.environment_type }}
{{- fail "environment_type parameter is required" }}
{{- end }}
# Configure control plane
controlPlane:
# Default to 1 replica if none is set
replicas: {{ .Values.replica_count | default 1 }}
resources:
limits:
# Set CPU limit based on value or fallback to environment
cpu: {{- if .Values.cpu_limit }}
{{ .Values.cpu_limit }}
{{- else if eq .Values.environment_type "production" }}2000m
{{- else }}1000m
{{- end }}