Managed control planes expose a set of APIs for users to interact with their control planes. Configurations define these APIs.

Configurations are a Crossplane package that bundles a set of API definitions. Every Crossplane Configuration in the Upbound environment has its source synced directly from a Git repository. Users choose from this selection of Configurations in their Upbound environment when they want to install a set of APIs on a managed control plane.

How configurations work on Upbound

All managed control planes on Upbound install configurations from a definition stored in a Version Control Service. Configurations in Upbound are special objects that you can create directly from the Console or via the up CLI. When you create a Configuration choose to either:

• start from a gallery of existing Configurations curated by Upbound
• start from a scratch configuration, which is an empty configuration with a placeholder crossplane.yaml file

Upbound automatically creates a Git repository in your version control service provider on your behalf. After Upbound creates your repository, it watches for new commits to the main branch. For every commit, Upbound automatically attempts to build the Configuration package for you. If it’s successful, you can then upgrade the definition on your managed control planes.

Because Git is the source of truth for a control plane’s APIs, users can use typical Git workflows. Upbound deploys API changes out to their control planes once merged without users handling any of the package building processes.

Anatomy of a configuration

Creating a configuration in Upbound creates a Git repository. Configurations from the Upbound gallery contain:

• crossplane.yaml - this file is where you name your configuration, declare dependencies on Crossplane providers, and other Configurations
• apis folder - this folder is where you should define your XRDs and compositions.
• .up/examples folder - this folder contains example claims that invoke APIs defined in the Configuration

If you choose to make a blank configuration, Upbound creates a crossplane.yaml file.

Version control service integration

All Configurations in Upbound sync from Git.

Building an API

Upbound attempts to build a new version of your configuration for every commit to the main branch of the repository that backs your configuration. It’s your responsibility to push content to the repository which builds into a valid Crossplane configuration package.

Build status

Upbound uses a GitHub app to read your configuration’s repository contents. Upbound builds a configuration package for you and pushes it to Upbound. Then, you can deploy the latest configuration package your control planes. For each commit, the app reports a build status. While the configuration is building, you can see a status like below in GitHub:

When the repository contents finishes building, the Upbound GitHub app reports a green checkmark and status like below:

When the repository contents fail to build a configuration, the Upbound GitHub app reports a failure and brief message explaining why. Hover over the status text on GitHub to see the full message:

Apply an update in Upbound

When a repository builds into a configuration, Upbound shows the image as available for each control plane that has installed that configuration. You can find the update available prompt in the control plane explorer view.

Select the text to begin an update on the control plane. Confirm the update operation to kickoff the install. Notice the version string of the configuration image is a SemVer-formatted string appended with the ID of the associated commit.