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.).

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:

• WorkloadDeployment.Metadata.Annotations with rendering.spectrocloud.com/ prefix - Propagates directly to Workload.Metadata.Annotations.

• Workload.Metadata.Annotations with rendering.spectrocloud.com/ prefix - Is not applied to rendered resources.

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

There are several types of annotations, including:

• Flux reconciliation

• PaletteAI reconciliation

• Definitions

• Filters

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, and Environment
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)

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'

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

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