function-pkl

This composition function allows to deploy Crossplane Managed Resources from Pkl Packages.

Installation

apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-pkl
spec:
  package: xpkg.upbound.io/crossplane-contrib/function-pkl:v0.0.1

Usage

To use this function add the following to your composition:

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: function-pkl
spec:
  compositeTypeRef:
    apiVersion: example.crossplane.io/v1
    kind: XR
  mode: Pipeline
  pipeline:
  - step: run-the-template
    functionRef:
      name: function-pkl
    input:
      apiVersion: pkl.fn.crossplane.io/v1beta1
      kind: Pkl
      spec:
        type: uri
        # This pkl file is at `pkl/crossplane.contrib.example/compositions/steps/full.pkl` in this repo
        uri: "package://pkg.pkl-lang.org/github.com/crossplane-contrib/function-pkl/crossplane.contrib.example@0.0.1#/compositions/steps/full.pkl"

Example

see examples and see pkl/crossplane.contrib.example/DEPLOY.md on instructions how to deploy using Pkl Packages.

Alternatively example/git/README.md shows an appraoch without releasing Packages.

Creating a new Composition Function

see pkl/crossplane.contrib.example/DEVELOP.md

Development

This function uses Go, Docker, the Crossplane CLI, and the Pkl CLI to build functions

# Run code generation - see input/generate.go
$ make generate

# Run tests - see fn_test.go
$ go test ./...

# Build the function's runtime image and package it - see Dockerfile and package/crossplane.yaml
$ make build-image

# Push the Package to a registry
$ crossplane xpkg push -f function-pkl*.xpkg ghcr.io/crossplane-contrib/function-pkl

# Resolve Pkl Project Dependencies
$ make pkl-resolve

# Release a Pkl Project
$ git tag crossplane.contrib@x.y.z
$ git push --tags

# Packages the Pkl Projects. Uses the latest existing git tags to version them.
$ make pkl-package

# Manually release a Pkl Package on github
$ make pkl-release TAG=crossplane.contrib@x.y.z

# Debugging this function
# While a Debugging session is running run on the same host:
$ crossplane beta render xr.yaml composition.yaml functions.yaml --verbose

Creating a new Release

Composition Function

Run the CI action and provide a Package version.

Pkl Packages

Create a git tag in the style of <PklProject.package.name>@<PklProject.package.version> e.g. git tag crossplane.contrib@0.0.1

Push it git push --tags

Pkl Function Flow

This Chart illustrates the intereactions between the function and Pkl, when Crossplane Triggers this Composition Function.

sequenceDiagram
    participant fun as RunFunction
    box rgb(20, 100, 60) Pkl Files
        participant full.pkl as full.pkl
        participant c.pkl as crossplane.pkl
    end
    box rgb(20,60,100) CrossplaneReader
        participant c.r as crossplane:request
    end

    fun->>fun: Create Pkl Evaluator
    activate fun
    fun->>full.pkl: Evaluate Pkl File
    full.pkl->>c.pkl: import
    c.pkl->>full.pkl: Module with helper functions
    full.pkl->>+c.pkl: get CompositionRequest
        c.pkl->>c.r: Get RunFunctionRequest
        c.r->>c.pkl: Return it in yaml
        c.pkl->>c.pkl: convert from yaml to Pkl Objects
    c.pkl->>-full.pkl: return CompositionRequest
    full.pkl->>fun: Function Respone
    deactivate fun

Loading