Version: v1.0.0-rc.1 (pre-release)

ClusterComponentType

A ClusterComponentType is a cluster-scoped variant of ComponentType that defines reusable deployment templates available across all namespaces. This enables platform engineers to define shared component types once and reference them from Components in any namespace, eliminating duplication.

ClusterComponentTypes share the same spec structure as ComponentTypes with two key constraints: because ClusterComponentTypes are cluster-scoped, they can only reference ClusterTraits (not namespace-scoped Traits) in their traits and allowedTraits fields, and can only reference ClusterWorkflows (not namespace-scoped Workflows) in their allowedWorkflows field.

API Version

openchoreo.dev/v1alpha1

Resource Definition

Metadata

ClusterComponentTypes are cluster-scoped resources (no namespace).

apiVersion: openchoreo.dev/v1alpha1
kind: ClusterComponentType
metadata:
  name: <clustercomponenttype-name>

note

ClusterComponentType manifests must not include metadata.namespace. If you are copying from a namespace-scoped ComponentType example, remove the namespace field.

Short names: cct, ccts

Spec Fields

Field	Type	Required	Default	Description
`workloadType`	string	Yes	-	Primary workload type: `deployment`, `statefulset`, `cronjob`, `job`, `proxy`
`allowedWorkflows`	[ClusterWorkflowRef]	No	[]	ClusterWorkflow references developers can use for building this component type; if empty, no workflows are allowed
`parameters`	SchemaSection	No	-	Configurable parameters schema for components of this type
`environmentConfigs`	SchemaSection	No	-	Environment-specific configuration schema for components of this type
`traits`	[ClusterComponentTypeTrait]	No	[]	Pre-configured ClusterTrait instances automatically applied to all Components of this type
`allowedTraits`	[ClusterTraitRef]	No	[]	ClusterTraits that developers can attach to components of this type
`validations`	[ValidationRule]	No	[]	CEL-based rules evaluated during rendering; all must pass for rendering to proceed
`resources`	[ResourceTemplate]	Yes	-	Templates for generating Kubernetes resources

note

The workloadType field is immutable after creation and determines the primary resource type for components of this type. For non-proxy workload types, one resource template must have an id matching the workloadType.

ClusterWorkflowRef

Specifies a ClusterWorkflow that developers can use with components of this type. Because ClusterComponentType is cluster-scoped, only ClusterWorkflow references are allowed (not namespace-scoped Workflows).

Field	Type	Required	Default	Description
`kind`	string	No	`ClusterWorkflow`	Must be `ClusterWorkflow`
`name`	string	Yes	-	Name of the ClusterWorkflow resource

Example:

allowedWorkflows:
  - kind: ClusterWorkflow
    name: docker
  - kind: ClusterWorkflow
    name: google-cloud-buildpacks

ClusterComponentTypeTrait

Represents a pre-configured trait instance embedded in a ClusterComponentType. Only ClusterTrait references are allowed since ClusterComponentType is cluster-scoped.

Field	Type	Required	Default	Description
`kind`	string	No	`ClusterTrait`	Must be `ClusterTrait`
`name`	string	Yes	-	Name of the ClusterTrait
`instanceName`	string	Yes	-	Unique instance name within the component type
`parameters`	object	No	-	Trait parameter values (can use CEL expressions referencing the ComponentType schema, e.g., `${parameters.storage.mountPath}`)
`environmentConfigs`	object	No	-	Environment-specific configuration values for the trait

ClusterTraitRef

Specifies a ClusterTrait that developers can attach to components of this type. Unlike the namespace-scoped TraitRef, only ClusterTrait references are allowed.

Field	Type	Required	Default	Description
`kind`	string	Yes	`ClusterTrait`	Must be `ClusterTrait`
`name`	string	Yes	-	Name of the ClusterTrait

SchemaSection

Defines a schema section used for parameters and environmentConfigs fields using standard JSON Schema.

Field	Type	Required	Default	Description
`openAPIV3Schema`	object	Yes	-	Standard OpenAPI V3 JSON Schema definition

Example:

parameters:
  openAPIV3Schema:
    type: object
    properties:
      replicas:
        type: integer
        default: 1
      imagePullPolicy:
        type: string
        default: IfNotPresent
      port:
        type: integer
        default: 80

environmentConfigs:
  openAPIV3Schema:
    type: object
    properties:
      cpu:
        type: string
        default: 100m
      memory:
        type: string
        default: 256Mi

ValidationRule

Defines a CEL-based validation rule evaluated during rendering. All rules must evaluate to true for rendering to proceed.

Field	Type	Required	Description
`rule`	string	Yes	CEL expression wrapped in `${...}` that must evaluate to true
`message`	string	Yes	Error message shown when the rule evaluates to false

Example:

validations:
  - rule: ${parameters.replicas >= 1}
    message: "replicas must be at least 1"
  - rule: ${parameters.port > 0 && parameters.port <= 65535}
    message: "port must be between 1 and 65535"

ResourceTemplate

Defines a template for generating Kubernetes resources with CEL expressions for dynamic values.

Field	Type	Required	Default	Description
`id`	string	Yes	-	Unique identifier (must match `workloadType` for primary)
`targetPlane`	string	No	`dataplane`	Target plane: `dataplane` or `observabilityplane`
`includeWhen`	string	No	-	CEL expression determining if resource should be created
`forEach`	string	No	-	CEL expression for generating multiple resources from list
`var`	string	No	-	Variable name for `forEach` iterations (required if `forEach` is set)
`template`	object	Yes	-	Kubernetes resource template with CEL expressions

CEL Expression Syntax

Templates use CEL expressions enclosed in ${...} that have access to context variables. Refer to the ComponentType CEL Expression Syntax for the full list of available context variables (metadata, parameters, environmentConfigs, workload, configurations, dataplane) and helper functions.

Examples

Basic Deployment ClusterComponentType

apiVersion: openchoreo.dev/v1alpha1
kind: ClusterComponentType
metadata:
  name: service
spec:
  workloadType: deployment

  parameters:
    openAPIV3Schema:
      type: object
      properties:
        replicas:
          type: integer
          default: 1
        port:
          type: integer
          default: 80

  resources:
    - id: deployment
      template:
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: ${metadata.name}
          namespace: ${metadata.namespace}
        spec:
          replicas: ${parameters.replicas}
          selector:
            matchLabels: ${metadata.podSelectors}
          template:
            metadata:
              labels: ${metadata.podSelectors}
            spec:
              containers:
                - name: main
                  image: ${workload.container.image}
                  ports:
                    - containerPort: ${parameters.port}

ClusterComponentType with Embedded Traits and Validations

apiVersion: openchoreo.dev/v1alpha1
kind: ClusterComponentType
metadata:
  name: web-service
spec:
  workloadType: deployment

  parameters:
    openAPIV3Schema:
      type: object
      properties:
        replicas:
          type: integer
          default: 1
          minimum: 1
        port:
          type: integer
          default: 8080

  environmentConfigs:
    openAPIV3Schema:
      type: object
      properties:
        cpu:
          type: string
          default: 100m
        memory:
          type: string
          default: 256Mi

  validations:
    - rule: ${parameters.replicas >= 1}
      message: "replicas must be at least 1"

  # Pre-configured traits automatically applied to all components
  traits:
    - kind: ClusterTrait
      name: resource-limits
      instanceName: default-limits
      environmentConfigs:
        cpuLimit: "${environmentConfigs.cpu}"
        memoryLimit: "${environmentConfigs.memory}"

  # Additional traits developers can attach
  allowedTraits:
    - kind: ClusterTrait
      name: persistent-volume

  resources:
    - id: deployment
      template:
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: ${metadata.name}
          namespace: ${metadata.namespace}
          labels: ${metadata.labels}
        spec:
          replicas: ${parameters.replicas}
          selector:
            matchLabels: ${metadata.podSelectors}
          template:
            metadata:
              labels: ${metadata.podSelectors}
            spec:
              containers:
                - name: main
                  image: ${workload.container.image}
                  ports:
                    - containerPort: ${parameters.port}

    - id: service
      template:
        apiVersion: v1
        kind: Service
        metadata:
          name: ${metadata.componentName}
          namespace: ${metadata.namespace}
        spec:
          selector: ${metadata.podSelectors}
          ports:
            - port: 80
              targetPort: ${parameters.port}

    - id: httproute-external
      forEach: '${workload.endpoints.transformList(name, ep, ("external" in ep.visibility && ep.type in ["HTTP", "REST", "GraphQL", "Websocket"]) ? [name] : []).flatten()}'
      var: endpoint
      template:
        apiVersion: gateway.networking.k8s.io/v1
        kind: HTTPRoute
        metadata:
          name: ${oc_generate_name(metadata.componentName, endpoint)}
          namespace: ${metadata.namespace}
          labels: '${oc_merge(metadata.labels, {"openchoreo.dev/endpoint-name": endpoint, "openchoreo.dev/endpoint-visibility": "external"})}'
        spec:
          parentRefs:
            - name: ${gateway.ingress.external.name}
              namespace: ${gateway.ingress.external.namespace}
          hostnames: |
            ${[gateway.ingress.external.?http, gateway.ingress.external.?https]
              .filter(g, g.hasValue()).map(g, g.value().host).distinct()
              .map(h, oc_dns_label(endpoint, metadata.componentName, metadata.environmentName, metadata.componentNamespace) + "." + h)}
          rules:
          - matches:
            - path:
                type: PathPrefix
                value: /${metadata.componentName}-${endpoint}
            filters:
              - type: URLRewrite
                urlRewrite:
                  path:
                    type: ReplacePrefixMatch
                    replacePrefixMatch: '${workload.endpoints[endpoint].?basePath.orValue("") != "" ? workload.endpoints[endpoint].?basePath.orValue("") : "/"}'
            backendRefs:
            - name: ${metadata.componentName}
              port: ${workload.endpoints[endpoint].port}

Scheduled Task ClusterComponentType

apiVersion: openchoreo.dev/v1alpha1
kind: ClusterComponentType
metadata:
  name: scheduled-task
spec:
  workloadType: cronjob

  parameters:
    openAPIV3Schema:
      type: object
      properties:
        schedule:
          type: string
        concurrencyPolicy:
          type: string
          default: Forbid
          enum:
            - Allow
            - Forbid
            - Replace

  resources:
    - id: cronjob
      template:
        apiVersion: batch/v1
        kind: CronJob
        metadata:
          name: ${metadata.name}
          namespace: ${metadata.namespace}
        spec:
          schedule: ${parameters.schedule}
          concurrencyPolicy: ${parameters.concurrencyPolicy}
          jobTemplate:
            spec:
              template:
                spec:
                  containers:
                    - name: main
                      image: ${workload.container.image}
                  restartPolicy: OnFailure

Usage

Components reference a ClusterComponentType using spec.componentType with kind: ClusterComponentType:

apiVersion: openchoreo.dev/v1alpha1
kind: Component
metadata:
  name: my-service
  namespace: default
spec:
  componentType:
    kind: ClusterComponentType
    name: deployment/service  # format: workloadType/name
  parameters:
    replicas: 3
    port: 8080

Best Practices

Use for shared patterns: Define ClusterComponentTypes for deployment patterns used across multiple namespaces; use namespace-scoped ComponentTypes for namespace-specific patterns
Naming convention: Use descriptive names like service, web-application, scheduled-task
Trait restrictions: Remember that ClusterComponentTypes can only reference ClusterTraits, not namespace-scoped Traits
Parameter design: Keep parameters focused and provide sensible defaults
Validations: Add validation rules for parameters that have constraints (e.g., minimum replicas, valid port ranges)
Testing: Validate ClusterComponentTypes with sample Components before platform-wide deployment

ComponentType - Namespace-scoped variant of ClusterComponentType
ClusterWorkflow - Cluster-scoped workflows that can be referenced by ClusterComponentTypes
ClusterTrait - Cluster-scoped traits that can be referenced by ClusterComponentTypes
Configuration Helpers - Configuration helper functions reference
Component - Uses ComponentTypes or ClusterComponentTypes for deployment
ReleaseBinding - Binds a ComponentRelease to an environment with parameter overrides
Trait - Namespace-scoped traits (cannot be used with ClusterComponentTypes)

API Version​

Resource Definition​

Metadata​

Spec Fields​

ClusterWorkflowRef​

ClusterComponentTypeTrait​

ClusterTraitRef​

SchemaSection​

ValidationRule​

ResourceTemplate​

CEL Expression Syntax​

Examples​

Basic Deployment ClusterComponentType​

ClusterComponentType with Embedded Traits and Validations​

Scheduled Task ClusterComponentType​

Usage​

Best Practices​

Related Resources​

API Version

Resource Definition

Metadata

Spec Fields

ClusterWorkflowRef

ClusterComponentTypeTrait

ClusterTraitRef

SchemaSection

ValidationRule

ResourceTemplate

CEL Expression Syntax

Examples

Basic Deployment ClusterComponentType

ClusterComponentType with Embedded Traits and Validations

Scheduled Task ClusterComponentType

Usage

Best Practices

Related Resources