finish support for create

The arch system section should be separate from the os.
This change will fully read in a compatibiity request (yaml),
and then map requested fields to extractor output fields,
and with the option to add on-the-fly custom metadata.
We output a finished compatibility artifact that is ready
to be pushed to a registry and later used paired with an
image. Note that I need to run a final jsonSchema validate
on generation (before save) still.

Signed-off-by: vsoch <[email protected]>

Author: vsoch

README.md

@@ -15,6 +15,7 @@ This is a prototype compatibility checking tool. Right now our aim is to use in
 ## TODO
 
  - metadata namespace and exposure: someone writing a spec to create an artifact needs to know the extract namespace (and what is available) for the mapping.
+ - create: the final step of create should be validation of the spec with the jsonSchema linked (not done yet)
  - tests: matrix that has several different flavors of builds, generating compspec json output to validate generation and correctness
  - likely we want a common configuration file to take an extraction -> check recipe
  - need to develop check plugin family

cmd/compspec/compspec.go

@@ -6,8 +6,8 @@ import (
 	"os"
 
 	"github.com/akamensky/argparse"
-	"github.com/supercontainers/compspec-go/cmd/compspec/extract"
 	"github.com/supercontainers/compspec-go/cmd/compspec/create"
+	"github.com/supercontainers/compspec-go/cmd/compspec/extract"
 	"github.com/supercontainers/compspec-go/cmd/compspec/list"
 	"github.com/supercontainers/compspec-go/pkg/types"
 )
@@ -38,7 +38,11 @@ func main() {
 
 	// Extract arguments
 	filename := extractCmd.String("o", "out", &argparse.Options{Help: "Save extraction to json file"})
-	specname := createCmd.String("i", "in", &argparse.Options{Help: "Input yaml that contains spec for creation"})
+
+	// Create arguments
+	options := parser.StringList("a", "append", &argparse.Options{Help: "One or more custom metadata fields to append"})
+	specname := createCmd.String("i", "in", &argparse.Options{Required: true, Help: "Input yaml that contains spec for creation"})
+	specfile := createCmd.String("o", "out", &argparse.Options{Help: "Save compatibility json artifact to this file"})
 
 	// Now parse the arguments
 	err := parser.Parse(os.Args)
@@ -51,12 +55,18 @@ func main() {
 	if extractCmd.Happened() {
 		err := extract.Run(*filename, *pluginNames)
 		if err != nil {
-			log.Fatalf("Issue with extraction: %s", err)
+			log.Fatalf("Issue with extraction: %s\n", err)
 		}
 	} else if createCmd.Happened() {
-		create.Run(*specname)	
+		err := create.Run(*specname, *options, *specfile)
+		if err != nil {
+			log.Fatal(err.Error())
+		}
 	} else if listCmd.Happened() {
-		list.Run(*pluginNames)
+		err := list.Run(*pluginNames)
+		if err != nil {
+			log.Fatal(err.Error())
+		}
 	} else if versionCmd.Happened() {
 		RunVersion()
 	} else {

cmd/compspec/create/create.go

@@ -1,6 +1,118 @@
 package create
 
+import (
+	"fmt"
+	"os"
+
+	"github.com/supercontainers/compspec-go/pkg/types"
+	p "github.com/supercontainers/compspec-go/plugins"
+	"sigs.k8s.io/yaml"
+)
+
+// loadRequest loads a Compatibility Request YAML into a struct
+func loadRequest(filename string) (*types.CompatibilityRequest, error) {
+	request := types.CompatibilityRequest{}
+	yamlFile, err := os.ReadFile(filename)
+	if err != nil {
+		return &request, err
+	}
+
+	err = yaml.Unmarshal(yamlFile, &request)
+	if err != nil {
+		return &request, err
+	}
+	return &request, nil
+}
+
 // Run will create a compatibility artifact based on a request in YAML
-func Run(specname string) error {
+func Run(specname string, fields []string, saveto string) error {
+
+	// Cut out early if a spec not provided
+	if specname == "" {
+		return fmt.Errorf("A spec input -i/--input is required")
+	}
+	request, err := loadRequest(specname)
+	if err != nil {
+		return err
+	}
+
+	// Right now we only know about extractors, when we define subfields
+	// we can further filter here.
+	extractors := request.GetExtractors()
+	plugins, err := p.GetPlugins(extractors)
+	if err != nil {
+		return err
+	}
+
+	// Finally, add custom fields and extract metadata
+	result, err := plugins.Extract()
+
+	// Update with custom fields (either new or overwrite)
+	result.AddCustomFields(fields)
+
+	// The compspec returned is the populated Compatibility request!
+	compspec, err := PopulateExtractors(&result, request)
+	output, err := compspec.ToJson()
+	if err != nil {
+		return err
+	}
+	if saveto == "" {
+		fmt.Println(string(output))
+	} else {
+		err = os.WriteFile(saveto, output, 0644)
+		if err != nil {
+			return err
+		}
+	}
 	return nil
 }
+
+// LoadExtractors loads a compatibility result into a compatibility request
+// After this we can save the populated thing into an artifact (json DUMP)
+func PopulateExtractors(result *p.Result, request *types.CompatibilityRequest) (*types.CompatibilityRequest, error) {
+
+	for i, compat := range request.Compatibilities {
+		for key, extractorKey := range compat.Annotations {
+
+			// Get the extractor, section, and subfield from the extractor lookup key
+			f, err := p.ParseField(extractorKey)
+			if err != nil {
+				fmt.Printf("warning: cannot parse %s: %s, setting to empty\n", key, extractorKey)
+				compat.Annotations[key] = ""
+				continue
+			}
+
+			// If we get here, we can parse it and look it up in our result metadata
+			extractor, ok := result.Results[f.Extractor]
+			if !ok {
+				fmt.Printf("warning: extractor %s is unknown, setting to empty\n", f.Extractor)
+				compat.Annotations[key] = ""
+				continue
+			}
+
+			// Now get the section
+			section, ok := extractor.Sections[f.Section]
+			if !ok {
+				fmt.Printf("warning: section %s.%s is unknown, setting to empty\n", f.Extractor, f.Section)
+				compat.Annotations[key] = ""
+				continue
+			}
+
+			// Now get the value!
+			value, ok := section[f.Field]
+			if !ok {
+				fmt.Printf("warning: field %s.%s.%s is unknown, setting to empty\n", f.Extractor, f.Section, f.Field)
+				compat.Annotations[key] = ""
+				continue
+			}
+
+			// If we get here - we found it! Hooray!
+			compat.Annotations[key] = value
+		}
+
+		// Update the compatibiity
+		request.Compatibilities[i] = compat
+	}
+
+	return request, nil
+}

docs/design.md

@@ -9,7 +9,7 @@ The compatibility tool is responsible for extracting information about a system,
 
 ### Extractor
 
-An **extractor** is a core plugin that knows how to retrieve metadata about a host. An extractor is ususally going to be run for two cases:
+An **extractor** is a core plugin that knows how to retrieve metadata about a host. An extractor is usually going to be run for two cases:
 
 1. During CI to extract (and save) metadata about a particular build to put in a compatibility artifact.
 2. During image selection to extract information about the host to compare to.

docs/usage.md

@@ -56,21 +56,91 @@ $ ./bin/compspec list
 ```console
  Compatibility Plugins               
         TYPE      NAME     SECTION   
-        extrator  kernel   boot      
-        extrator  kernel   config    
-        extrator  kernel   modules   
-        extrator  system   cpu       
-        extrator  system   processor 
-        extrator  system   os        
-        extrator  library  mpi       
- TOTAL  7                            
+        extractor  kernel   boot      
+        extractor  kernel   config    
+        extractor  kernel   modules   
+        extractor  system   cpu       
+        extractor  system   processor 
+        extractor  system   os        
+        extractor  system   arch      
+        extractor  library  mpi       
+ TOTAL  8                            
 ```
 
 Note that we will eventually add a description column - it's not really warranted yet!
 
+## Create
+
+The create command is how you take a compatibility request, or a YAML file that has a mapping between the extractors defined by this tool and your compatibility metadata namespace, and generate an artifact. The artifact typically will be a JSON dump of key value pairs, scoped under different namespaces, that you might push to a registry to live alongside a container image, and with the intention to eventually use it to check compatiility against a new system. To run create
+we can use the example in the top level repository:
+
+```bash
+./bin/compspec create --in ./examples/lammps-experiment.yaml
+```
+
+Note that you'll see some errors about fields not being found! This is because we've implemented this for the fields to be added custom, on the command line.
+The idea here is that you can add custom metadata fields during your build, which can be easier than adding for automated extraction. Let's add them now.
+
+```bash
+# a stands for "append" and it can write a new field or overwrite an existing one
+./bin/compspec create --in ./examples/lammps-experiment.yaml -a custom.gpu.available=yes
+```
+```console
+{
+  "version": "0.0.0",
+  "kind": "CompatibilitySpec",
+  "metadata": {
+    "name": "lammps-prototype",
+    "jsonSchema": "https://raw.githubusercontent.com/supercontainers/compspec/main/supercontainers/compspec.json"
+  },
+  "compatibilities": [
+    {
+      "name": "org.supercontainers.mpi",
+      "version": "0.0.0",
+      "annotations": {
+        "implementation": "mpich",
+        "version": "4.1.1"
+      }
+    },
+    {
+      "name": "org.supercontainers.hardware.gpu",
+      "version": "0.0.0",
+      "annotations": {
+        "available": "yes"
+      }
+    },
+    {
+      "name": "io.archspec.cpu",
+      "version": "0.0.0",
+      "annotations": {
+        "model": "13th Gen Intel(R) Core(TM) i5-1335U",
+        "target": "amd64",
+        "vendor": "GenuineIntel"
+      }
+    }
+  ]
+}
+```
+
+Awesome! That, as simple as it is, is our compatibility artifact. I ran the command on my host just now, but run for a container image during
+a build will generate it for that context. We would want to save this to file:
+
+```bash
+./bin/compspec create --in ./examples/lammps-experiment.yaml -a custom.gpu.available=yes -o ./examples/generated-compatibility-spec.json
+```
+
+And that's it! We would next (likely during CI) push this compatibility artifact to a URI that is likely (TBA) linked to the image.
+For now we will manually remember the pairing, at least until the compatibility working group figures out the final design!
+
 ## Extract
 
-If you want to extract metadata to your local machine, you can use extract! Either just run all extractors and dump to the terminal:
+Extraction has two use cases, and likely you won't be running this manually, but within the context of another command:
+
+1. Extracting metadata about the container image at build time to generate an artifact (done via "create")
+2. Extracting metadata about the host at image selection time, and comparing against a set of contender container images to select the best one (done via "check").
+
+However, for the advanced or interested user, you can run extract as a standalone utility to inspect or otherwise save metadata from extractors.
+For example, if you want to extract metadata to your local machine, you can use extract! Either just run all extractors and dump to the terminal:
 
 ```bash
 # Not recommend, it's a lot!
@@ -84,7 +154,17 @@ the full ability to specify:
 2. One or more specific sections known to an extractor
 3. Saving to json metadata instead of dumping to terminal
 
-### Library
+
+### Extractors 
+
+Current Extractors include:
+
+ - Library: library-specific metadata (e.g., mpi)
+ - System: system-specific metadata (e.g., processor, cpu, arch, os)
+ - Kernel: kernel-speific metadata (e.g., boot, config, modules)
+
+
+#### Library
 
 The library extractor currently just has one section for "mpi"
 
@@ -96,7 +176,7 @@ The library extractor currently just has one section for "mpi"
  --Result for library
  -- Section mpi
    mpi.variant: mpich
-   mpi.version: 4.0
+   mpi.version: 4.1.1
 Extraction has run!
 ```
 
@@ -119,7 +199,7 @@ cat test-library.json
       "sections": {
         "mpi": {
           "mpi.variant": "mpich",
-          "mpi.version": "4.0"
+          "mpi.version": "4.1.1"
         }
       }
     }
@@ -129,32 +209,45 @@ cat test-library.json
 
 That shows the generic structure of an extractor output. The "library" extractor owns a set of groups (sections) each with their own namespaced attributes.
 
-### System
+#### System
 
 The system extractor supports three sections
 
  - cpu: Basic CPU counts and metadata
  - processor: detailed information on every processor
  - os: operating system information
+ - arch: architecture
 
 For example:
 
 ```bash
-./bin/comspec extract --name system[os]
+./bin/compspec extract --name system[os]
 ```
 ```console
 ⭐️ Running extract...
  --Result for system
  -- Section os
-   arch.os.name: Ubuntu 22.04.3 LTS
-   arch.os.version: 22.04
-   arch.os.vendor: ubuntu
-   arch.os.release: 22.04.3
-   arch.name: amd64
+   release: 22.04.3
+   name: Ubuntu 22.04.3 LTS
+   version: 22.04
+   vendor: ubuntu
+Extraction has run!
+```
+
+Or for arch:
+
+```bash
+./bin/compspec extract --name system[arch]
+```
+```console
+⭐️ Running extract...
+ --Result for system
+ -- Section arch
+   name: amd64
 Extraction has run!
 ```
 
-### Kernel
+#### Kernel
 
 Kernel supports three sections: