Katalog

3 min read

A Katalog declares one or more CRDs and defines how Orkestra manages them. It is the unit of operator definition.

Wire format

apiVersion: orkestra.orkspace.io/v1   # required
kind: Katalog                          # required

metadata:
  name: my-operator                    # required
  description: string                  # optional

profiles:                              # optional → see profiles schema
  reconciler: [...]
  networkPolicies: [...]
  resourceQuotas: [...]
  limitRanges: [...]
  pdb: [...]
  rollingUpdate: [...]
  resources: [...]
  probes: [...]
  containerSecurity: [...]
  podSecurity: [...]

notes:                                 # optional — user-defined template functions
  functions:
    - name: fullImage
      description: string
      expression: '{{ .spec.image }}:{{ .spec.tag | default "latest" }}'

spec:
  finalizers:                          # optional — applied to every CRD
    - platform.example.io/cleanup

  crds:                                # required — map of CRD entries by name
    <name>:                            # ← map key is the CRD name
      ...                              # → see crd-entry.md

security:                              # optional → see katalog-security.md
  ...

notification:                          # optional → see katalog-notification.md
  ...

providers:                             # optional → see katalog-providers.md
  - ...

metadata

FieldRequiredDescription
nameyesUnique identifier. Written as the managed-by annotation on all CRs.
descriptionnoShown in the /katalog API response.

spec.finalizers

Katalog-level finalizers applied to every CRD in this Katalog. Override per-CRD via operatorBox.finalizers.

spec.crds

A map — the key is the CRD name, the value is a CRDEntry.

spec:
  crds:
    database:          # ← CRD name
      enabled: true
      apiTypes:
        group: apps.example.io
        version: v1alpha1
        kind: Database
        plural: databases

→ Full field reference: crd-entry

notes

User-defined template functions, available in every {{ }} expression in this Katalog — status fields, resource names, when: conditions, and anywhere else a template is evaluated.

notes:
  functions:
    - name: fullImage
      description: Qualified image reference combining image and tag
      expression: "{{ .spec.image }}:{{ .spec.tag | default \"latest\" }}"

    - name: inBusinessHours
      expression: '{{ and weekday (timeInWindow "09:00" "18:00") }}'

    - name: statusLabel
      expression: "{{ if inBusinessHours }}Active{{ else }}Suspended{{ end }}"
FieldRequiredDescription
nameyesFunction name. Called as {{ noteName }} in templates. Must be a valid Go identifier.
expressionyesGo template expression. May call built-in notes and other user-defined notes.
descriptionnoHuman-readable description. Shown in ork validate --notes.

Notes are pure: same input → same output. They may call any built-in note and any other user-defined note declared in the same notes.functions: block (order-independent).

→ Full reference: Notes concept


profiles

Named profile definitions shared across all CRD entries in this Katalog. Profiles are resolved by name at reconcile time — user-defined profiles take precedence over built-ins.

KeyClass
profiles.reconcilerReconciler tuning (workers, resync, queue depth)
profiles.networkPoliciesNetworkPolicy ingress/egress rules
profiles.resourceQuotasHard resource quota limits
profiles.limitRangesContainer and pod limit items
profiles.pdbPodDisruptionBudget min/max settings
profiles.rollingUpdateDeployment rolling update strategy
profiles.resourcesContainer CPU and memory requests/limits
profiles.probesProbe timing parameters
profiles.containerSecurityContainer-level securityContext
profiles.podSecurityPod-level securityContext

→ Full reference: User-Defined Profiles

Where to go next