Add CPU variant to image config

This commit adds the CPU variant to the image config type. It also
refactors the image index specification to isolate the platform
variant specifications, allowing a reference from the config spec.
The go specs are updated to include the new field in the v1.Image
struct, and tests are updated to include the new field.

Signed-off-by: Chris Price <chris.price@docker.com>

config.md

@@ -105,6 +105,11 @@ 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.

conversion.md

@@ -46,17 +46,19 @@ These fields all affect the `annotations` of the runtime configuration, and are
 | ------------------- | --------------- | ----- |
 | `os`                | `annotations`   | 1,2   |
 | `architecture`      | `annotations`   | 1,3   |
-| `author`            | `annotations`   | 1,4   |
-| `created`           | `annotations`   | 1,5   |
+| `variant`           | `annotations`   | 1,4   |
+| `author`            | `annotations`   | 1,5   |
+| `created`           | `annotations`   | 1,6   |
 | `Config.Labels`     | `annotations`   |       |
-| `Config.StopSignal` | `annotations`   | 1,6   |
+| `Config.StopSignal` | `annotations`   | 1,7   |
 
 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.author` in `annotations`.
-5. The value of this field MUST be set as the value of `org.opencontainers.image.created` in `annotations`.
-6. The value of this field MUST be set as the value of `org.opencontainers.image.stopSignal` 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`.
 
 ## Parsed Fields
 

image-index.md

@@ -76,15 +76,7 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
     - **`variant`** *string*
 
         This OPTIONAL property specifies the variant of the CPU.
-        Image indexes SHOULD use, and implementations SHOULD understand, values listed in the following table.
-        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`   |
-        |-----------------|----------------|-------------|
-        | ARM 32-bit, v6  | `arm`          | `v6`        |
-        | ARM 32-bit, v7  | `arm`          | `v7`        |
-        | ARM 32-bit, v8  | `arm`          | `v8`        |
-        | ARM 64-bit, v8  | `arm64`        | `v8`        |
+        Image indexes SHOULD use, and implementations SHOULD understand, `variant` values listed in the [Platform Variants](#platform-variants) table.
 
     - **`features`** *array of strings*
 
@@ -97,6 +89,16 @@ 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`   |
+|-----------------|----------------|-------------|
+| ARM 32-bit, v6  | `arm`          | `v6`        |
+| ARM 32-bit, v7  | `arm`          | `v7`        |
+| ARM 32-bit, v8  | `arm`          | `v8`        |
+| ARM 64-bit, v8  | `arm64`        | `v8`        |
+
 ## Example Image Index
 
 *Example showing a simple image index pointing to image manifests for two platforms:*

schema/config-schema.json

@@ -14,6 +14,9 @@
     "architecture": {
       "type": "string"
     },
+    "variant": {
+        "type": "string"
+    },
     "os": {
       "type": "string"
     },

schema/config_test.go

@@ -39,6 +39,23 @@ func TestConfig(t *testing.T) {
       "type": "layers"
     }
 }
+`,
+			fail: true,
+		},
+		// expected failure: field "variant" has numeric value, must be string
+		{
+			config: `
+{
+    "architecture": "arm64",
+    "variant": 123,
+    "os": "linux",
+    "rootfs": {
+      "diff_ids": [
+        "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
+      ],
+      "type": "layers"
+    }
+}
 `,
 			fail: true,
 		},
@@ -140,7 +157,8 @@ func TestConfig(t *testing.T) {
 {
     "created": "2015-10-31T22:22:56.015925234Z",
     "author": "Alyssa P. Hacker <alyspdev@example.com>",
-    "architecture": "amd64",
+    "architecture": "arm64",
+    "variant": "v8",
     "os": "linux",
     "config": {
         "User": "1:1",

schema/validator.go

@@ -168,6 +168,7 @@ func validateIndex(r io.Reader) error {
 		}
 		if manifest.Platform != nil {
 			checkPlatform(manifest.Platform.OS, manifest.Platform.Architecture)
+			checkArchitecture(manifest.Platform.Architecture, manifest.Platform.Variant)
 		}
 
 	}
@@ -189,6 +190,7 @@ func validateConfig(r io.Reader) error {
 	}
 
 	checkPlatform(header.OS, header.Architecture)
+	checkArchitecture(header.Architecture, header.Variant)
 
 	envRegexp := regexp.MustCompile(`^[^=]+=.*$`)
 	for _, e := range header.Config.Env {
@@ -200,6 +202,31 @@ func validateConfig(r io.Reader) error {
 	return nil
 }
 
+func checkArchitecture(Architecture string, Variant string) {
+	validCombins := map[string][]string{
+		"arm":      {"v6", "v7", "v8"},
+		"arm64":    {"v8"},
+		"386":      {""},
+		"amd64":    {""},
+		"ppc64":    {""},
+		"ppc64le":  {""},
+		"mips64":   {""},
+		"mips64le": {""},
+		"s390x":    {""},
+	}
+	for arch, variants := range validCombins {
+		if arch == Architecture {
+			for _, variant := range variants {
+				if variant == Variant {
+					return
+				}
+			}
+			fmt.Printf("warning: combination of architecture %q and variant %q is not valid.\n", Architecture, Variant)
+		}
+	}
+	fmt.Printf("warning: architecture %q is not supported yet.\n", Architecture)
+}
+
 func checkPlatform(OS string, Architecture string) {
 	validCombins := map[string][]string{
 		"android":   {"arm"},
@@ -219,7 +246,7 @@ func checkPlatform(OS string, Architecture string) {
 					return
 				}
 			}
-			fmt.Printf("warning: combination of %q and %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)

specs-go/v1/config.go

@@ -89,6 +89,9 @@ type Image struct {
 	// Architecture is the CPU architecture which the binaries in this image are built to run on.
 	Architecture string `json:"architecture"`
 
+	// Variant is the variant of the specified CPU architecture which image binaries are intended to run on.
+	Variant string `json:"variant,omitempty"`
+
 	// OS is the name of the operating system which the image is built to run on.
 	OS string `json:"os"`