Introduction

An index sha is a sha256 sum which is generated from an image index json file. View the definition of an image index here: https://github.com/opencontainers/image-spec/blob/main/image-index.md. Below is the image index for the zarf agent at version v0.32.6. There are three distinct digests that are created for this image. There is the arm64 digest, the amd64 digest, and the index digest. The index digest value is sha256 of the below index.json.

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:b3fabdc7d4ecd0f396016ef78da19002c39e3ace352ea0ae4baa2ce9d5958376",
      "size": 673,
      "platform": {
        "architecture": "arm64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:454bf871b5d826b6a31ab14c983583ae9d9e30c2036606b500368c5b552d8fdf",
      "size": 673,
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    }
  ]
}

Index Sha in Zarf

When an image is pulled by tag Zarf will automatically pull the platform for the package's architecture. However this cannot be done with an index sha as the sha in the zarf.yaml wouldn't match the sha in the built package. Additionally, users would likely have their Kubernetes manifests use the image index sha which would not work if a specific platform sha was instead pulled.

Many images have several platforms, nginx:1.29-perl, for example has eight and still many others have more. In order to keep the index sha in tact, Zarf would have to pull in every image which in this case would mean the image takes up 8x the amount of space. Most users don't want this and would instead rather pull a specific image, so we decided to error and force them to choose their image from a printed list of supported platforms.

Alternatives

Make architecture a list

If .metadata.architecture was a list users could pull set both amd64 and arm64. In this case every image would need both of these architectures or their package build would fail. We would allow index sha's when the package has more than one architecture

Considerations

• Less likely for users to mess up and accidentally bloat their packages as they will receive an explicit fail and have to manually set their architecture in order to pull all the architectures we want
• Maybe should change this in the next schema version?

Handle index sha's

When an image index sha is used pull the index.json along with all the manifest entries and push everything up to the Zarf registry.

Considerations

• Users will need to use SHAs to have multi-platform support
• Zarf will label the package as a amd64 or arm64 architecture and it will be at least partially lying
• Users who don't understand how OCI work might be confused as to why seemingly one image is taking up potentially 8x the amount of space they thought it would (not everyone reads warnings)
• Not a breaking change since we would only act on image indexes which are already broken.
• In this case, every image would need to pulled by index sha for the package to be truly multi-arch.