Skip to main content

Publish packages

Upbound repositories lets you centrally store control plane artifacts, extensions, and build dependencies as part of an integrated Upbound experience.

This guide shows you how to:

  • Create a repository on Upbound
  • Build and push a Crossplane package to a repository
  • Publish the package in the repository to the Marketplace for public consumption

Prerequisites

For this guide, you'll need:

  • The up CLI installed
  • An account on Upbound

Create a repository

Create a repository to store the Configuration created as part of this guide.

  1. Run the following command to create a new repository named quickstart-project-repo:
up repository create quickstart-project-repo
  1. Verify your repository exists with the up repository list command:
up repository list

Build a package

Build a package using crossplane xpkg build.

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

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

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

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

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

The crossplane xpkg build command reference contains all available options.

Push a package to the repository

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

The crossplane 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 crossplane 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 crossplane xpkg push command:

crossplane xpkg push upbound-docs/my-repo:v0.2 -f my-package.xpkg
xpkg pushed to upbound-docs/my-repo:v0.2
note

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: https://marketplace.upbound.io/<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 https://marketplace.upbound.io/providers/upbound/provider-aws/

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

Troubleshooting

A package is in the repository to but not in the Marketplace. Can users pull the package?

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

The package status lists ACCEPTED in the Marketplace but isn't visible.

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

The package status lists REJECTED in the Marketplace.

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.

Why are only some package versions published?

The Marketplace only publishes release versions with valid semver tags.

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.