Specification Deviation in Multi Arch Artifacts

[TerryHowe]

What happened in your environment?

A user was mentioning that we may not be properly following the specification for multi arch artifacts. Specifically around https://github.com/opencontainers/image-spec/blob/main/artifacts-guidance.md

I don't completely understand all the details, but wanted to record that though for investigation.

What did you expect to happen?

The spec to be followed

How can we reproduce it?

Create a multiarch artifact

What is the version of your ORAS CLI?

1.3.0

What is your OS environment?

Linux

Are you willing to submit PRs to fix it?

• Yes, I am willing to fix it.

[FeynmanZhou]

@apparentlymart do you have any context regarding this issue from opentofu' point of view? @TerryHowe mentioned someone from opentofu raised this issue to us at KubeCon EU.

[TerryHowe]

@bupd you were familiar with this issue and the person that brought this up to me. Who was that again? Thanks in advance.

[TerryHowe]

Issue Assessment

After reviewing the relevant spec and code, I've identified two likely deviations.

---

Issue 1 — Missing config.mediaType fallback for descriptor artifactType

descriptor.md specifies:

artifactType in a descriptor "is the value of the config descriptor mediaType when the descriptor references an image manifest"

And manifest.md notes:

"Implementers note: artifacts have historically been created without an artifactType field, and tooling to work with artifacts should fallback to the config.mediaType value."

ORAS's enrichDescriptor in cmd/oras/root/manifest/index/create.go:239 sets:

desc.ArtifactType = manifest.ArtifactType

For old-style artifacts (those using a custom config.mediaType rather than the manifest.artifactType field — which is the case for historically created artifacts like OpenTofu providers), this leaves desc.ArtifactType empty in the index descriptor. The correct behavior is to fall back to manifest.Config.MediaType when manifest.ArtifactType is empty and config.mediaType is not the standard OCI image config type.

The fix in enrichDescriptor:

desc.ArtifactType = manifest.ArtifactType
// Fall back to config.mediaType for old-style artifacts
if desc.ArtifactType == "" && manifest.Config.MediaType != ocispec.MediaTypeImageConfig {
    desc.ArtifactType = manifest.Config.MediaType
}

The same fix is needed in cmd/oras/root/manifest/index/update.go.

---

Issue 2 — No mechanism to attach platform to artifact descriptors in an index

getPlatform (create.go:185) reads platform info from the config blob by unmarshalling it and looking for architecture/os fields. This works for OCI image configs but not for arbitrary artifact configs. For platform-specific artifacts (e.g., a per-arch provider binary), the config blob typically won't have those fields, so platform will always be nil in the index descriptor.

Currently there is no flag on oras manifest index create to explicitly specify os/arch per source manifest, so there's no way for users to produce a spec-compliant multi-platform artifact index.

A --platform flag (or similar) would be needed to allow callers to specify os/arch for artifact manifests that don't embed platform in their config.

---

Test gap

All existing unit tests in create_test.go use manifests with artifactType already set explicitly. There is no test for the old-style fallback path (artifactType empty, custom config.mediaType).

---

@apparentlymart — does either of these match what you observed? Knowing whether it's the artifactType fallback, the missing platform mechanism, or something else would help narrow down the fix.

[apparentlymart]

I'm afraid that it's been a while since I was thinking about this stuff and so I don't have the context ready in my brain, but what follows are some quick reactions based on what I was able to find with some quick research:

• OpenTofu doesn't make use of the config property of a manifest at all, because it doesn't need any additional metadata beyond what's already tracked elsewhere in the manifests.

  IIRC in our earlier instructions about manually constructing manifests (before we updated our docs to use the ORAS CLI commands) we suggested folks should set the config descriptor to refer to the zero-length blob digest and use mediaType application/vnd.oci.empty.v1+json, but as far as I can tell OpenTofu doesn't actually check that and really just ignores the config descriptor entirely.

  OpenTofu's logic for deciding whether an artifact is intended to be an OpenTofu provider package is based purely on the artifactType property, where we require application/vnd.opentofu.provider for the index manifest and application/vnd.opentofu.provider-target for each image manifest it refers to. The new features we previously contributed to ORAS CLI were primarily motivated by allowing folks to set those custom artifactType values.

  We documented what OpenTofu expects for a provider package artifact in Manifest Structure.

• While I was working on that I noticed (and briefly participated in) Identifying Platform-Specific OCI Artifacts opencontainers/image-spec#1216 where ORAS team members were discussing how ORAS could "remember" the target platform for an image manifest when someone uses oras push with the --artifact-platform option, because the only standardized place to store that information is in the descriptors in the index manifest, which doesn't exist yet at that point in the workflow.

• I think I remember finding at the time I was working on this stuff that oras push was using the config blob as a temporary place to stash the platform information, but perhaps I'm misremembering. If that's still true then I assume that means ORAS CLI itself must be generating or modifying the config blob, and so both the data in it and the mediaType used to refer to it would be decided by ORAS CLI.

With all of this said: I'm not 100% sure I understand exactly what problem this issue is aiming to solve, and so perhaps what I've shared above is not actually helpful. If it seems like I'm sharing things that aren't relevant to what you are asking please let me know and I'm happy to answer some more specific questions, either from my memory or by reading the relevant parts of the OpenTofu code.

In case it's useful context, our documentation on how to use ORAS CLI to build provider package artifacts for OpenTofu is in Assembling and Pushing Provider Manifests. In particular notice that the example oras push command only sets --artifact-platform and doesn't attempt to directly specify the content or mediaType for the "config" blob.

[github-actions]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[github-actions]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days.