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 ¶
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 ¶
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 ¶
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
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.
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.