Crossplane Packages

Crossplane Packages are a portable and reusable method to distribute Crossplane settings. Packages are Open Container Initiative (OCI) compatible containers. Packages support versioning and dependency mapping.

This section discusses installing Crossplane packages. For information about building and publishing packages read the Creating and Publishing Packages section.

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.

Install a package

Install packages using Kubernetes manifest files for the API group.

Packages hosted in the Upbound Marketplace are available from the domain.

Install a configuration package using a Configuration Kubernetes manifest. For example, this manifest installs the Upbound “AWS reference platform.”

2kind: Configuration
4  name: platform-ref-aws
6  package:

Verify the configuration installation with kubectl get pkgrev

1kubectl get pkgrev
2NAME                                                                       HEALTHY   REVISION   IMAGE                                                                   STATE    DEP-FOUND   DEP-INSTALLED   AGE    True      1   Active                               73s   True      1                    Active                               68s
6NAME                                                                    HEALTHY   REVISION   IMAGE                                             STATE    DEP-FOUND   DEP-INSTALLED   AGE   True      1   Active   2           2               75s

Install a provider package using a Provider Kubernetes manifest. For example, this manifest installs the open source Crossplane community provider for AWS.

2kind: Provider
4  name: provider-aws
6  package:
Upbound Official Providers require a PackagePullSecret to authenticate to the Upbound Marketplace.
The Authentication section contains more information about using and generating secrets for Official Providers.

Apply the manifest with kubectl apply -f.

1kubectl apply -f provider.yml created

Use kubectl get providers to view the installed provider.

1kubectl get providers
2NAME           INSTALLED   HEALTHY   PACKAGE                                           AGE
3provider-aws   True        True   8m58s

Authentication with packages

Private Upbound Marketplace repositories and Official Providers require authentication to install.

You can install packages that require authentication in one of two methods:

  • Updating the crossplane service account to use an image pull secret. This method updates the crossplane service account to use an image pull secret across all Crossplane related authentication requests.

  • Using a packagePullSecret in a Kubernetes manifest.
    This method applies an image pull secret as part of a single Kubernetes manifest to the package.

The recommended authentication method depends on the specific package and its dependencies.

Use the following table to determine which authentication method to use.

Public DependenciesPrivate Dependencies
Public Package RepositoryNo authentication required.Update the crossplane service account.
Private Package RepositoryUse a packagePullSecret.Update the crossplane service account.

Some packages include dependencies of other packages to install. For example, a configuration package may include a provider package as a dependency.


packagePullSecrets applied to a Configuration don’t apply to the dependencies. If a package’s dependencies include Official Providers or resources from another private repository you must patch the crossplane service account.

View dependencies on the package listing in the Marketplace.

Crossplane uses the crossplane service account to download and install the dependent resources. Patching the crossplane service account allows Crossplane to use the packagePullSecret across all dependent resources.

To patch the service account use the following kubectl patch command.

1kubectl patch serviceaccount crossplane \
2  -p "{\"imagePullSecrets\": [{\"name\": \"package-pull-secret\"}]}" \
3  -n upbound-system
If you didn’t install Upbound Universal Crossplane in the default upbound-system namespace, change the -n upbound-system command to match the UXP namespace.

Use kubectl describe serviceaccount crossplane -n upbound-system to verify the service account’s Image Pull secret updated.

 1kubectl describe serviceaccount crossplane -n upbound-system
 2Name:                crossplane
 3Namespace:           upbound-system
 4Labels:              app=crossplane
12Annotations: universal-crossplane
13            upbound-system
14Image pull secrets:  package-pull-secret
15Mountable secrets:   <none>
16Tokens:              <none>
17Events:              <none>
Read the Authentication section for more information on using secrets with the Marketplace.

To provide authentication information add a spec.packagePullSecret to the package install manifest. For example, to add a packagePullSecret to the AWS reference platform manifest:

2kind: Configuration
4  name: platform-ref-aws
6  package:
7  packagePullSecrets:
8    - name: package-pull-secret
If you manually created a Kubernetes secret the secret must be in the upbound-system namespace.
The must match the name of the Kubernetes secret.