Annotations and Labels

PaletteAI handles annotations and labels through a hierarchical propagation system that determines where they appear in the final rendered resources. Understanding this behavior is crucial for proper configuration management.

General Propagation

Generally, annotations and labels flow through the system in the following hierarchy:

1. WorkloadDeployment.Metadata - Not propagated (with the exception of Flux-related rendering.spectrocloud.com/ annotations, such as suspend, oci-interval, oci-timeout, and kustomization-*).

   info

   resync-period does not propagate from WorkloadDeployment metadata; it must be set on WorkloadDeployment.Spec.Workload.Metadata.

2. WorkloadDeployment.Spec.Workload.Metadata - Propagates to Workload.Metadata.

3. Workload.Metadata - Propagates to rendered resources (Deployments, Services, etc.).

4. Repository.Metadata - Annotations and labels applied directly to Repository resources (Helm Repositories and OCI Repositories) are not propagated. They are used for resource identification and organization within the Project.

Render Annotations

PaletteAI supports configuring the reconciliation parameters of PaletteAI resources as well as generated Flux resources via annotations. Rendering annotations (those with the rendering.spectrocloud.com/ prefix) are treated specially:

• Only the Flux-related rendering.spectrocloud.com/ annotations (suspend, oci-interval, oci-timeout, and kustomization-*) propagate from WorkloadDeployment.Metadata.Annotations to Workload.Metadata.Annotations. The resync-period and field-validation annotations do not propagate from WorkloadDeployment.Metadata.

• The Flux-related rendering.spectrocloud.com/ annotations and resync-period are stripped from rendered resources. The field-validation annotation is not stripped and propagates to rendered resources if present on Workload.Metadata.Annotations.

Filter Annotations and Labels

You can control which annotations and labels are applied to rendered resources using filter annotations:

• filter.spectrocloud.com/annotation-keys - Comma-separated list of annotation keys to exclude from rendered resources.

• filter.spectrocloud.com/label-keys - Comma-separated list of label keys to exclude from rendered resources.

Available Annotations and Labels

There are several types of annotations and labels, including:

• Flux reconciliation

• PaletteAI reconciliation

• Definitions

• Pack deployment

• Filters

• UI visibility

Flux Reconciliation Annotations

Flux reconciliation annotations control Flux behavior and are applied to Workload and WorkloadDeployment resources but not to rendered resources. They are used to override the default values set on the Hue controller on a per-workload basis.

Annotation	Description	Resource Types
rendering.spectrocloud.com/suspend	If true, Flux reconciliation is paused for the workload's OCIRepository and Kustomization resources	Workload and WorkloadDeployment
rendering.spectrocloud.com/oci-interval	Specifies the reconcile interval for the Flux OCIRepository. Must be parsable as a time.Duration.	Workload and WorkloadDeployment
rendering.spectrocloud.com/oci-timeout	Specifies a timeout for Flux validation, applying health check operations on a workload's OCIRepository. Must be parsable as a time.Duration.	Workload and WorkloadDeployment
rendering.spectrocloud.com/kustomization-force	If true, Flux recreates resources when patching fails due to an immutable field change.	Workload and WorkloadDeployment
rendering.spectrocloud.com/kustomization-prune	Specifies whether to garbage collect resources associated with components or traits that are removed from the WorkloadProfile after the initial deployment. If false, Flux does not garbage collect resources that are no longer rendered.	Workload and WorkloadDeployment
rendering.spectrocloud.com/kustomization-timeout	Specifies a timeout for Flux validation, applying health check operations on a workload's Kustomization. Must be parsable as a time.Duration.	Workload and WorkloadDeployment
rendering.spectrocloud.com/kustomization-interval	Specifies the reconcile interval for the Flux Kustomization. Must be parsable as a time.Duration.	Workload and WorkloadDeployment
rendering.spectrocloud.com/kustomization-retry-interval	Specifies the retry interval for the Flux Kustomization. Must be parsable as a time.Duration.	Workload and WorkloadDeployment

info

When not specified, the default values for reconciliation parameters of Flux resources are configured in the Hue controller arguments.

PaletteAI Reconciliation Annotations

PaletteAI reconciliation annotations control the rendering, reconciliation, and validation behavior of certain PaletteAI resources.

Annotation	Description	Resource Types
rendering.spectrocloud.com/resync-period	Specifies how often resources are synced. Must be parsable as a time.Duration.	Workload, WorkloadDeployment, Environment, Helm Repositories, and OCI Repositories
rendering.spectrocloud.com/field-validation	Specifies the field validation mode for dry-run applying resources rendered from a Workload during validation.	Workload, WorkloadProfile, and any Kubernetes resource within a definition's CUE template (overrides Workload annotation)

info

When not specified, the default sync period of PaletteAI resources is configured in the Hue controller arguments.

Definition Annotations

Definition annotations modify the default system behavior when set within the annotations property for select components.

Annotation	Description	Resource Types
wl.spectrocloud.com/disable-health-check	Disables component health checks, forcing it to be considered healthy	WorkloadProfile (component properties)

info

The statefulset component uses app.spectrocloud.com/disable-health-check instead of wl.spectrocloud.com/disable-health-check.

To use definition annotations, add them to <component>.properties.annotations for all components that support an annotations property and implement a healthPolicy. Be sure to add the annotation to the component properties, not the WorkloadDeployment metadata.

The annotation value can be any string (for example, "true", "disabled", or even an empty string); only the presence of the annotation key matters.

warning

You must disable health checks when working with OCI HelmRepository components, because the source-controller does not populate a Ready condition for HelmRepository resources with spec.type: "oci". Refer to the OCI HelmRepository documentation for further detail.

Example annotation for helmrepository component

apiVersion: spectrocloud.com/v1beta1
kind: WorkloadProfile
metadata:
  name: annotation-demo-wlp
spec:
  components:
    - name: bitnami-repo
      type: helmrepository
      deploymentPriority: 1
      properties:
        url: 'https://charts.bitnami.com/bitnobody' # purposefully invalid url to verify the annotation behaviour
        annotations:
          wl.spectrocloud.com/disable-health-check: 'true' # forces the "bitnobody" repo to be considered healthy
        # url: "https://charts.bitnami.com/bitnami" # remove the url and annotation above and use this correct url to verify the default behaviour
        interval: '10m0s'
        timeout: '60s'

Pack Deployment Annotations

Pack deployment annotations control the installation order and behavior of packs during appliance deployment.

Annotation	Description	Resource Types
spectrocloud.com/install-priority	Controls the installation priority for packs during appliance deployment. Higher values indicate higher priority.	Pack values.yaml

To use pack deployment annotations, add them to the pack values.yaml file at the top level. The annotation controls the order in which packs are installed during the appliance deployment process.

Example pack deployment annotation

pack:
  namespace: 'palette-ai-system'
  # ... other pack configuration
  spectrocloud.com/install-priority: '100'

Filter Annotations

Filter annotations control what gets propagated to rendered resources.

Annotation	Description	Resource Types
filter.spectrocloud.com/annotation-keys	Comma-separated list of annotation keys to exclude from rendered resources	Workload
filter.spectrocloud.com/label-keys	Comma-separated list of label keys to exclude from rendered resources	Workload

Available Labels

UI Visibility Labels

UI visibility labels control whether resources are displayed in the PaletteAI UI.

Label	Description	Resource Types
ui-hidden	Hides resources from the PaletteAI UI. When set to "true", the labeled resource is filtered out from UI lists, dropdowns, and wizard selectors. The resource remains accessible through the API.	ComponentDefinitions, TraitDefinitions, PolicyDefinitions, DefinitionRevisions, and other definition sources

The ui-hidden label is enforced at the API level through a centralized filtering mechanism. When you list components, traits, policies, and definition revisions, the system automatically applies the label selector ui-hidden!=true to exclude resources with the ui-hidden label set to "true". This filtering occurs in multiple contexts, including:

• The definitions wizard when fetching sources
• The profiles/new route when loading definitions
• The definitions list route

The filtering operates across both project and system namespaces, ensuring consistent behavior throughout the platform. All definition loaders use this centralized mechanism to provide uniform filtering of UI-hidden resources at the backend level.

To use the ui-hidden label, add it to the resource metadata. The label is useful for hiding internal or deprecated definitions from users while keeping them available for programmatic access or backward compatibility.

Example ui-hidden label

apiVersion: spectrocloud.com/v1beta1
kind: ComponentDefinition
metadata:
  name: internal-component
  labels:
    ui-hidden: 'true'
spec:
  # ... component definition

For examples of applying annotations and labels to Repository resources, refer to Create and Manage Repositories.

Example

Following is an example showing how different annotations propagate.

apiVersion: spectrocloud.com/v1beta1
kind: WorkloadDeployment
metadata:
  name: my-workload-deployment
  namespace: my-namespace
  annotations:
    rendering.spectrocloud.com/oci-timeout: '10s' # → Flux Resource specs, Workload.Metadata.Annotations
    rendering.spectrocloud.com/kustomization-timeout: '10s' # → Flux Resource specs, NOT Workload.Metadata.Annotations (overwritten, see below)
    foo.spectrocloud.com/test: test # → NOT propagated anywhere
  labels:
    some-label: some-value # → NOT propagated anywhere
spec:
  workload:
    metadata:
      annotations:
        rendering.spectrocloud.com/kustomization-timeout: '45s' # → Workload.Metadata.Annotations, Flux Resource specs. Overwrites the values set on the WorkloadDeployment.
        foo.spectrocloud.com/test: abc # → Workload.Metadata.Annotations, Rendered resources
        bar.spectrocloud.com/test: def # → Workload.Metadata.Annotations, NOT Rendered resources (filtered out based on filter.spectrocloud.com/annotation-keys)
        baz.spectrocloud.com/test: ghi # → Workload.Metadata.Annotations, NOT Rendered resources (filtered out based on filter.spectrocloud.com/annotation-keys)
        filter.spectrocloud.com/annotation-keys: 'bar.spectrocloud.com/test,baz.spectrocloud.com/test' # → Workload.Metadata.Annotations, NOT Rendered resources (filtered out)
        filter.spectrocloud.com/label-keys: 'some-other-label' # → Workload.Metadata.Annotations, NOT Rendered resources (filtered out)
      labels:
        some-label: some-value # → Workload.Metadata.Labels, Rendered resources
        some-other-label: some-other-value # → Workload.Metadata.Labels, NOT Rendered resources (filtered out based on filter.spectrocloud.com/label-keys)
    name: my-workload
    namespace: my-namespace