Creating and Pushing Packages

Package types

Crossplane supports these package types: Configurations, Functions and Providers.

• Configuration packages combine Crossplane Composite Resource Definitions, Compositions and metadata.
• Function packages include the compiled function code for single or multiple processor architectures.
• 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.

Prerequisites

• Building and pushing packages require the crossplane CLI.
• Pushing packages requires an Upbound account.

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

Before pushing a package you must login to the Upbound Marketplace using docker login. You can also use up login with a configured credential helper.

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.

tip

All newly created repositories are public by default. To create a private repository, use the --private flag.

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 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's backing registry for pulling. If you wish to publish a Marketplace listing page, see Publishing public packages.

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

Users can now publish their own Marketplace listing pages with the up repository update command with the --publish flag. This requires up CLI version v0.39.0 or later.

Your repository's listing page is automatically generated at: https://marketplace.upbound.io/<package_type>/<organization or user>/<repository>/

info

To report a package you believe is violating the legal Terms of Service, use the "Report this package" link at the bottom left corner of a listing.

The table below illustrates the relationship between accessing an image and publishing a public Marketplace listing page.

	Published	Not Published
Public	Pull: Anyone View: Anyone	Pull: Anonymous View: No one
Private	Pull: Authorized View: Authorized	Pull: Authorized View: No one

Adding documentation, icons, and other assets to your package

Users may also provide their additive package content, which renders on the listing page for that package version.

The Marketplace currently supports optionally adding an icon, release notes, readme, and SBOMs. By convention, organize these files in a directory-of-directories hierarchy, typically in the source tree. For example, the following is a valid layout for an icon, readme, and release notes:

extensions
├── icons
│   └── icon.svg
├── readme
│   └── readme.md
└── release-notes
    └── release_notes.md

Then, to add these assets to your package version, use the up CLI:

up alpha xpkg append --extensions-root=./extensions xpkg.upbound.io/<your account>/<your repository>:<version>

warning

This is an alpha feature, and requires up CLI version v0.39.0 or later. See up alpha xpkg append for complete documentation and conventions.

Troubleshooting

A package is in the repository 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.