How To Add New Capabilities to OCI *

[SteveLasker]

How To Add New Capabilities to OCI *

We have a few issues we're all wrestling with, with varied approaches and opinions on how to solve a problem. I'd suggest we each have slightly different priorities and we're focusing on the problems we either think we need or can solve. Unfortunately, we have come to a point where we have some bottlenecks in what extensibility we have.

To help frame a discussion, I'd suggest we need a framework for the discussions:

1. Gather a list of the core issues we collectively believe are relevant.
2. Find the things we can agree upon.
3. Propose some solutions, which map back to the agreed upon list.
4. Capture the pros and cons with each approach. There is no silver bullet here

Categories of changes

We have at least 2 major categories of changes:

1. How to add new capabilities to the container image, including compression formats:
   • Proposal to add Encrypted Layer Mediatype by lumjjb · Pull Request #775
   • Formalize support for zstd compression: v1.1.0 ? · Issue #803
   • Additional usability issues related to building and maintaining multi-arch images.
2. How to add signatures, and other linked artifacts
   • Add a new OCI artifact manifest PR #29
   • Add new descriptor.data field PR #826 and descriptor.reference field PR #828 to image-spec
   • Add new generic object manifest - which could account for README: Replace tabs with spaces #1 as well

Constraints

What are the constraints we're trying to adhere to:

1. Not break existing container runtimes, including down-level clients
2. Not break container registries

"Not break" means we can add behaviors, but do it in a deterministic way.

Elephants in the Room

To confront, head-on, some concerns we're all facing:

1. Is the image-spec frozen?
2. How do we unblock innovation for various projects

Is the image-spec frozen

I don't believe anyone desires the image-spec to be frozen. Rather, the question is: How do we make changes to the image-spec without breaking down-stream clients?

The varied designs around OCI Artifacts, Notary v2, cosign/sigstore, Compression Support all bump into this question, which we haven't actually clarified.

Facts:

• The image-spec has a declared version 1.0, dating back to August 2017.
• Registries (implementations of the distribution-spec) use the schemas within image-spec and image-index to manage content.
• Folks are brainstorming around OCI Image v2. It's unclear how many of these can be implemented if we don't unlock extensibility.
• Registries store more than container images. Although OCI Artifacts was able to work within the current image-spec, there were many constraints that make this awkward.
  • Config is required and used to determine the artifactType
  • At least 1 layer is required
  • Lack support for reference types (in either direction)
• OCI Artifacts was created with the constraint that any schema change to the image-spec would require a version change to the image-spec.
• Although the distribution-spec doesn't explicitly call out garbage collection, delete semantics are specified are defined, and some form of content management is a requirement for any production registry.
• The image-spec and distribution-spec exist to provide consistent user expectations for images and other artifact types as they work with various cloud providers, vendor products and OSS projects that adhere to the specs.
• Any change will take time for adoption and will require work to be useful. Where the work is required is in the details of the various proposals, based around a set of constraints.

What types of changes can be made, and how

The question could then be sub-categorized as:

• What changes to the spec can be done within v1?
  • Annotations, as optional strings appear to meet the bar
• What changes require a version change?

Things We Agree Upon

Are we in agreement to the following?

• Linking artifacts is needed to support signatures, SBoMs and other artifact types to be addeded, without changing the digest and/or tag.
  • There's no specifics on which signature format, nor which SBoM format here. Simply an additional artifact can be added, referencing existing artifacts
• An API for querying the references
  • Whether this is added to the distribution-spec, or an optional extension, the API is considered matched behavior to the ability to link artifacts.

Current Proposals

There are three proposals up for consideration, with pros and cons associated with each. Before we can get into the pros & cons, there's presumptions for how OCI will support extensibility.

1. Add a new OCI artifact manifest
2. Add new descriptor.data field and descriptor.reference field to image-spec
3. Add new generic object manifest

• 1 and 2 are based on whether changes to the image-spec are possible. Conceptually, either proposal can be captured in a new manifest, or merged into the image-spec, with various limitations.
• 1 and 2 do not account for compression formats, or other OCI Image v2 points of extensibility.
• 1 and 2 are focused on linking new types to image-manifest and image-index objects, they don't focus on changing behavior of the existing container image toolchains.
• 3 accounts for references and may account for OCI Image v2 extensibility options.

Decision Criteria

1. As 2 of the proposals are based on how we can make changes to the image-spec, I'd suggest we start with describing what and how we might accept changes to image-spec.
2. Based on the outcome of image-spec changes, we can discuss the 3 options. The 3 options can be adapted to how they apply to the image-spec change process.

[mikebrow]

Thanks for putting a stake in the ground. Progress is needed.
Time to rally the troops .. all those cliches ..

[estesp]

I understand the sentiment of this issue; I also perceive there is frustration at the lack of progress on several fronts and it isn't due to the lack of significant and interesting ideas to solve various real issues people are having in this ecosystem. What I think this "call to action" misses is that none of these people attend the weekly call or participate in any of the recent discussions (other than vbatts when he's able):

Brendan Burns <bburns@microsoft.com> (@brendandburns)
Jason Bouzane <jbouzane@google.com> (@jbouzane)
John Starks <jostarks@microsoft.com> (@jstarks)
Jonathan Boulle <jon@nstack.com> (@jonboulle)
Stephen Day <stevvooe@gmail.com> (@stevvooe)
Vincent Batts <vbatts@redhat.com> (@vbatts)
Aleksa Sarai <asarai@suse.de> (@cyphar)
Keyang Xie <keyang.xie@gmail.com> (@xiekeyang)

Based on how the OCI, and open source generally, works, these are the only people who have the actual authority and ownership to change the image-spec repository in any meaningful way. I love that we have lots of participation on the weekly call and important topics are being presented and discussed. But until people from the above list join that participation, I don't see any way forward with changes suggested for image-spec. I don't even mean live on the call as I know that isn't always possible, and definitely not possible for some people above due to timezone pain. It's a spec so we shouldn't see any kind of high traffic in commits/merges, but it is telling that the only commit in the last 14 months is to remove a maintainer!

To make it simpler, the image-spec (and any open source repo) is frozen, not explicitly by fiat from any authority on the subject, but implicitly because there is a lack of active maintainers working on the project. This is why I sent my note to the tob@ list last week and suggested Jon Johnson replace Jason (agreed to via email) as a starting point.

Until a maintainer comes around and says "yeah, we should do that" and LGTM's a proposal, nothing is going to move.

[imjasonh]

Is there any appetite or plan for removing/replacing inactive maintainers over time, to unblock progress on the spec? Or is the lack of ability to modify the spec "working as intended"?

In either case it would be helpful to spell that intention out somewhere.

If changes aren't expected to be approved, we can avoid a lot of needless back and forth. 😅

If changes are expected to be approved, a more timely and transparent approval process would avoid a lot of contributor pain too.

[vbatts]

This notion of requiring a product requirement doc is not, and has not been the case.

The decision tree is not to push things to a new manifest type.

Incremental iteration on the specs, now that folks have production hardened uses cases is exactly the improvement we're looking for. Such that it isn't breaking change, and isn't "weaponizing" any aspect of the community discussion.
Going off to reinvent a new registry API would be more destructive than this kind of incremental improvement.

[SteveLasker]

The decision tree probably should have been more related to a new versioned thing. Whatever that may be.
The breaking change is the concern. Adding something optional, that has major impact when it is added, is a concern that we should consider.
I don't think anyone suggested a new registry API. While the details of the various proposals add APIs as the details all require new indexing support, and querying, the question here is really, what defines a change requiring a version bump so implementors can fairly declare their support for a change. They shouldn't be forced into something that wasn't defined in a versioned spec.

The specifics on the APIs are basically, should these be declared in an optional /v2/_ext/ proposal, or added to the existing spec.

The larger issue is the image-spec and distribution-spec are tightly coupled. Now that we embrace users storing anything in a registry, how can we decouple these, so the image maintainers can make progress, independent of registries and other artifact types.

[mikebrow]

was a great OCI call yesterday thanks go out to the team for the show of support!

[SteveLasker]

Closing in lieu of #95 as the first step to getting a decision tree for how the specs will be maintained.