Skip to main content

Build and push a project

This guide explains how to build your control plane project into a versioned artifact and push it to the Upbound Marketplace for deployment.

Control plane projects are source-level representations of your control plane. Like any other software project, control plane projects require a build stage to assemble all parts of your project into a versioned artifact.

Before you start​

Before you build and push your control plane project, ensure:

  • You have the up CLI installed
  • You have a complete control plane project with an upbound.yaml file
  • You have login credentials for Upbound

Build your control plane project​

Build the dependencies and metadata in your Upbound project as a single OCI image.

  1. Run the build command in your control plane project directory.

    up project build

    This command builds functions, generates language-specific schemas, and packages everything into a single .uppkg file. New builds update the control plane project dependency cache in the same way running the up dependency update-cache command does.

    The command builds the image in your control plane project directory in _output/<userProject>.uppkg.

How the build process works​

The up project build command builds and packages your configuration and embedded functions through several steps:

  1. Build embedded function packages - Each function in the project functions/ directory builds into a Crossplane function package by adding your code to a base image and generating metadata.

  2. Generate Configuration Package Metadata - The up CLI creates Crossplane configuration package metadata based on your project, including dependencies on the embedded functions.

  3. Build the Configuration Package - All relevant YAML files (XRDs and compositions) bundle into a Crossplane configuration package using the generated metadata.

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

Push your project to the Upbound Marketplace​

Upload your built project to make it available for deployment to control planes.

  1. Login to Upbound.

    up login

  2. Push your package to the Upbound Marketplace.

    up project push

    If you don't have a Marketplace repository, the up project push command automatically creates the repository based on the spec.repository field in your upbound.yaml file. When you push a project with embedded functions, Upbound automatically creates sub-repositories for these functions.

How the push process works​

The up project push command uploads your configuration and its embedded functions to the Upbound Marketplace:

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

Use embedded functions in compositions​

Reference your embedded functions in compositions to make use of the custom logic you've built.

  1. Understand the function reference format. The functionRef name follows this format: [organization-name]-[project-name][function-name].

  2. Add the function reference to your composition pipeline.

    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

    For example, if your organization is my-org and your project is my-conf, use the naming pattern shown above.

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 manually in the functionRef parameter.

Note: Embedded functions require Crossplane 1.18 or later.

See also​