search

opencontainers / distribution-spec

OCI Distribution Specification
https://opencontainers.org
Apache License 2.0
811 stars 202 forks source link

Missing backwards compatibility and upgrade procedures for Artifact Manifest #368

Closed AaronFriel closed 1 year ago

AaronFriel commented 1 year ago

The heading of the "Backwards Compatibility" section suggests to me that section(s) are missing:

Backwards Compatibility

Client implementations MUST support registries that implement partial or older versions of the OCI Distribution Spec. This section describes client fallback procedures that MUST be implemented when a new/optional API is not available from a registry.

The OCI Image Spec - artifact (apdx-7) type may not be supported by older versions of the OCI Distribution Spec, however this document prescribes that clients MUST support registries that fail to support this media type.

The oras CLI client's push command for example will automatically push an image manifest when an artifact manifest fails.

Should the oras push client behavior be documented and codified here? I believe that documenting this would clarify what should happen on oras cp and other subcommands.

sudo-bmitch commented 1 year ago

Clients MUST support older version of the distribution-spec, but the manifest definitions are part of image-spec. Registries and clients may chose to reject unknown media types, and the distribution-spec describes the Accept headers the clients should send, and the responses from the registry when it rejects a manifest.

So if a registry does not support the artifact manifest, and a client attempts to push it, the registry should reject it with an error (I believe MANIFEST_INVALID or MANIFEST_UNKNOWN). The client should then fail it's attempt to push.

I would strongly discourage an automatic fallback from Artifact to Image manifests. Attempting to do this changes the manifest, so it is no longer the same, breaking reproducibility and the ability to compare manifests across different registries. When creating a manifest with an automatic fallback capability, there would be a motivation to default to the Artifact manifest and rely on the fallback, which will create non-portable manifests the moment the originating registry is upgraded before all other registries where the artifact may be later copied. And if an automatic fallback is attempted on a copy of an artifact between registries, that would alter the digest, breaking signing and causing a significant headache for mirroring tools to try to sort out what artifact maps to which between two registries. That mapping would also break when the fallback registry is later upgraded.

Instead of an automatic fallback, I would recommend that tooling creating artifacts default to the Image manifest until there is reason to believe that all registries where the artifact may be copied have been upgraded.

AaronFriel commented 1 year ago

@sudo-bmitch I've changed my mind here, see:

https://github.com/opencontainers/image-spec/pull/1004/files#r1093930361