pkg

package
v0.1.9 Latest Latest
Warning

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

 Go to latest Published: Jul 22, 2026 License: Apache-2.0, MIT Imports: 23 Imported by: 0

Documentation

Overview

Package pkg assembles an installable Crossplane Configuration xpkg image from the YAML a single CUE module generates, and pushes it to an OCI registry.

It is the author-time packaging core. The pure half builds the three packaged objects — the XRD (reused from internal/schema), a pipeline-mode Composition wired to the cuefn function, and the meta.pkg.crossplane.io Configuration — marshals them into the package.yaml YAML stream, and tars that stream into an xpkg image layer with the correct media types and the io.crossplane.xpkg=base annotation. All registry/network IO lives at the edge in push.go, preserving the hexagonal boundary the rest of the codebase follows.

xpkg packaging spike (P5/P6 de-risk)

crossplane's own builder, github.com/crossplane/crossplane/internal/xpkg, is under internal/ and therefore NOT importable from this module. The escape hatch is github.com/crossplane/crossplane-runtime/v2/pkg/xpkg, which IS public (and already in the module graph via the v2 runtime dependency). It exports exactly the contract primitives needed: the StreamFile ("package.yaml"), PackageAnnotation ("base") and AnnotationKey ("io.crossplane.xpkg") constants, Layer (tar a YAML stream into a layer and record its annotation as a config label), and AnnotateLayers (propagate those labels to real OCI layer annotations). Building on those plus go-containerregistry — empty.Image as the base, mutate to append the layer and set the config, then a remote.Write push — yields a package that `crossplane xpkg inspect` accepts, without any dependency on the crossplane CLI for building.

Function xpkg (embed-runtime)

The same BuildXpkgImage shape ships the Function xpkg (function.go). The package layer is a meta.pkg.crossplane.io Function plus the Input CRD generated from input/v1beta1 (Crossplane reads the Input CRD from the package to validate pipeline step inputs), and the base is the apko-built runtime image rather than empty.Image — so the package image IS the runtime image plus the package layer. BuildFunctionImage specializes that generic base by moving its default `function` command into the package entrypoint and clearing Cmd, which lets Crossplane supply runtime flags such as `--insecure` directly. BuildFunctionIndex/PushIndex extend this to a multi-arch index for a real release, since the package image is the runtime and must run on every node arch. The Configuration path (empty base) and the Function path (runtime base) share the one assembler.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildConfigurationImage 

func BuildConfigurationImage(c Configuration, options ...ConfigurationImageOption) (v1.Image, error)

BuildConfigurationImage marshals c into the package.yaml stream and assembles a Configuration xpkg image (empty base, single annotated package layer) ready to push.

func BuildFunctionImage 

func BuildFunctionImage(base v1.Image, f Function) (v1.Image, error)

BuildFunctionImage assembles a single-arch Function xpkg: the package.yaml layer (meta + Input CRD) appended over the apko runtime image base. It moves the base's default command into the package entrypoint so Crossplane can replace Cmd with runtime flags while the standalone base remains generic.

func BuildFunctionIndex 

func BuildFunctionIndex(bases []v1.Image, f Function) (v1.ImageIndex, error)

BuildFunctionIndex wraps each per-arch runtime base into a Function xpkg image and assembles a multi-arch OCI image index (the release path). A Function package image is the runtime image, so a real multi-node-arch install needs an index over both arches; the platform of each manifest entry is taken from its base's config. The index media type is OCI, matching apko's published runtime index.

func BuildXpkgImage 

func BuildXpkgImage(base v1.Image, packageYAML []byte) (v1.Image, error)

BuildXpkgImage tars packageYAML (a marshaled multi-doc YAML stream) into the package layer of base and returns the assembled xpkg image. The layer is named package.yaml and carries the io.crossplane.xpkg=base annotation Crossplane uses to locate a package's contents; base's existing config labels and layers are preserved.

base is empty.Image for a Configuration (no runtime); for an embed-runtime Function xpkg it is the runtime image, so the package layer rides on top of the runtime filesystem. This single shape is the spike's shared assembler for both the Configuration package (this phase) and the Function package (P6).

func DerivedFunctionName added in v0.1.2 

func DerivedFunctionName(ref string) (string, error)

DerivedFunctionName returns the metadata.name Crossplane's package manager gives a Function it auto-installs from a Configuration's dependsOn entry for ref. Crossplane strips the registry host and DNS-labelizes the repository path (xpkg.ToDNSLabel over name.RepositoryStr), so e.g. "ghcr.io/meigma/function-cuefn" installs as "meigma-function-cuefn".

A generated Composition must reference the function by this exact name for the pipeline step to bind to the auto-installed Function. Referencing the bare last path segment ("function-cuefn") leaves the step unresolved with "cannot find an active FunctionRevision", and hand-installing a separate Function to match would poison the package Lock (two Functions on one package source).

func GenerateComposition 

func GenerateComposition(xrd *xv2.CompositeResourceDefinition, in CompositionInput) (*apiextv1.Composition, error)

GenerateComposition builds a pipeline-mode Composition for xrd. Its compositeTypeRef is taken from the XRD's group, referenceable version, and kind. The pipeline runs function-environment-configs (step 1, to surface EnvironmentConfigs to the module) then cuefn (step 2, carrying the module ref and expected digest from in). The Composition is named after the XRD's plural.

func GenerateConfigurationMeta 

func GenerateConfigurationMeta(m ConfigurationMeta) (*metav1cp.Configuration, error)

GenerateConfigurationMeta builds the meta.pkg.crossplane.io/v1 Configuration object (the package's crossplane.yaml) with a dependsOn entry for the cuefn Function, so installing the Configuration pulls the function it relies on.

func GenerateFunctionMeta 

func GenerateFunctionMeta(m FunctionMeta) (*metav1cp.Function, error)

GenerateFunctionMeta builds the meta.pkg.crossplane.io/v1 Function object (the package's crossplane.yaml). A Function package carries no dependsOn — it is the leaf a Configuration depends on — so the spec is just the optional Crossplane constraint and capabilities.

func Push 

func Push(ctx context.Context, ref string, img v1.Image, insecure bool, opts ...remote.Option) (name.Digest, error)

Push writes img to the OCI reference ref and returns the pushed image's digest. It is the only network seam in the package: callers assemble the image purely, then push it here.

When insecure is true the reference is parsed with name.Insecure so the push uses plain HTTP (needed for a non-loopback throwaway registry; loopback registries already resolve to HTTP automatically). opts carry auth and transport. A malformed ref or an unreachable/refusing destination surfaces as a clear error naming ref, never a panic.

func PushIndex 

func PushIndex(
	ctx context.Context,
	ref string,
	idx v1.ImageIndex,
	insecure bool,
	opts ...remote.Option,
) (name.Digest, error)

PushIndex writes a multi-arch image index idx to the OCI reference ref and returns the pushed index's digest. It is the multi-arch release path for a Function xpkg (the package image is the runtime image, so a real install needs a per-node-arch index). It mirrors Push: insecure selects plain HTTP, opts carry auth/transport, and a malformed/unreachable destination surfaces a clear error naming ref.

func ValidateDestination added in v0.1.8 

func ValidateDestination(ref string, insecure bool) error

ValidateDestination verifies that ref is a valid package push target without performing any registry operation.

Types

type CompositionInput 

type CompositionInput struct {
	// Module is the CUE module ref in "path@version" semver form.
	Module string
	// ExpectedDigest is the resolved OCI manifest digest ("sha256:...") the
	// module must match at render time.
	ExpectedDigest string
	// FunctionName is the in-cluster Function resource name the cuefn step
	// references (the functionRef.name). It must match the Function name the
	// installed Configuration's dependsOn entry produces — see DerivedFunctionName.
	FunctionName string
	// EnvironmentConfigRefs are the names of EnvironmentConfigs the
	// function-environment-configs step merges into the pipeline context (by
	// Reference) before cuefn evaluates the module. When empty the step is omitted
	// entirely, so a default install needs only the cuefn Function. Each name
	// becomes a `type: Reference` entry in the step's Input.
	EnvironmentConfigRefs []string
	// EnvironmentConfigSelectors select additional EnvironmentConfigs by labels
	// whose values are read from the composite resource at render time. Each
	// selector becomes a `type: Selector` entry (mode Single) after the Reference
	// entries, so its data merges over theirs. Single mode fails the render when
	// zero or multiple EnvironmentConfigs match.
	EnvironmentConfigSelectors []EnvironmentConfigSelector
	// EnvironmentConfigFunctionName is the in-cluster Function resource name the
	// function-environment-configs step references. Like FunctionName it must match
	// the auto-installed Function name (DerivedFunctionName of the env-config
	// function package). Only used when EnvironmentConfigRefs or
	// EnvironmentConfigSelectors is non-empty; defaults to
	// "function-environment-configs" when blank.
	EnvironmentConfigFunctionName string
}

CompositionInput is the author half of the schema<->runtime digest lock-step: the semver module ref the cuefn function fetches, and the exact OCI manifest digest it must resolve to. Both are embedded in the cuefn pipeline step's Input so the runtime loader (OCIConfig.Expect) can verify the module has not drifted.

type Configuration 

type Configuration struct {
	// Meta is the meta.pkg.crossplane.io Configuration object.
	Meta *metav1cp.Configuration
	// XRD is the generated CompositeResourceDefinition (from internal/schema).
	XRD *xv2.CompositeResourceDefinition
	// Composition is the pipeline-mode Composition (from GenerateComposition).
	Composition *apiextv1.Composition
}

Configuration is the full set of objects packaged into one Configuration xpkg: the package metadata (crossplane.yaml), the XRD, and the Composition.

func (Configuration) PackageYAML 

func (c Configuration) PackageYAML() ([]byte, error)

PackageYAML marshals the Configuration's three objects into the package.yaml YAML stream, with the package metadata first, then the XRD, then the Composition. Crossplane reads every document from this single stream; the document order matches crossplane's own builder (meta first).

type ConfigurationImageOption added in v0.1.8 

type ConfigurationImageOption func(*v1.Config) error

ConfigurationImageOption customizes a Configuration image after its xpkg layer and generated labels have been assembled.

func WithConfigurationLabels added in v0.1.8 

func WithConfigurationLabels(labels map[string]string) ConfigurationImageOption

WithConfigurationLabels adds labels to the Configuration image config. It rejects empty fields and collisions with labels already generated by xpkg.

type ConfigurationMeta 

type ConfigurationMeta struct {
	// Name is the package metadata.name (e.g. "xapps-configuration").
	Name string
	// CrossplaneConstraint is an optional semver constraint on the Crossplane
	// version the package supports (e.g. ">=v1.14.0-0"); omitted when empty.
	CrossplaneConstraint string
	// FunctionPackage is the dependsOn Function package OCI ref
	// (e.g. "xpkg.meigma.io/cuefn").
	FunctionPackage string
	// FunctionVersion is the dependsOn semver version constraint
	// (e.g. ">=v0.1.0").
	FunctionVersion string
	// EnvironmentConfigFunctionPackage is the dependsOn ref for the
	// function-environment-configs Function; when set, a second dependsOn entry is
	// emitted so installing the Configuration also pulls it (only needed when the
	// Composition uses EnvironmentConfigs). Empty omits the dependency.
	EnvironmentConfigFunctionPackage string
	// EnvironmentConfigFunctionVersion is the version constraint for the
	// function-environment-configs dependency; used only when the package is set.
	EnvironmentConfigFunctionVersion string
}

ConfigurationMeta names the Configuration package and its dependency on the cuefn composition Function.

type EnvironmentConfigLabelMatch added in v0.1.9 

type EnvironmentConfigLabelMatch struct {
	// Key is the label key on the EnvironmentConfig.
	Key string
	// ValueFromFieldPath is the composite-resource field path whose value the
	// label must equal (for example "metadata.name").
	ValueFromFieldPath string
}

EnvironmentConfigLabelMatch matches one EnvironmentConfig label against a value read from the composite resource (FromCompositeFieldPath).

type EnvironmentConfigSelector added in v0.1.9 

type EnvironmentConfigSelector struct {
	// MatchLabels are the label matchers the selected EnvironmentConfig must
	// satisfy. At least one is required.
	MatchLabels []EnvironmentConfigLabelMatch
}

EnvironmentConfigSelector selects exactly one EnvironmentConfig by labels (function-environment-configs Selector source, mode Single).

type Function 

type Function struct {
	// Meta is the meta.pkg.crossplane.io Function object (the crossplane.yaml).
	Meta *metav1cp.Function
	// InputCRD is the CustomResourceDefinition generated from input/v1beta1,
	// carried inside the package so Crossplane can validate pipeline step inputs.
	InputCRD *apiextensionsv1.CustomResourceDefinition
}

Function is the full content of a Function xpkg's package.yaml stream: the meta.pkg.crossplane.io Function plus the embedded Input CRD that ships inside every Crossplane function package.

func DefaultFunction 

func DefaultFunction(meta *metav1cp.Function) (Function, error)

DefaultFunction builds a Function from meta plus the embedded Input CRD. It is the normal constructor: callers supply only the package metadata, and the Input CRD is the one generated from this module's input/v1beta1 type. A parse failure of the embedded CRD is a build/codegen error (the file is generated and committed alongside this package).

func (Function) PackageYAML 

func (f Function) PackageYAML() ([]byte, error)

PackageYAML marshals the Function's objects into the package.yaml YAML stream, with the package metadata first, then the Input CRD. The document order matches crossplane's own builder (meta first); the CRD reuses the same status-dropping marshalDoc the Configuration path uses.

type FunctionMeta 

type FunctionMeta struct {
	// Name is the package metadata.name (e.g. "function-cuefn").
	Name string
	// CrossplaneConstraint is an optional semver constraint on the Crossplane
	// version the package supports (e.g. ">=v2.0.0-0"); omitted when empty.
	CrossplaneConstraint string
	// Capabilities are optional opaque capability strings advertised by the
	// package; omitted when empty.
	Capabilities []string
}

FunctionMeta names the Function package and its optional Crossplane compatibility constraint and capabilities.

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.