render

package
v2.4.1 Latest Latest
Warning

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

Go to latest
Published: Jul 24, 2026 License: Apache-2.0 Imports: 48 Imported by: 0

Documentation

Overview

Package render implements helpers shared by the render subcommands (xr and op).

Index

Constants

View Source
const (
	// AnnotationKeyRuntimeDockerCleanup configures how a Function's Docker
	// container should be cleaned up once rendering is done.
	AnnotationKeyRuntimeDockerCleanup = "render.crossplane.io/runtime-docker-cleanup"

	// AnnotationKeyRuntimeDockerImage overrides the Docker image that will be
	// used to run the Function. By default render assumes the Function package
	// (i.e. spec.package) can be used to run the Function.
	AnnotationKeyRuntimeDockerImage = "render.crossplane.io/runtime-docker-image"

	// AnnotationKeyRuntimeNamedContainer sets the Docker container name that will
	// be used for the container. it will also reuse the same container as long as
	// it is available and also try to restart if it is not running.
	AnnotationKeyRuntimeNamedContainer = "render.crossplane.io/runtime-docker-name"

	// AnnotationKeyRuntimeEnvironmentVariables sets the environment variables
	// that will be used for the container. This is helpful to control kpm registry
	// access to use a different registry.
	// It is a comma separated string of key=value pairs e.g. "key1=value1,key2=value2".
	AnnotationKeyRuntimeEnvironmentVariables = "render.crossplane.io/runtime-docker-env"

	// AnnotationKeyRuntimeDockerPublishAddress configures the host address that
	// Docker should publish (bind) the Function's container port to. Defaults to 127.0.0.1.
	// Use 0.0.0.0 to publish to all host interfaces for remote Docker access.
	AnnotationKeyRuntimeDockerPublishAddress = "render.crossplane.io/runtime-docker-publish-address"

	// AnnotationKeyRuntimeDockerTarget configures the address that the render
	// CLI should use to connect to the Function's Docker container.
	AnnotationKeyRuntimeDockerTarget = "render.crossplane.io/runtime-docker-target"

	// AnnotationKeyRuntimeDockerNetwork specifies which Docker network the
	// Function container should be connected to. When set, the container is
	// reached via its Docker hostname on port 9443 rather than via host port
	// bindings. This is useful when the render process itself runs inside a
	// Docker container (e.g. a GitHub Actions container job) and function
	// containers must be on the same network to be reachable.
	AnnotationKeyRuntimeDockerNetwork = "render.crossplane.io/runtime-docker-network"
)

Annotations that can be used to configure the Docker runtime.

View Source
const AnnotationKeyRuntime = "render.crossplane.io/runtime"

AnnotationKeyRuntime can be added to a Function to control what runtime is used to run it locally.

View Source
const (
	// AnnotationKeyRuntimeDevelopmentTarget can be used to configure the gRPC
	// target where the Function is listening. The default is localhost:9443.
	AnnotationKeyRuntimeDevelopmentTarget = "render.crossplane.io/runtime-development-target"
)

Annotations that can be used to configure the Development runtime.

View Source
const AnnotationKeyRuntimeDockerPullPolicy = "render.crossplane.io/runtime-docker-pull-policy"

AnnotationKeyRuntimeDockerPullPolicy can be added to a Function to control how its runtime image is pulled.

View Source
const DefaultCrossplaneImage = "xpkg.crossplane.io/crossplane/crossplane"

DefaultCrossplaneImage is the default Crossplane image used for rendering.

View Source
const ExitCodePipelineFatal = 3

ExitCodePipelineFatal is the exit code that `crossplane internal render` returns when a pipeline step responds with SEVERITY_FATAL. The binary populates stdout with a partial RenderResponse on this code so callers can recover output.RequiredResources (and similar) and iterate. See crossplane/crossplane#7455 for the upstream contract.

View Source
const FunctionPort = 9443

FunctionPort is the port that Composition Functions listen on inside their container.

Variables

This section is empty.

Functions

func BuildCompositeRequest

func BuildCompositeRequest(in CompositionInputs) (*renderv1alpha1.RenderRequest, error)

BuildCompositeRequest builds a RenderRequest for a composite resource from the supplied inputs and function addresses.

func BuildContextData

func BuildContextData(fs afero.Fs, ctxFiles, ctxValues map[string]string) (map[string][]byte, error)

BuildContextData merges --context-files and --context-values into a single map. Files are read first; values take precedence when a key appears in both.

func BuildOperationRequest

func BuildOperationRequest(in OperationInputs) (*renderv1alpha1.RenderRequest, error)

BuildOperationRequest builds a RenderRequest for an Operation from the supplied inputs and function addresses.

func LoadCompositeResource

func LoadCompositeResource(fs afero.Fs, file string) (*composite.Unstructured, error)

LoadCompositeResource from a YAML manifest.

func LoadComposition

func LoadComposition(fs afero.Fs, file string) (*apiextensionsv1.Composition, error)

LoadComposition form a YAML manifest.

func LoadCredentials

func LoadCredentials(fs afero.Fs, file string) ([]corev1.Secret, error)

LoadCredentials from a stream of YAML manifests.

func LoadFunctions

func LoadFunctions(filesys afero.Fs, file string) ([]pkgv1.Function, error)

LoadFunctions from a stream of YAML manifests.

func LoadObservedResources

func LoadObservedResources(fs afero.Fs, file string) ([]composed.Unstructured, error)

LoadObservedResources from a stream of YAML manifests.

func LoadRequiredResources

func LoadRequiredResources(fs afero.Fs, file string) ([]unstructured.Unstructured, error)

LoadRequiredResources from a stream of YAML manifests.

func LoadRequiredSchemas

func LoadRequiredSchemas(fs afero.Fs, dir string) ([]spec3.OpenAPI, error)

LoadRequiredSchemas loads OpenAPI v3 schema documents from a directory, recursively. Each file should contain a single OpenAPI v3 document in JSON format (as returned by /openapi/v3/<group-version>).

func LoadXRD

LoadXRD from a YAML manifest.

func LoadYAMLStream

func LoadYAMLStream(filesys afero.Fs, fileOrDir string) ([][]byte, error)

LoadYAMLStream from the supplied file or directory. Returns an array of byte arrays, where each byte array is expected to be a YAML manifest.

func LoadYAMLStreamFromFile

func LoadYAMLStreamFromFile(fs afero.Fs, file string) ([][]byte, error)

LoadYAMLStreamFromFile from the supplied file. Returns an array of byte arrays, where each byte array is expected to be a YAML manifest.

func OverrideFunctionAnnotations

func OverrideFunctionAnnotations(fns []pkgv1.Function, annotations []string) error

OverrideFunctionAnnotations applies annotation overrides from flags to functions.

func ParseContextData

func ParseContextData(raw map[string][]byte) (map[string]any, error)

ParseContextData parses each raw context value as YAML/JSON and returns a map suitable for seeding the pipeline context.

func PullImage

func PullImage(ctx context.Context, p pullClient, image string, options typesimage.PullOptions) error

PullImage pulls the supplied image using the supplied client. It blocks until the image has either finished pulling or hit an error.

func ReplaceConditionTimestamps added in v2.3.2

func ReplaceConditionTimestamps(o runtime.Object) error

ReplaceConditionTimestamps replaces the lastTransitionTime timestamps in any of the argument's conditions with a static timestamp (the same one used by the old CLI renderer). This makes render output stable across runs despite the render engine producing real timestamps. It is a no-op if the argument does not have a status or has a status without conditions.

func RewriteAddressesForDocker

func RewriteAddressesForDocker(fns []*renderv1alpha1.FunctionInput) []*renderv1alpha1.FunctionInput

RewriteAddressesForDocker rewrites function addresses so they are reachable from inside a Docker container. Addresses targeting localhost or 127.0.0.1 are rewritten to host.docker.internal.

func StopFunctionRuntimes

func StopFunctionRuntimes(log logging.Logger, fa *FunctionAddresses)

StopFunctionRuntimes stops all function runtimes with a timeout.

Types

type Annotations added in v2.4.0

type Annotations map[string]string

Annotations is a type used to store annotations.

func NewAnnotationsFromStrings added in v2.4.0

func NewAnnotationsFromStrings(annotations []string) Annotations

NewAnnotationsFromStrings parses an array of strings in the format "key=value" into a map. Silently skips strings in incorrect format.

type CompositionInputs

type CompositionInputs struct {
	CompositeResource   *ucomposite.Unstructured
	Composition         *apiextensionsv1.Composition
	FunctionAddrs       map[string]string
	FunctionCredentials []corev1.Secret
	ObservedResources   []composed.Unstructured
	RequiredResources   []kunstructured.Unstructured
	RequiredSchemas     []spec3.OpenAPI

	// XRD is the CompositeResourceDefinition the binary should consider
	// when rendering. The binary uses it to pick the right composite.Schema
	// (Legacy vs Modern) for the input XR's GVK, mirroring the production
	// reconciler. Optional; when nil the binary falls back to its default
	// behavior (Schema=Modern).
	XRD *kunstructured.Unstructured
}

CompositionInputs contains all inputs to the render process.

type CompositionOutputs

type CompositionOutputs struct {
	CompositeResource *ucomposite.Unstructured
	ComposedResources []composed.Unstructured
	Results           []kunstructured.Unstructured
	Context           *kunstructured.Unstructured
	RequiredResources []*fnv1.ResourceSelector
	RequiredSchemas   []*fnv1.SchemaSelector
}

CompositionOutputs contains all outputs from the render process.

func ParseCompositeResponse

func ParseCompositeResponse(out *renderv1alpha1.CompositeOutput) (CompositionOutputs, error)

ParseCompositeResponse converts a CompositeOutput into Outputs for the CLI.

type DockerCleanup

type DockerCleanup string

DockerCleanup specifies what Docker should do with a Function container after it has been run.

const (
	// AnnotationValueRuntimeDockerCleanupStop is the default. It stops the
	// container once rendering is done.
	AnnotationValueRuntimeDockerCleanupStop DockerCleanup = "Stop"

	// AnnotationValueRuntimeDockerCleanupRemove stops and removes the
	// container once rendering is done.
	AnnotationValueRuntimeDockerCleanupRemove DockerCleanup = "Remove"

	// AnnotationValueRuntimeDockerCleanupOrphan leaves the container running
	// once rendering is done.
	AnnotationValueRuntimeDockerCleanupOrphan DockerCleanup = "Orphan"

	AnnotationValueRuntimeDockerCleanupDefault = AnnotationValueRuntimeDockerCleanupRemove
)

Supported AnnotationKeyRuntimeDockerCleanup values.

func GetDockerCleanup

func GetDockerCleanup(fn pkgv1.Function) (DockerCleanup, error)

GetDockerCleanup extracts Cleanup configuration from the supplied Function.

type DockerPullPolicy

type DockerPullPolicy string

DockerPullPolicy can be added to a Function to control how its runtime image is pulled by Docker.

const (
	// AnnotationValueRuntimeDockerPullPolicyAlways always pulls the image.
	AnnotationValueRuntimeDockerPullPolicyAlways DockerPullPolicy = "Always"

	// AnnotationValueRuntimeDockerPullPolicyNever never pulls the image.
	AnnotationValueRuntimeDockerPullPolicyNever DockerPullPolicy = "Never"

	// AnnotationValueRuntimeDockerPullPolicyIfNotPresent pulls the image if
	// it's not present.
	AnnotationValueRuntimeDockerPullPolicyIfNotPresent DockerPullPolicy = "IfNotPresent"

	AnnotationValueRuntimeDockerPullPolicyDefault DockerPullPolicy = AnnotationValueRuntimeDockerPullPolicyIfNotPresent
)

Supported pull policies.

func GetDockerPullPolicy

func GetDockerPullPolicy(fn pkgv1.Function) (DockerPullPolicy, error)

GetDockerPullPolicy extracts PullPolicy configuration from the supplied Function.

type Engine

type Engine interface {
	// CheckContextSupport validates whether context injection and collection
	// works with this engine in the current runtime environment.
	CheckContextSupport() error

	// Setup performs engine-specific pre-render preparation, such as
	// creating Docker networks and annotating functions so their containers
	// can reach the render engine. It may mutate fns. The returned cleanup
	// function must be called when rendering is done.
	Setup(ctx context.Context, fns []pkgv1.Function) (cleanup func(), err error)

	// Render executes the render request and returns the response.
	//
	// On a pipeline-fatal exit (ExitCodePipelineFatal — see
	// crossplane/crossplane#7455), Render may return BOTH a non-nil partial
	// response AND a non-nil error. Callers that need to recover
	// output.RequiredResources (or any other partial output) must check the
	// returned response even when err != nil. Standard "nil-rsp on err"
	// callers can ignore this; the response will simply be nil for them on
	// any other failure mode.
	Render(ctx context.Context, req *renderv1alpha1.RenderRequest) (*renderv1alpha1.RenderResponse, error)
}

An Engine executes a crossplane internal render request and returns the response.

func NewEngineFromFlags

func NewEngineFromFlags(f *EngineFlags, log logging.Logger) Engine

NewEngineFromFlags creates an Engine from the flag configuration. If a binary path is set, it returns a local engine. Otherwise it returns a Docker engine using the resolved image reference.

type EngineFlags

type EngineFlags struct {
	CrossplaneVersion       string `` /* 149-byte string literal not displayed */
	CrossplaneImage         string `` /* 149-byte string literal not displayed */
	CrossplaneBinary        string `` /* 193-byte string literal not displayed */
	CrossplaneDockerNetwork string `help:"The docker network to start the crossplane container in"                                      xor:"crossplane-docker"`
}

EngineFlags contains flags for configuring the render engine. It is embedded by render command structs to provide shared engine configuration.

func (*EngineFlags) SetDefaultCrossplaneDockerNetwork added in v2.4.0

func (f *EngineFlags) SetDefaultCrossplaneDockerNetwork(fns []pkgv1.Function)

SetDefaultCrossplaneDockerNetwork defaults the Crossplane render engine's Docker network to the first function runtime Docker network annotation. If network is already set, return with no changes.

type FunctionAddresses

type FunctionAddresses struct {
	// contains filtered or unexported fields
}

FunctionAddresses maps function names to their gRPC target addresses.

func StartFunctionRuntimes

func StartFunctionRuntimes(ctx context.Context, log logging.Logger, fns []pkgv1.Function) (*FunctionAddresses, error)

StartFunctionRuntimes starts the runtime for each function and returns their gRPC addresses. The caller must call Stop on the returned FunctionAddresses when done.

func (*FunctionAddresses) Addresses

func (fa *FunctionAddresses) Addresses() map[string]string

Addresses returns the function name to gRPC address map.

func (*FunctionAddresses) Stop

func (fa *FunctionAddresses) Stop(ctx context.Context) error

Stop all function runtimes.

type MockEngine

type MockEngine struct {
	MockCheckContextSupport func() error
	MockSetup               func(ctx context.Context, fns []pkgv1.Function) (func(), error)
	MockRender              func(ctx context.Context, req *renderv1alpha1.RenderRequest) (*renderv1alpha1.RenderResponse, error)
}

MockEngine is a function-field mock of the Engine interface.

func (*MockEngine) CheckContextSupport

func (m *MockEngine) CheckContextSupport() error

CheckContextSupport calls MockCheckContextSupport. If unset, it returns nil.

func (*MockEngine) Render

Render calls MockRender. If unset, it returns a RenderResponse echoing the request's composite resource as the output.

func (*MockEngine) Setup

func (m *MockEngine) Setup(ctx context.Context, fns []pkgv1.Function) (func(), error)

Setup calls MockSetup. If unset, it returns a no-op cleanup and no error.

type OperationInputs

type OperationInputs struct {
	Operation           *opsv1alpha1.Operation
	FunctionAddrs       map[string]string
	FunctionCredentials []corev1.Secret
	RequiredResources   []kunstructured.Unstructured
	RequiredSchemas     []spec3.OpenAPI
}

OperationInputs contains all inputs to the render process for an operation.

type OperationOutputs

type OperationOutputs struct {
	Operation         *opsv1alpha1.Operation
	AppliedResources  []kunstructured.Unstructured
	Results           []kunstructured.Unstructured
	Context           *kunstructured.Unstructured
	RequiredResources []*fnv1.ResourceSelector
	RequiredSchemas   []*fnv1.SchemaSelector
}

OperationOutputs contains all outputs from the render process.

func ParseOperationResponse

func ParseOperationResponse(out *renderv1alpha1.OperationOutput) (OperationOutputs, error)

ParseOperationResponse converts an OperationOutput into unstructured types for the CLI.

type Runtime

type Runtime interface {
	// Start the Function.
	Start(ctx context.Context) (RuntimeContext, error)
}

A Runtime runs a Function.

func GetRuntime

func GetRuntime(fn pkgv1.Function, log logging.Logger) (Runtime, error)

GetRuntime for the supplied Function, per its annotations.

type RuntimeContext

type RuntimeContext struct {
	// Target for RunFunctionRequest gRPCs.
	Target string

	// Stop the running Function.
	Stop func(context.Context) error
}

RuntimeContext contains context on how a Function is being run.

type RuntimeDevelopment

type RuntimeDevelopment struct {
	// Target is the gRPC target for the running function, for example
	// localhost:9443.
	Target string

	// Function is the name of the function to be run.
	Function string
	// contains filtered or unexported fields
}

RuntimeDevelopment is largely a no-op. It expects you to run the Function manually. This is useful for developing Functions.

func GetRuntimeDevelopment

func GetRuntimeDevelopment(fn pkgv1.Function, log logging.Logger) *RuntimeDevelopment

GetRuntimeDevelopment extracts RuntimeDevelopment configuration from the supplied Function.

func (*RuntimeDevelopment) Start

Start does nothing. It returns a Stop function that also does nothing.

type RuntimeDocker

type RuntimeDocker struct {
	// Image to run
	Image string

	// Container name
	Name string

	// Cleanup controls how the containers are handled after rendering.
	Cleanup DockerCleanup

	// PullPolicy controls how the runtime image is pulled.
	PullPolicy DockerPullPolicy

	// Keychain to use for pulling images from private registry.
	Keychain authn.Keychain

	// Env is the list of environment variables to set for the container.
	Env []string

	// BindAddress is the address to bind the function container to.
	BindAddress string

	// Target is the host address to use when connecting to the function.
	// If empty, it defaults to the published HostIP from Docker inspect.
	// When published on 0.0.0.0, set this explicitly (e.g. the remote Docker host).
	Target string

	// Network is the Docker network to connect the Function container to.
	// When empty (the default), the container uses the default Docker network
	// and is reached via host port bindings. When set, the container joins
	// the specified network and is reached via its Docker hostname on port 9443.
	Network string
	// contains filtered or unexported fields
}

RuntimeDocker uses a Docker daemon to run a Function.

func GetRuntimeDocker

func GetRuntimeDocker(fn pkgv1.Function, log logging.Logger) (*RuntimeDocker, error)

GetRuntimeDocker extracts RuntimeDocker configuration from the supplied Function.

func (*RuntimeDocker) Start

Start a Function as a Docker container.

type RuntimeInProcess

type RuntimeInProcess struct{}

RuntimeInProcess is a no-op runtime for functions the CLI hosts in-process. The real target is injected by the caller after StartFunctionRuntimes returns.

func (RuntimeInProcess) Start

Start does nothing and returns an empty target.

type RuntimeType

type RuntimeType string

RuntimeType is a type of Function runtime.

const (
	// AnnotationValueRuntimeDocker uses a Docker daemon to run a Function. It
	// uses the standard DOCKER_ environment variables to determine how to
	// connect to the daemon.
	AnnotationValueRuntimeDocker RuntimeType = "Docker"

	// AnnotationValueRuntimeDevelopment expects you to deploy a Function
	// locally. This is mostly useful when developing a Function. The Function
	// must be running with the --insecure flag, i.e. without transport security.
	AnnotationValueRuntimeDevelopment RuntimeType = "Development"

	// AnnotationValueRuntimeInProcess indicates that the Function is hosted
	// in-process by the CLI itself. The CLI owns the listener lifecycle and
	// injects the real target post-hoc; the runtime's Start is a no-op.
	AnnotationValueRuntimeInProcess RuntimeType = "InProcess"

	AnnotationValueRuntimeDefault = AnnotationValueRuntimeDocker
)

Supported runtimes.

Directories

Path Synopsis
Package contextfn implements an in-process composition function that the CLI hosts to inject and capture pipeline context for `crossplane render`.
Package contextfn implements an in-process composition function that the CLI hosts to inject and capture pipeline context for `crossplane render`.
Package op implements operation rendering using operation functions.
Package op implements operation rendering using operation functions.
Package xr implements composite resource (XR) rendering.
Package xr implements composite resource (XR) rendering.

Jump to

Keyboard shortcuts

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