feat: add how-to for multiple architecture #395
Conversation
TerryHowe
requested review from
asmitbm,
FeynmanZhou,
sajayantony,
shizhMSFT,
SteveLasker and
vsoch
as code owners
|
Only if OCI gave a way to not use the config blobs for archs, but I guess this is what we have today and IMHO we should publish this and chase a better experience in some brighter future. /cc @shizhMSFT |
TerryHowe
force-pushed
the
multiple-architecture
branch
4 times, most recently
from
f8bc97e to
718885d
Compare
shizhMSFT
changed the title
shizhMSFT
changed the title
There was a problem hiding this comment.
Thank @TerryHowe for the contribution and I agree with @sajayantony.
This PR depends on oras-project/oras#1500. Mark Request changes to prevent accidental merge.
Linking oras-project/oras#1066
|
|
||
| First we push a Linux ARM64 executable: | ||
| ```shell | ||
| % oras push --plain-http localhost:15000/oras:linux,arm64 --platform linux/arm64 --artifact-type 'application/vnd.oci.image.config.v1+json' bin/linux/arm64/oras:application/octet-stream |
There was a problem hiding this comment.
The flag name depends on the discussion of oras-project/oras#1500
There was a problem hiding this comment.
changed to --artifact-platform
TerryHowe
force-pushed
the
multiple-architecture
branch
2 times, most recently
from
083bd12 to
0604e76
Compare
TerryHowe
force-pushed
the
multiple-architecture
branch
from
0604e76 to
fffaf6b
Compare
| sidebar_position: 110 | ||
| --- | ||
|
|
||
| # Multiple Architecture Image Support for ORAS |
There was a problem hiding this comment.
Should the title be Multi-platform Image/Artifact Support with ORAS?
There was a problem hiding this comment.
I made this change, but I think "architecture" communicates more than "platform"
| ORAS can help you manage multiple 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 |
There was a problem hiding this comment.
As there are several features demonstrated in this doc are a part of ORAS v1.3.0, we need to create a new version of documentation before merging this PR. This article is supposed to be v1.3.0.
There was a problem hiding this comment.
Thanks @TerryHowe . We will hold on this PR before ORAS v1.3 documentation folder created.
TerryHowe
force-pushed
the
multiple-architecture
branch
from
fffaf6b to
923b780
Compare
TerryHowe
force-pushed
the
multiple-architecture
branch
from
923b780 to
62ce8f8
Compare
| Pushed [registry] localhost:15000/oras:v1 | ||
| Digest: sha256:0fd4ac889c6f1f3e4fbb1c88b0cc18b97176bf7fd0841ac9c5264d20dd54e2d8 | ||
| ``` | ||
|
|
There was a problem hiding this comment.
I would suggest adding a section "View the multi-architecture manifest" and using oras manifest fetch localhost:15000/oras:v1 to 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.
versioned_docs/version-1.3.0-beta.1/how_to_guides/multiarch.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-1.3.0-beta.1/how_to_guides/multiarch.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-1.3.0-beta.1/how_to_guides/multiarch.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-1.3.0-beta.1/how_to_guides/multiarch.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-1.3.0-beta.1/how_to_guides/multiarch.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-1.3.0-beta.1/how_to_guides/multiarch.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-1.3.0-beta.1/how_to_guides/multiarch.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-1.3.0-beta.1/how_to_guides/multiarch.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-1.3.0-beta.1/how_to_guides/multiarch.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-1.3.0-beta.1/how_to_guides/multiarch.mdx
Outdated
Show resolved
Hide resolved
| First we push a Linux ARM64 executable: | ||
| ```shell | ||
| % oras push --plain-http 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 | ||
| Tagged arm64 | ||
| ArtifactType: application/vnd.oci.image.config.v1+json | ||
| Digest: sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd | ||
| ``` | ||
|
|
||
| Next, we push a Linux AMD64 executable: | ||
| ```shell | ||
| % oras push --plain-http 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 | ||
| 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. |
There was a problem hiding this comment.
Question: What's the meaning to tag linux?
There was a problem hiding this comment.
or do you mean linux_arm64 and linux_amd64?
|
|
||
| After you have pushed all your platform specific artifacts, create a manifest referencing them: | ||
| ```shell | ||
| % oras manifest index create localhost:15000/oras:v1 sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4 |
There was a problem hiding this comment.
You may also want to have a section to create index using tags.
TerryHowe
force-pushed
the
multiple-architecture
branch
from
6ea436b to
e1bf5ea
Compare
|
|
||
| First we push a Linux ARM64 executable: | ||
| ```console | ||
| $ oras push --plain-http 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 |
There was a problem hiding this comment.
Do we want to put specify a more meaningful artifact type? The artifact to push is not an image config.
BTW, Is the --plain-http flag necessary here? I feel that it makes the command too long.
There was a problem hiding this comment.
Anyone have thoughts on what would be a better artifact-type here? I thought it was an image config containing application/octet-stream.
There was a problem hiding this comment.
Should the artifact type refer to the type of bin/linux/arm64/oras?
There was a problem hiding this comment.
Got rid of --plain-http I don't think artificate type should refer to application/octet-stream that is the type of the artifact itself
There was a problem hiding this comment.
How about something like "application/vnd.example 😂
|
|
||
| After you have pushed all your platform specific artifacts, create a manifest referencing them using the OCI image index format: | ||
| ```console | ||
| $ oras manifest index create localhost:15000/oras:v1 sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4 |
There was a problem hiding this comment.
nit: How about putting the digests into environment variables for better readability?
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Co-authored-by: Feynman Zhou <feynmanzhou@microsoft.com> Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Co-authored-by: Feynman Zhou <feynmanzhou@microsoft.com> Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Co-authored-by: Shiwei Zhang <shizh@microsoft.com> Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Co-authored-by: Shiwei Zhang <shizh@microsoft.com> Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Co-authored-by: Feynman Zhou <feynmanzhou@microsoft.com> Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
TerryHowe
force-pushed
the
multiple-architecture
branch
from
e1bf5ea to
9d403e5
Compare
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
|
|
||
| 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?
Add a how-to guilde for multiple architecture artifact management.
Closes: #247