Documentation
¶
Overview ¶
Package render implements helpers shared by the render subcommands (xr and op).
Index ¶
- Constants
- func BuildCompositeRequest(in CompositionInputs) (*renderv1alpha1.RenderRequest, error)
- func BuildContextData(fs afero.Fs, ctxFiles, ctxValues map[string]string) (map[string][]byte, error)
- func BuildOperationRequest(in OperationInputs) (*renderv1alpha1.RenderRequest, error)
- func LoadCompositeResource(fs afero.Fs, file string) (*composite.Unstructured, error)
- func LoadComposition(fs afero.Fs, file string) (*apiextensionsv1.Composition, error)
- func LoadCredentials(fs afero.Fs, file string) ([]corev1.Secret, error)
- func LoadFunctions(filesys afero.Fs, file string) ([]pkgv1.Function, error)
- func LoadObservedResources(fs afero.Fs, file string) ([]composed.Unstructured, error)
- func LoadRequiredResources(fs afero.Fs, file string) ([]unstructured.Unstructured, error)
- func LoadRequiredSchemas(fs afero.Fs, dir string) ([]spec3.OpenAPI, error)
- func LoadXRD(fs afero.Fs, file string) (*apiextensionsv1.CompositeResourceDefinition, error)
- func LoadYAMLStream(filesys afero.Fs, fileOrDir string) ([][]byte, error)
- func LoadYAMLStreamFromFile(fs afero.Fs, file string) ([][]byte, error)
- func OverrideFunctionAnnotations(fns []pkgv1.Function, annotations []string) error
- func ParseContextData(raw map[string][]byte) (map[string]any, error)
- func PullImage(ctx context.Context, p pullClient, image string, ...) error
- func ReplaceConditionTimestamps(o runtime.Object) error
- func RewriteAddressesForDocker(fns []*renderv1alpha1.FunctionInput) []*renderv1alpha1.FunctionInput
- func StopFunctionRuntimes(log logging.Logger, fa *FunctionAddresses)
- type Annotations
- type CompositionInputs
- type CompositionOutputs
- type DockerCleanup
- type DockerPullPolicy
- type Engine
- type EngineFlags
- type FunctionAddresses
- type MockEngine
- type OperationInputs
- type OperationOutputs
- type Runtime
- type RuntimeContext
- type RuntimeDevelopment
- type RuntimeDocker
- type RuntimeInProcess
- type RuntimeType
Constants ¶
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.
const AnnotationKeyRuntime = "render.crossplane.io/runtime"
AnnotationKeyRuntime can be added to a Function to control what runtime is used to run it locally.
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.
const AnnotationKeyRuntimeDockerPullPolicy = "render.crossplane.io/runtime-docker-pull-policy"
AnnotationKeyRuntimeDockerPullPolicy can be added to a Function to control how its runtime image is pulled.
const DefaultCrossplaneImage = "xpkg.crossplane.io/crossplane/crossplane"
DefaultCrossplaneImage is the default Crossplane image used for rendering.
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.
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 ¶
LoadCompositeResource from a YAML manifest.
func LoadComposition ¶
func LoadComposition(fs afero.Fs, file string) (*apiextensionsv1.Composition, error)
LoadComposition form a YAML manifest.
func LoadCredentials ¶
LoadCredentials from a stream of YAML manifests.
func LoadFunctions ¶
LoadFunctions from a stream of YAML manifests.
func LoadObservedResources ¶
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 ¶
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 ¶
func LoadXRD(fs afero.Fs, file string) (*apiextensionsv1.CompositeResourceDefinition, error)
LoadXRD from a YAML manifest.
func LoadYAMLStream ¶
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 ¶
LoadYAMLStreamFromFile from the supplied file. Returns an array of byte arrays, where each byte array is expected to be a YAML manifest.
func OverrideFunctionAnnotations ¶
OverrideFunctionAnnotations applies annotation overrides from flags to functions.
func ParseContextData ¶
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
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
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.
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 ¶
func (m *MockEngine) Render(ctx context.Context, req *renderv1alpha1.RenderRequest) (*renderv1alpha1.RenderResponse, error)
Render calls MockRender. If unset, it returns a RenderResponse echoing the request's composite resource as the output.
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.
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 ¶
func (r *RuntimeDevelopment) Start(_ context.Context) (RuntimeContext, error)
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 ¶
GetRuntimeDocker extracts RuntimeDocker configuration from the supplied Function.
func (*RuntimeDocker) Start ¶
func (r *RuntimeDocker) Start(ctx context.Context) (RuntimeContext, error)
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 ¶
func (RuntimeInProcess) Start(_ context.Context) (RuntimeContext, error)
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.
Source Files
¶
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. |