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.

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.

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.

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 simple for most users while still allowing advanced customizations when needed.

Policies

Policies are system-level Definitions that control where Workloads are deployed and how Component settings can be overridden per environment.

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 |

In most cases, you do not create Policies directly. 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.

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

Deleting a Definition (which removes the Definition and all its revisions or versions) requires 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

System-level Definitions (those in the system namespace) cannot be deleted, even if you have delete permissions. Only Definitions in project namespaces can be deleted.

Deletion is permanent and cannot be undone. The Delete button is available in the Definition details view for users with the appropriate delete permission. When you delete a Definition, all its versions or revisions are removed.

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.