From fccfb090ec648c4542db770fd0a1e01276f3a78d Mon Sep 17 00:00:00 2001 From: Aleksa Sarai Date: Wed, 19 Apr 2023 23:50:13 +1000 Subject: [PATCH] config: add support for org.opencontainers.image annotations These annotations are specified as part of the official conversion process from an OCI image configuration to an OCI runtime configuration since v1.0.0-rc7 of the image-spec but they were never officially specified in the runtime-spec. The fact these are not allowed by the current runtime-spec causes some issues with inter-spec compatibility. In order for tools like umoci to be able to do this generation properly, we need to allow this namespace to be used. Ref: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/conversion.md Signed-off-by: Aleksa Sarai --- config.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/config.md b/config.md index e2a9dda66..c022796c6 100644 --- a/config.md +++ b/config.md @@ -648,7 +648,21 @@ If there are no annotations then this property MAY either be absent or an empty Keys MUST be strings. Keys MUST NOT be an empty string. Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`. -Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by subsequent specifications. + +The `org.opencontainers` namespace for keys is reserved for use by this specification, annotations using keys in this namespace MUST be as described in this section. +The following keys in the `org.opencontainers` namespaces MAY be used: +| Key | Definition | +| --------------------------------------- | -----------------------------------------------------------------------------------------------------------------------------------| +| `org.opencontainers.image.os` | Indicates the operating system the container image was built to run on. The annotation value MUST have a valid value for the `os` property as defined in [the OCI image specification][oci-image-config-properties]. This annotation SHOULD only be used in accordance with the [OCI image specification's runtime conversion specification][oci-image-conversion]. | +| `org.opencontainers.image.os.version` | Indicates the operating system version targeted by the container image. The annotation value MUST have a valid value for the `os.version` property as defined in [the OCI image specification][oci-image-config-properties]. This annotation SHOULD only be used in accordance with the [OCI image specification's runtime conversion specification][oci-image-conversion]. | +| `org.opencontainers.image.os.features` | Indicates mandatory operating system features required by the container image. The annotation value MUST have a valid value for the `os.features` property as defined in [the OCI image specification][oci-image-config-properties]. This annotation SHOULD only be used in accordance with the [OCI image specification's runtime conversion specification][oci-image-conversion]. | +| `org.opencontainers.image.architecture` | Indicates the architecture that binaries in the container image are built to run on. The annotation value MUST have a valid value for the `architecture` property as defined in [the OCI image specification][oci-image-config-properties]. This annotation SHOULD only be used in accordance with the [OCI image specification's runtime conversion specification][oci-image-conversion]. | +| `org.opencontainers.image.variant` | Indicates the variant of the architecture that binaries in the container image are built to run on. The annotation value MUST have a valid value for the `variant` property as defined in [the OCI image specification][oci-image-config-properties]. This annotation SHOULD only be used in accordance with the [OCI image specification's runtime conversion specification][oci-image-conversion]. | +| `org.opencontainers.image.author` | Indicates the author of the container image. The annotation value MUST have a valid value for the `author` property as defined in [the OCI image specification][oci-image-config-properties]. This annotation SHOULD only be used in accordance with the [OCI image specification's runtime conversion specification][oci-image-conversion]. | +| `org.opencontainers.image.created` | Indicates the date and time when the container image was created. The annotation value MUST have a valid value for the `created` property as defined in [the OCIimage specification][oci-image-config-properties]. This annotation SHOULD only be used in accordance with the [OCI image specification's runtime conversion specification][oci-image-conversion]. | +| `org.opencontainers.image.stopSignal` | Indicates signal that SHOULD be sent by the container runtimes to [kill the container](runtime.md#kill). The annotation value MUST have a valid value for the `config.StopSignal` property as defined in [the OCI image specification][oci-image-config-properties]. This annotation SHOULD only be used in accordance with the [OCI image specification's runtime conversion specification][oci-image-conversion]. | + +All other keys in the `org.opencontainers` namespace not specified in this above table are reserved and MUST NOT be used by subsequent specifications. Runtimes MUST handle unknown annotation keys like any other [unknown property](#extensibility). Values MUST be strings. @@ -1074,6 +1088,8 @@ Here is a full example `config.json` for reference. [ieee-1003.1-2008-xbd-c8.1]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_01 [ieee-1003.1-2008-functions-exec]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html [naming-a-volume]: https://aka.ms/nb3hqb +[oci-image-config-properties]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/config.md#properties +[oci-image-conversion]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/conversion.md [capabilities.7]: http://man7.org/linux/man-pages/man7/capabilities.7.html [mount.2]: http://man7.org/linux/man-pages/man2/mount.2.html