Creating and Pushing Packages

Package types

Crossplane supports two package types, Configurations and Providers.

  • Configuration packages combine Crossplane Composite Resource Definitions, Compositions and metadata.
  • Provider packages combine a Kubernetes controller container, associated Custom Resource Definitions (CRDs) and metadata. The Crossplane open source AWS provider package is an example a provider’s metadata and CRDs.


Build a package

Build a package using up xpkg build.

The up xpkg build command expects a crossplane.yaml file to provide the metadata for the package file.

The default name is the value in the crossplane.yaml file.

up xpkg build
xpkg saved to /home/vagrant/pkg/test-config-15ab02d92a30.xpkg

Provide a specific package name with up xpkg build --name <package name>.

By default up xpkg build saves the package to the current directory. Specify a specific location with up xpkg build -o <path>.

The up xpkg build command reference contains all available options.

Push a package

Before pushing a package you must login to the Upbound Marketplace using up login.

Create a repository

Upbound hosts packages in an Upbound repository. Create a repository with the up repository create command.

For example, to create a repository called my-repo

up repository create my-repo
upbound-docs/my-repo created

Repositories have either public or private visibility:

  • public visibility means that any published versions of your package have a public listing page in the Marketplace and authorized credentials aren’t required to pull.
  • private visibility means that any published versions of your package have a listing page that only you and other collaborators in your organization can see. Packages require authorized credentials to pulled.
All newly created repositories are public by default, and only public repositories can be created for free at this time.

View any existing repositories with up repository list.

up repo list
NAME         TYPE            PUBLIC   UPDATED
my-repo      configuration   true     23h

Add annotations to your package

The Upbound Marketplace automatically renders specific metadata annotations into listing pages. Upbound recommends that all package maintainers add these annotations into their crossplane.yaml. Adding annotations ensures listing have all the required information like licenses, links to source code, and contact information for maintainers.

Upbound supports all annotations specified in the xpkg specification.

Push a package to the repository

Push a package to the Upbound Marketplace using the up xpkg push command.

The up xpkg push command requires:

  • The repository to push a package to.
  • A package version tag. The package version tag is a semantic versioning number determining package upgrades and dependency requirements.

The push command syntax is
up xpkg push <repository>:<version tag> -f <xpkg file>.

For example, to push a package with the following parameters:

  • Repository upbound-docs/my-repo
  • Version v0.2
  • Package file named my-package.xpkg

Use the following up xpkg push command:

up xpkg push upbound-docs/my-repo:v0.2 -f my-package.xpkg
xpkg pushed to upbound-docs/my-repo:v0.2
You need to login to the Marketplace to see packages in private repositories.

The package is now available from the Upbound Marketplace. View the Marketplace listing at:<package_type>/<organization or user>/<repository>/

For example, the Upbound AWS Official Provider is a provider package in the upbound organization’s provider-aws repository. The package address is

Publishing public packages

Upbound reviews all public packages, and new repositories have a default publishing policy of requiring a one-time manual approval. Contact the Upbound team via the #upbound channel in the Crossplane Slack to request Upbound to review your package.

Upbound needs the following information before considering a package:

  • Public Git repository of the package.
  • The Upbound account to list as an owner and point of contact.
  • The Upbound repository name.

Publish status indicates whether a package version appears in the Marketplace, while privacy indicates who can access it.

PublishedNot Published
PublicPull: Anyone
View: Anyone
Pull: Anonymous
View: No one
PrivatePull: Authorized
View: Authorized
Pull: Authorized
View: No one


Published packages don’t need to be visible to pull. Verify pulling a package with any OCI client like docker or crane.

ACCEPTED means the package is available for publishing to the Marketplace, but not yet visible to others. Users can still pull the package.

A status of REJECTED means that the package isn’t available for publishing to the Marketplace. Select the status badge to get more information on why Upbound rejected the package. Users can still pull the package.

The Marketplace only publishes release versions with valid semver tags.