, , ,

Podman introduces support for OCI artifacts

Open Container Initiative (OCI hereafter) artifacts have been evolving with some significance lately.  Projects like OCI Registry As Storage (ORAS) have been stalwarts in this arena.  In fact, I think ORAS probably has the best explanation of artifacts.  It is certainly worth a read if you are at all unfamiliar with the topic.  In short, artifacts are files that can be stored on OCI registries and can be used in conjunction with containerized applications allowing for more flexibility in their packaging and delivery.

Podman and Buildah have been capable of supporting OCI artifacts since 2024 through its manifest verb.  Artifacts could be added to a manifest and pushed to an image registry in the same manner that multi-arch container images were added.  This approach required users to understand more about OCI internals than necessary, likely leading to less usage for artifacts.

As such, the recent work in Podman to add artifacts centered around the following ideas:

  • Initial support will be experimental and Linux only
  • Artifacts are managed
  • Simplify the process through assumptions about artifacts and advanced use cases can still use the manifest commands

The support currently in Podman is considered experimental and is only available for Podman on Linux.  The initial solution does not include support for the remote functions or the RESTFUL API.  I am hopeful that during this time users will provide feedback to affirm our approach on artifacts.  If you have feedback, it would be appropriate to communicate those via our upstream GH repository (as issues or discussions) or via other community interactions like our meetings for chat.

In Podman, I implemented artifacts as managed objects.  This means we have some state information on them.  They reside in specific stores (directories) on the system.  The implementation follows approaches as defined in containers/image and containers/storage, which is the heart of how Podman deals with container images.  The default store for artifacts for an unprivileged user is ~/.local/share/containers/storage/artifacts.  Podman managed artifacts use the OCI standards for manifests much like container images.

Artifacts must be “added” to the store for Podman to recognize them, this can be done from the local filesystem or by pulling an artifact from a container registry.  Once in the store, Podman can inspect, list (ls), remove (rm), and push artifacts.  The initial implementation in Podman does not allow for any special annotations or declaration of the artifact type.

As mentioned earlier, I wanted to simplify how users interact with artifacts.  To do this, we had to also make some assumptions about how artifacts are used (use cases).  In this case, some advanced use cases and customization of artifacts will not be possible, but we still have podman|buildah manifest for this.

We have several artifact related roadmap items planned.  The most important of which is the ability to create volumes from artifacts.  The goal here is to be able to add artifacts into a container at runtime via volumes.  The container image will need to have the logic to deal with the artifact but at that point, the artifacts would basically be akin to a bind mount.  We will also be adding a function to extract files from an artifact to the local filesystem.

We also need to implement support for artifacts in our RESTFUL API.  Once this is complete, we have the gateway to add support to Podman’s remote client including Mac and Windows.  And finally, adding support to containers/podman-py is also logical.

If you are interested in the code that went into Podman for artifacts specifically, then check out the pull request on our upstream GitHub repo.

The podman artifact command has many options.  These can be displayed with the podman artifact –help command.

$ podman artifact --help
Manage OCI artifacts

Description:
  Manage OCI artifacts

Usage:
  podman artifact [command]

Available Commands:
  add         Add an OCI artifact to the local store
  inspect     Inspect an OCI artifact
  ls          List OCI artifacts
  pull        Pull an OCI artifact
  push        Push an OCI artifact
  rm          Remove an OCI artifact

Podman allows you to create an artifact from a file on your local machine.  This can be done with the podman artifact add command.  In addition, you will need the fully-qualified name and the path to the artifact file.

$ podman artifact add quay.io/baude/artifact:1 /home/baude/myartifact1
c3c50e599906b242af0ab264ca9ef4346866cc31f57d2e7091fff6c3c9124aef

The artifact add command returns the digest of the artifact’s manifest.

Once the artifact has been added to the local artifact store, Podman is now aware of it.  You can see your artifacts with the podman artifact ls command.  This command requires no additional inputs. Note the artifact ls command also shows the digest and the size of the artifact.

$ podman artifact ls
REPOSITORY              TAG         DIGEST        SIZE
quay.io/baude/artifact  1           c3c50e599906  20.97MB

An artifact can also have more than one file associated with it.  Here an artifact is added with two files:

$ podman artifact add quay.io/baude/artifact:2 /home/baude/myartifact2 /home/baude/myartifact3
4fb2a21ac95ba90ae028f0f2315d15a061f714e75498d4d2a97e000787f92532

And the store now has two artifacts.

$ podman artifact ls
REPOSITORY              TAG         DIGEST
quay.io/baude/artifact  1           c3c50e599906  20.97MB
quay.io/baude/artifact  2           4fb2a21ac95b  1.363GB

When an artifact is in the local artifact store, it can be inspected much like images, containers, and machines.  The podman artifact inspect command shows more detailed information about the artifact, including annotations, media type, size in bytes, and much more.  Also, note that inspect shows the original file name in the artifact as represented by the org.opencontainers.image.title fields in the annotations.

$ podman artifact inspect quay.io/baude/artifact:2
{
     "Manifests": [
          {
               "schemaVersion": 2,
               "mediaType": "application/vnd.oci.image.manifest.v1+json",
               "config": {
                    "mediaType": "application/vnd.oci.empty.v1+json",
                    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
                    "size": 2,
                    "data": "e30="
               },
               "layers": [
                    {
                         "mediaType": "application/octet-stream",
                         "digest": "sha256:c4fa7b2c66f970a425feacb37e2397dc3e2a11b3bfd02886cc05b1d6a37b290f",
                         "size": 209715200,
                         "annotations": {
                              "org.opencontainers.image.title": "myartifact3"
                         }
                    },
                    {
                         "mediaType": "application/octet-stream",
                         "digest": "sha256:1fa946e45abbf77033a49e9804a093f2afab996cb411905f92397a4c27e6da9d",
                         "size": 1153433600,
                         "annotations": {
                              "org.opencontainers.image.title": "myartifact3"
                         }
                    }
               ]
          }
     ],
     "Name": "quay.io/baude/artifact:2",
     "Digest": "sha256:4fb2a21ac95ba90ae028f0f2315d15a061f714e75498d4d2a97e000787f92532"
}

Artifacts are much more interesting when they are being shared.  The most common way to do this is using a container image registry like quay.io.  You can pull artifacts from a registry, just like images, using the podman artifact pull command.  In the following example, an existing artifact on quay.io called quay.io/baude/artifact:single is pulled. 

Note: Unlike images, artifacts will not use so-called “shortnames” which means you must always use the fully qualified artifact name.  A shortname is when a user provides only a portion of the image name and Podman must figure out the registry for that reference.  For example, when pulling alpine , podman must translate that to docker.io/library/alpine:latest.

$ podman artifact pull quay.io/baude/artifact:single
Getting image source signatures
Copying blob 3ddc0a3cdb61 done   | 
Copying config 44136fa355 done   | 
Writing manifest to image destination

Notice how the output from the pull is very similar to pulling a container image with Podman.

The artifact ls command shows the newly pulled artifact.

$ podman artifact ls
REPOSITORY              TAG         DIGEST                                                            SIZE
quay.io/baude/artifact  1           88c890e87ebf251e603adb79a334f251bf3c3351ecb83f8492f4d058d550f17a  5.243GB
quay.io/baude/artifact  2           f0d6534e77684c2f5f80de05a4a47a4bcea2335ec941d33836dbd3a39056eb30  623.9MB
quay.io/baude/artifact  single      281c5b9261eeb11af44008980631664be6d3b89fb62a83533b26e01ecd960db9  524.3MB

Like container images, artifacts are pushed with the podman artifact push command.  This will take your local artifact and transfer it to the container image registry of your choice (according to the fully qualified artifact reference).  In this example, the artifact created with multiple files is pushed to quay.io.

$ podman artifact push quay.io/baude/artifact:2
quay.io/baude/artifact  1           c3c50e599906  20.97MB
quay.io/baude/artifact  2           4fb2a21ac95b  1.363GB
quay.io/baude/artifact  single      281c5b9261ee  524.3MB
Writing manifest to image destination

And finally, an artifact in the local store can be removed from the local store with the podman artifact rm command.

$ podman artifact rm quay.io/baude/artifact:1
c3c50e599906b242af0ab264ca9ef4346866cc31f57d2e7091fff6c3c9124aef

If artifacts are a topic of interest to you, stay tuned because our support should continue to mature over the next several months upstream.  Several colleagues of mine were crucial in helping shape Podman’s support of artifacts.  As such, I like to thank Nalin Dahyabhai, Miloslav Trmac, Valentin Rothberg, and Dan Walsh for their contributions and support during the development of this function.

Leave a Reply

Subscribe

Sign up with your email address to receive updates by email from this website.


Categories


Search