From caec2e2505edbecf039d8f8991ab75c6500f33f0 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 11 Jan 2018 11:28:42 -0800 Subject: [PATCH] runtime: Document state annotations as a copy of config annotations The spec was not very clear on how state annotations are related to [config annotations. In the pull-request that landed state annotations, it sounds like these were supposed to be copied opaquely from the config [1]. It's still not clear to me why we'd copy annotations but not the rest of the config [2], but I'm leaving that alone for now. There was previous interest in runtime-specified annotations [3,4] (e.g. a RunV socket path [5]), but this commit does not allow runtimes to inject additional entries because I don't like: * Relying on config authors to avoid squatting on the namespace used by the runtime (if ties are broken in favor of the config) or * Silently clobbering configured annotations (if ties are broken in favor of the runtime). My preference would be to follow [3] and: * Only include runtime-specified information in the state annotations. * Require state readers to follow 'bundle' to the config.json if they wanted configured annotations (or embed the whole config.json in the state). But with 1.0 released and spec-maintainer comments like [1], I think it's too late to return to that approach. If we want to expose runtime-specified annotations, I think we'll need a new state property. There has been previous discussion of using "labels" and "annotations" to carry both types of information in the state [6], and while it's not as elegant as a full config copy, the labels/annotations approach is still viable. [1]: https://github.com/opencontainers/runtime-spec/pull/484#issuecomment-223645095 [2]: https://github.com/opencontainers/runtime-spec/pull/484#issuecomment-223413336 [3]: https://github.com/opencontainers/runtime-spec/pull/188 [4]: https://github.com/opencontainers/runtime-spec/pull/331#issuecomment-192463221 [5]: https://github.com/opencontainers/runtime-spec/pull/188#issuecomment-140296423 [6]: https://github.com/opencontainers/runtime-spec/pull/331#issuecomment-192441264 Signed-off-by: W. Trevor King --- runtime.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/runtime.md b/runtime.md index d92088b06..fa8d6ac0c 100644 --- a/runtime.md +++ b/runtime.md @@ -26,7 +26,8 @@ The state of a container includes the following properties: * **`bundle`** (string, REQUIRED) is the absolute path to the container's bundle directory. This is provided so that consumers can find the container's configuration and root filesystem on the host. * **`annotations`** (map, OPTIONAL) contains the list of annotations associated with the container. - If no annotations were provided then this property MAY either be absent or an empty map. + If the configuration set [`annotations`](config.md#annotations), this value MUST exactly match the configured `annotations`. + If no annotations were configured then this property MAY either be absent or an empty map. The state MAY include additional properties.