feat: add how-to for multiple architecture #395
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,174 @@ | ||
| --- | ||
| title: Multi-Architecture Image/Artifact Support | ||
| sidebar_position: 110 | ||
| --- | ||
|
|
||
| # Multi-Architecture Image/Artifact Support | ||
|
|
||
| ORAS can help you create and manage multi-architecture artifacts such as configurations, executables, and container images. | ||
| This example shows how you can use ORAS to manage executables for different operating systems and architectures. | ||
|
|
||
| ## Pushing the artifacts | ||
| The first step is to push the artifact with platform information to your container registry. | ||
|
|
||
| First we push a Linux ARM64 executable: | ||
| ```console | ||
| $ oras push localhost:15000/oras:linux_arm64 --artifact-platform linux/arm64 --artifact-type 'application/vnd.oci.image.config.v1+json' bin/linux/arm64/oras:application/octet-stream | ||
| ✓ Uploaded bin/linux/arm64/oras 10.5/10.5 MB 100.00% 36ms | ||
| └─ sha256:32374a656f830f5d7504ad06c3c7be025fb38257d6793d8e70fed6f2b753c7ab | ||
| ✓ Exists application/vnd.unknown.config.v1+json 37/37 B 100.00% 0s | ||
| └─ sha256:d6f56bc20064075ce319ac2e6fcef5de9ea21773b0a8a4398c4405222971f9c0 | ||
| ✓ Uploaded application/vnd.oci.image.manifest.v1+json 581/581 B 100.00% 0s | ||
| └─ sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd | ||
| Pushed [registry] localhost:15000/oras:linux_amd64 | ||
| Tagged arm64 | ||
| ArtifactType: application/vnd.oci.image.config.v1+json | ||
| Digest: sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd | ||
| ``` | ||
|
|
||
| Next, we push a Linux AMD64 executable: | ||
| ```console | ||
| $ oras push localhost:15000/oras:linux_amd64 --artifact-platform linux/amd64 --artifact-type 'application/vnd.oci.image.config.v1+json' bin/linux/amd64/oras:application/octet-stream | ||
| ✓ Uploaded bin/linux/amd64/oras 11/11 MB 100.00% 0s | ||
| └─ sha256:4640fefdb4e22eb1308e40d5fac9fd9d16e17dfbc20202bb3ed42033d01d823e | ||
| ✓ Exists application/vnd.unknown.config.v1+json 37/37 B 100.00% 0s | ||
| └─ sha256:9d99a75171aea000c711b34c0e5e3f28d3d537dd99d110eafbfbc2bd8e52c2bf | ||
| ✓ Uploaded application/vnd.oci.image.manifest.v1+json 581/581 B 100.00% 0s | ||
| └─ sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4 | ||
| Pushed [registry] localhost:15000/oras:linux_amd64 | ||
| Tagged amd64 | ||
| ArtifactType: application/vnd.oci.image.config.v1+json | ||
| Digest: sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4 | ||
| ``` | ||
| This example pushes the executable for two architectures, but you could also push artifacts with a different operating system or other platform attribute. | ||
|
|
||
| ## Create a multi-architecture manifest | ||
|
|
||
| After you have pushed all your platform specific artifacts, create a manifest referencing them using the OCI image index format: | ||
| ```console | ||
| $ LINUX_ARM64_SHA=sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd | ||
| $ LINUX_AMD64_SHA=sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4 | ||
| $ oras manifest index create localhost:15000/oras:v1 ${LINUX_ARM64_SHA} ${LINUX_AMD64_SHA} | ||
| Fetching sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd | ||
| Fetched sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd | ||
| Fetching sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4 | ||
| Fetched sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4 | ||
| Packed 0fd4ac889c6f application/vnd.oci.image.index.v1+json | ||
| Pushed [registry] localhost:15000/oras:v1 | ||
| Digest: sha256:0fd4ac889c6f1f3e4fbb1c88b0cc18b97176bf7fd0841ac9c5264d20dd54e2d8 | ||
| ``` | ||
|
|
||
| You may also create a multi-architecture manifest with tags: | ||
| ```console | ||
| $ oras manifest index create localhost:15000/oras:v1 linux_arm64 linux_amd64 | ||
| Fetching linux_arm64 | ||
| Fetched sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd linux_arm64 | ||
| Fetching linux_amd64 | ||
| Fetched sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4 linux_amd64 | ||
| Packed 0fd4ac889c6f application/vnd.oci.image.index.v1+json | ||
| Pushed [registry] localhost:15000/oras:v1 | ||
| Digest: sha256:0fd4ac889c6f1f3e4fbb1c88b0cc18b97176bf7fd0841ac9c5264d20dd54e2d8 | ||
| ``` | ||
|
|
||
| ## View the multi-architecture manifest | ||
|
|
||
| View the generated manifest: | ||
| ```console | ||
| $ oras manifest fetch localhost:15000/oras:v1 --pretty | ||
| { | ||
| "schemaVersion": 2, | ||
| "mediaType": "application/vnd.oci.image.index.v1+json", | ||
| "manifests": [ | ||
| { | ||
| "mediaType": "application/vnd.oci.image.manifest.v1+json", | ||
| "digest": "sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd", | ||
| "size": 590, | ||
| "platform": { | ||
| "architecture": "arm64", | ||
| "os": "linux" | ||
| } | ||
| }, | ||
| { | ||
| "mediaType": "application/vnd.oci.image.manifest.v1+json", | ||
| "digest": "sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4", | ||
| "size": 590, | ||
| "platform": { | ||
| "architecture": "amd64", | ||
| "os": "linux" | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| ## Download your platform specific artifact | ||
|
|
||
| Pull the artifact to that directory: | ||
| ```console | ||
| $ oras pull localhost:15000/oras:v1 --platform linux/amd64 -o ./download | ||
| ✓ Skipped application/vnd.unknown.config.v1+json 37/37 B 100.00% 0s | ||
| └─ sha256:9d99a75171aea000c711b34c0e5e3f28d3d537dd99d110eafbfbc2bd8e52c2bf | ||
| ✓ Pulled bin/linux/amd64/oras 11/11 MB 100.00% 19ms | ||
| └─ sha256:4640fefdb4e22eb1308e40d5fac9fd9d16e17dfbc20202bb3ed42033d01d823e | ||
| ✓ Pulled application/vnd.oci.image.manifest.v1+json 581/581 B 100.00% 81µs | ||
| └─ sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4 | ||
| Skipped pulling layers without file name in "org.opencontainers.image.title" | ||
| Use 'oras copy localhost:15000/oras:v1 --to-oci-layout <layout-dir>' to pull all layers. | ||
| ``` | ||
|
|
||
| Validate your download | ||
| ```console | ||
| $ file download/bin/linux/amd64/oras | ||
| download/bin/linux/amd64/oras: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, Go BuildID=g5htPJf4jOBYObk8HPGK/C_STgrrtpidMtnOXIshh/AwKGiCqqgvmy7kvjXixL/hvqsAg3dicj7a6T6waJe, not stripped | ||
| $ sha256sum ./download/bin/linux/amd64/oras | ||
| 4640fefdb4e22eb1308e40d5fac9fd9d16e17dfbc20202bb3ed42033d01d823e ./download/bin/linux/amd64/oras | ||
| ``` | ||
|
|
||
| ## Update your multi-architecture manifest | ||
|
|
||
| You can also update your manifest if you want to add a new artifact. | ||
| For example, say you created an executable for Darwin, push the executable: | ||
| ```console | ||
| $ oras push localhost:15000/oras:darwin,amd64 --artifact-platform darwin/amd64 --artifact-type 'application/vnd.oci.image.config.v1+json' bin/darwin/amd64/oras:application/octet-stream | ||
| ✓ Exists bin/darwin/amd64/oras 11.1/11.1 MB 100.00% 0s | ||
| └─ sha256:a839f5d9cd3502b87b8d8edca31cd9f6f66c4835364e73b87a1645353631590f | ||
| ✓ Exists application/vnd.unknown.config.v1+json 38/38 B 100.00% 0s | ||
| └─ sha256:e9302bbb2fb8f6c2df866d3c4e41917849442f89a575f36f43366a7279804f70 | ||
| ✓ Uploaded application/vnd.oci.image.manifest.v1+json 589/589 B 100.00% 0s | ||
| └─ sha256:f5758b75ebc4d82280078afb9ebeb859f91a481667c018c9edf91a432518cb20 | ||
| Pushed [registry] localhost:15000/oras:darwin | ||
| Tagged amd64 | ||
| ArtifactType: application/vnd.oci.image.config.v1+json | ||
| Digest: sha256:f5758b75ebc4d82280078afb9ebeb859f91a481667c018c9edf91a432518cb20 | ||
| ```` | ||
|
|
||
| Add it to your manifest: | ||
| ```console | ||
| $ oras manifest index update localhost:15000/oras:v1 --add sha256:f5758b75ebc4d82280078afb9ebeb859f91a481667c018c9edf91a432518cb20 | ||
|
There was a problem hiding this comment. Use an environment variable for the digest here as well? |
||
| Fetching v1 | ||
| Fetched sha256:0fd4ac889c6f1f3e4fbb1c88b0cc18b97176bf7fd0841ac9c5264d20dd54e2d8 v1 | ||
| Fetching sha256:f5758b75ebc4d82280078afb9ebeb859f91a481667c018c9edf91a432518cb20 | ||
| Fetched sha256:f5758b75ebc4d82280078afb9ebeb859f91a481667c018c9edf91a432518cb20 | ||
| Added sha256:f5758b75ebc4d82280078afb9ebeb859f91a481667c018c9edf91a432518cb20 | ||
| Updated sha256:a694281dcf1248049c3d43e55d88ad1276c90b2b92f9b7d964fcc18e1fab7eb7 | ||
| Pushed [registry] localhost:15000/oras:v1 | ||
| Digest: sha256:a694281dcf1248049c3d43e55d88ad1276c90b2b92f9b7d964fcc18e1fab7eb7 | ||
| ``` | ||
|
|
||
| Download your new referenced executable: | ||
| ```console | ||
| $ oras pull localhost:15000/oras:v1 --platform darwin/amd64 -o ./download | ||
| ✓ Skipped application/vnd.unknown.config.v1+json 38/38 B 100.00% 0s | ||
| └─ sha256:e9302bbb2fb8f6c2df866d3c4e41917849442f89a575f36f43366a7279804f70 | ||
| ✓ Pulled bin/darwin/amd64/oras 11.1/11.1 MB 100.00% 30ms | ||
| └─ sha256:a839f5d9cd3502b87b8d8edca31cd9f6f66c4835364e73b87a1645353631590f | ||
| ✓ Pulled application/vnd.oci.image.manifest.v1+json 589/589 B 100.00% 132µs | ||
| └─ sha256:f5758b75ebc4d82280078afb9ebeb859f91a481667c018c9edf91a432518cb20 | ||
| Skipped pulling layers without file name in "org.opencontainers.image.title" | ||
| Use 'oras copy localhost:15000/oras:v1 --to-oci-layout <layout-dir>' to pull all layers. | ||
| ``` | ||
|
|
||
| Validate the executable: | ||
| ```console | ||
| $ file download/bin/darwin/amd64/oras | ||
| download/bin/darwin/amd64/oras: Mach-O 64-bit executable x86_64 | ||
| ``` | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would suggest adding a section "View the multi-architecture manifest" and using
oras manifest fetch localhost:15000/oras:v1to show the manifest JSON metadata. It can help users to list the created manifest list with different platforms. Users can also check the platform information of each architecture-specific manifest and know what object has been created before downloading it.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.