Merge pull request #8493 from DataDog/image-verifier-bindir-plugin

Add image verifier transfer service plugin system based on a binary directory

docs/image-verification.md

@@ -0,0 +1,51 @@
+# Image Verification
+
+The following covers the default "bindir" `ImageVerifier` plugin implementation.
+
+To enable image verification, add a stanza like the following to the containerd config:
+
+```yaml
+[plugins]
+  [plugins."io.containerd.image-verifier.v1.bindir"]
+    bin_dir = "/opt/containerd/image-verifier/bin"
+    max_verifiers = 10
+    per_verifier_timeout = "10s"
+```
+
+All files in `bin_dir`, if it exists, must be verifier executables which conform to the following API.
+
+## Image Verifier Binary API
+
+### CLI Arguments
+
+- `-name`: The given reference to the image that may be pulled.
+- `-digest`: The resolved digest of the image that may be pulled.
+- `-stdin-media-type`: The media type of the JSON data passed to stdin.
+
+### Standard Input
+
+A JSON encoded payload is passed to the verifier binary's standard input. The
+media type of this payload is specified by the `-stdin-media-type` CLI
+argument, and may change in future versions of containerd. Currently, the
+payload has a media type of `application/vnd.oci.descriptor.v1+json` and
+represents the OCI Content Descriptor of the image that may be pulled. See
+[the OCI specification](https://github.com/opencontainers/image-spec/blob/main/descriptor.md)
+for more details.
+
+### Image Pull Judgement
+
+Print to standard output a reason for the image pull judgement.
+
+Return an exit code of 0 to allow the image to be pulled and any other exit code to block the image from being pulled.
+
+## Image Verifier Caller Contract
+
+- If `bin_dir` does not exist or contains no files, the image verifier does not block image pulls.
+- An image is pulled only if all verifiers that are called return an "ok" judgement (exit with status code 0). In other words, image pull judgements are combined with an `AND` operator.
+- If any verifiers exceeds the `per_verifier_timeout` or fails to exec, the verification fails with an error and a `nil` judgement is returned.
+- If `max_verifiers < 0`, there is no imposed limit on the number of image verifiers called.
+- If `max_verifiers >= 0`, there is a limit imposed on the number of image verifiers called. The entries in `bin_dir` are lexicographically sorted by name, and the first `n = max_verifiers` of the verifiers will be called, and the rest will be skipped.
+- There is no guarantee for the order of execution of verifier binaries.
+- Standard error output of verifier binaries is logged at debug level by containerd, subject to truncation.
+- Standard output of verifier binaries (the "reason" for the judgement) is subject to truncation.
+- System resources used by verifier binaries are currently accounted for in and constrained by containerd's own cgroup, but this is subject to change.