Documentation
¶
Overview ¶
pkg/generat/crd_generator.go
CRD generator — derives a CustomResourceDefinition from a Katalog.
The Katalog is the single source of truth. Everything needed to produce a valid CRD is already declared:
apiTypes → group, version, kind, plural, scope
validation → required fields (deny rules with operator: exists)
mutation → optional fields with defaults + type inference
template exprs → additional spec fields referenced as {{ .spec.* }}
status.fields → status subresource schema + printer columns
conversion → webhook config (when conversion paths are declared)
Usage:
gen := generator.NewCRDGenerator(katalogEntry) crd, err := gen.Generate() yaml.NewEncoder(os.Stdout).Encode(crd)
CLI:
ork generate crd --katalog katalog.yaml -o crd.yaml
pkg/generate/helper.go
pkg/generate/katalog_generator.go
KatalogScaffold generates a starter katalog.yaml for a new operator.
Three reconcile modes:
dynamic (default) — operatorBox.default: true; commented onCreate / onReconcile / onDelete
template blocks are included so the user can see the available structure.
typed + hooks — mode: typed, commented hooks declaration, default: true.
The user writes a Go hook function and registers it in the Katalog.
typed + constructor — mode: typed, operatorBox.default: false, commented constructor.
The user owns the entire reconcile loop; Orkestra calls their constructor.
Optional sections (security, notification, providers) are injected after the metadata block when the corresponding flag is set. They are independent of the reconcile mode and may be combined freely.
The generated file is pure YAML — all conditional logic is resolved at generation time by the Go template. No template syntax leaks into the output.
pkg/generate/registry_generator.go
Index ¶
- Constants
- func ConfigMap(inputFile, namespace, outputFile string) ([]byte, error)
- func Dashboards(c []orktypes.CRDEntry, dryRun bool) error
- func Docs(c []orktypes.CRDEntry, dryRun bool) error
- func KatalogScaffold(opts KatalogScaffoldOptions) (string, error)
- func RBAC(kfg *konfig.Konfig, rules []rbacv1.PolicyRule, namespace, outputFile string) ([]byte, error)
- func RenderBundle(kfg *konfig.Konfig, rules []rbacv1.PolicyRule, ...) (string, error)
- func Runtime(m *merger.Merger, dryRun bool) error
- type CRDGenerator
- type CRDMeta
- type CRGenerator
- type DashboardTemplateData
- type DocsTemplateData
- type KatalogScaffoldOptions
Constants ¶
const ( // RuntimePackage is the fixed output directory for all generated runtime files. // Both the registry and declarative hook implementations are written here. // The Orkestra runtime imports this package directly. RuntimePackage = "pkg/runtime" // RegistryFile is the generated file containing: // - ObjectRegistry // - ListRegistry // - HookRegistry // - ReconcilerRegistry // - RegisterScheme() // // It is regenerated on every `ork generate registry` invocation. RegistryFile = "zz_generated_runtime_registry.go" // ExamplesDir is the output directory for generated example manifests. // Each CRD receives a minimal example YAML manifest for onboarding and testing. ExamplesDir = "_runtime/examples" // DocsDir is the output directory for generated Markdown documentation. // Includes per-CRD docs, an index, and dependency graph documentation. DocsDir = "_runtime/docs" // TestDir is the output directory for generated test scaffolding. // Contains unit test stubs and integration test templates for each CRD. TestDir = "_runtime/test" // DashDir is the output directory for generated Grafana dashboards. // Each CRD receives a dashboard JSON file with metrics panels. DashDir = "_runtime/dashboards" )
Variables ¶
This section is empty.
Functions ¶
func KatalogScaffold ¶ added in v0.2.9
func KatalogScaffold(opts KatalogScaffoldOptions) (string, error)
KatalogScaffold renders a starter katalog.yaml according to opts and writes it to opts.OutputFile (default "katalog.yaml"). The rendered YAML is also returned as a string so callers can use it for dry-run display or testing.
When opts.Typed is true, a warning is printed to stderr explaining that the user must uncomment exactly one of the two generated sections.
func RenderBundle ¶ added in v0.2.9
func RenderBundle( kfg *konfig.Konfig, rules []rbacv1.PolicyRule, inputFile, namespace, workloadNamespace string, ) (string, error)
RenderBundle assembles a complete installation bundle: Namespace (once) → ServiceAccounts → ClusterRole → ClusterRoleBinding → ConfigMap. The Namespace appears exactly once at the top regardless of how many components are combined, so the output is safe to pipe directly into kubectl apply.
func Runtime ¶
Runtime generates zz_generated_runtime_registry.go from the merged Katalog.
When generation is needed (and why):
Typed CRDs (apiTypes.location set) The compiled Go type must be registered so the informer and REST client can decode API server responses. Without this, List/Watch calls fail with "not suitable for converting" errors. Go hooks (reconciler.hooks declared) The hook function lives in an external package. The generator writes the import and wires it into HookRegistry so addHooks() can find it. Custom constructors (reconciler.default: false) Same as Go hooks — external function needs import and ReconcilerRegistry entry.
When generation is NOT needed:
Dynamic template CRDs (only onCreate/onReconcile/onDelete declared) GenericReconciler.runTemplateReconcile() reads the Katalog's operatorBox:Config directly at runtime and calls the OrkestraRegistry functions itself. No generated file. No ork generate registry. Just ork run.
Types ¶
type CRDGenerator ¶
type CRDGenerator struct {
// contains filtered or unexported fields
}
CRDGenerator produces a CRD from a CRDEntry.
func NewCRDGenerator ¶
func NewCRDGenerator(crd orktypes.CRDEntry) *CRDGenerator
NewCRDGenerator creates a generator for one CRD entry.
func (*CRDGenerator) Generate ¶
func (g *CRDGenerator) Generate() (*apiextv1.CustomResourceDefinition, error)
Generate produces the complete CRD object.
type CRDMeta ¶
type CRDMeta struct {
Name string
Description string
Group string
Version string
Kind string
Plural string
Namespaced bool
Namespace string
Workers int
Resync string
DependsOn []string
Reconciler struct {
Default bool
Function string // for custom reconcilers
}
Queue struct {
MaxQueueDepth int
Default bool
}
API struct {
Object string
List string
Alias string
Import string
}
}
Docs and dashboards
type CRGenerator ¶
type CRGenerator struct {
// contains filtered or unexported fields
}
CRGenerator produces an example CR from a CRDEntry.
func NewCRGenerator ¶
func NewCRGenerator(crd orktypes.CRDEntry) *CRGenerator
NewCRGenerator creates a CR generator for one CRD entry.
func (*CRGenerator) Generate ¶
func (g *CRGenerator) Generate() map[string]interface{}
Generate produces an example CR as a plain map (ready for YAML encoding). Required fields are filled with typed placeholders. Optional fields show their default values.
type DashboardTemplateData ¶
type DocsTemplateData ¶
type KatalogScaffoldOptions ¶ added in v0.2.9
type KatalogScaffoldOptions struct {
// AddHook generates a typed Katalog with a commented hooks declaration.
// Mutually exclusive with AddConstructor and Typed.
AddHook bool
// AddConstructor generates a typed Katalog with a commented constructor
// declaration and operatorBox.default: false.
// Mutually exclusive with AddHook and Typed.
AddConstructor bool
// Typed generates a typed Katalog with both hooks and constructor sections
// commented. A warning is printed to stderr — the user must uncomment one
// and delete the other before running. Mutually exclusive with AddHook and
// AddConstructor.
Typed bool
// AddSecurity appends a security block (namespace + deletion protection).
AddSecurity bool
// AddNotification appends a notification block with example team entries.
AddNotification bool
// Provider appends a providers block for the named cloud.
// Accepted: "aws", "azure", "gcp". Empty means no providers block.
Provider string
// OutputFile is the destination path. Defaults to "katalog.yaml".
OutputFile string
}
KatalogScaffoldOptions controls what the scaffold generates.
At most one of AddHook, AddConstructor, or Typed may be true. All other options are additive and may be combined with any mode.
func (KatalogScaffoldOptions) Validate ¶ added in v0.2.9
func (o KatalogScaffoldOptions) Validate() error
Validate returns a descriptive error when mutually exclusive flags are combined, or when an unsupported provider name is given.
Source Files