Definitions

Definitions is an umbrella term that encapsulates Components, Traits, and Policies. They are reusable building blocks that describe how to deploy Workloads.

• Components - Define what runs, such as a web server, a database, or a batch job.

• Traits - Modify how it runs, such as scaling behavior, health checks, and resource limits.

• Policies - Specify where and how Workloads get deployed, controlling placement and environment-specific overrides.

Under the hood, Definitions are written using CUE, an advanced data validation and templating language. All Definitions require zero or more inputs and produce one or more Kubernetes resources (or custom resources) as outputs.

Each Definition type is stored on the PaletteAI hub cluster as its own custom resource: ComponentDefinition, TraitDefinition, and PolicyDefinition. All three types share the same lifecycle: they are versioned, packaged into Profile Bundles, and distributed to spoke clusters through the same mechanisms.

Definitions operate at the Workload level, including Workloads created automatically by AIWorkloads. When you deploy an AIWorkload, it generates WorkloadDeployments, which in turn create Workloads that use Definitions.

For detailed a technical reference on definitions, including how to author, build, and render definitions, refer to the Build Definitions and Render Definitions pages.

Components

Components are the essential building blocks of your AI/ML applications and models. They let you deploy Workloads without needing to write complex Kubernetes manifests, generating all the necessary resources for you.

Each Component type is registered as a ComponentDefinition custom resource on the hub cluster. Platform engineers author ComponentDefinitions, while application teams consume them by referencing the Component type name in a Workload Profile.

Components act as a contract: you specify what you want, and the Component guarantees the result. Platform engineers can change how the Component works under the hood (for example, adding security policies, adjusting resource limits, or updating best practices) without breaking the applications that use them.

For example, by providing only a container image, the default webservice Component produces a Kubernetes Deployment and Service. Webservices support other optional inputs, but this demonstrates the potential for abstracting the complexity of Kubernetes from application developers who are unfamiliar with its many concepts and configurations.

Platform engineers can also pre-install helper applications, such as operators, on spoke clusters for Components to use. For example, if you deploy a Component that outputs a Bucket resource, the Crossplane operator (if installed) will automatically create an actual cloud storage bucket. This concept applies to many other operators, including Vault (secrets management), Prometheus (monitoring), and more.

Deployment Priorities

Deployment priorities control the order in which Components are deployed. A lower numeric value means the Component is deployed earlier. For instance, if Component B depends on Component A, assigning Component A a deployment priority of 1 and Component B a deployment priority of 2 ensures that Component A is available before Component B is deployed.

The deployment order is determined by the deploymentPriority field on each Component. When not explicitly set, a Component defaults to a deployment priority of 1. All Components with the same deployment priority are deployed concurrently. The set of deployment priorities within a Workload must be a contiguous sequence starting at 1 (in other words, it must include every number from 1 up to the highest priority used, with no gaps). The order you write them in the YAML does not matter, only that all numbers are present. For example, 3, 1, 2 is valid (contains 1, 2, and 3), but 1, 3 is invalid (missing 2), and 2, 3, 4 is invalid (missing 1).

The following example demonstrates how deployment priorities can be applied within a Workload.

Example Workload manifest

apiVersion: spectrocloud.com/v1beta1
kind: Workload
metadata:
  name: deployment-priority-example
spec:
  components:
    - name: component-a
      properties: ...
      type: my-custom-component # omitted deploymentPriority; defaults to 1
    - name: component-b
      deploymentPriority: 2
      properties: ...
      type: my-custom-component
    - name: component-c
      deploymentPriority: 3
      properties: ...
      type: my-custom-component
    - name: component-d
      deploymentPriority: 2
      properties: ...
      type: my-custom-component

In this example, component-a (with the default deployment priority of 1) deploys first. Then, component-b and component-d are deployed concurrently, followed by component-c, which is deployed last.

For the complete behavior, including how batches are gated during rollout, when outputs are resolved, and how to inspect priority phase status while debugging, refer to the Deployment Priorities reference.

Traits

Traits are modifiers for Components, designed to handle uncommon or specialized requirements. If a Component covers 80% of use cases with its standard inputs, Traits let you address the remaining 20% of edge cases without making the Component itself more complex. This keeps Components approachable for most users while still allowing advanced customizations when needed.

Each Trait type is registered as a TraitDefinition custom resource on the hub cluster. Like Components, Traits are written in CUE, are versioned, and can define their own health policies and custom status messages. Platform engineers author custom Traits in the definition playground. For details, refer to Build Definitions.

You encounter Traits when you author a Workload Profile: each Component can list zero or more Traits, and each Trait entry specifies a Trait type and its properties. PaletteAI ships built-in Traits for common needs, such as scaler (manual replica scaling), hpa (horizontal pod autoscaling), env (environment variables), and expose (service exposure).

During rendering, PaletteAI first renders a Component's template and then applies the Component's Traits in the order they are listed. A Trait template can patch the resources the Component produced, such as adding labels or a sidecar container, or it can generate additional resources of its own, such as a HorizontalPodAutoscaler. For an example Workload Profile that pairs a webservice Component with the hpa and scaler Traits, refer to Workload Profiles.

Policies

Policies are system-level Definitions that control where Workloads are deployed and how Component settings can be overridden per Environment. Unlike Traits, which attach to a single Component, Policies apply to a Workload as a whole and are applied after Components and Traits are rendered.

Each Policy type is registered as a PolicyDefinition custom resource on the hub cluster. In most cases, you do not create Policies directly; PaletteAI configures them for you as part of the Compute Pool and Environment workflows. The built-in Policies fall into two groups: topology Policies, which control placement, and the override Policy, which adjusts configuration per Environment.

Topology Policies

PaletteAI provides two built-in topology Policies:

• topology-ocm - Creates a Placement automatically based on the Policy's configuration. This is used by default when ComputePools create Environments.
• topology-ocm-byop - References a preexisting Placement ("Bring Your Own Placement") resource.

When you create a Compute Pool, PaletteAI automatically creates an Environment with a topology Policy configured. This handles Workload placement to the Compute Pool's clusters without additional setup.

Under the hood, the Policy defines the Placement, an Open Cluster Management (OCM) resource that selects which clusters should receive a workload. The Environment (automatically with the Compute Pool) references the Policy. When you deploy a Workload to a Compute Pool, the Policy generates an OCM Placement that selects the target clusters. When clusters are added, removed, or change state, the Placement automatically updates its selections.

Override Policies

The built-in override Policy changes how a Workload's Components are configured in a specific Environment without editing the underlying Workload Profile. An override Policy can:

• Replace or extend the properties of one or more Components.

• Change the properties of a Trait attached to a Component, or disable the Trait entirely.

• Select which Components receive the override by name, or apply it to all Components when no selector is set.

Override Policies are typically attached to Environments, which lets the same Workload Profile deploy with different settings in each Environment, such as a lower replica count in a staging Environment. For more information, refer to Policies in Environments.

Definitions in Profile Bundles

Profile Bundles package everything a deployment needs, including the Definitions that its Workload Profiles depend on. A Profile Bundle's spec.customDefinitions field carries the ComponentDefinition, TraitDefinition, and PolicyDefinition resources that are not part of PaletteAI's default definition set. When you import a Profile Bundle, for example from PaletteAI Studio, PaletteAI registers each bundled Definition in the Profile Bundle's namespace unless a Definition with the same name (or the same name and semantic version, when semantic versioning is enabled) already exists.

Because bundled Definitions are managed by the Profile Bundle, deleting the Profile Bundle can also delete them. PaletteAI removes a bundled Definition only when the Profile Bundle's deletion policy is set to delete and no other Profile Bundle references the Definition. For details, refer to Deletion Policy.

Distribution to Spoke Clusters

Definitions live on the hub cluster, but Workloads are rendered on spoke clusters. So that every spoke can render Workloads consistently, the hub periodically bundles all ComponentDefinitions, TraitDefinitions, and PolicyDefinitions in a Tenant and pushes them to the OCI registries of the Tenant's spoke clusters. Each spoke pulls the bundle and applies the Definitions locally. For details, refer to Resource Federation.

Status and Health

Definitions can include custom health checks and status reporting to provide visibility into the state of deployed resources. For detailed information about health policies, custom status messages, and status details, refer to Status Attributes in Definition Rendering.

Permissions

Definition operations are controlled by role-based access control (RBAC) permissions. If certain UI elements such as the Add Definition button or Delete button are not displayed, your role does not include the required permission. Contact your administrator to request access.

Create Permissions

Creating a Definition, adding versions or revisions to an existing Definition, or cloning a Definition requires the appropriate create permission:

• spectrocloud.com/componentdefinitions:create - Create Component Definitions and add revisions or versions to existing Component Definitions.
• spectrocloud.com/traitdefinitions:create - Create Trait Definitions and add revisions or versions to existing Trait Definitions.
• spectrocloud.com/policydefinitions:create - Create Policy Definitions and add revisions or versions to existing Policy Definitions.

Users without the appropriate create permission cannot create Definitions, add new versions or revisions, or clone existing Definitions. These options are not visible in the UI for users without the required permissions.

Delete Permissions

Deletion operations require the appropriate delete permission:

• spectrocloud.com/componentdefinitions:delete - Delete Component Definitions.
• spectrocloud.com/traitdefinitions:delete - Delete Trait Definitions.
• spectrocloud.com/policydefinitions:delete - Delete Policy Definitions.

info

The system namespace (mural-system) is fully reserved for the platform. All resources in this namespace are managed exclusively by the PaletteAI installer and internal controllers. Users cannot create, update, or delete any Definitions in the system namespace, regardless of their RBAC permissions. To customize a system Definition, clone it into your project namespace and modify the clone.

You can delete a Definition in two ways:

• Delete entire Definition - Removes the Definition and all its revisions or versions. The Delete button is available in the Definition details view for users with the appropriate delete permission.

• Delete individual revision - Removes a specific revision while keeping the Definition and other revisions intact. A revision can only be deleted if both of the following conditions are met:

  • It is not the latest version (determined by semantic version comparison, not revision number).
  • It is not currently in use by any Workloads, Environments, or other resources.

Deletion is permanent and cannot be undone. Deleting individual revisions allows you to clean up old, unused revisions while protecting active and latest versions.

Component, ComponentDefinition, and DefinitionRevision

In the PaletteAI UI and in these docs, "Component" is sometimes used as shorthand for the reusable ComponentDefinition resource. When you author Definitions or troubleshoot resources on the hub cluster, it helps to distinguish three related resources: the Component entry in a Workload or Workload Profile, the ComponentDefinition custom resource, and the DefinitionRevision custom resource. The following table summarizes what each resource represents and who or what creates it.

Resource	What it represents	Who or what creates it
Component	A named entry in the spec.components list of a Workload or Workload Profile. Each entry references a ComponentDefinition through its type field and supplies inputs through its properties field.	You, when you author a Workload Profile or Workload. PaletteAI also generates these entries when it creates Workloads from AIWorkloads.
ComponentDefinition	The custom resource on the hub cluster that stores a Component's CUE template, custom health checks, and optional semantic version. It determines how Component inputs render into Kubernetes resources.	Definition authors, typically platform engineers, through the definition playground or by applying manifests to the hub cluster. The PaletteAI installer creates the system Definitions in the Helm release namespace (mural-system by default).
DefinitionRevision	An immutable snapshot of a Definition at a specific point in time, identified by a revision number and a content hash.	PaletteAI. A controller on the hub cluster automatically saves a new DefinitionRevision whenever a Definition's spec changes. You never create or edit DefinitionRevision resources directly.

The same model applies to Traits and Policies through the TraitDefinition and PolicyDefinition custom resources. PaletteAI also snapshots Environments, Workload Profiles, and Profile Bundles as DefinitionRevision resources.

Definition Authoring Flow

When a Definition author creates or edits a ComponentDefinition and saves it, PaletteAI compares the new spec against the most recent snapshot. If the content changed, PaletteAI saves a new DefinitionRevision, such as my-component-v2, and updates the status.latestRevision field on the ComponentDefinition. For details on authoring Definitions in the playground, refer to Build Definitions.

Deployment Flow

When PaletteAI renders a Workload, each Component's type field determines which snapshot of the ComponentDefinition is used:

• Unpinned (type: my-component) - PaletteAI renders using the latest version of the ComponentDefinition. When the Definition is updated, Workloads that reference it pick up the change during the next reconciliation cycle.

• Pinned (type: my-component@v2 or type: my-component@v1.2.0) - PaletteAI resolves the reference to the matching DefinitionRevision and renders from the snapshot stored in it. Later edits to the ComponentDefinition do not affect the Workload.

For details on how PaletteAI renders CUE templates into Kubernetes resources, refer to Render Definitions.

Version History, Rollback, and Deployment Stability

DefinitionRevision resources are the foundation of Definition versioning:

• Versioning - Every change to a Definition produces a new revision, so the history of a Definition is preserved and auditable. Refer to Definition Versions for the basic and semantic version formats.

• Rollback - To return to an earlier state of a Definition, pin your Workloads to an earlier revision, or publish a new revision that restores the earlier configuration.

• Deployment stability - Because each DefinitionRevision is immutable, pinned Workloads keep rendering the same resources regardless of later Definition edits. PaletteAI also prevents deletion of revisions that are in use by Workloads, Environments, or other resources.

Definition Versions

All Definitions are versioned, allowing you to track changes over time and control which version your Workloads use.

• Default behavior - Workloads automatically use the latest version of each Definition. When you update a Definition, your Workloads automatically pick up the change during the next reconciliation cycle.

• Pinning versions - You can "pin" a workload to a specific Definition version (either basic or semantic) if you need stability and do not want automatic updates. Use this sparingly, as it prevents you from receiving infrastructure improvements automatically.

Basic Versions

PaletteAI creates a new DefinitionRevision following every update to the spec of any Component, Trait, Policy, Environment, ProfileBundle, or WorkloadProfile. Revisions are autoincrementing integers starting at 1. For example, when a Component named my-custom-component is first created, a v1 Definition revision is created to store that Component's initial state. The next time my-custom-component is edited, a v2 Definition revision is created.

Any Workload can request the latest version of the Component my-custom-component as follows:

Example Workload manifest using latest Component version

apiVersion: spectrocloud.com/v1beta1
kind: Workload
metadata:
  name: versioning-example-latest
spec:
  components:
    - name: custom-component-example
      properties: ...
      type: my-custom-component

Alternatively, a Workload may request a specific revision of a Component by adding @<revisionId> to the type.

Example Workload manifest using a pinned Component version

apiVersion: spectrocloud.com/v1beta1
kind: Workload
metadata:
  name: versioning-example-pinned
spec:
  components:
    - name: custom-component-example
      properties: ...
      type: my-custom-component@v1

Semantic Versions

PaletteAI also supports semantic versioning and version ranges. A Definition version may be pinned to a specific semantic version or to a particular semantic version range. Semantic versioning ensures consistency when deploying workloads into multiple PaletteAI environments with potentially differing Definition revision histories.

To use semantic versioning, a Definition's spec.Version field must contain a valid semantic version. The Version field is optional for all Definition types. If unset, basic versioning will be used. Like basic versioning, a semantic version for any Definition may be specified in a Workload's spec.components[*].type field.

• Pinning to a major version range (for example, my-component@v1) uses the latest major.minor.patch version with a matching major version.

• Pinning to a major.minor version range (for example, my-component@v1.3) uses the latest major.minor.patch version with a matching major.minor version.

• Pinning to an exact major.minor.patch version (for example, my-component@v1.3.6) uses that version, if it exists.

warning

Definitions with semantic versions specified override Definitions without a semantic version.

For example, if you create a TraitDefinition named my-trait, an initial Definition revision is created with name my-trait-v1. When you create a Workload that leverages my-trait, the my-trait-v1 revision is used. If you edit the my-trait TraitDefinition and set spec.Version to 1.2.0, a new Definition revision is created with the name my-trait-v1.2.0. As a result, the Workload is automatically updated to use the my-trait-v1.2.0 revision, since the trait was only pinned to within the 1.x range.

For this reason, we recommend avoiding mixing basic and semantic versioning in a single PaletteAI environment.