Create and Manage Variables

Updated: February 23, 2026

Variables provide a flexible way to inject custom configuration values across Workload Profiles using the macro syntax {{ .var.<variable-name> }}. Variables are managed through the VariableSet custom resource, which is a namespace singleton named mural-variables. For a full description of each field, refer to VariableSet Structure.

Variables follow a four-tier resolution order: Profile Bundle Variables take the highest precedence, followed by Workload Deployment overrides, then Project-scoped Variables, then system-wide Variables. Locked Variables cannot be overridden by a higher-precedence source. For details on resolution, refer to Variable Resolution.

info

Variables are only valid within the hub context. They cannot be referenced in the spoke context.

Limitations

• VariableSet and the Variables within it are not intended for sensitive data. The value field (including variableType-specific sub-fields such as string, int32, and bool) is stored in plain text in Kubernetes. Do not store secrets, passwords, API keys, or other sensitive values in a VariableSet. Use Kubernetes Secrets or a dedicated secrets management solution for sensitive data.

• A Variable cannot be both required and locked.

• A locked Variable must have a default value. This constraint is enforced by the UI. It is not enforced at the API level, so applying a locked Variable without a default value directly via kubectl is permitted.

• In a Project namespace, you can only lock a Variable that already exists in the system VariableSet.

• You cannot create a Project Variable with a name that is locked in the system VariableSet.

• A Variable that is locked in the Project or System scope cannot be overridden in a Profile Bundle.

• The variableType field must match the type of the value field. For example, setting variableType: 'bool' with value: { string: 'hello' } is rejected.

Create Variables

Add Variables to a VariableSet to make them available for use in Workload Profiles through the macro syntax.

Prerequisites

UI Workflow

• A Project in Ready status.

• A user with Project Editor or Admin permissions.

YAML Workflow

• kubectl installed and available in your $PATH.

• The KUBECONFIG environment variable set to the path of the PaletteAI hub cluster's kubeconfig file.

  export KUBECONFIG=<kubeconfig-location>

• A Project namespace for the Project you are adding Variables to.

Enablement

UI Workflow

info

The UI only supports creating and editing Project Variables. System Variables are scoped to the mural-system namespace and can only be created and managed using the YAML workflow.

1. Log in to PaletteAI, and then open your Project.

2. In the left main menu, select Variables.

3. Ensure the Project tab is selected. The System tab is read-only and displays Variables defined by an administrator in the system namespace.

4. Select Add Variable.

5. In the Add new variable drawer, fill in the following fields.

   Field	Description
   Name	Enter a unique variable key. Must be lowercase alphanumeric, may contain hyphens, and be 253 characters or less.
   Description	(Optional) Provide a description explaining the variable's purpose.
   Type	Select the data type: string, bool, int32, int64, float32, or float64.
   Default Value	(Optional) Set a default value. This value is used when no override is provided.
   Required	(Optional) Toggle on if this variable must have a value at deployment time.
   Locked	(Optional) Toggle on to prevent deployments from overriding this variable. A variable cannot be both required and locked.

6. Select Confirm.

A success notification confirms the Variable was created. The Variable now appears in the Project variables table.

YAML Workflow

1. If a VariableSet does not yet exist in your Project namespace, create one. The VariableSet name must be mural-variables.

   cat << 'EOF' > variableset.yaml
   apiVersion: spectrocloud.com/v1beta1
   kind: VariableSet
   metadata:
     name: mural-variables
     namespace: <project-namespace>
   spec:
     variables:
       - name: environment
         variableType: 'string'
         value:
           string: 'production'
         description: 'Deployment environment'
       - name: max-replicas
         variableType: 'int32'
         value:
           int32: 5
         description: 'Maximum replica count'
   EOF

   Replace <project-namespace> with your Project namespace.

2. Apply the manifest.

   kubectl apply --filename variableset.yaml

3. To add a Variable to an existing VariableSet, use kubectl patch with a JSON patch.

   kubectl patch variableset mural-variables \
     --namespace <project-namespace> \
     --type json \
     --patch '[{"op": "add", "path": "/spec/variables/-", "value": {"name": "debug-enabled", "variableType": "bool", "value": {"bool": false}, "description": "Enable debug mode"}}]'

To create system-scoped Variables available across all Projects, apply a VariableSet in the mural-system namespace. This requires cluster-admin permissions.

kubectl apply --filename - <<'EOF'
apiVersion: spectrocloud.com/v1beta1
kind: VariableSet
metadata:
  name: mural-variables
  namespace: mural-system
spec:
  variables:
    - name: company-name
      variableType: 'string'
      value:
        string: 'Acme Corp'
      description: 'Company name used across all deployments'
      locked: true
EOF

Edit Variables

Update the value, type, or settings of an existing Variable.

UI Workflow

1. In the left main menu, select Variables.

2. Ensure the Project tab is selected.

3. In the row for the Variable you want to edit, select the action menu, and then select Edit.

4. In the Edit variable drawer, update the desired fields.

   info

   If the Variable is used by one or more Profile Bundles that have active deployments, a banner informs you that changing the value could impact those deployments.

5. Select Confirm.

YAML Workflow

Use kubectl patch with a JSON patch to update a specific Variable by its index in the variables array. The index is zero-based.

For example, to update the second Variable (index 1):

kubectl patch variableset mural-variables \
  --namespace <project-namespace> \
  --type json \
  --patch '[{"op": "replace", "path": "/spec/variables/1", "value": {"name": "max-replicas", "variableType": "int32", "value": {"int32": 10}, "description": "Maximum replica count (updated)"}}]'

Alternatively, update the full VariableSet manifest and reapply it.

kubectl apply --filename variableset.yaml

Delete Variables

Remove a Variable from a VariableSet.

warning

You cannot delete a Variable through the UI if it is referenced by one or more Profile Bundles. Update or remove those references before deleting the Variable.

UI Workflow

1. In the left main menu, select Variables.

2. Ensure the Project tab is selected.

3. In the row for the Variable you want to remove, select the action menu, and then select Delete.

   The Variable is removed and a success notification confirms the deletion.

YAML Workflow

Use kubectl patch with a JSON patch to remove a Variable by its index. The index is zero-based.

For example, to remove the first Variable (index 0):

kubectl patch variableset mural-variables \
  --namespace <project-namespace> \
  --type json \
  --patch '[{"op": "remove", "path": "/spec/variables/0"}]'

Alternatively, remove the Variable from your VariableSet manifest and reapply it.

kubectl apply --filename variableset.yaml

Bulk Edit Variables

The PaletteAI UI provides a bulk editor that allows you to edit all Project Variables at once through a YAML editor. This is useful when you need to add, modify, or remove multiple Variables in a single operation.

1. In the left main menu, select Variables.

2. Ensure the Project tab is selected.

3. Select Bulk Editor.

4. In the YAML editor drawer, modify the VariableSet manifest. You can add, edit, or remove Variables directly in the YAML.

5. Select Confirm to apply all changes.

   warning

   The bulk editor replaces the entire variables array. Any Variables that you remove from the YAML are deleted from the VariableSet.

Validate

Confirm that your Variables were created and are effective.

UI Workflow

1. In the left main menu, select Variables.

2. In the Project tab, verify the Variable appears in the table with the expected Variable Name, Value, and Description.

3. (Optional) Select the System tab to review system-scoped Variables. The System tab is read-only.

4. (Optional) Use the Required variables filter to display only Variables with validationMode set to required.

YAML Workflow

1. List the VariableSet in your namespace. The short name vs is available.

   kubectl get variablesets --namespace <project-namespace>

   Example Output

   NAME              VARIABLE-COUNT   AGE
   mural-variables   3                5m

2. View the full VariableSet spec and effective variables.

   kubectl get variableset mural-variables --namespace <project-namespace> --output yaml

3. Confirm that status.effectiveVariables contains the expected Variables with the correct source values (system or activeNamespace).

February 23, 2026 Summary of Changes

• Added new how-to guide for creating, editing, deleting, and bulk-editing Variables via the UI and YAML workflows.
• Documented the four-tier Variable resolution order, Limitations, and Validate steps.