Outputs

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

• Definition Outputs - Expose metadata from Kubernetes resources created by components or traits within the workload.

• Object Outputs - Expose metadata from arbitrary Kubernetes resources that exist outside the workload.

• System Outputs - Expose PaletteAI defined workload values.

Outputs support the following data types:

• string

• integer

• boolean

• jsonRaw (for arbitrarily complex objects)

Definition Outputs

Definition outputs are used to expose metadata from Kubernetes resources created by components or traits within the workload. These outputs reference resources that were created by the workload itself.

Define Definition Outputs

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, and 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-marshalled 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:

1. Definition Annotations - The definition object must declare what outputs it can generate using generates.output.spectrocloud.com/<name> annotations.

2. 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 will contain the output. kind - The kind of the resource that will contain 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 will be 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 are not found during rendering, the component will be marked unhealthy, and the Workload rendering will 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 a button instead of visiting a URL or IP address.

For guidance on accessing your application or model, refer to our 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.

info

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

To determine whether to expose the URL with an HTTP or HTTPS prefix, the ingress's spec.tls.[0].hosts[0] is inspected. If an entry is found in the list, PaletteAI prepends https:// to the URL when a user selects the Access button. Otherwise, http:// is prefixed.

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.

info

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

To determine whether to expose the URL with an HTTP or HTTPS prefix, the gateway's spec.listeners[0].protocol is inspected. If an entry is found in the list, PaletteAI prepends https:// to the URL when a user selects the Access button. Otherwise, http:// is prefixed.

Note that 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 a set of outputs that have been defined by PaletteAI. They can be seen on each WorkloadDeployments status within .status.systemOutputs.

There are two system outputs:

• wl-name-hash - The hash of the deployed workload's name.

• wl-namespace - The namespace that the workload is being deployed into.