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 andCRDs
.
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.
--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
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 below.
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>/
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>
up
CLI version v0.39.0
or later. See up alpha xpkg append
for complete documentation and conventions.