Merge pull request #5 from supercontainers/add-create-prototype

add create prototype

Author: vsoch

README.md

@@ -3,183 +3,9 @@
 ![img/compspec.png](img/compspec.png)
 
 This is a prototype compatibility checking tool. Right now our aim is to use in the context of
-[these build matrices](https://github.com/rse-ops/lammps-matrix) for LAMMPS and these prototype [specifications](https://github.com/supercontainers/compspec) that are based off of [Proposal C](https://github.com/opencontainers/wg-image-compatibility/pull/8) of the Compatibility Working Group. This is experimental because all of that is subject (and likely) to change.
-
-## Design
-
-The design is based on the prototype from that pull request, shown below.
-
-![img/proposal-c-plugin-design.png](img/proposal-c-plugin-design.png)
-
-Specifically, I'll try to do simple interfaces (in [plugins](plugins)) to:
-
- - **Extract** Scan a system to collect compatibility metadata / attributes for a named set of extractions
-   - this maybe isn't great practice, but if I build the containers I trust them
-   - I can also do something simple like run this tool in a pod-> container small cluster
- - load in an artifact spec (json) from a URL
- - compare with a request for a specific system (with any level of detail desired)
-   - "basic" might just be providing the architecture
-   - "descriptive" might include other variables
-
-The extraction step is also important, but likely this would happen at build time (maybe by another tool).
-For now (since this is a prototype) I'm going to just manually do it.
-
-## Usage
-
-### Build
-
-Build the `compspec` binary with:
-
-```bash
-make
-```
-
-This generates the `bin/compspec` that you can use:
-
-```bash
-./bin/compspec
-```
-```console
-┏┏┓┏┳┓┏┓┏┏┓┏┓┏
-┗┗┛┛┗┗┣┛┛┣┛┗ ┗
-          ┛  ┛    
-
-[sub]Command required
-usage: compspec <Command> [-h|--help] [-n|--name "<value>" [-n|--name "<value>"
-                ...]]
-
-                Compatibility checking for container images
-
-Commands:
-
-  version  See the version of compspec
-  extract  Run one or more extractors
-
-Arguments:
-
-  -h  --help  Print help information
-  -n  --name  One or more specific extractor plugin names
-```
-
-
-### Version
-
-```bash
-$ ./bin/compspec version
-```
-```console
-⭐️ compspec version 0.1.0-draft
-```
-
-I know, the star should not be there. Fight me.
-
-### List
-
-The list command lists each extractor, and sections available for it.
-
-```bash
-$ ./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                            
-```
-
-Note that we will eventually add a description column - it's not really warranted yet!
-
-### 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:
-
-```bash
-# Not recommend, it's a lot!
-./bin/compspec extract
-```
-
-Or target a specific one:
-
-```bash
-./bin/compspec extract --name kernel
-```
-
-Better, save to json file:
-
-```bash
-./bin/compspec extract --name kernel -o test-kernel.json
-```
-
-This has a better structure for inspecting easily (only the top of the file is shown):
-
-<details>
-
-<summary>Kernel JSON output</summary>
-
-```json
-{
-  "extractors": {
-    "kernel": {
-      "sections": {
-        "boot": {
-          "BOOT_IMAGE": "/boot/vmlinuz-6.1.0-1028-oem",
-          "quiet": "",
-          "ro": "",
-          "root": "UUID",
-          "splash": "",
-          "vt.handoff": "7"
-        },
-        "config": {
-          "CONFIG_104_QUAD_8": "m",
-          "CONFIG_60XX_WDT": "m",
-          "CONFIG_64BIT": "y",
-          "CONFIG_6LOWPAN": "m"
-        }
-      }
-    }
-  }
-}
-```
-
-</details>
-
-An extractor is made up of sections, and you can ask for parsing just a specific one. 
-
-```bash
-./bin/compspec extract --name kernel[config]
-```
-```console
-⭐️ Running extract...
- --Result for kernel
- -- Section boot
-   root: UUID
-   ro: 
-   quiet: 
-   splash: 
-   vt.handoff: 7
-   BOOT_IMAGE: /boot/vmlinuz-6.1.0-1028-oem
-Extraction has run!
-```
-
-To ask for more than one, it's a comma separated list.
-
-```bash
-./bin/compspec extract --name kernel[config,boot]
-```
-
-The ordering of your list is honored.
-
-## Developer
-
-Note that there is a [developer environment](.devcontainer) that provides a consistent version of Go, etc.
-However, it won't work with all extractors.  Note that for any command that uses a plugin (e.g., `extract` and `check`)
+[these build matrices](https://github.com/rse-ops/lammps-matrix) for LAMMPS and these prototype [specifications](https://github.com/supercontainers/compspec) that are based off of [Proposal C](https://github.com/opencontainers/wg-image-compatibility/pull/8) of the Compatibility Working Group. This is experimental because all of that is subject (and likely) to change. This project is under development, and you can see our [docs](docs) for early documentation.
 
+ - ⭐️ [Documentation](docs) ⭐️
 
 ### Limitations
 
@@ -188,6 +14,9 @@ However, it won't work with all extractors.  Note that for any command that uses
 
 ## 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
  - todo thinking around manifest.yaml that has listing of images / artifacts
@@ -197,16 +26,8 @@ However, it won't work with all extractors.  Note that for any command that uses
 A `*` indicates required for the work / prototype I want to do
 
  - power usage data [valorium](https://ipo.llnl.gov/sites/default/files/2023-08/Final_variorum-rnd-100-award.pdf)
- - * architecture [archspec](https://github.com/archspec)
- - * MPI existence / variants
- - * operating system stuff
  - ... please add more!
 
-
-## Thanks and Previous Art
-
-- I learned about kernel parsing from [mfranczy/compat](https://github.com/mfranczy/compat)
-
 ## License
 
 This repository contains code derived from [sysinfo](https://github.com/zcalusic/sysinfo/tree/30169cfb37112a562cbf9133494a323764ad852c)

cmd/compspec/compspec.go

@@ -6,6 +6,7 @@ import (
 	"os"
 
 	"github.com/akamensky/argparse"
+	"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"
@@ -30,13 +31,19 @@ func main() {
 	versionCmd := parser.NewCommand("version", "See the version of compspec")
 	extractCmd := parser.NewCommand("extract", "Run one or more extractors")
 	listCmd := parser.NewCommand("list", "List plugins and known sections")
+	createCmd := parser.NewCommand("create", "Create a compatibility artifact for the current host according to a definition")
 
 	// Shared arguments (likely this will break into check and extract, shared for now)
 	pluginNames := parser.StringList("n", "name", &argparse.Options{Help: "One or more specific plugins to target names"})
 
 	// Extract arguments
 	filename := extractCmd.String("o", "out", &argparse.Options{Help: "Save extraction to json file"})
 
+	// 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)
 	if err != nil {
@@ -48,10 +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() {
+		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

@@ -0,0 +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, 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
+}

cmd/compspec/list/list.go

@@ -4,7 +4,7 @@ import (
 	p "github.com/supercontainers/compspec-go/plugins"
 )
 
-// Run will run an extraction of host metadata
+// Run will list the extractor names and sections known
 func Run(pluginNames []string) error {
 	// parse [section,...,section] into named plugins and sections
 	// return plugins