Connector Generation
TOC
OverviewProblem It SolvesData StructureConnectorClass —spec.generationConnector — spec.generatorsGenerated child ConnectorsAddress templatingStatus and ConditionsRecoveryLifecycleExamplesReferencesOverview
Some backends expose several package ecosystems behind a single service. A
Nexus or JFrog Artifactory instance, for example, serves npm, Maven and PyPI
repositories from one host. Instead of asking users to hand-create one
Connector per ecosystem, an aggregator Connector can declare its children
in spec.generators, and the controller materializes one child Connector per
entry — each bound to the appropriate per-ecosystem ConnectorClass.
The feature has two halves:
- On the
ConnectorClass,spec.generation.supportedClassesis an allowlist of the ConnectorClass names an aggregator of this class may generate children for. It is the class author's assertion that those child classes can serve the path-scoped addresses this aggregator produces. - On the
Connector,spec.generatorsdeclares the child Connectors to materialize. Each entry carries a child ConnectorClass name, an address, and optional auth/params.
The following example declares a Nexus aggregator that generates an npm, a Maven and a PyPI child Connector:
The controller reconciles this into three child Connectors — nexus-npm,
nexus-maven and nexus-pypi — in the same namespace, each owned by the
aggregator and carrying identity labels, and sets the aggregator's
GenerationReady condition to True.
Problem It Solves
One backend, many ecosystems. A single Nexus/JFrog host serves npm, Maven and PyPI. Modelling each as an independent Connector means users repeat the same host, credentials and proxy wiring three times and keep them in sync by hand.
Path-scoped addressing. Each ecosystem lives under a different path of the
same host (/repository/<name>/ on Nexus, /artifactory/api/<type>/<repo>/
on JFrog). Generators let the aggregator own the host and credentials once,
while each child carries the ecosystem-specific path-scoped address.
Lifecycle as one unit. Children are owned by the aggregator, so deleting
the aggregator cascades to its children, and removing an entry from
spec.generators prunes exactly that child — no orphaned Connectors.
Data Structure
ConnectorClass — spec.generation
A ConnectorClass opts into being an aggregator by declaring the child classes
it supports:
An aggregator class itself typically ships no per-ecosystem ResourceInterface
— those are provided by the generated child Connectors, each of which carries
its own ConnectorClass and ResourceInterface.
Connector — spec.generators
Each entry in spec.generators describes one child Connector. The entry embeds
the same fields as a Connector's own spec (address, auth, params, …) inline,
plus a name:
Generated child Connectors
For every valid entry, the controller creates (and thereafter maintains) one child Connector in the parent's namespace with:
-
an ownerReference to the parent (
controller: true,blockOwnerDeletion: true), so children cascade-delete with the parent; -
identity labels:
-
an annotation
connectors.cpaas.io/managed-by-generatornaming the parent.
The controller treats the entry as the source of truth: if a child's spec
(for example its address) is changed out-of-band, the next reconcile restores
it to the declared value.
Address templating
The address of a generator entry is a Go text/template evaluated against the
parent Connector. Available context:
The parent's spec.address is exposed with any trailing / trimmed, so the
idiom {{.connector.spec.address}}/repository/npm-proxy/ yields a clean URL.
Templating uses missingkey=error: referencing a field that does not exist
fails the entry with reason InvalidAddress rather than rendering an empty
segment.
Status and Conditions
The aggregator's generation outcome is summarized on the GenerationReady
condition. This condition is informational — it reports the state of child
generation but does not gate the aggregator's own Ready condition (the
aggregator can be Ready while a generator entry is failing, and vice versa).
Recovery
- Validation failures (
ClassNotFound,InvalidParams,AuthIncompatible,InvalidAddress,InvalidName) recover when the underlying cause is fixed — editspec.generators, or create the missing childConnectorClass— which triggers a fresh reconcile. NameConflictis requeued automatically about every 1 minute, so the aggregator recovers once the conflicting Connector is removed or renamed.ChildRejectedis requeued automatically about every 5 minutes, so the aggregator recovers once the child-class admission issue is resolved.
Lifecycle
Examples
Nexus aggregator generating npm / Maven / PyPI children
The three generated children carry the aggregator's ownerReference and the
generated-by: nexus-aggregator / generator-entry: <name> labels:
JFrog aggregator works the same way, with JFrog's per-ecosystem API paths: