feat: add platform option to push command

[TerryHowe]

What this PR does / why we need it:

Add the platform option to the push command for example:

oras push --plain-http localhost:15000/oras:darwin,arm64  --artifact-platform darwin/arm64 --artifact-type 'application/vnd.oci.image.config.v1+json'  bin/darwin/arm64/oras:application/x-elf

Create the manifest for example:

oras manifest index create localhost:15000/oras:v1 sha256:ed3691788db69623790c46256dd11d8d6edc31be6e4762b53c74dfc3bb6792cf

The results

% oras manifest fetch --pretty localhost:15000/oras@sha256:c9e54542075ad502900d11b9b5d5bdb4b974ad580842515684d3fbb4849e2bb1
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.oci.image.config.v1+json",
  "config": {
    "mediaType": "application/vnd.unknown.config.v1+json",
    "digest": "sha256:e9302bbb2fb8f6c2df866d3c4e41917849442f89a575f36f43366a7279804f70",
    "size": 38
  },
  "layers": [
    {
      "mediaType": "application/x-elf",
      "digest": "sha256:69c16b8386b7949fe37ff2356296b6331c1e6d5fbbc3e616192cc10ece55ea8d",
      "size": 11673840,
      "annotations": {
        "org.opencontainers.image.title": "bin/darwin/amd64/oras"
      }
    }
  ],
  "annotations": {
    "org.opencontainers.image.created": "2024-09-16T16:54:48Z"
  }
}
% oras manifest fetch-config --pretty localhost:15000/oras@sha256:c9e54542075ad502900d11b9b5d5bdb4b974ad580842515684d3fbb4849e2bb1
{
  "architecture": "amd64",
  "os": "darwin"
}

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Closes #1066
Partial #1053

Please check the following list:

• Does the affected code have corresponding tests, e.g. unit test, E2E test?
• Does this change require a documentation update?
• Does this introduce breaking changes that would require an announcement or bumping the major version?
• Do all new files have an appropriate license header?

[codecov]

Codecov Report

Attention: Patch coverage is 82.60870% with 4 lines in your changes missing coverage. Please review.

Project coverage is 85.95%. Comparing base (1d60e22) to head (0a9eb54).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
cmd/oras/root/push.go	77.77%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1500      +/-   ##
==========================================
- Coverage   85.97%   85.95%   -0.02%     
==========================================
  Files         118      118              
  Lines        4228     4251      +23     
==========================================
+ Hits         3635     3654      +19     
- Misses        354      356       +2     
- Partials      239      241       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Wwwsylvia]

LGTM with nit, but I am not a maintainer.

[sabre1041]

LGTM

[qweeah]

LGTM with minor suggestion

[qweeah]

Sorry merging 55cf426 is not intended, I was playing with the PR locally and the upstream is accidentally set to this PR.

[TerryHowe]

Sorry merging 55cf426 is not intended, I was playing with the PR locally and the upstream is accidentally set to this PR.

reverted

[shizhMSFT]

In fact, I have a more fundamental question: How do I specify both artifactType and config.mediaType? It seems not possible for image-spec 1.1 in the current PR.

We need the ability to set config.mediaType to application/vnd.oci.image.config.v1+json when --artifact-platform is set in order to support OCI volumes. /cc @FeynmanZhou

[TerryHowe]

In fact, I have a more fundamental question: How do I specify both artifactType and config.mediaType? It seems not possible for image-spec 1.1 in the current PR.

This is out of the scope for this PR and I don't think that was possible before this PR.

[shizhMSFT]

This is out of the scope for this PR and I don't think that was possible before this PR.

Can you mark the flag --artifact-platform as [Experimental] or [Preview] so that we can complete it in next few iterations / PRs?

[shizhMSFT]

LGTM

[qweeah]

In fact, I have a more fundamental question: How do I specify both artifactType and config.mediaType? It seems not possible for image-spec 1.1 in the current PR.

Through oras push --artifact-type $ARTIFACT_TYPE --config $CONFIG_PATH:$CONFIG_TYPE. It's by design --artifact-platform cannot be used to customize any media type.

[qweeah]

We need the ability to set config.mediaType to application/vnd.oci.image.config.v1+json when --artifact-platform is set in order to support OCI volumes. /cc @FeynmanZhou

In that case --image-spec v1.0 --artifact-type application/vnd.oci.image.config.v1+json --artifact-platform xxx/xxx

[shizhMSFT]

We need the ability to set config.mediaType to application/vnd.oci.image.config.v1+json when --artifact-platform is set in order to support OCI volumes. /cc @FeynmanZhou

In that case --image-spec v1.0 --artifact-type application/vnd.oci.image.config.v1+json --artifact-platform xxx/xxx

This workaround should work.

[qweeah]

We need the ability to set config.mediaType to application/vnd.oci.image.config.v1+json when --artifact-platform is set in order to support OCI volumes. /cc @FeynmanZhou

In that case --image-spec v1.0 --artifact-type application/vnd.oci.image.config.v1+json --artifact-platform xxx/xxx

This workaround should work.

It just came to me that if application/vnd.oci.image.config.v1 is a critical scenario that oras push --artifact-platform need to support for v1.0 image, why not making it default?

This default media type switch will only happen when --artifact-platform being used and thus is not breaking.

[TerryHowe]

This default media type switch will only happen when --artifact-platform being used and thus is not breaking.

I'm not 100% following here, maybe create an issue if you think there is something. If --artifact-platform is used, it creates a 1.1 image right now. Without specifying the image version, it creates a 1.0 imager

[qweeah]

@TerryHowe What I am thinking is to use application/vnd.oci.image.config.v1 instead of application/vnd.unknown.config.v1+json as default config media type.

Actually, it requires oras to extra work on baking the config blob to meet below spec: https://github.com/opencontainers/image-spec/blob/da92727e9c8761ec087890466b8756b755aefd37/manifest.md#L68-73

   When the `config.mediaType` is set to `application/vnd.oci.image.config.v1+json`, the following additional restrictions apply:

  - The array MUST have the base layer at index 0.
  - Subsequent layers MUST then follow in stack order (i.e. from `layers[0]` to `layers[len(layers)-1]`).
  - The final filesystem layout MUST match the result of [applying](layer.md#applying-changesets) the layers to an empty directory.
  - The [ownership, mode, and other attributes](layer.md#file-attributes) of the initial empty directory are unspecified

This work goes below the scope of oras so what I am thinking is not doable for now.

[Wwwsylvia]

Just realized that the config media type has to be application/vnd.oci.image.config.v1, otherwise the end-to-end workflow won't work. See #1517 for details.