Builder Contract Migration (release 2)

Builder contract: release 2 migration notes

This page is the ledger for the second release of the builder contract (ADR-038, the “thin core + admissible sugar” decision). Release 1 made the upstream Go struct the construction API and removed the bare forwarders and injected defaults; its ledger is the release 1 migration notes . Release 2 removes the one construction path that survived it: the Kind(&Config) layer — a function per kind taking a kure-invented Config struct and translating it into the upstream spec — in the six packages that still carried one, together with the sealed-interface sum types and the values that layer used to inject. The normative contract text is the Kubernetes Builders page.

Every removed function, type and field is listed here once, with the upstream expression that replaces it.

Why the layer went

In four of the six packages the Config was lossy by construction: the vocabulary reached 5 of a cert-manager Certificate’s 24 spec fields, 2 of an issuer’s 5 arms (no Vault, SelfSigned or Venafi), 15 of a CNPG Cluster’s 55, 6 of a ServiceMonitor’s 19 — and every upstream release widened the gap. In the other two (cilium, volsync) it was a verbatim copy of obj.Spec = spec. cert-manager’s IssuerVariant, ACMESolver and DNS01Provider and volsync’s SourceMover and DestinationMover were interfaces closed by an unexported marker method — the only compile-time wall in kure: a caller could not add an Azure DNS solver or a Vault issuer even by hand. The layer also held the last injected values the release 1 purge deferred to it (CNPG enablePDB, primaryUpdateStrategy, S3 key names, the barman-cloud plugin entry, the pooler type coercion).

One idiom remains: the generated Create<Kind> constructor plus the upstream struct.

The rule that replaces it

No exported function under pkg/kubernetes/... takes a kure-defined type where an upstream spec type exists.

TestAdmission_NoOwnParameterTypes (pkg/kubernetes/admission_params_test.go) walks every exported top-level function in the non-test, non-generated files and fails on any parameter whose type names a struct or interface this tree defines — declared under pkg/kubernetes, written as a literal in the signature, or reached through pointer, slice, array, map or channel layers, a callback’s parameters and results, an alias or a named container (type Config = *struct{...}), or a type argument of an instantiated generic or generic alias, or a type parameter’s constraint (its embedded types and union terms included). Upstream named types are not otherwise entered. There is no exclusion list. A named scalar such as kubernetes.PSALevel (a string enum with no upstream spec type) is not a spec type and passes; a defined type over an upstream struct (volsync’s former SourceResticConfig) does not.

How a call site migrates

Every Kind(&KindConfig{Name: n, Namespace: ns, ...}) becomes the generated constructor plus assignments on the upstream struct:

// before
cert := certmanager.Certificate(&certmanager.CertificateConfig{
    Name: "api-tls", Namespace: "default",
    SecretName: "api-tls-secret",
    DNSNames:   []string{"api.example.com"},
})

// after
cert := certmanager.CreateCertificate("api-tls", "default")
cert.Spec = certv1.CertificateSpec{
    SecretName: "api-tls-secret",
    DNSNames:   []string{"api.example.com"},
}

Cluster-scoped kinds take (name) only. Two behaviours of the layer have no equivalent and need no replacement: a nil *Config returned a nil object (constructors never return nil), and a typed-nil variant stored in a sealed interface was treated as “no variant” (there is no interface to store it in — an unset pointer arm is unset).

Most of the remaining differences share one shape. Where the layer guarded a field, it set a pointer only when the input behind it was non-empty or positive, and it filled a list by appending in a loop, so an empty input left the field nil. A struct literal writes exactly what it is given, so for those fields an assigned empty value can change the manifest: an empty slice renders [] where nil renders null on a field without omitempty, and a pointer to an empty struct renders {}. The guard is a property of each field, not a general default — the rows below that carry one state its condition, and only those fields should be left nil for an empty input. A pointer the layer always wrote, whatever its value, has no such guard: CNPG’s EnablePodAntiAffinity was written as false when asked for false, and leaving it nil instead lets the operator apply anti-affinity.

The golden fixtures under each package’s testdata/ were written by the layer as it stood before this release; the tests that now produce them use Create<Kind> and the upstream struct and reproduce that output byte for byte, including every value the layer used to inject. Those values are the caller’s own lines now, and each package section below lists them.

pkg/kubernetes/certmanager

Removed functions (3)

Removed types (14) and their fields

The sealed interfaces IssuerVariant, ACMESolver and DNS01Provider are gone with the eleven structs that implemented or carried them. The upstream one-of is certv1.IssuerConfig, embedded in IssuerSpec (the Spec type of both Issuer and ClusterIssuer), with a pointer per arm: ACME, CA, Vault, SelfSigned, Venafi.

Behaviour of the layer that a struct literal does not have

None of these was documented as a feature; each is listed so a caller relying on it can see what to write instead.

Golden deltas: none. Every fixture in pkg/kubernetes/certmanager/testdata is reproduced byte for byte.

pkg/kubernetes/cnpg

Removed functions (5)

Removed types (21) and their fields

Values the layer injected

Each of these was a line in emitted YAML the caller never wrote. The release 1 defaults purge deferred them to this release (they lived in the layer, not in a constructor or a sugar helper). They are all expressible — the re-authored goldens write every one of them — but nothing writes them for you.

Every conditional in the retired CNPG builders (pkg/kubernetes/cnpg/create.go and pooler.go as of 4729da0) is accounted for above: its row or this table states the guard, including the ones where the only risk is writing a value the layer left out (a connection limit, a role ensure, a pool mode), or the guarded field is omitempty and the layer wrote nothing a literal would write differently.

Golden deltas: none. Every fixture in pkg/kubernetes/cnpg/testdata is reproduced byte for byte, the injected values above included.

pkg/kubernetes/externalsecrets

Removed functions (3)

Removed types (3) and their fields

The layer skipped Provider when nil and Controller when empty; a nil pointer and an empty string serialise to nothing either way, so there is no behaviour to replace. Golden deltas: none. Every fixture in pkg/kubernetes/externalsecrets/testdata is reproduced byte for byte.

pkg/kubernetes/prometheus

Removed functions (3)

Removed types (3) and their fields

The layer skipped JobLabel when empty, NamespaceSelector and SampleLimit when nil and Labels when nil; an empty string, a nil pointer and a nil map serialise to nothing either way, so there is no behaviour to replace. spec.endpoints and spec.podMetricsEndpoints carry no omitempty: the layer filled them by appending, so an empty (even explicitly allocated) input list left them nil and rendered null, which release 1 recorded when the layer stopped seeding empty slices. A literal that assigns an empty slice renders [] instead; leave the field nil, or use AddServiceMonitorEndpoint / AddPodMonitorEndpoint, to keep null. Golden deltas: none. Every fixture in pkg/kubernetes/prometheus/testdata is reproduced byte for byte.

pkg/kubernetes/cilium

Removed functions (13)

Every one of these was obj.Spec = cfg.Spec (or the Spec / Specs pair on the two policy kinds, or the ExternalCIDRs list on the CIDR group) behind a Name and, for the namespaced kinds, a Namespace. The replacement is the generated constructor and the same assignment.

Removed types (13) and their fields

The two policy builders skipped a nil Spec; a nil pointer serialises to nothing either way. CiliumCIDRGroup filled spec.externalCIDRs by appending, so an empty input list left it nil and rendered externalCIDRs: null (the field has no omitempty); assigning an empty slice renders [] — leave it nil, or use AddCiliumCIDRGroupCIDR, to keep null. Golden deltas: none. Every fixture in pkg/kubernetes/cilium/testdata is reproduced byte for byte.

pkg/kubernetes/volsync

Removed functions (2) and one changed signature

Removed types (15) and their fields

The sealed interfaces SourceMover and DestinationMover are gone with the nine mover types defined over the upstream specs, ExternalConfig, TriggerConfig and the two parent Config structs. The upstream one-of is a pointer per arm on the spec; VolSync validates “exactly one” at apply time. CopyMethod and its four constants stay: they re-export the upstream type and were never part of the layer.

Each Source<Mover>Config / Destination<Mover>Config had exactly the fields of the upstream spec it was defined over, so a literal keeps its body and changes its type name. The release 1 ledger’s volsync section named ReplicationSourceConfig.* as the replacement for the setters it removed; those replacements are now the rs.Spec.* assignments listed above. Golden deltas: none. Every fixture in pkg/kubernetes/volsync/testdata is reproduced byte for byte.