README
¶
pkg/motif
The motif package loads, validates, and expands Motif YAML files. A Motif is a reusable infrastructure template — a named set of Kubernetes resources (StatefulSets, Services, PVCs, etc.) with declared inputs that callers bind when importing.
A Katalog imports a Motif instead of writing all stateful resource declarations by hand:
operatorBox:
imports:
- motif: postgres # load from registry or local file
with:
image: "{{ .data.postgresImage }}"
volumeSize: "{{ .data.postgresVolumeSize }}"
What lives here
| File | Role |
|---|---|
loader.go |
Load, LoadImport — read a Motif YAML from disk or registry; strict structural validation via utils.StrictUnmarshal |
expander.go |
Expand — bind inputs and render the Motif's resource templates into a HookTemplates value; MergeHookTemplates — merge expanded resources into an existing block |
Validation model
Motif YAML passes through two validation layers before any expansion runs:
- Structural (
loader.go) —utils.StrictUnmarshalrejects unknown fields.kind: Motifandmetadata.nameare required. - Semantic (
pkg/katalog/motif_validate.go) — duplicate input names,required+defaultconflict, missingresourcesblock, and unknown{{ inputs.* }}references are all errors.
See pkg/katalog/docs/06-motif-validation.md for the full validation pipeline.
Developer documentation
| I want to… | Go to |
|---|---|
| Understand the Motif YAML format and input system | docs/01-structure.md |
| Understand how Motifs are loaded and validated | docs/02-loading.md |
| Understand input binding and resource expansion | docs/03-expansion.md |
Documentation
¶
Overview ¶
pkg/motif/expander.go
Expander instantiates a Motif by binding its inputs and expanding its resource blocks into a concrete HookTemplates value.
Two modes:
Static (ork doctor init): inputs resolved from explicit with: bindings at generation time. The expanded resources are inlined into the generated Katalog. No runtime dependency on the Motif.
Dynamic (Katalog runtime): inputs resolved at Katalog startup, before any reconcile. The Motif is loaded once and its templates compiled with the input bindings.
pkg/motif/loader.go
Loads a Motif from a file path or registry reference.
Resolution mirrors RegistrySource in a Komposer exactly — the same four reference forms are supported:
motif: postgres # bare name → default motif registry (OCI) motif: oci://ghcr.io/orkspace/orkestra-motifs/postgres:v0.1.0 # oci:// prefix → OCI motif: ghcr.io/orkspace/orkestra-motifs/postgres@v0.1.0 # full OCI ref with oci: true motif: https://github.com/myorg/postgres-motif@main # git URL motif: ./motifs/postgres/motif.yaml # file path
Bare names and oci:// prefixes are auto-detected so oci: true is not required for those forms. For full OCI refs (host with dots), oci: true is still required — same as RegistrySource.
pkg/motif/pull.go
PullImport fetches a motif OCI artifact to the local registry cache. Used as the pre-pull step before validate, generate, or run commands.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Load ¶
Load loads a Motif from a local file path. For full import resolution (registry, OCI, auth), use LoadImport.
func LoadImport ¶
func LoadImport(imp *orktypes.MotifImport) (*orktypes.Motif, error)
LoadImport resolves and loads a Motif from a MotifImport declaration.
Resolution order:
- File path (starts with ./, ../, /, or ends with .yaml/.yml)
- oci:// prefix → OCI pull (auto-detected, oci: field not required)
- Bare name (no scheme, no dots in registry host) → resolved against the default motif registry (ORK_MOTIFS_REGISTRY or ghcr.io/orkspace/orkestra-motifs)
- Full OCI ref + oci: true → OCI pull (komposer-compatible form)
- Git URL (https://, http://, git@) → git pull
func PullImport ¶ added in v0.4.8
func PullImport(imp *orktypes.MotifImport) error
PullImport fetches a motif artifact into the registry cache (~/.orkestra/registry/...) so subsequent loads are served from disk. Non-OCI refs (file paths, git URLs) are silently skipped. Resolution mirrors LoadImport exactly, including bare-name → default registry expansion.
func ValidateMotifTemplates ¶
ValidateMotifTemplates checks that all inputs.X references in the resource YAML correspond to declared input names. Returns a list of error strings.
Types ¶
type ExpandedMotif ¶
type ExpandedMotif struct {
// Name is the motif's metadata.name, used in conflict error messages.
Name string
// OnCreate contains resources from resources.onCreate: — merged into the CRD's OnCreate phase.
OnCreate *orktypes.HookTemplates
// OnReconcile contains resources from the flat resources: fields — merged into OnReconcile.
OnReconcile *orktypes.HookTemplates
Status *orktypes.StatusConfig
Admission *orktypes.Admission
// Profiles carries user-defined profiles declared in the motif.
// Merged into the katalog's ProfileRegistry during expandMotifImports.
Profiles orktypes.ProfileRegistry
}
ExpandedMotif holds the result of expanding a motif.
func Expand ¶
Expand instantiates a Motif with the given input bindings and returns the expanded resources, status, and admission configuration.
bindings maps input name → resolved value. Required inputs missing from bindings are a validation error. Unknown inputs in bindings are also an error. Optional inputs not in bindings use their Motif-declared defaults.
Expand replaces all `{{ .inputs.Name }}` and `{{ inputs.Name }}` expressions in the YAML of resources, status, and admission with the resolved binding values. Other template expressions (e.g., `{{ .children.* }}`) are left untouched and will be evaluated at runtime by the reconciler.
func (*ExpandedMotif) HasAdmission ¶ added in v0.4.0
func (e *ExpandedMotif) HasAdmission() bool
HasAdmission reports whether the motif includes admission rules.
func (*ExpandedMotif) HasResources ¶ added in v0.4.0
func (e *ExpandedMotif) HasResources() bool
HasResources returns true when the motif produced any resource templates.
func (*ExpandedMotif) HasStatus ¶ added in v0.4.0
func (e *ExpandedMotif) HasStatus() bool
HasStatus reports whether the motif defines status fields or conditions.
Source Files