generate

package
v0.6.2 Latest Latest
Warning

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

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

README

pkg/generate

generate transforms a Katalog into deployable Kubernetes artifacts and Go code. Each sub-command reads one or more katalog.yaml files, merges them, and writes a specific type of output.

ork generate registry  -f katalog.yaml          # Go TypeRegistry code
ork generate rbac      -f katalog.yaml          # RBAC ClusterRoles + ServiceAccounts
ork generate configmap -f katalog.yaml          # ConfigMap embedding the Katalog
ork generate bundle    -f katalog.yaml          # RBAC + ConfigMap in one file
ork generate dashboards -f katalog.yaml         # Grafana dashboard JSON (starting point)
ork generate katalog                            # Starter katalog.yaml scaffold
ork generate crd       -f katalog.yaml          # CRD + sample CR manifests
ork generate all       -f katalog.yaml          # registry + dashboards in one pass

All file-writing commands accept --dry-run to print output to stdout instead.

Developer documentation

I want to… Go to
Understand all generators and what each produces docs/01-generators.md
Understand RBAC, ConfigMap, and Bundle generation docs/02-bundle-rbac.md
Understand TypeRegistry code generation docs/03-type-registry.md
Understand CRD and sample CR generation docs/04-crd-generation.md

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 --file 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

View Source 
const (
	// TypeRegistryPackage is the fixed output directory for all generated typeregistry files.
	// Both the registry and declarative hook implementations are written here.
	// The Orkestra runtime imports this package directly.
	TypeRegistryPackage = "pkg/typeregistry"

	// RegistryFile is the generated file containing:
	//   - ObjectRegistry
	//   - ListRegistry
	//   - HookRegistry
	//   - ReconcilerRegistry
	//   - RegisterScheme()
	//
	// It is regenerated on every `ork generate registry` invocation.
	RegistryFile = "zz_generated_typeregistry.go"

	// DashDir is the output directory for generated Grafana dashboards.
	// Each CRD receives a dashboard JSON file with metrics panels.
	DashDir = "_generated/dashboards"
)

Variables

This section is empty.

Functions

func ConfigMap 

func ConfigMap(expandedYAML []byte, namespace string) ([]byte, error)

ConfigMap renders a Namespace + ConfigMap from pre-expanded katalog bytes. expandedYAML must be the output of katalog.Katalog.SerializeExpanded() — fully resolved, no OCI imports remaining.

func Dashboards 

func Dashboards(c []orktypes.CRDEntry, dryRun bool) error

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 RBAC 

func RBAC(rules []rbacv1.PolicyRule, namespace, outputFile string) ([]byte, error)

RBAC generates a Namespace + ServiceAccounts + ClusterRole + ClusterRoleBinding for backwards compatibility. runtimeRules are bound to the orkestra ClusterRole. Deprecated callers may pass all rules as runtimeRules and nil as gatewayRules.

func RBACWithOptions added in v0.4.9 

func RBACWithOptions(runtimeRules, gatewayRules []rbacv1.PolicyRule, opts BundleOptions, namespace, outputFile string) ([]byte, error)

RBACWithOptions generates RBAC resources with fine-grained control over which components are included. runtimeRules are bound to the orkestra ClusterRole; gatewayRules are bound to the orkestra-gateway ClusterRole.

func RenderBundle added in v0.2.9 

func RenderBundle(
	runtimeRules, gatewayRules []rbacv1.PolicyRule,
	expandedYAML []byte,
	namespace, workloadNamespace string,
	opts BundleOptions,
) (string, error)

RenderBundle assembles a complete installation bundle: Namespace (once) → ServiceAccounts → ClusterRoles → ClusterRoleBindings → ConfigMap. expandedYAML must be the output of katalog.Katalog.SerializeExpanded() — fully resolved, no OCI imports remaining. The ConfigMap embeds this content so the runtime never needs to do OCI pulls at startup.

runtimeRules are bound to the orkestra ClusterRole. gatewayRules are bound to the orkestra-gateway ClusterRole. opts controls which components are included in the output.

func TypeRegistry added in v0.4.9 

func TypeRegistry(crds map[string]orktypes.CRDEntry, dryRun bool) error

TypeRegistry generates zz_generated_typeregistry.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 BundleOptions added in v0.4.9 

type BundleOptions struct {
	IncludeRuntime       bool
	IncludeGateway       bool
	IncludeControlCenter bool
}

BundleOptions controls which components are included in a generated bundle. Each flag defaults to true; pass false to exclude that component's ServiceAccount, ClusterRole, and ClusterRoleBinding from the output. IncludeConfigMap follows: included when IncludeRuntime || IncludeGateway.

func DefaultBundleOptions added in v0.4.9 

func DefaultBundleOptions() BundleOptions

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 {
		MaxDepth int
		Shared   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 DashboardTemplateData struct {
	Timestamp time.Time
	CRD       CRDMeta
}

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

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.