search

opencontainers / distribution-spec

OCI Distribution Specification
https://opencontainers.org
Apache License 2.0
824 stars 202 forks source link

Specify `Warning` header usage #393

Closed imjasonh closed 1 year ago

imjasonh commented 1 year ago

Fixes https://github.com/opencontainers/distribution-spec/issues/390

This is heavily inspired by Kubernetes' support for warnings returned by the API server and surfaced by clients like kubectl: https://kubernetes.io/blog/2020/09/03/warnings/

tl;dr: Registries MAY return informational warning messages in the Warning header, as described in https://www.rfc-editor.org/rfc/rfc7234#section-5.5, with the added restriction that the warn-code must be 299 and the warn-agent must be unset (-). Clients SHOULD surface those messages to the user in an unobtrusive and helpful way -- how they do that is up to them.

Blatantly cribbing further helpful advice from https://github.com/opencontainers/distribution-spec/issues/390#issuecomment-1472827380:

From https://kubernetes.io/blog/2020/09/03/warnings/#admission-webhooks

If you are implementing a webhook that returns a warning message, here are some tips:

  • Don't include a "Warning:" prefix in the message (that is added by clients on output)
  • Use warning messages to describe problems the client making the API request should correct or be aware of
  • Be brief; limit warnings to 120 characters if possible

and from https://github.com/opencontainers/distribution-spec/issues/390#issuecomment-1472832235

One more side note: a key provision of the warnings RFC is that for warnings returned with code 299: "A system receiving this warning MUST NOT take any automated action." Kubernetes leans heavily on this to assume it is always safe to return a warning or stop returning a warning without backwards compatibility implications. You would think it goes without saying, but warning header contents are not APIs.

cc @BenTheElder @liggitt

@jonjohnsonjr @jdolitsky @sudo-bmitch @sajayantony