Add details around package management procedures (pull, push, etc)

[bobh66]

What's Missing?

Crossplane package reconciliation relies on layer annotations that are only applied when crossplane xpkg push is used to push a package into a registry. While it is physically possible to use docker pull, tag, push and other container-based commands to move packages around, they will not add the layer annotations required by Crossplane to efficiently cache and reconcile the packages.

There should be some specific information in the Packages section that details the fact that docker pull, tag, push can be used but will not add the layer annotations that Crossplane needs. Commands such as crane pull can be used to retrieve the Package from a registry, and crossplane xpkg push is currently the only "official" way to push packages to a registry with the associated annotations.

Some related Crossplane issues on the topic:

crossplane/crossplane#5579
crossplane/crossplane#5580

[bobh66]

I can take a look at this next week, I just wanted to make sure the issue got created before I forget.

[phisco]

I remember someone mentioning to use crane to copy images between registries instead of docker and one of the reasons being exactly that docker didn't preserve the manifest when pushing. 😅

[bobh66]

crane pull retrieves the package in the same format that crossplane xpkg build creates, but crane push doesn't add the layer annotations that crossplane xpkg push does. It would be nice to decouple the package from the crossplane xpkg push command so any OCI-compliant client can push and have the labels set properly.

[phisco]

crane copy is the right one iirc

[bobh66]

crane copy is the right one iirc

That worked - the package was pushed to the target repo with the layer annotations intact.

[bobh66]

One other piece of complexity - the packages on xpkg.upbound.io are multi-architecture, so the following doesn't work:

crane copy xpkg.upbound.io/upbound/[email protected]  myharbor.com/upbound/provider-aws-efs:v1.3.1
Error: parsing reference "xpkg.upbound.io/upbound/[email protected]": could not parse reference: xpkg.upbound.io/upbound/[email protected]

I have to pull the manifest for the base package and then use the sha256 value for the architecture that I want

crane copy xpkg.upbound.io/upbound/provider-aws-efs@sha256:d8653be305a1a75103dbfe8138fe2954926de51deec8dcf80b6d45056d2e92b2 myharbor.com/upbound/provider-aws-efs:v1.3.1