From 7f7bcf045ef33ccc4fa9f1cce490707675cd4322 Mon Sep 17 00:00:00 2001 From: Deepesha Burse Date: Mon, 17 Jul 2023 20:56:30 +0530 Subject: [PATCH 1/3] docs: add guide to distribute artifacts to oci image Signed-off-by: Deepesha Burse --- .../distributing_oci_layouts.mdx | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/how_to_guides/distributing_oci_layouts.mdx diff --git a/docs/how_to_guides/distributing_oci_layouts.mdx b/docs/how_to_guides/distributing_oci_layouts.mdx new file mode 100644 index 00000000..c7443927 --- /dev/null +++ b/docs/how_to_guides/distributing_oci_layouts.mdx @@ -0,0 +1,112 @@ +--- +title: Distributing OCI Layouts +sidebar_position: 6 +--- + +# Distributing OCI Layouts + +### Phase 1: Creating an OCI Image + +#### Step 1.1: Writing in the Dockerfile + +Put the following commands in the `Dockerfile` in order to run an image of Alpine Linux. + +``` +FROM alpine +CMD echo 'hello world!' +``` + +Our image is based on alpine and runs the command `echo hello world!`. + +#### Step 1.2: Building the image using docker + +``` +docker buildx create —use +``` + +This command is used to create a new instance of a builder with a single node based on the current configuration. + + +``` +docker buildx build . -f Dockerfile -o type=oci,dest=hello-world.tar -t hello-world:v1 +``` + +Expected output: +``` +[+] Building 7.0s (7/7) FINISHED                 docker-container:hungry_wilson + => [internal] booting buildkit                                            3.0s + => => pulling image moby/buildkit:buildx-stable-1                         2.5s + => => creating container buildx_buildkit_hungry_wilson0                   0.5s + + + + => => exporting manifest sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd17  0.0s + => => exporting config sha256:5e9872dc690060c52e4ea6e9357aaebb9d9187b44a  0.0s + => => sending tarball                                                     0.0s +``` + +This command has multiple parts to break down: + +`build` is needed to build the OCI Image based on the Dockerfile we provide. +hello-world:v1 is the name and tag associated with the image built. + +| Flag | Description | +|--------------|------------------------------------------------------| +| file or -f | Name of the Dockerfile (default: PATH/Dockerfile) | +| output or -o | Output destination (format: type=local,dest=path) | + +#### Step 1.3: View the OCI Image + +If you would like to view the image, you will need to extract the `.tar` file first. + +``` +mkdir hello-world +tar -xf ./hello-world.tar -C hello-world +``` + +### Phase 2: Push the OCI Image to a Repository + +You may use [`oras copy`](../commands/oras_copy.mdx) to push the OCI Image from your local disk to a repository. + +In the following example, we are pushing the image to a local repository like zot, + +``` +oras cp --from-oci-layout ./hello-world.tar:v1 localhost:5000/hello-artifact:v1 +``` + +Expected output: + +``` +Copied [oci-layout] ./hello-world.tar:v1 => [registry] localhost:5000/hello-artifact:v1 +Digest: sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd1793d0c580d3fd8bb280d07809 +``` + +### Phase 3: Pull the OCI Image from a Repository + +You can pull the OCI image using the [`oras pull`](../commands/oras_pull.mdx) command. + +``` +oras pull localhost:5000/hello-artifact:v1 +``` + +Expected Output: + +``` +Downloaded empty artifact +Pulled [registry] localhost:5000/hello-artifact:v1 +Digest: sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd1793d0c580d3fd8bb280d07809 +``` + +If you would like to access the artifact files from the OCI layout archive, you may run: + +``` +oras pull --oci-layout hello-world.tar:v1 +``` + +Expected Output: + +``` +Downloaded empty artifact +Pulled [oci-layout] hello-world.tar:v1 +Digest: sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd1793d0c580d3fd8bb280d07809 +``` \ No newline at end of file From 9945d93a5c0b42926fc69ca466441838ff5341aa Mon Sep 17 00:00:00 2001 From: Deepesha Burse Date: Thu, 3 Aug 2023 01:07:11 +0530 Subject: [PATCH 2/3] add introduction Signed-off-by: Deepesha Burse --- .../distributing_oci_layouts.mdx | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/how_to_guides/distributing_oci_layouts.mdx b/docs/how_to_guides/distributing_oci_layouts.mdx index c7443927..8e6faac1 100644 --- a/docs/how_to_guides/distributing_oci_layouts.mdx +++ b/docs/how_to_guides/distributing_oci_layouts.mdx @@ -5,9 +5,17 @@ sidebar_position: 6 # Distributing OCI Layouts -### Phase 1: Creating an OCI Image +The directory structure for OCI content-addressable blobs and location-addressable references (refs) is called the [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md). An OCI Image needs to include: -#### Step 1.1: Writing in the Dockerfile +- `blobs` directory: Each hash algorithm's directory and its children, which make up the object names in the blobs subdirectories, will hold the real content. + +- `oci-layout` file: This JSON object indicates the base of an Open Container Image Layout and provides information about the current image-layout version. + +- `index.json` file: The image index is a multi-descriptor entry point. + +## Creating an OCI Image + +### Step 1: Writing in the Dockerfile Put the following commands in the `Dockerfile` in order to run an image of Alpine Linux. @@ -18,7 +26,7 @@ CMD echo 'hello world!' Our image is based on alpine and runs the command `echo hello world!`. -#### Step 1.2: Building the image using docker +### Step 2: Building the image using docker ``` docker buildx create —use @@ -55,7 +63,7 @@ hello-world:v1 is the name and tag associated with the image built. | file or -f | Name of the Dockerfile (default: PATH/Dockerfile) | | output or -o | Output destination (format: type=local,dest=path) | -#### Step 1.3: View the OCI Image +### Step 3: View the OCI Image If you would like to view the image, you will need to extract the `.tar` file first. @@ -64,7 +72,7 @@ mkdir hello-world tar -xf ./hello-world.tar -C hello-world ``` -### Phase 2: Push the OCI Image to a Repository +## Push the OCI Image to a Repository You may use [`oras copy`](../commands/oras_copy.mdx) to push the OCI Image from your local disk to a repository. @@ -81,7 +89,7 @@ Copied [oci-layout] ./hello-world.tar:v1 => [registry] localhost:5000/hello-arti Digest: sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd1793d0c580d3fd8bb280d07809 ``` -### Phase 3: Pull the OCI Image from a Repository +## Pull the OCI Image from a Repository You can pull the OCI image using the [`oras pull`](../commands/oras_pull.mdx) command. From b0ba0c993d3d49aabede0c930277499d8262e5c2 Mon Sep 17 00:00:00 2001 From: Deepesha Burse <87636253+deepeshaburse@users.noreply.github.com> Date: Fri, 4 Aug 2023 15:03:22 +0530 Subject: [PATCH 3/3] Update docs/how_to_guides/distributing_oci_layouts.mdx Co-authored-by: Terry Howe Signed-off-by: Deepesha Burse <87636253+deepeshaburse@users.noreply.github.com> --- docs/how_to_guides/distributing_oci_layouts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to_guides/distributing_oci_layouts.mdx b/docs/how_to_guides/distributing_oci_layouts.mdx index 8e6faac1..63b925c2 100644 --- a/docs/how_to_guides/distributing_oci_layouts.mdx +++ b/docs/how_to_guides/distributing_oci_layouts.mdx @@ -76,7 +76,7 @@ tar -xf ./hello-world.tar -C hello-world You may use [`oras copy`](../commands/oras_copy.mdx) to push the OCI Image from your local disk to a repository. -In the following example, we are pushing the image to a local repository like zot, +In the following example, we are pushing the image to a local registry like zot: ``` oras cp --from-oci-layout ./hello-world.tar:v1 localhost:5000/hello-artifact:v1