From 1dc8bba9ab5b6b54acd429aed3574357660ba038 Mon Sep 17 00:00:00 2001 From: Brian Goff Date: Wed, 30 Sep 2020 13:17:39 -0700 Subject: [PATCH] Embedded other platform fields in image spec This makes sure that an index can be generated from an image spec. `OSVersion` in particular is fairly important for Windows since Windows can only run containers for the OS version it was built for, and currently the only way to reliably get this is from the index. Signed-off-by: Brian Goff --- config.md | 23 ++++++++++++++++++----- conversion.md | 16 ++++++++++------ image-index.md | 1 + schema/config-schema.json | 11 ++++++++++- schema/fs.go | 36 ++++++++++++++++++------------------ schema/validator.go | 8 ++++---- specs-go/v1/config.go | 8 ++++++++ 7 files changed, 69 insertions(+), 34 deletions(-) diff --git a/config.md b/config.md index 4f33fdfbc..ffba65ac4 100644 --- a/config.md +++ b/config.md @@ -105,16 +105,29 @@ Note: Any OPTIONAL field MAY also be set to null, which is equivalent to being a The CPU architecture which the binaries in this image are built to run on. Configurations SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOARCH`][go-environment]. -- **variant** *string*, OPTIONAL - - The variant of the specified CPU architecture. - Configurations SHOULD use, and implementations SHOULD understand, `variant` values listed in the [Platform Variants](image-index.md#platform-variants) table. - - **os** *string*, REQUIRED The name of the operating system which the image is built to run on. Configurations SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOOS`][go-environment]. +- **os.version** *string*, OPTIONAL + + This OPTIONAL property specifies the version of the operating system targeted by the referenced blob. + Implementations MAY refuse to use manifests where `os.version` is not known to work with the host OS version. + Valid values are implementation-defined. e.g. `10.0.14393.1066` on `windows`. + +- **os.features** *array of strings*, OPTIONAL + + This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature. + When `os` is `windows`, image indexes SHOULD use, and implementations SHOULD understand the following values: + + - `win32k`: image requires `win32k.sys` on the host (Note: `win32k.sys` is missing on Nano Server) + +- **variant** *string*, OPTIONAL + + The variant of the specified CPU architecture. + Configurations SHOULD use, and implementations SHOULD understand, `variant` values listed in the [Platform Variants](image-index.md#platform-variants) table. + - **config** *object*, OPTIONAL The execution parameters which SHOULD be used as a base when running a container using the image. diff --git a/conversion.md b/conversion.md index 3e5ed06c0..d406baedc 100644 --- a/conversion.md +++ b/conversion.md @@ -47,18 +47,22 @@ These fields all affect the `annotations` of the runtime configuration, and are | `os` | `annotations` | 1,2 | | `architecture` | `annotations` | 1,3 | | `variant` | `annotations` | 1,4 | -| `author` | `annotations` | 1,5 | -| `created` | `annotations` | 1,6 | +| `os.version` | `annotations` | 1,5 | +| `os.features` | `annotations` | 1,6 | +| `author` | `annotations` | 1,7 | +| `created` | `annotations` | 1,8 | | `Config.Labels` | `annotations` | | -| `Config.StopSignal` | `annotations` | 1,7 | +| `Config.StopSignal` | `annotations` | 1,9 | 1. If a user has explicitly specified this annotation with `Config.Labels`, then the value specified in this field takes lower [precedence](#annotations) and the converter MUST instead use the value from `Config.Labels`. 2. The value of this field MUST be set as the value of `org.opencontainers.image.os` in `annotations`. 3. The value of this field MUST be set as the value of `org.opencontainers.image.architecture` in `annotations`. 4. The value of this field MUST be set as the value of `org.opencontainers.image.variant` in `annotations`. -5. The value of this field MUST be set as the value of `org.opencontainers.image.author` in `annotations`. -6. The value of this field MUST be set as the value of `org.opencontainers.image.created` in `annotations`. -7. The value of this field MUST be set as the value of `org.opencontainers.image.stopSignal` in `annotations`. +5. The value of this field MUST be set as the value of `org.opencontainers.image.os.version` in `annotations`. +6. The value of this field MUST be set as the value of `org.opencontainers.image.os.features` in `annotations`. +7. The value of this field MUST be set as the value of `org.opencontainers.image.author` in `annotations`. +8. The value of this field MUST be set as the value of `org.opencontainers.image.created` in `annotations`. +9. The value of this field MUST be set as the value of `org.opencontainers.image.stopSignal` in `annotations`. ## Parsed Fields diff --git a/image-index.md b/image-index.md index 55122b910..6acb0120a 100644 --- a/image-index.md +++ b/image-index.md @@ -90,6 +90,7 @@ For the media type(s) that this document is compatible with, see the [matrix][ma See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys). ## Platform Variants + When the variant of the CPU is not listed in the table, values are implementation-defined and SHOULD be submitted to this specification for standardization. | ISA/ABI | `architecture` | `variant` | diff --git a/schema/config-schema.json b/schema/config-schema.json index 58e0c849b..9b3be97c5 100644 --- a/schema/config-schema.json +++ b/schema/config-schema.json @@ -15,11 +15,20 @@ "type": "string" }, "variant": { - "type": "string" + "type": "string" }, "os": { "type": "string" }, + "os.version": { + "type": "string" + }, + "os.features": { + "type": "array", + "items": { + "type": "string" + } + }, "config": { "type": "object", "properties": { diff --git a/schema/fs.go b/schema/fs.go index ca5bbe95a..9c6b29415 100644 --- a/schema/fs.go +++ b/schema/fs.go @@ -226,19 +226,19 @@ var _escData = map[string]*_escFile{ "/config-schema.json": { name: "config-schema.json", local: "config-schema.json", - size: 2771, - modtime: 1619819526, + size: 2969, + modtime: 1625865937, compressed: ` -H4sIAAAAAAAC/+RWQY/TPBC951dE2T22m+/wnXot3JCKVAGHFarcZNLOEnvMeIKIUP87itNCkjpp6apc -OEUaz7z35nns+EcUx0kOLmO0gmSSRZysLJglGVFogOMlmQJ38dpChgVmymfNmrJHl+1Bq6ZkL2IXafri -yMzb6BPxLs1ZFTL/7/+0jT20dZifStwiTcmCyU5szpe12SlqtYM08/xtpdQWmlravkAmbcwyWWBBcMki -btqJ4yRjUAL5r0Cn1AmjaeF8vCDWSpqVXAnMBTUkfu3QpiSqkj3xBFQ/m7M9CmRSMVxbQ+7azKMXgeyO -Iz4ecMXHPzjgXmSEscPqc95+t+Qgf08sblj/yFB4A6FwT80IPKQ5FGiwGRWXamXXHnnVagzjm29jshSz -qpNZdwkF9FDGRCNxfBghFa4toZEhNxlYNT099wj6dJMSJ2RekNqXO5A8qcJUZdlH6uJ8Dlqw1Pk/2/tH -KisN7sb+b536e3f1ifgLmt0bvOmcv1NbKO9tyTqw8fe0ZC1k17gzqrzakqj7PV2/TCSFe831m2NRbDB3 -f/+uO+ZPdd+jBVPpsx1PSlUDuyTseDRgTRi+Vsj+P/wc8GCoLuoinjzfoxPiOmR636yAUWPbM75BwbfD -Zbem3hGB8T5/U1ze1FlA42ZbvwKDtIazP98fAIC2Um/8RIyDbIlKUGZkPvunLDoynM9N/1n1+9nUP5dR -MzuH6GcAAAD//0pj2wvTCgAA +H4sIAAAAAAAC/+RWsW7bQAzd9RWCkjGJOnTymnYrkAJG2yEojLNE2Ux1xyuPMioU/vdCJzvx2SfZteEu +XSnyvcdHSuLvJE2zElzBaAXJZJM0e7JgHsmIQgOcPpKpcJFOLRRYYaF81l1XduuKJWjVlSxF7CTPXxyZ ++z76QLzIS1aV3L97n/exm74Oy22Jm+Q5WTDFls35sj47R60WkBeev6+U1kJXS/MXKKSPWSYLLAgum6Rd +O2maFQxKoHwN7JQ6YTQ9nI9XxFpJ96RUAveCGjL/bN2nZKqRJfEIVJjNxRIFCmkYTq1ZKUZl5NR0cqdn +PqyAXT/WUysqUJ34KIliVu2bdyigd/MGwNN0HZBsJhrB35mrj0dm6+NfHHAQGWR+ZfU5H39ZclB+Jha3 +X3/LUPk1gMo9dIt8k5dQocFu4V2ulZ165KdeYxzfrIZkhdYN2DfayNbGQ1Lh1hIGG9RP08BT19NzQBDS +jUockXlEaih3T/KoCtPUdYi0i/M9asGjLv/b3r9S3WhwZ/Z/7tZfu6tvxD/QLD7gWe/5JzWH+tqWTCOD +v6YlUyE7xYVR9cmWRD+/TCSVu+TzW2JVzbB0//5bt8kf6z6gBdPog4lntWqBXRZ3PNljzRh+Nsj+mniO +eLCvLtlF3Hq+RCfE7WX/1L3xDA8oegEdd2vsGoqs9+FldHyodxGNs3l7AQZpDQd/vr8AAG2lnfmNGAaZ +E9WgzMB+hm9ZsmE43JvwOHy75sL3Mul2Z538CQAA//9C38scmQsAAA== `, }, @@ -246,7 +246,7 @@ MzuH6GcAAAD//0pj2wvTCgAA name: "content-descriptor.json", local: "content-descriptor.json", size: 1079, - modtime: 1619819526, + modtime: 1625865919, compressed: ` H4sIAAAAAAAC/5yTsW7cMAyGdz8F4QTIkos6BB2MIEu7d2i3ooNOok5Mz5JK8RBci7x7QcvX2G2RILfZ xP+Rn2zqVwfQe6yOqQjl1A/QfyqYPuQklhIy6BMmgY9zKDN8LugokLMTca0tLquLOFrFo0gZjHmoOW1a @@ -262,7 +262,7 @@ dIbaEm+G3WzZM/44EKMqff37riz3dL0uHcC37qn7HQAA//9DKIMKNwQAAA== name: "defs-descriptor.json", local: "defs-descriptor.json", size: 844, - modtime: 1619819526, + modtime: 1625865919, compressed: ` H4sIAAAAAAAC/5SST2/TTBDG7/kU826jt0DiOHBAqlWKKnrnUE6t0mi6O7aneP9od6IqVPnuaG03SYtA cLC1+2jmefwbz9MEQBlKOnIQ9k5VoK6oZsf5liBgFNabDiOIh6+B3BfvBNlRhKuxzUe4DqS5Zo29x3ww @@ -279,7 +279,7 @@ TAMAAA== name: "defs.json", local: "defs.json", size: 1670, - modtime: 1619819526, + modtime: 1625865903, compressed: ` H4sIAAAAAAAC/7STza6bMBCF9zzFyO2S9oJtbGDb7hMpy6oLSiaJq2AjY6RWEe9e8RNChFuJKneRgGc8 3zmeMbcAgByxKa2qnTKa5EC+4klp1a8aaBs8grtY054vpnXgLgi7GvUXo12hNFo41FiqkyqLoTwceTOA @@ -295,7 +295,7 @@ fIvD7in0ryMEy+fK1G6UfmdTE+tvpoL+1wV/AgAA//96IpqyhgYAAA== name: "image-index-schema.json", local: "image-index-schema.json", size: 2993, - modtime: 1619819526, + modtime: 1625865919, compressed: ` H4sIAAAAAAAC/6yWz0/jOhDH7/0rRgGJC5CnJ/QOFeLy9sJpD4v2suJg7EkybGNnx1Ogu+r/vrJN2qRJ C4Te2rHnO5/vxL/+zAAyg14zNULOZnPIvjZo/3dWFFlkuK1ViXBrDb7AtwY1FaRVnHoeck+9rrBWIa8S @@ -316,7 +316,7 @@ VmZjL8HOE24GcD9bz/4GAAD//yCnv52xCwAA name: "image-layout-schema.json", local: "image-layout-schema.json", size: 439, - modtime: 1619819526, + modtime: 1625865903, compressed: ` H4sIAAAAAAAC/2yPQUvEMBCF7/0VQ/Sg4DYVPOW6pwVhD4IX8VDTaTvLNonJVFik/12SaRXRU5g38+W9 91kBqA6TjRSYvFMG1DGg23vHLTmMcJjaAeGxvfiZ4cmOOLXqLlPXSQYDamQORutT8m4nau3joLvY9rxr @@ -330,7 +330,7 @@ HrRoV8JRtyHJaO0DOruZpYLJtaZsrM/FWEi+BMysfzuhXbUQfcDIhEkZyG2yQyYl8TPGJLVk97fth1yA name: "image-manifest-schema.json", local: "image-manifest-schema.json", size: 921, - modtime: 1619819526, + modtime: 1625865903, compressed: ` H4sIAAAAAAAC/5ySMW8iMRCF+/0VI0MJ+O501bZXUZxSJEoTpXB2x7uDWNsZmygo4r9HtnHAkCKifTvv zTdv/dEAiB59x+QCWSNaEHcOzT9rgiKDDOtJDQj/lSGNPsC9w440dSpNL6J97rsRJxWtYwiulXLjrVlm diff --git a/schema/validator.go b/schema/validator.go index 48c20a999..50d42b55f 100644 --- a/schema/validator.go +++ b/schema/validator.go @@ -22,8 +22,8 @@ import ( "io/ioutil" "regexp" + v1 "github.com/opencontainerd/image-spec/specs-go/v1" digest "github.com/opencontainers/go-digest" - "github.com/opencontainers/image-spec/specs-go/v1" "github.com/pkg/errors" "github.com/xeipuuv/gojsonschema" ) @@ -204,8 +204,8 @@ func validateConfig(r io.Reader) error { func checkArchitecture(Architecture string, Variant string) { validCombins := map[string][]string{ - "arm": {"v6", "v7", "v8"}, - "arm64": {"v8"}, + "arm": {"", "v6", "v7", "v8"}, + "arm64": {"", "v8"}, "386": {""}, "amd64": {""}, "ppc64": {""}, @@ -246,7 +246,7 @@ func checkPlatform(OS string, Architecture string) { return } } - fmt.Printf("warning: combination of OS %q and architecture %q is invalid.\n", OS, Architecture) + fmt.Printf("warning: combination of os %q and architecture %q is invalid.\n", OS, Architecture) } } fmt.Printf("warning: operating system %q of the bundle is not supported yet.\n", OS) diff --git a/specs-go/v1/config.go b/specs-go/v1/config.go index 486c3cbc7..ffff4b6d1 100644 --- a/specs-go/v1/config.go +++ b/specs-go/v1/config.go @@ -95,6 +95,14 @@ type Image struct { // OS is the name of the operating system which the image is built to run on. OS string `json:"os"` + // OSVersion is an optional field specifying the operating system + // version, for example on Windows `10.0.14393.1066`. + OSVersion string `json:"os.version,omitempty"` + + // OSFeatures is an optional field specifying an array of strings, + // each listing a required OS feature (for example on Windows `win32k`). + OSFeatures []string `json:"os.features,omitempty"` + // Config defines the execution parameters which should be used as a base when running a container using the image. Config ImageConfig `json:"config,omitempty"`