Version: v1.4.x

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.

Credential Masking

PaletteAI masks the default value of a variable whose name indicates a credential, so that passwords and connection strings are not displayed in plain text on the Variables page.

Masking affects display only. The value stored in the VariableSet custom resource is unchanged, and Workload Deployments still resolve the full value through the {{ .var.<variable-name> }} macro.

Location	Behavior
Default Value column	Displays a fixed mask in place of the value on the Variables page (Project and System tabs) and in the Variables table of the Profile Bundle builder.
Search	Excludes masked values from the searchable text, so a search cannot confirm a credential.
Variable drawer	Displays the value in a password field. For a single-line value, use the toggle in the field (Show password and Hide password). For a multi-line value, select Reveal value to display it and Hide value to mask it again.

PaletteAI masks a variable when its name contains any of the following fragments. Matching is case-insensitive, and each family accepts a hyphen or an underscore in place of the separator shown.

Fragment	Examples
`password`, `passwd`, `passphrase`, `pwd`	`zot-password`, `MYSQL_PWD`
`secret`	`client-secret`, `mySecret`
`token`	`auth-token`, `GH_TOKEN`
`credential`	`svc-credential`
`authorization`	`proxy-authorization`
`apikey`, `api-key`, `api_key`	`myApiKey`
`accesskey`, `access-key`, `access_key`	`AWS_ACCESS_KEY`
`privatekey`, `private-key`, `private_key`	`TLS_PRIVATE_KEY`
`authconfig`, `auth-config`, `auth_config`	`DOCKER_AUTH_CONFIG`
`connectionstring`, `connection-string`, `connection_string`	`AZURE_STORAGE_CONNECTION_STRING`

Names that end in url, uri, or dsn are also masked, because the value is a connection string that carries the credential inside it, for example postgres://admin:<password>@db:5432/app. The suffix must be a whole word, so DATABASE_URL, databaseUrl, mongodb_uri, and dsn are masked.

A name that references a credential instead of holding one is not masked. Names ending in name, ref, or endpoint keep their value visible, because the value is an identifier rather than the credential itself. For example, zot-auth-secret-name, credential-ref, and token-endpoint are displayed as-is.

The check is fail-safe. A variable whose name matches is masked even when the value is not sensitive, and a variable whose name matches nothing is displayed as-is. Name a variable after the credential it holds so that PaletteAI masks it.

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	✅	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	✅	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	❌	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	❌	A description of the variable's purpose. Maximum 1024 characters.
`validationMode`	string	❌	Controls whether a value is required at deployment time. Accepted values: `required`, `optional`. Defaults to `optional`.
`locked`	boolean	❌	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	✅	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:

Profile Bundle Variables - Declared directly in ProfileBundle.spec.variableSet.
Workload Deployment Variables - Defined directly in WorkloadDeployment.spec.variables.
Project-Scoped Variables - Defined in the mural-variables VariableSet custom resource in the Workload Deployment's namespace.
System-Wide Variables - Defined in the mural-variables VariableSet custom resource in the system namespace, pai-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:

Workload Deployment Variables - Includes values defined directly in WorkloadDeployment.spec.variables and values carried forward from inline ProfileBundle.spec.variableSet entries.
Project-Scoped Variables - Defined in the mural-variables VariableSet custom resource in the Workload Deployment's namespace.
System-Wide Variables - Defined in the mural-variables VariableSet custom resource in the system namespace, pai-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 namespace, pai-system, to provide default variables across Tenants and 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: pai-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'

Credential Masking​

VariableSet Resource​

VariableSet Structure​

Variable Resolution​

Profile Bundle Variables​

Workload Deployment Variables​

Namespace-Scoped VariableSet​

System-Wide VariableSet​