edit: the PR for this is now open! --> #393

What

Prior art: Kubernetes added support for server-sent warning messages to be sent out-of-band of regular API responses in K8s v1.19, Sept 2020: https://kubernetes.io/blog/2020/09/03/warnings/

tl;dr: K8s webhook admission controllers can respond with a Warning: header that indicates some non-critical informational piece of data. Clients like kubectl print those warnings to stderr in addition to their regular output.

OCI registries could do the same thing: emit a Warning response header when the registry has some information to convey to the client without constituing a full-blown error.

What registries decide to use this side channel for is out of scope of OCI. OCI should not specify a standard set of warning messages for instance.

If enough of us happen to agree on the value and (importantly) semantics of this, I'd like to see if we can get this into OCI 1.1. 🤞

Proof of concept

As a quick proof of concept: google/go-containerregistry@main...imjasonh:go-containerregistry:warn

This adds random warning messages when pulling manifests from a simple in-memory registry implementation, and shows those warnings when the crane client sees them.

$ crane digest localhost:1338/alpine
2023/03/13 13:55:37 [[WARNING]]: Your auth token will expire in 30 seconds.
sha256:ff6bdca1701f3a8a67e328815ff2346b0e4067d32ec36b7992c1fdc001dc8517

(The warning message is written to to stderr, the command output is undisturbed on stdout)

Nitty gritty details

The HTTP Warning header is technically deprecated. However, K8s decided to use it anyway, and I think we'd be better off following their example than inventing our own new warning header.

K8s only uses the warn-code 299, and warn-agent -, which side-steps many of the concerns about the Warning header that led to its deprecation AIUI. I think we should also specify that warn-date not be set, for simplicity.

An example Warning header:

Warning: 299 - "Your auth token will expire in 30 seconds."

K8s also limits the warning headers returned by the server. No more than 4KB of warnings are passed on, and they truncate warnings until they fit under the limit. I think we could have a similar effect in OCI-land, while giving registry implementations flexibility to decide which warnings they want to emit vs truncate.

Spec language

As a first crack at spec language:

• registry implementations MAY respond with a Warning header (see https://tools.ietf.org/html/rfc7234#section-5.5)
  • if set, the warn-code MUST be 299, and warn-agent MUST be -
  • registry implementations MUST NOT emit more than 4KB of Warning headers
• client implementations SHOULD surface any Warning headers encountered from the registry in an unobtrusive way (for example, stderr)

Further reading

• https://www.rfc-editor.org/rfc/rfc7234#section-5.5
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Warning
• KEP-1693: Warning mechanism for use of deprecated APIs
  • KEP 1693: Warning mechanism for use of deprecated APIs kubernetes/enhancements#1694
  • KEP 1693: copy edits, GA criteria, kubectl warnings-as-errors option, extension mechanisms kubernetes/enhancements#1697

cc @jonjohnsonjr @jdolitsky