Create and Manage Variables

Variables let you inject custom configuration values into Workload Profiles with the macro syntax {{ .var.<variable-name> }}. PaletteAI stores variables in a VariableSet custom resource named mural-variables. Each namespace can contain only one VariableSet with that name. For field-level details, refer to VariableSet Structure.

Variables can be locked or required:

• Locked variables cannot be overridden by a higher-precedence source. Variables locked at the Project or System scope also cannot be overridden in a Profile Bundle.

• Required variables must have a value at deployment time. A variable cannot be both locked and required.

PaletteAI uses variables from four configuration sources:

• Profile Bundle Variables: Declared directly in ProfileBundle.spec.variableSet. They define bundle-specific defaults and metadata, and they cannot override variables locked at the Project or System scope.

• Workload Deployment Variables: Defined in WorkloadDeployment.spec.variables. In supported bundle workflows, this field also receives values carried forward from inline ProfileBundle.spec.variableSet entries. Each key must already be declared in the effective VariableSet for the namespace or in an inline Profile Bundle variable set.

• Project-Scoped Variables: Defined in the mural-variables VariableSet in a Project namespace. They apply to all Workload Deployments in that namespace and override system-wide variables.

• System-Wide Variables: Defined in the mural-variables VariableSet in the mural-system namespace. They provide organization-wide defaults available across all Projects.

At render time, PaletteAI resolves variables in the following order of precedence:

• Workload Deployment Variables: Includes values defined directly in WorkloadDeployment.spec.variables and values carried forward from inline ProfileBundle.spec.variableSet entries.

• Project-Scoped Variables

• System-Wide Variables

For details, refer to Variable Resolution.

info

Variables are available only in the hub context. You cannot reference them in the spoke context.

Limitations

• VariableSet and the variables it contains 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.

  Instead, use Kubernetes Secrets or a dedicated secrets management solution. Reference the secret from your workload container with standard Kubernetes mechanisms such as environment variable injection (secretKeyRef) or volume mounts, so the sensitive value never passes through a VariableSet.

• In the UI, you can create and manage only Project variables. System variables are scoped to the mural-system namespace and require the YAML workflow.

• The value field is optional. If you set it, PaletteAI uses it as the default value. To require a value at deployment time, set validationMode: required or toggle Required in the UI.

• PaletteAI does not allow a variable to be both required and locked.

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

• You cannot create a Project variable that uses a name already locked in the system VariableSet.

• PaletteAI does not allow a variable locked in the Project or System scope to be overridden in a Profile Bundle.

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

• When authoring YAML directly, set inputType for every variable. Use text for standard single-line values or multiline for multi-line string values such as PEM certificates.

Create Variables

Add variables to a VariableSet to make them available in Workload Profiles through the macro syntax.

Prerequisites

UI Workflow

• You have a Project in Ready status.

• You have Project Editor or Admin permissions.

YAML Workflow

• kubectl is installed and available in your $PATH.

• You set the KUBECONFIG environment variable to the path of the PaletteAI hub cluster kubeconfig file.

  Set KUBECONFIG

  export KUBECONFIG=<kubeconfig-location>

• You have a Project namespace where you want to add variables.

Enablement

UI Workflow

1. Log in to PaletteAI, 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, complete the following fields.

   Field	Description	Default
   Name	Enter a unique variable key. For compatibility with macros and the UI, start with a letter or underscore, then use only letters, digits, underscores, or hyphens.	None
   Description	(Optional) Provide a description explaining the variable's purpose.	None
   Type	Select the data type: string, bool, int32, int64, float32, or float64.	string
   Input Type	(Optional) If Type is string, select Single line or Multi-line (for example, for PEM certificates).	Single line
   Default Value	(Optional) Set a default value. This value is used when no override is provided.	None
   Required	(Optional) Toggle on if this variable must have a value at deployment time.	Off
   Locked	(Optional) Toggle on to prevent deployments from overriding this variable. A variable cannot be both required and locked.	Off

6. Select Confirm.

   A success notification confirms that PaletteAI created the variable. The variable now appears in the Project variables table.

YAML Workflow

1. If no VariableSet exists in your Project namespace, create one. The VariableSet name must be mural-variables.

   Create VariableSet

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

   Replace <project-namespace> with your Project namespace.

2. Apply the manifest.

   Apply VariableSet

   kubectl apply --filename variableset.yaml

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

   Patch VariableSet

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

4. (Optional) To create system-scoped variables available across all Projects, apply a VariableSet in the mural-system namespace. This action requires cluster-admin permissions.

   Apply System VariableSet

   kubectl apply --filename - <<'EOF'
   apiVersion: spectrocloud.com/v1beta1
   kind: VariableSet
   metadata:
     name: mural-variables
     namespace: mural-system
   spec:
     variables:
       - name: company-name
         variableType: 'string'
         inputType: 'text'
         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 one or more Profile Bundles with active deployments use the variable, a banner explains that changing the value can affect those deployments.

5. Select Confirm.

YAML Workflow

1. To update a single variable, use kubectl patch with a JSON patch. The index in the variables array is zero-based.

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

   Patch VariableSet

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

2. (Optional) If you maintain the full manifest, update variableset.yaml and reapply it.

   Apply VariableSet

   kubectl apply --filename variableset.yaml

Delete Variables

Remove a variable from a VariableSet.

warning

You cannot delete a variable through the UI if one or more Profile Bundles reference it. Update or remove those references before you delete 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.

   PaletteAI removes the variable and displays a success notification.

YAML Workflow

1. To remove a single variable, use kubectl patch with a JSON patch. The index in the variables array is zero-based.

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

   Patch VariableSet

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

2. (Optional) If you maintain the full manifest, remove the variable from variableset.yaml and reapply it.

   Apply VariableSet

   kubectl apply --filename variableset.yaml

Bulk Edit Variables

The PaletteAI UI includes a bulk editor for editing all Project variables in YAML at once. Use it when you need to add, modify, or remove multiple variables in one 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. Review the YAML carefully before you apply the change.

   warning

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

6. Select Confirm to apply all changes.

Validate

Confirm that your variables appear and resolve as expected.

UI Workflow

1. In the left main menu, select Variables.

2. In the Project tab, confirm that the variable appears in the table with the expected Variable Name, Default 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.

   List VariableSets

   kubectl get variablesets --namespace <project-namespace>

   Example Output

   NAME              VARIABLE-COUNT   AGE
   mural-variables   3                5m

2. View the full VariableSet specification and effective variables.

   View VariableSet

   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).

Next Steps

• Reference variables in Workload Profiles using the {{ .var.<variable-name> }} macro syntax. Refer to Macros.

• Create a Workload Profile that uses variables, then deploy it. Refer to Create Workload Profiles and Create App Deployments.

• Override Project or System variables at the Profile Bundle level. Refer to Create Profile Bundles.