Version: v0.2.x

Outputs

Components and traits are rendered into Kubernetes resources when a Workload is deployed. There are three types of outputs that workload profile macros can reference:

Output Type	Source	Use Case	Macro Context
Definition outputs	Metadata from Kubernetes resources created by components or traits in the workload	You need values from resources created by the workload itself	Hub and spoke
Object outputs	Metadata from arbitrary Kubernetes resources that exist outside the workload	You need values from existing cluster resources outside the workload	Hub and spoke
System outputs	Predefined workload values that PaletteAI exposes	You need PaletteAI-defined workload metadata rather than Kubernetes resource metadata	Hub only. For syntax and context rules, refer to Macros.

Outputs support the following data types:

string
integer
boolean
jsonRaw (for arbitrarily complex objects)

Use system outputs when you need predefined workload metadata from PaletteAI, rather than fields read from Kubernetes resources. For macro syntax and context rules for all output types, refer to Macros.

Definition Outputs

Definition outputs reference Kubernetes resources that were created by the workload itself. You define them as part of a component or trait specification, or directly inside CUE templates.

Specify Outputs in Components and Traits

A definition output is defined as part of a workload profile's component or trait specification. Each output references a field from a Kubernetes resource created by that component or trait.

apiVersion: spectrocloud.com/v1beta1
kind: WorkloadProfile
metadata:
  name: definition-output-example
spec:
  workload:
    components:
      - name: my-component
        properties: ...
        definitionOutputRefs:
          - name: hostname
            pathRef:
              apiVersion: v1
              kind: Service
              path: .status.loadBalancer.ingress[0].hostname
              labels:
                type: 'primary'
            skipHash: false
        type: my-component-type

The following table lists the parameters for spec.workload.components[].definitionOutputRefs, ordered alphabetically.

Parameter	Description	Required
`name`	A unique identifier for the output within the component or trait.	✅
`pathRef.apiVersion`	The `apiVersion` of the referenced object created by the component or trait in the spoke cluster.	✅
`pathRef.kind`	The `kind` of the referenced object created by the component or trait in the spoke cluster.	✅
`pathRef.labels`	Optional filters for objects when a component creates multiple objects of the same Group Version Kind (GVK).	❌
`pathRef.path`	A JSON path expression pointing to a field under `metadata`, `spec`, or `status` of the referenced object. The path can return any value type (integer, bool, string, or complex structures). If the path points to a structure, map, or slice, the JSON-marshaled value is returned.	✅
`skipHash`	Optional flag (defaults to `false`). When `true`, this output is not included in the workload hash.	❌

CUE-Based Definition Outputs

Definition outputs can also be configured directly inside component and trait CUE templates. CUE-based definition outputs rely on a two-part annotation system to declare and expose outputs:

Definition Annotations - The definition object must declare what outputs it can generate using generates.output.spectrocloud.com/<name> annotations.
Template Annotations - The CUE template must include corresponding output.spectrocloud.com/<name> annotations on the generated Kubernetes resources.

Definition-Level Annotations

The definition object (ComponentDefinition or TraitDefinition) must include generates.output.spectrocloud.com/<name> annotations that describe what outputs the definition can produce.

apiVersion: spectrocloud.com/v1beta1
kind: TraitDefinition
metadata:
  name: gateway
  annotations:
    definition.spectrocloud.com/description: 'Enable public web traffic for the component'
    generates.output.spectrocloud.com/ip: '{"apiVersion":"v1","kind":"Service","paths":".spec.clusterIP"}'
    generates.output.spectrocloud.com/ports: '{"apiVersion":"v1","kind":"Service","paths":".spec.ports"}'
spec:
  schematic:
    cue:
      template: |
        # CUE template content here...

The annotation format is as follows.

Key	Value
`generates.output.spectrocloud.com/<output_name>`	A JSON object with the following components: - `apiVersion` - The `apiVersion` of the resource that contains the output. - `kind` - The `kind` of the resource that contains the output. - `paths` - The JSON paths to the fields containing the output value. There can be multiple paths if the template contains conditional logic.

Template-Level Annotations

Within the CUE template, generated Kubernetes resources must include output.spectrocloud.com/<name> annotations that specify the exact JSON path to extract the output value.

outputs: service: {
  apiVersion: "v1"
  kind: "Service"
  metadata: {
    name: context.name
    annotations: {
      "output.spectrocloud.com/ports": ".spec.ports"
      "output.spectrocloud.com/ip": ".spec.clusterIP" // (populated after Service is created)
    }
  }
  spec: {
    ports: [
      // port configuration...
    ]
  }
}

Complete CUE Definition Example

gateway: {
  type: "trait"
  annotations: {
    "generates.output.spectrocloud.com/ip": "{\"apiVersion\":\"v1\",\"kind\":\"Service\",\"paths\":\".spec.clusterIP\"}"
    "generates.output.spectrocloud.com/ports": "{\"apiVersion\":\"v1\",\"kind\":\"Service\",\"paths\":\".spec.ports\"}"
  }
  description: "Enable public web traffic for the component"
}

template: {
  outputs: service: {
    apiVersion: "v1"
    kind: "Service"
    metadata: {
      name: context.name
      annotations: {
        "output.spectrocloud.com/ports": ".spec.ports"
        "output.spectrocloud.com/ip": ".spec.clusterIP" // (populated after Service is created)
      }
    }
    spec: {
      ports: [
        // Service port configuration based on parameters
      ]
    }
  }
}

Validation Rules

The system enforces validation between definition-level and template-level annotations. This ensures consistency between what outputs a definition declares it can produce and what outputs are actually exposed in the generated resources.

Every output.spectrocloud.com/<name> annotation in the CUE template must have a corresponding generates.output.spectrocloud.com/<name> annotation on the definition. This is enforced as an error.
Every generates.output.spectrocloud.com/<name> annotation on the definition should have a corresponding output.spectrocloud.com/<name> annotation in the CUE template. This produces a warning (not an error) because CUE templates may have conditional outputs that cannot be statically detected.

Object Outputs

Object outputs are used to expose metadata from arbitrary Kubernetes resources that exist outside the workload. These resources are not created by the workload itself but already exist on the cluster.

Define Object Outputs

Object outputs are defined at the workload level (not within individual components) and require explicit name and namespace references.

apiVersion: spectrocloud.com/v1beta1
kind: WorkloadProfile
metadata:
  name: object-output-example
spec:
  workload:
    objectOutputRefs:
      - name: clusterIP
        pathRef:
          apiVersion: v1
          kind: Service
          name: kube-dns
          namespace: kube-system
          path: .spec.clusterIP
        skipHash: false
        deploymentPriority: 1
    components:
      - name: my-component
        properties: ...
        type: my-component-type

The following table lists the parameters for spec.workload.objectOutputRefs, ordered alphabetically.

Parameter	Description	Required
`name`	A unique identifier for the output across all object outputs in the workload.	✅
`deploymentPriority`	The deployment priority at which this output is resolved. Must be between 1 and the max deployment priority in the workload. If not provided, the output is resolved after the final deployment priority.	❌
`pathRef.apiVersion`	The `apiVersion` of the referenced object.	✅
`pathRef.kind`	The `kind` of the referenced object.	✅
`pathRef.name`	The `metadata.name` of the referenced object.	✅
`pathRef.namespace`	The `metadata.namespace` of the referenced object. When not specified, the object is assumed to be cluster-scoped.	❌
`pathRef.path`	A JSON path expression pointing to a field under `metadata`, `spec`, or `status` of the referenced object.	✅
`skipHash`	Optional flag (defaults to `false`). When `true`, this output is not included in the workload hash.	❌

If the referenced object or the path within it is not found during rendering, the workload is marked unhealthy, and rendering does not proceed.

Predefined Object Outputs

You can use predefined objectOutputRefs to expose an App Deployment's or Model Deployment's service, ingress, or gateway (HTTP route). Adding predefined objectOutputRefs to your application's or model's workload profile allows you to access your application or model by selecting the Access button instead of visiting a URL or IP address.

For guidance on accessing your application or model, refer to the Expose Deployments guide.

There are three patterns for exposing an app. The patterns expect some combination of the following objectOutputRefs names to exist:

Service - webserverIp and webserverPort
Ingress - ingressDomain, ingressPath, and httpScheme
Gateway (HTTP Route) - gatewayDomain, gatewayPath, and httpScheme

warning

Only change the lines highlighted in the following examples. If the objectOutputRefs[i].name does not use one of the values listed above, PaletteAI cannot expose the application or model.

Service

To expose a service, insert the following objectOutputRefs, replacing <service-name> and <service-namespace> with the appropriate values.

objectOutputRefs:
  - name: webserverIp
    pathRef:
      name: <service-name>
      namespace: <service-namespace>
      path: .status.loadBalancer.ingress[0].ip
      apiVersion: v1
      kind: Service
  - name: webserverPort
    pathRef:
      name: <service-name>
      namespace: <service-namespace>
      path: .spec.ports[0].port
      apiVersion: v1
      kind: Service

Ingress

To expose an ingress, insert the following objectOutputRefs, replacing <ingress-name> and <ingress-namespace> with the appropriate values.

Defining an httpScheme is optional. If undefined, http:// is used by default.

info

When TLS is configured for the ingress (spec.tls[0].hosts[0]), PaletteAI adds https:// to the URL when a user selects the Access button. Otherwise, it adds http://.

objectOutputRefs:
  - name: ingressDomain
    pathRef:
      name: <ingress-name>
      namespace: <ingress-namespace>
      path: .spec.rules[0].host
      apiVersion: networking.k8s.io/v1
      kind: Ingress
  - name: ingressPath
    pathRef:
      name: <ingress-name>
      namespace: <ingress-namespace>
      path: .spec.rules[0].http.paths[0].path
      apiVersion: networking.k8s.io/v1
      kind: Ingress
  - name: httpScheme
    pathRef:
      name: <ingress-name>
      namespace: <ingress-namespace>
      path: .spec.tls[0].hosts[0]
      apiVersion: networking.k8s.io/v1
      kind: Ingress

Gateway (HTTP Route)

To expose an HTTP route and its gateway, insert the following objectOutputRefs, replacing <httproute-name>, <httproute-namespace>, <gateway-name>, and <gateway-namespace> with the appropriate values.

Defining an httpScheme is optional. If undefined, http:// is used by default.

info

When the listener protocol indicates HTTPS (spec.listeners[0].protocol), PaletteAI adds https:// to the URL when a user selects the Access button. Otherwise, it adds http://. Depending on your environment setup, the correct index may not be 0. Review your listeners and select the appropriate listener for your gateway.

objectOutputRefs:
  - name: gatewayDomain
    pathRef:
      name: <httproute-name>
      namespace: <httproute-namespace>
      path: .spec.hostnames[0]
      apiVersion: gateway.networking.k8s.io/v1
      kind: HTTPRoute
  - name: gatewayPath
    pathRef:
      name: <httproute-name>
      namespace: <httproute-namespace>
      path: .spec.rules[0].matches[0].path.value
      apiVersion: gateway.networking.k8s.io/v1
      kind: HTTPRoute
  - name: httpScheme
    pathRef:
      name: <gateway-name>
      namespace: <gateway-namespace>
      path: .spec.listeners[0].protocol
      apiVersion: gateway.networking.k8s.io/v1
      kind: Gateway

System Outputs

System outputs are predefined workload values that PaletteAI exposes. Use them when a workload profile needs PaletteAI-defined metadata, such as the deployed workload name hash or deployment namespace, instead of metadata from Kubernetes resources. Unlike definition outputs and object outputs, system outputs do not come from component-created or external cluster objects. PaletteAI exposes them on each WorkloadDeployment in .status.systemOutputs.

Available System Outputs

Name	Description	Where it is exposed	Use Case
`wl-name-hash`	The hash of the deployed workload's name.	`.status.systemOutputs` on the `WorkloadDeployment`	Use this value when a workload profile needs a deterministic workload-specific value.
`wl-namespace`	The namespace that the workload is being deployed into.	`.status.systemOutputs` on the `WorkloadDeployment`	Use this value when a workload profile needs the workload deployment namespace.

Examples

System output macros resolve only in the hub context. Use the .sys prefix to reference them.

Minimal example
'{{ .sys.wl-namespace }}'

Workload Profile Example
apiVersion: spectrocloud.com/v1beta1
kind: WorkloadProfile
metadata:
  name: my-workload-profile
spec:
  workload:
    components:
      - name: my-app
        properties:
          env:
            - name: WL_NAME_HASH
              value: '{{ .sys.wl-name-hash }}'
            - name: WL_NAMESPACE
              value: '{{ .sys.wl-namespace }}'
        type: webservice

Definition Outputs​

Specify Outputs in Components and Traits​

CUE-Based Definition Outputs​

Definition-Level Annotations​

Template-Level Annotations​

Complete CUE Definition Example​

Validation Rules​

Object Outputs​

Define Object Outputs​

Predefined Object Outputs​

Service​

Ingress​

Gateway (HTTP Route)​

System Outputs​

Available System Outputs​

Examples​