crdgen

package
v1.78.0 Latest Latest
Warning

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

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

Documentation

Overview

Package crdgen transpiles a chart's JSON Schema (values.schema.json) into a Kubernetes CustomResourceDefinition via a direct JSON-Schema -> structural-OpenAPI-v3 walk. See crdgen/docs/ref-resolution-redesign.md.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Generate

func Generate(opts Options) ([]byte, error)

Generate transpiles the Options' JSON Schemas into a Kubernetes CustomResourceDefinition (YAML).

It uses the direct JSON-Schema -> structural-OpenAPI-v3 transpiler (transpile.go): $refs are inlined by JSON pointer, cycles broken with x-kubernetes-preserve-unknown-fields, map value schemas preserved, and the result is gated on the API server's own CRD validation so the output is always structurally valid. See crdgen/docs/ref-resolution-redesign.md.

func GenerateWithWarnings

func GenerateWithWarnings(opts Options) ([]byte, []string, error)

GenerateWithWarnings is Generate plus the transpiler's warnings.

WHY THIS EXISTS. The transpiler has always collected warnings — a $ref cycle broken with x-kubernetes-preserve-unknown-fields, a kind it could not resolve, a generated CEL rule dropped because an enclosing array is unbounded — and until now every one of them was appended to a slice that nothing ever read. The generator knew things the chart author needed and discarded them.

That is the same shape as the defect the dropped-rule warning reports: a cost paid at install time, by a different person, in a different week, because nothing told the author at authoring time. A warning into a void is not a warning.

Generate is kept unchanged so no consumer has to move, but a caller that can surface warnings to a human or a log should prefer this one. The warnings are advisory: generation has SUCCEEDED when err is nil, whatever they say.

func NormalizeVersionName

func NormalizeVersionName(ver string) string

NormalizeVersionName converts an arbitrary version string (e.g. an OAS info.version like "1.2.3") into the legal Kubernetes CRD version name crdgen emits for it (e.g. "v1-2-3"). Callers deriving a GVK/GVR outside crdgen MUST use this so their version matches the generated CRD's version name.

Types

type Options

type Options struct {
	Group        string
	Version      string
	Kind         string
	Categories   []string
	SpecSchema   []byte
	StatusSchema []byte
	Managed      bool

	// NoParentDefaults disables the `default: {}` crdgen gives an optional object whose subtree
	// carries a reachable default (core-provider#138), which makes the apiserver materialize the
	// object and apply the nested defaults when a user omits it.
	//
	// The zero value keeps that behaviour. Set it when the schema's `default`s DESCRIBE rather than
	// instruct, e.g. an OpenAPI document generated from a vendor API, where a default states what the
	// server assumes. Materializing it there turns a documented assumption into a value the
	// controller sends, and a persisted default cannot later be told apart from an authored one
	// (plumbing#84). Every stamp is reported by GenerateWithWarnings either way.
	NoParentDefaults bool
}

Options configures CRD generation. SpecSchema/StatusSchema are JSON Schema documents (a chart's values.schema.json and an optional status schema). Managed adds the crossplane ConditionedStatus to the status subresource.

type Warning added in v1.28.0

type Warning struct {
	// Path is the location in the source schema walk (e.g. "spec.image.tag"), or "" for a warning
	// about the CRD as a whole.
	Path    string
	Kind    WarningKind
	Message string
}

Warning is one thing crdgen could not carry faithfully, or did on the caller's behalf.

func GenerateWithDiagnostics added in v1.28.0

func GenerateWithDiagnostics(opts Options) ([]byte, []Warning, error)

GenerateWithDiagnostics is GenerateWithWarnings with each warning TYPED: its path, its Kind and its message (core-provider#362). A caller that acts on warnings, rather than only displaying them, should use this and branch on Kind (or Kind.LosesEnforcement()), never on message text. GenerateWithWarnings returns exactly the String() of these.

func (Warning) String added in v1.28.0

func (w Warning) String() string

String is the text GenerateWithWarnings has always returned: "path: message", or the message alone when there is no path. Kept byte-identical so existing callers see no change.

type WarningKind added in v1.28.0

type WarningKind string

WarningKind classifies what a crdgen warning means for the generated CRD, so a caller can act on the ones that matter to it without matching message text (core-provider#362).

The kinds answer one question each about the CRD against its source schema:

const (
	// KindConstraintDropped: a validation the schema states is NOT enforced, so the CRD accepts
	// values the schema rejects (an unsupported `not`, if/then/else, dependentRequired, a dropped
	// uniqueness rule, ...).
	KindConstraintDropped WarningKind = "ConstraintDropped"

	// KindStructureLoosened: a subtree is accepted with unknown fields or any shape
	// (x-kubernetes-preserve-unknown-fields, an open object), e.g. a $ref cycle broken or an
	// unresolved $ref. Also accepts values the schema rejects.
	KindStructureLoosened WarningKind = "StructureLoosened"

	// KindAcceptanceNarrowed: the CRD REFUSES values the schema accepts (a union type reduced to
	// one member, an enum value that could not be carried). The opposite of a loss of enforcement,
	// and arguably worse for an author, because valid input is rejected.
	KindAcceptanceNarrowed WarningKind = "AcceptanceNarrowed"

	// KindDefaultDropped: a `default` the schema declares is not applied.
	KindDefaultDropped WarningKind = "DefaultDropped"

	// KindParentDefaulted: crdgen gave an optional parent `default: {}` so its nested defaults apply
	// when it is omitted (plumbing#84). Nothing is lost; the apiserver stores more.
	KindParentDefaulted WarningKind = "ParentDefaulted"

	// KindConventionConflict: a convention field crdgen would declare (status.observedGeneration)
	// is already declared with another type and was kept (plumbing#82).
	KindConventionConflict WarningKind = "ConventionConflict"
)

func (WarningKind) LosesEnforcement added in v1.28.0

func (k WarningKind) LosesEnforcement() bool

LosesEnforcement reports whether the CRD accepts values the source schema rejects. It is the question behind a "schema fully enforced" signal: true for KindConstraintDropped and KindStructureLoosened only.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL