Macros

This page covers how to reference outputs and user variables using PaletteAI's macro system in workload profiles. The different source types for macros include:

Definition outputs
Object outputs
System outputs
User variables

Macro Contexts

Macros can be used in the spoke or hub context:

Spoke Context - Within the same workload, object or definition outputs from with lower deployment priorities can be referenced by components with higher deployment priorities. This enables phased rollouts where later components can use data from earlier components.
Hub Context - Across different workloads, where one workload can reference the outputs of a previous workload deployment or user variables. This is useful for scenarios like referencing a global LoadBalancer IP that was deployed separately.

Definition and object outputs can be accessed in both contexts, while system outputs and user variables can only be accessed within the hub context.

Source Type	Hub Context	Spoke Context
Definition Outputs	✅	✅
Object Outputs	✅	✅
System Outputs	✅	❌
User Variables	✅	❌

Reference Definition and Object Outputs

Spoke Context

For workloads with deployment priorities, both definition outputs and object outputs are available to subsequent components in the same workload.

Use the spoke function to indicate that a macro should be resolved within the spoke context.

Definition outputs (including CUE-based)
'{{ spoke ".def.<component_name>.<definition_output_ref_name>" }}'

'{{ spoke ".def.<component_name>.<trait_name>.<definition_output_ref_name>" }}'

Object outputs
'{{ spoke ".obj.<object_output_ref_name>" }}'

Complete example with CUE-based trait
apiVersion: spectrocloud.com/v1beta1
kind: WorkloadProfile
metadata:
  name: my-phased-workload
spec:
  workload:
    # Define object outputs for the workload, sourced from an existing Service
    objectOutputRefs:
      - name: clusterDNS
        pathRef:
          apiVersion: v1
          kind: Service
          name: kube-dns
          namespace: kube-system
          path: .spec.clusterIP
    components:
      - name: web-server
        deploymentPriority: 1
        properties:
          image: nginx:latest
          replicas: 3
        # Explicitly define a definition output for the Deployment created
        # by the webservice Component.
        definitionOutputRefs:
          - name: cpu
            pathRef:
              path: .spec.containers[0].resources.requests.cpu
              kind: Deployment
              apiVersion: apps/v1
        traits:
          # Since the gateway Trait includes CUE-based definition outputs,
          # they can automatically be referenced below.
          - type: gateway
            properties:
              domain: api.example.com
              http:
                '/': 80
        type: webservice
      - name: backend-service
        deploymentPriority: 2
        properties:
          image: busybox:latest
          serviceIP: '{{ spoke ".def.web-server.gateway.ip" }}'
          servicePorts: '{{ spoke ".def.web-server.gateway.ports" }}'
          dnsServer: '{{ spoke ".obj.clusterDNS" }}'
        type: worker

Hub Context

Macros within the hub context enable workload profiles to reference outputs from other workload deployments.

Definition Outputs (including CUE-based)
{{ .def.<wld_namespace>.<wld_name>.<component_name>.<definition_output_ref_name> }}

{{ .def.<wld_namespace>.<wld_name>.<component_name>.<trait_name>.<definition_output_ref_name> }}

{{ .def.<wld_namespace>.<wld_name>.<component_name>.<definition_output_ref_name>.<resolution_strategy> }}

{{ .def.<wld_namespace>.<wld_name>.<component_name>.<trait_name>.<definition_output_ref_name>.<resolution_strategy> }}

Object outputs
{{ .obj.<wld_namespace>.<wld_name>.<object_output_ref_name> }}

{{ .obj.<wld_namespace>.<wld_name>.<object_output_ref_name>.<resolution_strategy> }}

Resolution Strategies

When a workload deployment spans multiple spoke clusters, each spoke produces its own output values. To control how these values are resolved within a macro, you can optionally append a resolution strategy. If omitted, the default strategy is first.

The following table lists the available resolution strategies.

Strategy	Description
`first`	(Default) Selects the first available value from the aggregated outputs across all spokes. This is the default behavior if no resolution strategy is selected.
`min`, `max`	Performs a comparison on the aggregated values and returns the minimum or maximum value, respectively. Supported for outputs of type string or integer.
`same`	Resolves only if all aggregated outputs are identical. If any value differs, resolution fails.
`spokeName=<cluster_name>`	Retrieves the value from a specific spoke cluster identified by name.

Example resolution with min and same strategies
min-replicas: '{{ .def.mynamespace.myworkloaddeployment.mywebservice.replicas.min }}'
dns-ip: '{{ .obj.mynamespace.myworkloaddeployment.clusterDNS.same }}'

Cross-workload example
apiVersion: spectrocloud.com/v1beta1
kind: WorkloadProfile
metadata:
  name: my-workload
spec:
  workload:
    components:
      - name: my-component
        properties:
          ipAddress: '{{ .def.lb-workload-deployment-namespace.lb-workload-deployment-name.my-load-balancer.ipAddress }}'
          dnsServer: '{{ .obj.infra-namespace.infra-workload.clusterDNS }}'
        type: custom-component

System Outputs References

System outputs provide a mechanism to inject system-level output values into workload profiles. System outputs must be resolved in macros within the hub context.

System outputs are referenced using the .sys prefix in macro expressions.

Basic system output reference
'{{ .sys.<system_output_name> }}'

Complete example
apiVersion: spectrocloud.com/v1beta1
kind: WorkloadProfile
metadata:
  name: my-workload-profile
spec:
  workload:
    components:
      - name: my-app
        properties:
          image: nginx:latest
          replicas: 2
          env:
            - name: WL_NAME_HASH
              value: '{{ .sys.wl-name-hash }}'
            - name: WL_NAMESPACE
              value: '{{ .sys.wl-namespace }}'
        type: webservice

User Variables References

User variables provide a flexible way to inject custom configuration values into workload profiles. User variables must be resolved in macros within the hub context.

User variables are referenced using the .var prefix in macro expressions.

Basic user variable reference
'{{ .var.<variable_name> }}'

Complete example
apiVersion: spectrocloud.com/v1beta1
kind: WorkloadProfile
metadata:
  name: my-workload-profile
spec:
  workload:
    components:
      - name: my-app
        properties:
          image: 'myapp:{{ .var.version }}'
          replicas: '{{ .var.maxReplicas }}'
          env:
            - name: ENVIRONMENT
              value: '{{ .var.environment }}'
        type: webservice

tip

If a variable value is numeric or boolean but should be templated as a string (for example, for YAML string fields), use the quote function to ensure proper string formatting.

# Variable: someStringNum with int32 value: 10
# Template usage:
myStringField: '{{ quote .var.someStringNum }}' # Results in: myStringField: "10"

Sprig Functions (Advanced)

Sprig Functions are supported for advanced processing of output values in both spoke and hub contexts.

Hub context
{{ <optional_sprig_functions> .def.<wld_namespace>.<wld_name>.<component_name>.<definition_output_ref_name> }}

{{ <optional_sprig_functions> .def.<wld_namespace>.<wld_name>.<component_name>.<trait_name>.<definition_output_ref_name> }}

{{ <optional_sprig_functions> .obj.<wld_namespace>.<wld_name>.<object_output_ref_name> }}

{{ <optional_sprig_functions> .sys.<system_output_name> }}

{{ <optional_sprig_functions> .var.<user_variable_name> }}

Example hub context
name: '{{ first .def.my-namespace.my-workload.my-component.hostname }}'
dns: '{{ upper .obj.my-namespace.my-workload.clusterDNS }}'

The spoke function expects a string literal, so the entire expression must be wrapped in quotes.

Example spoke context
name: '{{ spoke ".def.my-component.my-trait.hostname | upper | trim | replace `-` `_`" }}'
dns: '{{ spoke ".obj.clusterDNS | lower" }}'

Macro Contexts​

Reference Definition and Object Outputs​

Spoke Context​

Hub Context​

Resolution Strategies​

System Outputs References​

User Variables References​