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 pkg.crossplane.io API group.

    Packages hosted in the Upbound Marketplace are available from the xpkg.upbound.io domain.

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

    1
2
3
4
5
6

    apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  package: xpkg.upbound.io/upbound/platform-ref-aws:v0.2.3

    Verify the configuration installation with kubectl get pkgrev

    1
2
3
4
5
6
7

    kubectl get pkgrev
NAME                                                                       HEALTHY   REVISION   IMAGE                                                                   STATE    DEP-FOUND   DEP-INSTALLED   AGE
providerrevision.pkg.crossplane.io/crossplane-provider-aws-066cc5f36957    True      1          registry.upbound.io/crossplane/provider-aws:v0.32.0-rc.0.46.g88bf9b6c   Active                               73s
providerrevision.pkg.crossplane.io/crossplane-provider-helm-b9e90b3c7ff8   True      1          registry.upbound.io/crossplane/provider-helm:v0.10.0                    Active                               68s

NAME                                                                    HEALTHY   REVISION   IMAGE                                             STATE    DEP-FOUND   DEP-INSTALLED   AGE
configurationrevision.pkg.crossplane.io/platform-ref-aws-b15ca268431b   True      1          xpkg.upbound.io/upbound/platform-ref-aws:v0.2.3   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.

    1
2
3
4
5
6

    apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-aws
spec:
  package: xpkg.upbound.io/crossplane/provider-aws:v0.24.1
    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.

    1
2

    kubectl apply -f provider.yml
provider.pkg.crossplane.io/provider-aws created

    Use kubectl get providers to view the installed provider.

    1
2
3

    kubectl get providers
NAME           INSTALLED   HEALTHY   PACKAGE                                           AGE
provider-aws   True        True      xpkg.upbound.io/crossplane/provider-aws:v0.24.1   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.

    1
2
3

    kubectl patch serviceaccount crossplane \
  -p "{\"imagePullSecrets\": [{\"name\": \"package-pull-secret\"}]}" \
  -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.

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

    kubectl describe serviceaccount crossplane -n upbound-system
Name:                crossplane
Namespace:           upbound-system
Labels:              app=crossplane
                     app.kubernetes.io/component=cloud-infrastructure-controller
                     app.kubernetes.io/instance=universal-crossplane
                     app.kubernetes.io/managed-by=Helm
                     app.kubernetes.io/name=crossplane
                     app.kubernetes.io/part-of=crossplane
                     app.kubernetes.io/version=1.9.1-up.1
                     helm.sh/chart=universal-crossplane-1.9.1-up.1
Annotations:         meta.helm.sh/release-name: universal-crossplane
                     meta.helm.sh/release-namespace: upbound-system
Image pull secrets:  package-pull-secret
Mountable secrets:   <none>
Tokens:              <none>
Events:              <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:

    1
2
3
4
5
6
7
8

    apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  package: xpkg.upbound.io/upbound/platform-ref-aws:v0.2.3
  packagePullSecrets:
    - name: package-pull-secret
    If you manually created a Kubernetes secret the secret must be in the upbound-system namespace.
    The spec.packagePullSecrets.name must match the name of the Kubernetes secret.