Variables

Variables let you inject custom configuration values into Workload Profiles by using the PaletteAI macro syntax.

Variables are valid only in the hub context. You cannot reference them in the spoke context, including in Definition outputs or object outputs.

VariableSet Resource

Use the VariableSet custom resource to define variables that can be referenced across Workload Profiles. A VariableSet gives you a structured way to manage default values, validation rules, and override behavior.

VariableSet Structure

Each entry in the variables array supports the following fields.

Field	Type	Required	Description
name	string	Yes	The variable key. The API requires a non-empty name. For compatibility with macros and the UI, use a name that starts with a letter or underscore and then contains only letters, digits, underscores, or hyphens.
variableType	string	Yes	Determines the variable's type and is primarily useful when no value is set. It indicates the type to consumers and must correspond to the value. Accepted values: string, bool, int32, int64, float32, float64.
value	object	No	The default value for the variable. It must contain exactly one field that matches the variableType. For example, a variable with variableType: 'int32' uses value: { int32: 42 }.
description	string	No	A description of the variable's purpose. Maximum 1024 characters.
validationMode	string	No	Controls whether a value is required at deployment time. Accepted values: required, optional. Defaults to optional.
locked	boolean	No	When true, prevents higher-precedence sources from overriding this variable. Variables locked at the Project or System scope also cannot be overridden in a Profile Bundle. A variable cannot be both locked and required.
inputType	string	Yes	How PaletteAI edits string values: text (single-line input) or multiline (text area, for example PEM certificates). PaletteAI ignores this field for non-string variableType values. When you author YAML directly, set text unless you need multiline input.

Additional validation rules apply:

• PaletteAI does not allow a variable to use both validationMode: required and locked: true.

• In a Project namespace, a locked variable must already exist in the system VariableSet.

• Do not reuse the name of a system variable that is already locked when you create a Project variable.

apiVersion: spectrocloud.com/v1beta1
kind: VariableSet
metadata:
  name: mural-variables # Must be exactly "mural-variables"
  namespace: production # Determines scope (system or namespace level)
spec:
  variables:
    - name: textValue
      variableType: 'string'
      inputType: 'text'
      value:
        string: 'hello world'
      description: 'A string variable'
    - name: enabledFlag
      variableType: 'bool'
      inputType: 'text'
      value:
        bool: true
      description: 'A boolean variable'
    - name: smallNumber
      variableType: 'int32'
      inputType: 'text'
      value:
        int32: 42
      description: 'A 32-bit integer variable'
    - name: largeNumber
      variableType: 'int64'
      inputType: 'text'
      value:
        int64: 9223372036854775807
      description: 'A 64-bit integer variable'
    - name: percentage
      variableType: 'float32'
      inputType: 'text'
      value:
        float32: 85.5
      description: 'A 32-bit float variable'
    - name: preciseValue
      variableType: 'float64'
      inputType: 'text'
      value:
        float64: 3.141592653589793
      description: 'A 64-bit float variable'
      locked: true
    - name: apiKey
      variableType: 'string'
      inputType: 'text'
      validationMode: 'required'
      description: 'API key that must be provided (for example, in `WorkloadDeployment` or namespace `VariableSet`)'
    - name: tlsCertificate
      variableType: 'string'
      inputType: 'multiline'
      description: 'TLS certificate in PEM format'

Variable Resolution

PaletteAI uses variables from four configuration sources:

1. Profile Bundle Variables - Declared directly in ProfileBundle.spec.variableSet.

2. Workload Deployment Variables - Defined directly in WorkloadDeployment.spec.variables.

3. Project-Scoped Variables - Defined in the mural-variables VariableSet custom resource in the Workload Deployment's namespace.

4. System-Wide Variables - Defined in the mural-variables VariableSet custom resource in the SystemDefinition namespace, typically mural-system.

When you deploy from a Profile Bundle, PaletteAI uses inline ProfileBundle.spec.variableSet entries to declare bundle-specific defaults and metadata. In supported bundle workflows, PaletteAI carries those values into WorkloadDeployment.spec.variables before render.

At render time, PaletteAI resolves variables in the following order of precedence, from highest to lowest:

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

2. Project-Scoped Variables - Defined in the mural-variables VariableSet custom resource in the Workload Deployment's namespace.

3. System-Wide Variables - Defined in the mural-variables VariableSet custom resource in the SystemDefinition namespace, typically mural-system.

Higher-precedence sources override lower-precedence sources that use the same variable name. If a variable is marked locked in a VariableSet, higher-precedence sources cannot override it. Variables locked at the Project or System scope also cannot be overridden in a Profile Bundle.

Profile Bundle Variables

You can define variables directly in the ProfileBundle specification by using spec.variableSet. These variables declare bundle-specific defaults and metadata for the Workload Profiles in that bundle. In supported bundle workflows, PaletteAI carries those values into WorkloadDeployment.spec.variables before render. However, PaletteAI does not allow this tier to override variables that are locked at the Project or System scope.

Workload Deployment Variables

You can define variables directly in the WorkloadDeployment specification by using the variables field. At render time, these values override VariableSet values unless the matching VariableSet variable is locked. This option is useful for deployment-specific configuration that changes between environments.

Each key in spec.variables must already be declared in the effective VariableSet for the namespace or in an inline ProfileBundle.spec.variableSet. A Workload Deployment cannot introduce arbitrary new variable names.

apiVersion: spectrocloud.com/v1beta1
kind: WorkloadDeployment
metadata:
  name: my-workload-deployment
  namespace: production
spec:
  workload:
    name: my-workload
    namespace: my-workload-namespace
  workloadProfileRef:
    name: my-workload-profile
    namespace: profiles
  environmentRef:
    name: my-environment
    namespace: environments
  variables:
    environment: 'production'
    debug: 'false'
    apiUrl: 'https://api.production.example.com'
    maxReplicas: '10'

Namespace-Scoped VariableSet

Create a VariableSet resource in the same namespace as your Workload Deployment to make the variables available to all Workload Deployments in that namespace.

apiVersion: spectrocloud.com/v1beta1
kind: VariableSet
metadata:
  name: mural-variables
  namespace: production
spec:
  variables:
    - name: environment
      variableType: 'string'
      inputType: 'text'
      value:
        string: 'production'
      description: 'Environment name'
    - name: region
      variableType: 'string'
      inputType: 'text'
      value:
        string: 'us-west-2'
      description: 'AWS region'
    - name: team
      variableType: 'string'
      inputType: 'text'
      value:
        string: 'platform'
      description: 'Team ownership'
      locked: true
    - name: alertingEnabled
      variableType: 'bool'
      inputType: 'text'
      value:
        bool: true
      description: 'Enable alerting'
    - name: maxConnections
      variableType: 'int32'
      inputType: 'text'
      value:
        int32: 100
      description: 'Maximum connections'
    - name: timeout
      variableType: 'float32'
      inputType: 'text'
      value:
        float32: 30.5
      description: 'Timeout in seconds'

System-Wide VariableSet

Create a VariableSet resource in the system definition namespace, typically mural-system, to provide default variables across Projects.

info

The PaletteAI UI does not support creating or editing system-scoped variables. You must manage them using the YAML workflow.

apiVersion: spectrocloud.com/v1beta1
kind: VariableSet
metadata:
  name: mural-variables
  namespace: mural-system
spec:
  variables:
    - name: company
      variableType: 'string'
      inputType: 'text'
      value:
        string: 'Spectro Cloud'
      description: 'Company name'
      locked: true
    - name: region
      variableType: 'string'
      inputType: 'text'
      value:
        string: 'us-east-1'
      description: 'Default region'
    - name: clusterType
      variableType: 'string'
      inputType: 'text'
      value:
        string: 'managed'
      description: 'Cluster management type'
      locked: true
    - name: defaultLogLevel
      variableType: 'string'
      inputType: 'text'
      value:
        string: 'warn'
      description: 'System default log level'
    - name: monitoringEnabled
      variableType: 'bool'
      inputType: 'text'
      value:
        bool: true
      description: 'Enable monitoring by default'
    - name: maxRetries
      variableType: 'int32'
      inputType: 'text'
      value:
        int32: 3
      description: 'Default retry count'
    - name: requestTimeout
      variableType: 'float64'
      inputType: 'text'
      value:
        float64: 60.0
      description: 'Request timeout in seconds'