katalog

package
v0.4.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 18, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

README

pkg/katalog

The katalog package is the schema registry for an Orkestra operator. It parses and validates the user's Katalog YAML, enriches each CRD entry with runtime metadata, and exposes the result as a queryable *Katalog value that every other subsystem reads from.

Nothing in Orkestra hardcodes a CRD — everything is driven by what the Katalog says.

What the Katalog holds

What Where in code
Enabled CRD entries (enriched, validated) k.enabledCRDs
Katalog metadata (name, version, author, license) k.metadata
Security configuration (deletion protection, RBAC) k.Security
Conversion rules (/convert webhook) k.conversionRegistry
Admission rules (/validate, /mutate webhooks) k.admissionRegistry
Dependency DAG built lazily by NewDependencyGraph(k)

Boot sequence

merger.Merger (merges N katalog YAML files)
    ↓
NewKatalog(merger, konfig)
    → KomposeRuntimeKatalog  — decode YAML, enrich entries
    → ValidateConfig          — field-level, uniqueness, dependency, GVK, defaults
    → updateResourceMapAndReturn — build GVK → type index
    ↓
*Katalog (ready to use)

NewKatalog calls utils.Exit on any validation failure — the operator does not start with a broken Katalog.

CRD entry lifecycle

Each CRDEntry goes through several enrichment phases before it is considered ready:

  1. Parse — decoded from YAML via the merger.
  2. crdFile population — if crdFile: is declared, populateAPITypesFromCRDFile reads the CRD YAML and fills APITypes (group, version, kind, plural) from it. crdFile is the source of truth and overwrites any inline apiTypes: block. Typed-mode fields (Object, List, Alias, Location) are preserved from the inline declaration if present.
  3. Enrich — EnrichCRDEntry fills in computed fields (API path, plural, GVK). For built-in Kubernetes kinds (Deployment, ConfigMap, etc.), group/version/plural are looked up from builtins.go.
  4. Validate — uniqueness, dependency graph (existence + cycle), reconciler mode.
  5. Defaults — workers, resync interval, namespace handling, finalizers, description.
  6. Runtime objects — dynamic mode → *unstructured.Unstructured factory; typed mode → ObjectRegistry lookup.
  7. Reconcilers — hooks from HookRegistry, constructors from ReconcilerRegistry.
  8. Status flags — IgnoreStatusPatch and IgnoreObservedGeneration set from builtins.go.

After this pipeline, k.enabledCRDs contains fully-prepared entries. All runtime code reads from this map — it is never mutated after boot.

Step 2 (crdFile population) runs inside KomposeRuntimeKatalog, before ValidateConfig. By the time any validation runs, APITypes is fully populated regardless of whether the user declared apiTypes: or crdFile: or both.

Motif support

The katalog package also handles Motif imports — reusable infrastructure templates (databases, caches, message brokers) that a Katalog can import instead of writing all stateful resource declarations by hand.

File Role
motif_imports.go ResolveMotifImports — expands imports: blocks into concrete resource declarations
motif_validate.go ValidateMotif, ValidateMotifImports — structural and semantic validation of Motif YAML

Motif YAML is loaded by pkg/motif/loader.go using utils.StrictUnmarshal (same strict decoder as Katalog/Komposer) and then validated by motif_validate.go before any import expansion runs.

Developer documentation

I want to… Go to
Query the Katalog at runtime docs/01-querying.md
Understand the dependency graph docs/02-dependencies.md
Understand deletion protection docs/03-deletion-protection.md
Understand security defaults docs/04-security.md
Understand built-in type handling docs/05-builtins.md
Understand Motif validation and import expansion docs/06-motif-validation.md
Understand crdFile — auto-populating APITypes from a CRD YAML docs/07-crd-file.md

Documentation

Overview

pkg/katalog/admission_registry.go

pkg/katalog/builtins.go

Single authoritative registry for every Kubernetes built-in resource kind Orkestra knows about. Adding one entry here is the only change required to:

  • Resolve GVR for children and GVR lookups
  • Generate RBAC rules (ClusterRole) for any katalog that uses the resource
  • Detect usage in onReconcile / onCreate / onDelete template blocks
  • Expand kind shorthands (e.g. "hpa" → "horizontalpodautoscaler")
  • Derive the canonical PascalCase Kind name
  • Drive readiness and deletion-protection logic

Keys are lowercase singular Kind names (e.g. "deployment", "namespace").

pkg/katalog/children_gvr.go

pkg/katalog/conversion_registry.go

pkg/katalog/deletion_protection.go

Deletion protection — webhook rules and protected CRD name resolution.

Architecture: two-level filtering. 

Level 1 — Webhook rules (DeletionProtectionGVRs):
  Intercepts ALL DELETE on customresourcedefinitions and Orkestra deployments.
  Must be broad — Kubernetes webhook rules filter by GVR, not by object name.

Level 2 — Handler (isProtectedCRD):
  Narrows to only the CRDs managed by THIS Katalog.
  "websites.demo.orkestra.io" from a different operator → allowed.
  "cronjobs.demo.orkestra.io" from this Katalog → denied.

When to register the webhook: 

Requires a reachable Kubernetes Service. With ork run the operator runs
locally — there is no Service. failurePolicy: Fail would block ALL CRD
deletions when unreachable. Only register when running inside the cluster.

pkg/katalog/dependencies.go

pkg/katalog/enrichment.go

pkg/katalog/motif_imports.go

Expands imports: blocks at the CRD level (spec.crds[].imports). Each import loads the referenced Motif, binds its inputs from with:, and merges the expanded resources, status, and admission rules into the CRD.

pkg/katalog/motif_validate.go

pkg/katalog/parsek.go

pkg/katalog/security.go

Security accessors on *Katalog.

Precedence (highest → lowest):

  1. Katalog YAML (k.Security)
  2. ENV vars via SecurityConfig (k.konfig.Security())
  3. Hard defaults coded below

KatalogSecurity uses *bool fields which allows detecting "not declared" (nil) vs "explicitly false" (*false).

Deletion protection is ENABLED BY DEFAULT when the security block is present but deletionProtection is not declared.

pkg/katalog/serialize.go

Index

Constants

This section is empty.

Variables

View Source 
var (
	DeploymentGVR              = gvrOrPanic("deployment")
	ServiceGVR                 = gvrOrPanic("service")
	SecretGVR                  = gvrOrPanic("secret")
	ConfigMapGVR               = gvrOrPanic("configmap")
	JobGVR                     = gvrOrPanic("job")
	CronJobGVR                 = gvrOrPanic("cronjob")
	PodGVR                     = gvrOrPanic("pod")
	ServiceAccountGVR          = gvrOrPanic("serviceaccount")
	StatefulSetGVR             = gvrOrPanic("statefulset")
	IngressGVR                 = gvrOrPanic("ingress")
	PersistentVolumeClaimGVR   = gvrOrPanic("persistentvolumeclaim")
	PersistentVolumeGVR        = gvrOrPanic("persistentvolume")
	HorizontalPodAutoscalerGVR = gvrOrPanic("horizontalpodautoscaler")
	PodDisruptionBudgetGVR     = gvrOrPanic("poddisruptionbudget")
	DaemonSetGVR               = gvrOrPanic("daemonset")
	ReplicaSetGVR              = gvrOrPanic("replicaset")
	NetworkPolicyGVR           = gvrOrPanic("networkpolicy")
	RoleGVR                    = gvrOrPanic("role")
	RoleBindingGVR             = gvrOrPanic("rolebinding")
	ClusterRoleGVR             = gvrOrPanic("clusterrole")
	ClusterRoleBindingGVR      = gvrOrPanic("clusterrolebinding")
	NamespaceGVR               = gvrOrPanic("namespace")
	NodeGVR                    = gvrOrPanic("node")
	EndpointSliceGVR           = gvrOrPanic("endpointslice")
)

Functions

func AllBuiltInKinds 

func AllBuiltInKinds() []string

AllBuiltInKinds returns all canonical Kind names, sorted alphabetically.

func ApplyAutoscalerProfile 

func ApplyAutoscalerProfile(profile string, b orktypes.AutoscaleBaseline) (*orktypes.AutoscaleSpec, error)

ApplyAutoscalerProfile expands a named autoscale profile into a complete AutoscaleSpec using the CRD's declared baseline values.

This runs BEFORE merge, so the runtime only ever sees a fully-formed spec.

func ApplyResourceProfile added in v0.3.8 

func ApplyResourceProfile(profile string) (*orktypes.ResourceRequirements, error)

func ChildGVRs added in v0.2.3 

func ChildGVRs() []struct {
	GVR schema.GroupVersionResource
	Key string
}

ChildGVRs returns all built‑in child resource GVRs with their keys.

func DetectCyclesForTest 

func DetectCyclesForTest(k *Katalog) error

DetectCyclesForTest exposes detectDependencyCycles for integration tests.

func EnrichCRDEntry 

func EnrichCRDEntry(entry *orktypes.CRDEntry) (orktypes.EnrichmentOutcome, error)

EnrichCRDEntry checks whether a CRD entry uses kind-only declaration and, if so, enriches it with the corresponding built-in API metadata.

Called during Katalog validation before the CRD entry is used at runtime.

A CRD entry qualifies for enrichment when:

  • apiTypes.kind is set
  • apiTypes.group is empty
  • apiTypes.version is empty
  • apiTypes.plural is empty

All three must be empty for enrichment to trigger — a partially-specified entry (e.g. kind + group but no version) is an error, not an enrichment candidate. This prevents silent misconfigurations.

Returns:

  • EnrichmentNotNeeded: entry was already fully specified, no change
  • EnrichmentApplied: entry was enriched successfully
  • EnrichmentFailed: kind not found in built-in registry, error returned

func GVRForBuiltIn added in v0.1.9 

func GVRForBuiltIn(kind string) (schema.GroupVersionResource, bool)

GVRForBuiltIn returns the GroupVersionResource for a built-in kind.

func IsBuiltIn 

func IsBuiltIn(kind string) bool

IsBuiltIn reports whether kind is a known Kubernetes built-in (case-insensitive).

func NewSchemeRegistry 

func NewSchemeRegistry(k *Katalog) (*runtime.Scheme, error)

NewSchemeRegistry returns a new scheme

func ResolveCRDFiles added in v0.4.8 

func ResolveCRDFiles(path string) ([]byte, error)

ResolveCRDFiles reads the katalog YAML at path, resolves every crdFile reference to inline apiTypes, removes the crdFile key, and returns the rewritten YAML. The result is safe to embed in a bundle ConfigMap — the Orkestra runtime receives concrete apiTypes and never needs to read the file.

func SkipObservedGenerationGVKs 

func SkipObservedGenerationGVKs() []string

func SkipStatusSubresourceGVKs 

func SkipStatusSubresourceGVKs() []string

func StatuslessGVKs 

func StatuslessGVKs() []string

func ValidateCustomResource added in v0.4.6 

func ValidateCustomResource(cr *orktypes.CustomResourceTemplateSource, path string) error

ValidateCustomResource validates a single CustomResource declaration. It enforces the structural and semantic rules required by Orkestra while intentionally avoiding CRD schema validation (the API server owns that).

Validation responsibilities:

  • Ensure required top-level fields (apiVersion, kind) are present and well-formed.
  • Ensure metadata.name is present after templating.
  • Enforce namespaced vs cluster-scoped semantics using Metadata.Namespaced with a defensive default of namespaced=true.
  • Validate labels and annotations using existing validators.
  • Validate template syntax for spec/status/other fields (no structural schema).
  • Validate hasStatus semantics and warn when user-provided status will be ignored.
  • Return path-aware errors so callers can point users to the exact declaration.

Note: This function assumes the following helpers exist in the package or elsewhere in the codebase and will be used here:

  • isValidKind(kind string) bool
  • validateLabels(labels map[string]string) error
  • validateAnnotations(annotations map[string]string) error
  • validateTemplateFields(obj map[string]any, path string) error

The `path` parameter should identify the declaration location (e.g. "mycrd.onCreate.custom[0]") and is used to produce clear error messages.

Types

type AdmissionRegistry 

type AdmissionRegistry interface {
	// GetValidationRules returns the validation config for a GVR key.
	// Returns nil when no rules are registered for that resource.
	GetValidationRules(gvrKey string) *orktypes.ValidationConfig

	// GetMutationRules returns the mutation config for a GVR key.
	// Returns nil when no rules are registered for that resource.
	GetMutationRules(gvrKey string) *orktypes.MutationConfig

	// RegisterValidationRules stores validation rules for a GVR key.
	RegisterValidationRules(gvrKey string, cfg *orktypes.ValidationConfig)

	// RegisterMutationRules stores mutation rules for a GVR key.
	RegisterMutationRules(gvrKey string, cfg *orktypes.MutationConfig)

	// ValidationGVRs returns all GVR keys that have validation rules.
	// Used at startup to build the ValidatingWebhookConfiguration rules.
	ValidationGVRs() []GVREntry

	// MutationGVRs returns all GVR keys that have mutation rules.
	// Used at startup to build the MutatingWebhookConfiguration rules.
	MutationGVRs() []GVREntry
}

AdmissionRegistry is the interface used by the health server's admission handlers.

type AutoscaleProfile 

type AutoscaleProfile string
const (
	AutoscaleBurst            AutoscaleProfile = "burst"
	AutoscaleSteady           AutoscaleProfile = "steady"
	AutoscaleBatch            AutoscaleProfile = "batch"
	AutoscaleLatencySensitive AutoscaleProfile = "latency-sensitive"
	AutoscaleCostOptimized    AutoscaleProfile = "cost-optimized"
)

type BuiltInKind 

type BuiltInKind struct {
	Kind    string // PascalCase Kind name (e.g. "Deployment")
	Group   string // API group; empty string for core
	Version string // API version (e.g. "v1", "v2")
	Plural  string // plural resource name (e.g. "deployments")

	Namespaced bool   // true if resource is namespaced
	APIPath    string // "/api" for core, "/apis" otherwise

	// Shorthands are case-insensitive aliases resolved by LookupBuiltIn.
	// e.g. "hpa" → "horizontalpodautoscaler"
	Shorthands []string

	// Detect reports whether a CRD's operatorBox uses this resource in any
	// hook template block (onCreate / onReconcile / onDelete).
	// nil for resources that cannot appear in hook templates (e.g. Node, Event).
	Detect func(crd orktypes.CRDEntry) bool

	Statusless             bool // No meaningful status; treat as ready on existence
	SkipStatusSubresource  bool // No /status subresource; never PATCH status
	SkipObservedGeneration bool // Has status but no observedGeneration; skip generation check
	IsChild                bool // Orkestra may create this as a child resource
	OrkestraInternal       bool // Part of Orkestra's own control-plane installation
}

BuiltInKind holds the fully-qualified API metadata for a Kubernetes built-in resource kind, plus Orkestra-specific readiness and usage metadata.

func BuiltInMeta 

func BuiltInMeta(kind string) BuiltInKind

BuiltInMeta returns metadata for a built-in kind. Zero value when unknown.

type ConversionRegistry 

type ConversionRegistry interface {
	GetConversionRules(kind string) *orktypes.ConversionRules
	RegisterConversionRules(rules *orktypes.ConversionRules)
}

ConversionRegistry is the interface used by the health server's /convert handler. Decoupled from the Katalog struct so the health server has no import cycle.

type DependencyGraph 

type DependencyGraph struct {
	// contains filtered or unexported fields
}

DependencyGraph represents the CRD dependency DAG for a Katalog. Each CRD is a node, and edges represent "A must start before B" relationships.

The graph is used to:

  • compute deterministic startup order (topological sort)
  • compute deterministic shutdown order (reverse topological sort)
  • validate dependency correctness (no cycles, no missing CRDs)
  • expose dependency metadata to the runtime

The graph is immutable after construction.

func NewDependencyGraph 

func NewDependencyGraph(katalog *Katalog) *DependencyGraph

NewDependencyGraph constructs the dependency DAG for all enabled CRDs. It validates that all declared dependencies exist and builds the adjacency lists.

func (*DependencyGraph) GetDependencies 

func (g *DependencyGraph) GetDependencies(name string) []string

GetDependencies returns all CRDs that the given CRD depends on.

func (*DependencyGraph) GetDependents 

func (g *DependencyGraph) GetDependents(name string) []string

GetDependents returns all CRDs that depend on the given CRD.

func (*DependencyGraph) GetEdges 

func (g *DependencyGraph) GetEdges() map[string][]string

GetEdges returns the adjacency list: dependency → dependents.

func (*DependencyGraph) GetInDegree 

func (g *DependencyGraph) GetInDegree(name string) int

GetInDegree returns how many CRDs this CRD depends on.

func (*DependencyGraph) GetNode 

func (g *DependencyGraph) GetNode(name string) *Node

GetNode returns the node for a CRD name.

func (*DependencyGraph) GetNodes 

func (g *DependencyGraph) GetNodes() map[string]*Node

GetNodes returns all nodes in the graph.

func (*DependencyGraph) GetOutDegree 

func (g *DependencyGraph) GetOutDegree(name string) int

GetOutDegree returns how many CRDs depend on this CRD.

func (*DependencyGraph) ShutdownOrder 

func (g *DependencyGraph) ShutdownOrder() []string

ShutdownOrder returns the reverse of the startup order. This ensures CRDs are stopped only after all dependents have been drained.

func (*DependencyGraph) StartupOrder 

func (g *DependencyGraph) StartupOrder() []string

StartupOrder returns a deterministic topological ordering of CRDs. CRDs with no dependencies appear first; dependents appear after their prerequisites.

This order is used by the runtime to start CRDs in the correct sequence.

The result is cached and computed only once.

func (*DependencyGraph) Validate 

func (g *DependencyGraph) Validate() error

Validate performs basic sanity checks on the graph.

type EnrichmentResult 

type EnrichmentResult struct {
	Found        bool
	Kind         string
	BuiltIn      BuiltInKind
	DisplayGroup string
}

EnrichmentResult holds the result of a built-in lookup.

func LookupBuiltIn 

func LookupBuiltIn(kind string) EnrichmentResult

LookupBuiltIn looks up a Kind in the built-in registry. Case-insensitive. Expands shorthands (e.g. "hpa" → "horizontalpodautoscaler").

type GVREntry 

type GVREntry struct {
	// Key — the full GVR key string: "group/version/resource" or "version/resource"
	Key string

	// Group — API group. Empty for core group resources.
	Group string

	// Version — API version.
	Version string

	// Resource — plural resource name.
	Resource string

	// Operations — which operations this GVR should be webhoooked for.
	// Comes from AdmissionWebhookConfig.Operations or the default ["CREATE", "UPDATE"]
	Operations []string
}

GVREntry holds the parsed GVR components for webhook configuration. Built from the key during registry population.

func OrkestraInternalGVRs added in v0.1.8 

func OrkestraInternalGVRs() []GVREntry

OrkestraInternalGVRs returns GVRs for Orkestra's own control-plane resources. Used by the deletion-protection webhook.

type InMemoryAdmissionRegistry 

type InMemoryAdmissionRegistry struct {
	// contains filtered or unexported fields
}

InMemoryAdmissionRegistry is the concrete implementation used at runtime. Safe for concurrent use — the /validate and /mutate handlers read from it concurrently; the Katalog load writes to it once at startup.

func NewInMemoryAdmissionRegistry 

func NewInMemoryAdmissionRegistry() *InMemoryAdmissionRegistry

NewInMemoryAdmissionRegistry returns an initialised registry.

func (*InMemoryAdmissionRegistry) AddMutationGVR added in v0.3.1 

func (r *InMemoryAdmissionRegistry) AddMutationGVR(entry GVREntry, cfg *orktypes.MutationConfig)

AddMutationGVR registers both mutation rules and the GVR entry so that MutationGVRs() returns the entry. Used in tests and tooling.

func (*InMemoryAdmissionRegistry) AddValidationGVR added in v0.3.1 

func (r *InMemoryAdmissionRegistry) AddValidationGVR(entry GVREntry, cfg *orktypes.ValidationConfig)

AddValidationGVR registers both validation rules and the GVR entry so that ValidationGVRs() returns the entry. Used in tests and tooling.

func (*InMemoryAdmissionRegistry) GetMutationRules 

func (r *InMemoryAdmissionRegistry) GetMutationRules(gvrKey string) *orktypes.MutationConfig

func (*InMemoryAdmissionRegistry) GetValidationRules 

func (r *InMemoryAdmissionRegistry) GetValidationRules(gvrKey string) *orktypes.ValidationConfig

func (*InMemoryAdmissionRegistry) MutationGVRs 

func (r *InMemoryAdmissionRegistry) MutationGVRs() []GVREntry

func (*InMemoryAdmissionRegistry) RegisterMutationRules 

func (r *InMemoryAdmissionRegistry) RegisterMutationRules(gvrKey string, cfg *orktypes.MutationConfig)

func (*InMemoryAdmissionRegistry) RegisterValidationRules 

func (r *InMemoryAdmissionRegistry) RegisterValidationRules(gvrKey string, cfg *orktypes.ValidationConfig)

func (*InMemoryAdmissionRegistry) ValidationGVRs 

func (r *InMemoryAdmissionRegistry) ValidationGVRs() []GVREntry

type InMemoryConversionRegistry 

type InMemoryConversionRegistry struct {
	// contains filtered or unexported fields
}

InMemoryConversionRegistry holds per-Kind conversion rules. Safe for concurrent use — the /convert endpoint reads from multiple goroutines and Katalog load writes once at startup.

func NewInMemoryConversionRegistry 

func NewInMemoryConversionRegistry() *InMemoryConversionRegistry

NewInMemoryConversionRegistry returns an initialised registry.

func NewInMemoryRegistryForTest 

func NewInMemoryRegistryForTest() *InMemoryConversionRegistry

Test exports

func (*InMemoryConversionRegistry) GetConversionRules 

func (r *InMemoryConversionRegistry) GetConversionRules(kind string) *orktypes.ConversionRules

GetConversionRules returns the rules for a given Kind. Returns nil when no rules are registered for that Kind.

func (*InMemoryConversionRegistry) RegisterConversionRules 

func (r *InMemoryConversionRegistry) RegisterConversionRules(rules *orktypes.ConversionRules)

RegisterConversionRules stores rules for the Kind declared in rules.Kind. Called once per CRD entry during Katalog load.

type Katalog 

type Katalog struct {
	APIVersion   string                                `yaml:"apiVersion"`
	Kind         string                                `yaml:"kind"`
	Spec         orktypes.KatalogSpec                  `yaml:"spec"`
	Security     orktypes.KatalogSecurity              `yaml:"security"`
	Notification *orktypes.KatalogNotification         `yaml:"notification,omitempty"`
	Providers    []orktypes.KatalogProviderRequirement `yaml:"providers,omitempty"`

	KomposerMetadata orktypes.KatalogMeta `yaml:"metadata"`

	// AutogeneratedCerts is updated when internal.ensure security generates a certificate
	// Useful in deciding whether to generate RBAC needed to patch CRD or not
	AutogeneratedCerts atomic.Bool `yaml:"autogeneratedCerts,omitempty" json:"autogeneratedCerts,omitempty"`
	// contains filtered or unexported fields
}

----------------------------------------------------------------------------- Structs -----------------------------------------------------------------------------

func BuildExpanded added in v0.4.8 

func BuildExpanded(kfg *konfig.Konfig, m *merger.Merger) (*Katalog, error)

BuildExpanded is the canonical pipeline for CLI commands that need a fully ready Katalog: merge → expand motifs → validate.

Use this instead of calling KomposeRuntimeKatalog + ValidateConfig separately. For the rare case where validation must be skipped (e.g. ork template --no-validate), call KomposeRuntimeKatalog directly.

func NewEmptyKatalog 

func NewEmptyKatalog() *Katalog

Empty katalog for testing

func NewKatalog 

func NewKatalog(kfg *konfig.Konfig, m *merger.Merger) *Katalog

NewKatalog returns a list of CRD data

func NewKatalogForTest 

func NewKatalogForTest(crds map[string]orktypes.CRDEntry) *Katalog

NewKatalogForTest creates a Katalog with pre-set enabledCRDs for testing. Bypasses YAML parsing and ValidateConfig so tests can construct controlled graphs.

func ParseBytes added in v0.4.8 

func ParseBytes(data []byte, dir string) (*Katalog, error)

ParseBytes loads and enriches a Katalog from raw YAML bytes. dir is used as the base directory for resolving relative paths (e.g. crdFile). Pass "." when no specific directory context is available.

func ParseFile added in v0.4.8 

func ParseFile(path string) (*Katalog, error)

ParseFile loads and enriches a Katalog from a single YAML file path. Uses a default konfig — suitable for CLI tools (plan, simulate) that do not need the full operator runtime.

func (*Katalog) AdmissionRegistry 

func (k *Katalog) AdmissionRegistry() AdmissionRegistry

func (*Katalog) All 

func (k *Katalog) All() map[string]orktypes.CRDEntry

All returns every CRD in the katalog, including disabled ones.

func (*Katalog) AllCRDs 

func (k *Katalog) AllCRDs() map[string]orktypes.CRDEntry

AllCRDs returns all CRDs including disabled ones (from Spec).

func (*Katalog) CRDEntry added in v0.4.8 

func (k *Katalog) CRDEntry(name string) (orktypes.CRDEntry, bool)

CRDEntry returns the enabled CRD entry for the given name.

func (*Katalog) CRDNames 

func (k *Katalog) CRDNames() []string

CRDNames returns the names of all enabled CRDs.

func (*Katalog) Controllers 

func (k *Katalog) Controllers() []string

Controllers returns a list of CRDs that have reconcilers.

func (*Katalog) ConversionRegistry 

func (k *Katalog) ConversionRegistry() ConversionRegistry

func (*Katalog) ConversionWindow 

func (k *Katalog) ConversionWindow() int

ConversionWindow returns the effective rolling window size for conversion/admission stats.

Precedence: 

YAML security.conversion.conversionWindow > 0 → use YAML value
YAML absent or zero                           → fall back to CONVERSION_WINDOW env

func (*Katalog) DebugKatalogInformation added in v0.1.8 

func (k *Katalog) DebugKatalogInformation()

Debug katalog information from merger

func (*Katalog) DeletionProtectedCRDNames added in v0.1.9 

func (k *Katalog) DeletionProtectedCRDNames() map[string]struct{}

DeletionProtectedCRDNames returns the set of CRD full names managed by this Katalog. e.g. {"cronjobs.demo.orkestra.io": {}} Used by the /deletion-protection handler for name-based filtering. A CRD not in this set is allowed through even though the webhook intercepted it. When running outside the cluster (e.g. `ork run`), the webhook cannot be reached, so no protection is guaranteed.

func (*Katalog) DeletionProtectionCleanupOnShutdown 

func (k *Katalog) DeletionProtectionCleanupOnShutdown() bool

DeletionProtectionCleanupOnShutdown reports whether Deletion Protection should be deleted on shutdown.

Precedence: 

YAML security.deletionProtection.cleanupOnShutdown present → use YAML value
YAML block absent                                      → fall back to DELETION_PROTECTION_CLEANUP_ON_SHUTDOWN env

func (*Katalog) DeletionProtectionFailurePolicy 

func (k *Katalog) DeletionProtectionFailurePolicy() string

DeletionProtectionFailurePolicy returns the effective failure policy string. YAML value takes precedence over ENV.

func (*Katalog) DeletionProtectionGVRs 

func (k *Katalog) DeletionProtectionGVRs() []GVREntry

DeletionProtectionGVRs returns the list of GVRs that the deletion‑protection admission webhook should intercept.

This includes:

  • CRDs managed by this Katalog (broad match; handler filters by name)
  • Orkestra’s own admission webhooks (validating + mutating)
  • Orkestra’s internal control‑plane resources (deployment, service, serviceaccount, configmap, RBAC objects, ingress, etc.)

The internal resources are derived from the built‑ins registry via OrkestraInternalGVRs(), ensuring the list is declarative and maintained in a single place.

When running outside the cluster (e.g. `ork run`), the webhook cannot be reached, so no rules are returned.

func (*Katalog) DeletionProtectionServiceName 

func (k *Katalog) DeletionProtectionServiceName() string

DeletionProtectionServiceName returns the effective service name for deletion protection. YAML value takes precedence over ENV.

func (*Katalog) Dependents 

func (k *Katalog) Dependents(name string) []string

Dependents returns all CRDs that depend on the given CRD.

func (*Katalog) Depends 

func (k *Katalog) Depends(crdName, target string) bool

Depends returns true if crdName depends on target.

func (*Katalog) Describe 

func (k *Katalog) Describe(name string) (string, error)

Describe returns a human‑readable summary of a CRD.

func (*Katalog) Enabled 

func (k *Katalog) Enabled() map[string]orktypes.CRDEntry

Enabled returns only the enabled CRDs in the katalog.

func (*Katalog) EnabledCRDs 

func (k *Katalog) EnabledCRDs() map[string]orktypes.CRDEntry

EnabledCRDs returns a map of enabled CRDs.

func (*Katalog) Exists 

func (k *Katalog) Exists(name string) bool

Exists returns true if a CRD with the given name exists in the katalog.

func (*Katalog) Explain 

func (k *Katalog) Explain(name string) (string, error)

Explain returns a technical explanation of how Orkestra handles this CRD.

func (*Katalog) GenerateRBACRules 

func (k *Katalog) GenerateRBACRules() []rbacv1.PolicyRule

func (*Katalog) Get 

func (k *Katalog) Get(name string) (*orktypes.CRDEntry, error)

Get returns an enabled CRD by name.

func (*Katalog) Graph 

func (k *Katalog) Graph() map[string][]string

Graph returns a map of CRD name → dependency names.

func (*Katalog) HasConversionPaths 

func (k *Katalog) HasConversionPaths() bool

HasConversionPaths returns true only if conversion is enabled and at least one CRD declares conversion paths.

func (*Katalog) HasMutationRules 

func (k *Katalog) HasMutationRules() bool

HasMutationRules returns true if admission is enabled and at least one CRD declares mutation rules.

func (*Katalog) HasNotification added in v0.1.9 

func (k *Katalog) HasNotification() bool

HasNotification returns whether a katalog has notification configured or not

func (*Katalog) HasTeams 

func (k *Katalog) HasTeams() bool

HasTeams returns whether a katalog has teams configured or not

func (*Katalog) HasValidationOrMutationRules added in v0.1.8 

func (k *Katalog) HasValidationOrMutationRules() bool

HasValidationOrMutationRules returns true if any CRD has validation or mutation rules.

func (*Katalog) HasValidationRules 

func (k *Katalog) HasValidationRules() bool

HasValidationRules returns true if admission is enabled and at least one CRD declares validation rules.

func (*Katalog) IsAdmissionEnabled 

func (k *Katalog) IsAdmissionEnabled() bool

IsAdmissionEnabled reports whether admission webhooks are globally enabled.

Precedence: 

YAML security.webhooks.admission block present → use YAML value
YAML block absent                              → fall back to ENABLE_ADMISSION_WEBHOOK env

func (*Katalog) IsConversionEnabled 

func (k *Katalog) IsConversionEnabled() bool

IsConversionEnabled reports whether the conversion webhook is globally enabled.

Precedence: 

YAML security.conversion block present → use YAML value
YAML block absent                      → fall back to ENABLE_CONVERSION env

func (*Katalog) IsDeletionProtectionEnabled 

func (k *Katalog) IsDeletionProtectionEnabled() bool

IsDeletionProtectionEnabled reports whether deletion protection is active.

Precedence: 

YAML security.deletionProtection block present → use YAML value (default-on when block declared)
YAML block absent                              → fall back to ENABLE_DELETION_PROTECTION env

func (*Katalog) IsEmailNotificationEnabled 

func (k *Katalog) IsEmailNotificationEnabled() bool

IsEmailNotificationEnabled reports whether email notifications are possible.

Precedence: 

YAML team.email present → require SMTP env capability
YAML absent             → no email notifications

func (*Katalog) IsNamespaceProtectionEnabled added in v0.1.9 

func (k *Katalog) IsNamespaceProtectionEnabled() bool

IsNamespaceProtectionEnabled reports whether namespace protection is active.

Precedence: 

YAML security.namespaceProtection block present → use YAML value (default-on when block declared)
YAML block absent                               → fall back to ENABLE_NAMESPACE_PROTECTION env

func (*Katalog) IsSlackNotificationEnabled 

func (k *Katalog) IsSlackNotificationEnabled() bool

IsSlackNotificationEnabled reports whether Slack notifications are possible.

func (*Katalog) IsStrictModeEnabled added in v0.4.8 

func (k *Katalog) IsStrictModeEnabled() bool

IsStrictModeEnabled reports whether strict mode is active for deletion protection. Strict mode treats removal of the deletion-protection label as a deletion attempt. Only valid when deletion protection is also enabled.

func (*Katalog) IsWebhookControllerEnabled added in v0.1.9 

func (k *Katalog) IsWebhookControllerEnabled() bool

IsWebhookControllerEnabled reports whether the webhook controller is enabled.

func (*Katalog) KomposeRuntimeKatalog added in v0.3.1 

func (k *Katalog) KomposeRuntimeKatalog(kfg *konfig.Konfig, m *merger.Merger, paths ...string) (map[string]orktypes.CRDEntry, error)

func (*Katalog) List 

func (k *Katalog) List() map[string]orktypes.CRDEntry

func (*Katalog) Meta 

func (k *Katalog) Meta() orktypes.KatalogMeta

Useful Metadata

func (*Katalog) Metadata 

func (k *Katalog) Metadata() orktypes.KatalogMeta

func (*Katalog) NamespaceProtectionCleanupOnShutdown added in v0.1.9 

func (k *Katalog) NamespaceProtectionCleanupOnShutdown() bool

NamespaceProtectionCleanupOnShutdown reports whether Deletion Protection should be deleted on shutdown.

Precedence: 

YAML security.namespaceProtection.cleanupOnShutdown present → use YAML value
YAML block absent                                      → fall back to NAMESPACE_PROTECTION_CLEANUP_ON_SHUTDOWN env

func (*Katalog) NamespaceProtectionFailurePolicy added in v0.1.9 

func (k *Katalog) NamespaceProtectionFailurePolicy() string

NamespaceProtectionFailurePolicy returns the effective failure policy string. YAML value takes precedence over ENV.

func (*Katalog) NamespaceProtectionGVRs added in v0.1.9 

func (k *Katalog) NamespaceProtectionGVRs() []GVREntry

NamespaceProtectionGVRs returns the list of GVRs for CRDs that declare allowedNamespaces or restrictedNamespaces. Only these CRDs are intercepted by the namespace-protection webhook.

When running outside the cluster (e.g. `ork run`), the webhook cannot be reached, so no rules are returned.

func (*Katalog) NamespaceProtectionRuleMap added in v0.1.9 

func (k *Katalog) NamespaceProtectionRuleMap() map[string]NamespaceRuleEntry

NamespaceProtectionRuleMap returns the allowed/restricted namespace lists for every CRD that declares namespace rules. Key format is "plural.group" — matching the lookup key used by the /namespace-protection handler.

Returns nil when namespace protection is disabled.

func (*Katalog) NamespaceProtectionServiceName added in v0.1.9 

func (k *Katalog) NamespaceProtectionServiceName() string

NamespaceProtectionServiceName returns the effective service name for namespace protection. YAML value takes precedence over ENV.

func (*Katalog) NeedsCertificates 

func (k *Katalog) NeedsCertificates() bool

NeedsCertificates reports whether Orkestra must generate TLS certificates.

Certificates are required when deletion protection, admission webhooks, or conversion webhooks are enabled with valid usecases configured in at least 1 CRD— all three use the same TLS cert.

func (*Katalog) NotificationInterval 

func (k *Katalog) NotificationInterval(teamName string) orktypes.Duration

NotificationInterval returns the effective interval for a team.

Precedence: 

YAML team.interval > YAML defaults.interval > ENV defaultInterval > hard default

func (*Katalog) Order 

func (k *Katalog) Order() []string

Order returns CRDs in dependency‑safe order (topological sort).

func (*Katalog) OrkestraServiceName added in v0.2.5 

func (k *Katalog) OrkestraServiceName() string

Orkestra Service Name returns the effective service name for orkestra. YAML value takes precedence over ENV.

func (*Katalog) ProjectInfo added in v0.3.9 

func (k *Katalog) ProjectInfo() orktypes.ProjectInfo

ProjectInfo returns the project information for use by control center This is mostly helpful in actions performed by 'ork doctor'

func (*Katalog) Projects added in v0.4.2 

func (k *Katalog) Projects() map[string]orktypes.ProjectInfo

Projects returns the map of all project infos from the katalog metadata. Populated by the developer path (createdBy: orkdoctor) via ork doctor deploy.

func (*Katalog) ResolveGVR added in v0.4.1 

func (k *Katalog) ResolveGVR(r orktypes.ManagedResource) (schema.GroupVersionResource, bool)

ResolveGVR resolves a ManagedResource into a concrete GroupVersionResource.

Resolution priority (explicit always wins):

  1. Full explicit GVR: - group + version + plural are all provided → use them directly.

  2. Explicit group + version (plural omitted) → infer plural as strings.ToLower(kind) + "s".

  3. APIVersion + plural: - apiVersion: "group/version" - plural provided → parse apiVersion and use provided plural.

  4. APIVersion only: - apiVersion: "group/version" - plural omitted → parse apiVersion and infer plural as strings.ToLower(kind) + "s".

  5. Built‑in Kubernetes resource: - kind matches Orkestra's built‑in registry → use GVRForBuiltIn(kind).

  6. Otherwise: → resolution fails and (GVR{}, false) is returned.

This ensures:

  • Explicit declarations always override inference.
  • Custom resources can be fully specified without guessing.
  • Built‑ins remain simple (kind‑only).
  • RBAC generation remains deterministic and zero‑footprint safe.

func (*Katalog) SMTPConfig 

func (k *Katalog) SMTPConfig() (host string, port int, user, pass, from string)

SMTPConfig returns the effective SMTP configuration (from ENV only).

func (*Katalog) Scheme added in v0.4.8 

func (k *Katalog) Scheme() (*runtime.Scheme, error)

Scheme builds and returns a runtime.Scheme with all Katalog types registered.

func (*Katalog) SerializeExpanded added in v0.4.8 

func (k *Katalog) SerializeExpanded() ([]byte, error)

SerializeExpanded serializes the post-KomposeRuntimeKatalog state to YAML.

The output is a valid Katalog YAML with fully expanded CRDs (all motif imports already inlined, imports: field absent). This is what the bundle's ConfigMap should embed — the runtime can load it without any OCI pulls.

Must be called after KomposeRuntimeKatalog; returns an error if no CRDs are present (indicates expansion hasn't been run yet).

func (*Katalog) SlackWebhook 

func (k *Katalog) SlackWebhook() string

SlackWebhook returns the effective Slack webhook URL (from ENV only).

func (*Katalog) ToUI 

func (k *Katalog) ToUI() *orktypes.KatalogForUI

ToUI returns a UI-friendly representation of the merged Katalog. This method extracts only the fields needed for display in the Control Center:

  • API version and kind (always "Katalog" at runtime)
  • Metadata (name, description, version, author, license)
  • All merged CRD definitions

Internal fields (Scheme, GroupVersionKind, etc.) are excluded because they have `yaml:"-" json:"-"` tags and won't be serialized to JSON.

This method is used by the /katalog/raw endpoint to provide a clean, readable view of the Katalog that created the current operator.

func (*Katalog) Uses 

func (k *Katalog) Uses(resource string) bool

Uses reports whether any enabled CRD uses the given resource in a hook template block. Accepts both singular ("deployment") and plural ("deployments") keys, as well as shorthands ("hpa"). Drives off builtInRegistry — no separate table to maintain.

func (*Katalog) ValidateConfig 

func (k *Katalog) ValidateConfig(kfg *konfig.Konfig) (*Katalog, error)

Validate Config

func (*Katalog) WebhookCleanupOnShutdown 

func (k *Katalog) WebhookCleanupOnShutdown() bool

WebhookCleanupOnShutdown reports whether admission webhooks should be deleted on shutdown.

Precedence: 

YAML security.webhooks.cleanupOnShutdown present → use YAML value
YAML block absent                                → fall back to WEBHOOK_CLEANUP_ON_SHUTDOWN env

func (*Katalog) WebhookControllerSyncInterval added in v0.1.9 

func (k *Katalog) WebhookControllerSyncInterval() time.Duration

WebhookControllerSyncInterval returns the webhook controller sync interval.

func (*Katalog) WebhookResources added in v0.3.7 

func (k *Katalog) WebhookResources() []string

WebhookResources returns the list of admission webhook resources that Orkestra needs to manage when webhooks/certificates are required.

Rules:

  • validatingwebhookconfigurations is required for deletion protection, namespace protection, or any validation rules.
  • mutatingwebhookconfigurations is required only when mutation rules exist.
  • conversion webhooks are handled separately and do not require these resources.

func (*Katalog) WebhooksFailurePolicy 

func (k *Katalog) WebhooksFailurePolicy() string

WebhooksFailurePolicy returns the effective failure policy for admission webhooks. YAML value takes precedence over ENV.

func (*Katalog) WebhooksServiceName 

func (k *Katalog) WebhooksServiceName() string

WebhooksServiceName returns the effective service name for admission/conversion webhooks. YAML value takes precedence over ENV.

type MotifValidationError added in v0.3.9 

type MotifValidationError struct {
	Path    string
	Message string
}

MotifValidationError represents a single validation failure for a Motif.

func ValidateMotif added in v0.3.9 

func ValidateMotif(path string) []MotifValidationError

ValidateMotif validates a Motif YAML file at the given path. Returns a slice of errors — empty means valid.

func ValidateMotifImports added in v0.3.9 

func ValidateMotifImports(crdName string, imports []orktypes.MotifImport) []MotifValidationError

ValidateMotifImports validates that all imports in an operatorBox have required inputs provided in their with: block.

func (MotifValidationError) Error added in v0.3.9 

func (e MotifValidationError) Error() string

type NamespaceRuleEntry added in v0.1.9 

type NamespaceRuleEntry struct {
	Allowed    []string
	Restricted []string
}

NamespaceRuleEntry holds the raw allowed/restricted namespace lists for one CRD. Returned by NamespaceProtectionRuleMap so callers can build their own lookup structures.

type Node 

type Node struct {
	Name      string
	CRD       orktypes.CRDEntry
	InDegree  int // number of CRDs this CRD depends on
	OutDegree int // number of CRDs that depend on this CRD
}

Node represents a single CRD in the dependency graph.

type ProbeProfile added in v0.4.2 

type ProbeProfile string

ProbeProfile is a named set of probe timing parameters. 

const (
	// ProbeFast — quick detection, low tolerance. Good for HTTP APIs that
	// start quickly and should fail loud on the first real problem.
	// initialDelay: 5s, period: 10s, failureThreshold: 2
	ProbeFast ProbeProfile = "fast"

	// ProbeStandard — balanced defaults suitable for most web services.
	// initialDelay: 15s, period: 20s, failureThreshold: 3
	ProbeStandard ProbeProfile = "standard"

	// ProbePatient — tolerant of slow operations. Good for batch workers or
	// services with non-trivial startup that still finish within ~2 minutes.
	// initialDelay: 30s, period: 30s, failureThreshold: 5
	ProbePatient ProbeProfile = "patient"

	// ProbeSlowStart — 5-minute startup window, designed for startup probes on
	// JVM applications, databases, or other slow-initializing services.
	// initialDelay: 0s, period: 10s, failureThreshold: 30 (= 300s window)
	ProbeSlowStart ProbeProfile = "slow-start"
)

type ProfileConfig added in v0.4.4 

type ProfileConfig struct {
	QueueThresholdPct float64
	WorkerMultiplier  float64
	QueueMultiplier   float64
	Interval          time.Duration
	Cooldown          time.Duration
}

ProfileConfig defines the knobs for a single autoscale profile.

QueueThresholdPct: 

Percentage of maxQueueDepth at which scaling should trigger.
Example: 0.60 means "scale when queueDepth exceeds 60% of maxQueueDepth".

WorkerMultiplier: 

Multiplier applied to baseline workers to compute the override.

QueueMultiplier: 

Multiplier applied to baseline queueDepth to compute the override.

Interval / Cooldown: 

Default evaluation and cooldown windows for the profile.

type ResourceProfile added in v0.3.8 

type ResourceProfile string
const (
	ResourceTiny         ResourceProfile = "tiny"
	ResourceSmall        ResourceProfile = "small"
	ResourceMedium       ResourceProfile = "medium"
	ResourceLarge        ResourceProfile = "large"
	ResourceBurst        ResourceProfile = "burst"
	ResourceSteady       ResourceProfile = "steady"
	ResourceComputeHeavy ResourceProfile = "compute-heavy"
	ResourceMemoryHeavy  ResourceProfile = "memory-heavy"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.