Project API Reference

A Project defines an Upbound project, which can be built into a Crossplane Configuration package. The project file, upbound.yaml, is the entry point for every control plane project and configures metadata, dependencies, paths, and build options.

important

An upbound.yaml is a superset of a Crossplane configuration crossplane.yaml and replaces it.

API versions

The Project resource supports two API versions:

Version	Status	Notes
meta.dev.upbound.io/v1alpha1	Storage version	Stable, recommended for most projects
meta.dev.upbound.io/v2alpha1	Alpha	Adds operations path support

Example

A minimal upbound.yaml:

apiVersion: meta.dev.upbound.io/v1alpha1
kind: Project
metadata:
  name: example-project-aws
spec:
  repository: xpkg.upbound.io/upbound/example-project-aws

A project with dependencies and metadata:

apiVersion: meta.dev.upbound.io/v2alpha1
kind: Project
metadata:
  name: my-project
spec:
  description: A control plane project for managing cloud resources.
  license: Apache-2.0
  maintainer: Upbound User <user@example.com>
  repository: xpkg.upbound.io/upbound/my-project
  source: github.com/upbound/my-project
  crossplane:
    version: ">=v2.0.0-rc.0"
  dependsOn:
    - apiVersion: pkg.crossplane.io/v1
      kind: Provider
      package: xpkg.upbound.io/upbound/provider-aws-s3
      version: ">=v2.0.0"
  paths:
    apis: apis
    functions: functions
    examples: examples
    tests: tests

Spec fields

Required

Field	Type	Description
repository	string	The OCI repository to push built packages to. Must be a fully qualified image reference, for example xpkg.upbound.io/upbound/my-project.

Package metadata

These fields become package metadata when a project is built.

Field	Type	Description
description	string	A short description of the project.
maintainer	string	The project maintainer, for example Upbound User <user@example.com>.
source	string	The source code repository URL, for example github.com/upbound/my-project.
license	string	The project license, for example Apache-2.0.
readme	string	A longer readme for the project. Supports multi-line strings.
additionalMetadata	map[string]string	Arbitrary key-value metadata pairs. All keys must have the meta.upbound.io/ prefix.

Dependencies

Field	Type	Description
crossplane	object	Crossplane version constraints. Contains a version field with a semantic version constraint, for example ">=v2.0.0-rc.0".
dependsOn	[]Dependency	Package dependencies. Each entry specifies an apiVersion, kind, package, and version.

A dependency entry:

dependsOn:
  - apiVersion: pkg.crossplane.io/v1
    kind: Provider
    package: xpkg.upbound.io/upbound/provider-aws-s3
    version: ">=v2.0.0"

Paths

The paths field configures the directories for each part of the project. All paths must be relative.

Field	Type	Default	Description
paths.apis	string	apis/	Directory holding the project's APIs (XRDs and compositions).
paths.functions	string	functions/	Directory holding embedded composition functions.
paths.examples	string	examples/	Directory holding example composite resources.
paths.tests	string	tests/	Directory holding composition and end-to-end tests.
paths.operations	string	operations/	Directory holding operation definitions. Only available in v2alpha1.

Build options

Field	Type	Default	Description
architectures	[]string	["amd64", "arm64"]	Target architectures for the built package.
imageConfig	[]ImageConfig	None	Rules for matching and rewriting container image references during build.

Image configuration

Use imageConfig to rewrite image references during build. Each entry contains:

• matchImages: A list of prefix-based matching rules. Must have at least one element.
• rewriteImage: The prefix to use when rewriting matched images.

imageConfig:
  - matchImages:
      - type: Prefix
        prefix: "docker.io/library/"
    rewriteImage:
      prefix: "registry.example.com/mirror/"

API dependencies (experimental)

warning

This is an experimental feature and is subject to change.

The apiDependencies field declares external API schema dependencies for type checking and code generation. Each entry requires a type (k8s or crd) and exactly one source:

Source	Fields	Description
git	repository (required), ref, path	Fetch from a git repository.
http	url (required)	Fetch from an HTTP/HTTPS URL.
k8s	version (required)	Use a specific Kubernetes API version, for example v1.33.0.

apiDependencies:
  - type: k8s
    k8s:
      version: v1.33.0
  - type: crd
    git:
      repository: https://github.com/example/crds
      ref: main
      path: deploy/crds

Defaults

When a project is loaded, the following defaults are applied if not specified:

• paths.apis: apis
• paths.functions: functions
• paths.examples: examples
• paths.tests: tests
• paths.operations: operations (v2alpha1 only)
• architectures: ["amd64", "arm64"]
• crossplane.version: >=v2.0.0-rc.0 (v2alpha1 only)

Validation rules

• metadata.name must not be empty.
• spec must be present.
• spec.repository must not be empty.
• All paths must be relative, not absolute.
• If architectures is specified, it must not be empty.
• All additionalMetadata keys must have the meta.upbound.io/ prefix.
• Each apiDependencies entry must specify exactly one source (git, http, or k8s).

Full CRD schema

Loading CRD documentation...

Related

• Upgrade to control plane projects
• Builder's Workshop: Project Foundations
• CLI Reference for up project commands