Built-in Variables

There could be scenarios where a cluster name or specific values (based on defined cluster labels) need to be injected to a manifest dynamically as it is being deployed to the cluster. Controller's built-in variables can be leveraged for this purpose and the syntax below can be used either as part of cluster overrides or the manifest itself.

Cluster name

{{{ .global.Rafay.ClusterName }}}

For example, deploying the AWS Load Balancer Helm chart requires configuration of "clusterName". You can utilize the below cluster override to achieve that.

clusterName: {{{ .global.Rafay.ClusterName }}

Cluster labels

{{{ .global.Rafay.ClusterLabels.<label_key> }}}

If there is a need as an example to dynamically configure "region" based on a pre-defined cluster label (e.g. "awsRegion"), you can utilize the below cluster override to achieve that.

region: {{{ .global.Rafay.ClusterLabels.awsRegion }}

Workload Names

{{{ .global.Rafay.WorkloadName }}} provides the name of the workload being deployed. It can be used in configurations that require workload-specific references.

For example, if a configuration file needs to dynamically include the workload name, you can use the following override:

workloadName: {{{ .global.Rafay.WorkloadName }}

Workload Revision

{{{ .global.Rafay.WorkloadRevision }}} represents the revision number of the workload. This is useful for tracking deployment changes or versioning in configurations.

For instance, if a deployment process requires referencing the workload revision dynamically, you can use:

workloadRevision: {{{ .global.Rafay.WorkloadRevision }}

Handling Labels with Special Characters

Some labels contain characters like . (dot) or / (slash), which cannot be used directly in {{{ .global.Rafay.ClusterLabels.<labelname> }}}.

Incorrect Usage (Causes an Error)

{{{ .global.Rafay.ClusterLabels.rafay.dev/k8sVersion }}}

Correct Usage (Using index function)

{{{ index . “global” “Rafay” “ClusterLabels” “rafay.dev/k8sVersion” }}}

Using the index function allows retrieving labels with special characters safely.

Illustrative example

We will use the AWS Load Balancer Controller Helm chart for this example. The add-on called "aws-lb-controller" is configured with the helm chart provided by AWS. The helm chart requires that a "clusterName" be set before being deployed. By default, the value is left blank inside the chart. We will utilize a cluster override to set the value when the helm chart is deployed.

Step 1: Create Add-on

As an Admin in the console,

• Navigate to the Project
• Click on Add-Ons under Infrastructure. Select Create New Add-On from Catalog
• Search for "aws-load-balancer-controller"
• Click Create Add-On
• Provide a name for the add-on (e.g. aws=lb-controller), select the namespace
• Click Create
• Provide a version name (e.g. v1), clicck Save changes

Step 2: Create Cluster Override

• Navigate to the Project
• Click on Cluster Overrides under Infrastructure. Cluster Override page appears
• Click New Override and provide a name (e.g. aws-lb)
• Select the required File Type (Helm) and click Create
• For the Resource Selector, select the add-on for which the cluster override will be applied (e.g. aws-lb-controller)
• Select Specific Clusters as Type and select the required cluster(s) for which the cluster override will be applied
• Add the Override Value directly in the config screen as shown below

Multiple Override value(s)

To pass multiple built-in variables in cluster overrides, define each variable separately and concatenate them for dynamic configuration. For example, to set the app.name field with values from two ClusterLabels (cloud and demo), use the following syntax:

app:
  name: "{{{ .global.Rafay.ClusterLabels.cloud }}}-{{{ .global.Rafay.ClusterLabels.demo }}}"

(or)

app:
  name: "{{{ .global.Rafay.ClusterLabels.cloud }}},{{{ .global.Rafay.ClusterLabels.demo }}}"

Step 3: Deploy the Add-on

Deploy the blueprint to the cluster containing the add-on to utilize the newly created cluster override.

Step 4: Verify the cluster override has been applied to the deployment

kubectl describe pod -n kube-system aws-lb-controller-aws-load-balancer-controller-f5f6d6b47-9kjkl

Troubleshooting

Providing the following configuration results in an error:

podAnnotations:
  a1: "{{{ .global.Rafay.ClusterLabels.cloud }}},{{{ .global.Rafay.ClusterLabels.rafay.dev/clusterType }}}"

Error Message

rpc error: code = Unknown desc = prepare values: unable to replace values template: valueFileOverride:2: bad character U+002F '/'

This error occurs because Rafay labels, such as rafay.dev/clusterType, rafay.dev/projectID, rafay.dev/kubernetesProvider, and similar labels, include special characters like /, which are not recognized and result in parsing errors. Similar issues may also arise with other special characters in annotation values. To avoid this, refrain from using Rafay labels with unsupported characters like / in the override configuration.