Embedded Functions

Embedded functions are composition functions that you can build, package, and manage directly in your configuration. Instead of relying on a YAML-based patch-and-transform workflow, you can write composition logic in Python or configuration languages like KCL. Embedded functions allow for shared logic across multiple compositions within your configuration.

Some benefits of using embedded functions:

  • Write configurations in familiar languages Choose from KCL, Python, or Go to control your resources
  • Integration with your existing workflow. Write functions in your configuration project and avoid tool drift
  • Full IDE support. Auto completion, syntax highlighting, and other coding tools help you write functions using best practices
  • Deploy seamlessly. Package and push your functions with your configuration in a single step.

Embedded functions are composition functions that you can build, package, and manage directly in your configuration. Instead of relying on a YAML-based patch-and-transform workflow, you can write composition logic in Python or configuration languages like KCL. Embedded functions allow for shared logic across multiple compositions within your configuration.

Prerequisites

For this guide you need:

  • The latest version of the up CLI
  • An AWS account
Important
To use embedded functions in upstream Crossplane, you must pass the --enable-dependency-version-upgrades alpha flag during installation. For more information, review the Crossplane installation options.

Initialize your project

First, scaffold a new project with the up CLI.

up project init function-demo && cd function-demo

created directory path function-demo

initialized package "function-demo" in directory "function-demo" from https://github.com/upbound/project-template (main)

Generate a project function

Use up function generate and choose between KCL or Python.

Use an embedded function

When you create functions with up function generate, the up CLI automatically adds them to the specified composition. For manually created functions or those shared across multiple compositions, reference them in the functionRef parameter.

The functionRef name follows this format: [organization-name]-[project-name][function-name]. For example, if your organization is my-org and your project is my-conf, the functionRef name would be:

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: xexample.myorg.com
spec:
  mode: Pipeline
  pipeline:
    - step: compose
      functionRef:
        name: my-org-my-confcompose-xexample
    - step: propagate-status
      functionRef:
        name: my-org-my-confpropagate-status

Build your configuration deployment

The up project build command builds and packages your configuration and embedded functions.

Here’s how it works:

Build embedded function packages:

Each function in the project functions/ directory is built into a Crossplane function package by adding your code to a base image and generating metadata.

Generate Configuration Package Metadata:

The up CLI creates Crossplane configuration package metadata based on your project, including dependencies on the embedded functions.

Build the Configuration Package:

All relevant YAML files (XRDs and compositions) are bundled into a Crossplane configuration package using the generated metadata.

Write the Packages to Disk: Embedded function and configuration packages are saved to a single .uppkg file, which up project push can use to push packages to the Upbound Marketplace.

Push your configuration

The up project push command uploads your configuration and it’s embedded functions to the Upbound Marketplace.

The .uppkg file generated by up project build contains the packages that need to be pushed. Then the packages are pushed to sub-repositories within your configuration repository. Each sub-repository name follows this naming convention [organization-name]/[project-name]_[function-name]. The configuration package, which includes dependencies on embedded functions, is also pushed. Once uploaded, your configuration is ready to be deployed to control planes like any other configuration.

Note that embedded functions require Crossplane 1.18 or later.