From 11118b1d93fccd0dcfb8d865361159a7a2879360 Mon Sep 17 00:00:00 2001 From: vsoch Date: Sat, 24 Feb 2024 16:50:47 -0700 Subject: [PATCH 1/2] wip: add support for node extraction -> cluster metadata Problem: we need a extract metadata for nodes and then parse into a cluster graph Solution: create a compspec create nodes subcommand. In this PR I am adding a ClusterGraph, which still needs work to improve the output to easily map into a JGF (right now it has elements that can support any type that need further parsing). I am also generalizing the idea of plugins more, so we will have extractors and converters (that run create) but I need to finalize the design for the latter, right now the create commands are very separate. I am opening the PR sooner than later in case my computer explodes. A few problems I have run into is that NFD does not have cpu counts, let along physical vs. logical. This information is in /proc/cpuinfo for x86 but not arm. We also do not have a way to get socket -> core mapping. So likely we do need to add the hwloc extractor, and provide an automated build for doing that since it requires hwloc on the system. I will put some thought into this. Signed-off-by: vsoch --- cmd/compspec/compspec.go | 38 +++-- cmd/compspec/create/artifact.go | 127 +++++++++++++++ cmd/compspec/create/create.go | 117 -------------- cmd/compspec/create/nodes.go | 180 ++++++++++++++++++++++ cmd/compspec/extract/extract.go | 8 +- cmd/compspec/list/list.go | 12 +- docs/README.md | 6 +- docs/design.md | 21 ++- docs/img/rainbow-scheduler-register.png | Bin 0 -> 77659 bytes docs/rainbow/README.md | 48 ++++++ docs/usage.md | 18 ++- pkg/extractor/extractor.go | 1 + pkg/graph/cluster.go | 188 +++++++++++++++++++++++ pkg/graph/{graph.go => compatibility.go} | 0 pkg/graph/edges.go | 6 +- pkg/utils/utils.go | 16 ++ plugins/extractors/plugins.go | 80 ++++++++++ plugins/extractors/request.go | 59 +++++++ plugins/extractors/result.go | 95 ++++++++++++ plugins/extractors/system/extractors.go | 10 +- plugins/extractors/system/system.go | 10 +- plugins/field.go | 2 +- plugins/list.go | 22 +-- plugins/plugins.go | 76 +-------- plugins/request.go | 116 ++------------ 25 files changed, 918 insertions(+), 338 deletions(-) create mode 100644 cmd/compspec/create/artifact.go create mode 100644 cmd/compspec/create/nodes.go create mode 100644 docs/img/rainbow-scheduler-register.png create mode 100644 docs/rainbow/README.md create mode 100644 pkg/graph/cluster.go rename pkg/graph/{graph.go => compatibility.go} (100%) create mode 100644 plugins/extractors/plugins.go create mode 100644 plugins/extractors/request.go create mode 100644 plugins/extractors/result.go diff --git a/cmd/compspec/compspec.go b/cmd/compspec/compspec.go index 7a3a308..626797e 100644 --- a/cmd/compspec/compspec.go +++ b/cmd/compspec/compspec.go @@ -54,12 +54,21 @@ func main() { cachePath := matchCmd.String("", "cache", &argparse.Options{Help: "A path to a cache for artifacts"}) saveGraph := matchCmd.String("", "cache-graph", &argparse.Options{Help: "Load or use a cached graph"}) - // Create arguments - options := createCmd.StringList("a", "append", &argparse.Options{Help: "Append 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"}) - mediaType := createCmd.String("m", "media-type", &argparse.Options{Help: "The expected media-type for the compatibility artifact"}) - allowFailCreate := createCmd.Flag("f", "allow-fail", &argparse.Options{Help: "Allow any specific extractor to fail (and continue extraction)"}) + // Create subcommands - note that "nodes" could be cluster, but could want to make a subset of one + artifactCmd := createCmd.NewCommand("artifact", "Create a new artifact") + nodesCmd := createCmd.NewCommand("nodes", "Create nodes in Json Graph format from extraction data") + + // Artifaction creation arguments + options := artifactCmd.StringList("a", "append", &argparse.Options{Help: "Append one or more custom metadata fields to append"}) + specname := artifactCmd.String("i", "in", &argparse.Options{Required: true, Help: "Input yaml that contains spec for creation"}) + specfile := artifactCmd.String("o", "out", &argparse.Options{Help: "Save compatibility json artifact to this file"}) + mediaType := artifactCmd.String("m", "media-type", &argparse.Options{Help: "The expected media-type for the compatibility artifact"}) + allowFailCreate := artifactCmd.Flag("f", "allow-fail", &argparse.Options{Help: "Allow any specific extractor to fail (and continue extraction)"}) + + // Nodes creation arguments + nodesOutFile := nodesCmd.String("", "nodes-output", &argparse.Options{Help: "Output json file for cluster nodes"}) + nodesDir := nodesCmd.String("", "node-dir", &argparse.Options{Required: true, Help: "Input directory with extraction data for nodes"}) + clusterName := nodesCmd.String("", "cluster-name", &argparse.Options{Required: true, Help: "Cluster name to describe in graph"}) // Now parse the arguments err := parser.Parse(os.Args) @@ -75,10 +84,21 @@ func main() { log.Fatalf("Issue with extraction: %s\n", err) } } else if createCmd.Happened() { - err := create.Run(*specname, *options, *specfile, *allowFailCreate) - if err != nil { - log.Fatal(err.Error()) + if artifactCmd.Happened() { + err := create.Artifact(*specname, *options, *specfile, *allowFailCreate) + if err != nil { + log.Fatal(err.Error()) + } + } else if nodesCmd.Happened() { + err := create.Nodes(*nodesDir, *clusterName, *nodesOutFile) + if err != nil { + log.Fatal(err.Error()) + } + } else { + fmt.Println(Header) + fmt.Println("Please provide a --node-dir and (optionally) --nodes-output (json file to write)") } + } else if matchCmd.Happened() { err := match.Run( *manifestFile, diff --git a/cmd/compspec/create/artifact.go b/cmd/compspec/create/artifact.go new file mode 100644 index 0000000..9a98e55 --- /dev/null +++ b/cmd/compspec/create/artifact.go @@ -0,0 +1,127 @@ +package create + +import ( + "fmt" + "os" + + "github.com/compspec/compspec-go/pkg/types" + ep "github.com/compspec/compspec-go/plugins/extractors" + + p "github.com/compspec/compspec-go/plugins" +) + +// Artifact will create a compatibility artifact based on a request in YAML +// TODO likely want to refactor this into a proper create plugin +func Artifact(specname string, fields []string, saveto string, allowFail bool) 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 := ep.GetPlugins(extractors) + if err != nil { + return err + } + + // Finally, add custom fields and extract metadata + result, err := plugins.Extract(allowFail) + if err != nil { + return err + } + + // Update with custom fields (either new or overwrite) + result.AddCustomFields(fields) + + // The compspec returned is the populated Compatibility request! + compspec, err := PopulateExtractors(&result, request) + if err != nil { + return err + } + + 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 *ep.Result, request *types.CompatibilityRequest) (*types.CompatibilityRequest, error) { + + // Every metadata attribute must be known under a schema + schemas := request.Metadata.Schemas + if len(schemas) == 0 { + return nil, fmt.Errorf("the request must have one or more schemas") + } + for i, compat := range request.Compatibilities { + + // The compatibility section name is a schema, and must be defined + url, ok := schemas[compat.Name] + if !ok { + return nil, fmt.Errorf("%s is missing a schema", compat.Name) + } + if url == "" { + return nil, fmt.Errorf("%s has an empty schema", compat.Name) + } + + for key, extractorKey := range compat.Attributes { + + // 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.Attributes[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.Attributes[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.Attributes[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.Attributes[key] = "" + continue + } + + // If we get here - we found it! Hooray! + compat.Attributes[key] = value + } + + // Update the compatibiity + request.Compatibilities[i] = compat + } + + return request, nil +} diff --git a/cmd/compspec/create/create.go b/cmd/compspec/create/create.go index 2745b36..7d713e8 100644 --- a/cmd/compspec/create/create.go +++ b/cmd/compspec/create/create.go @@ -1,11 +1,9 @@ package create import ( - "fmt" "os" "github.com/compspec/compspec-go/pkg/types" - p "github.com/compspec/compspec-go/plugins" "sigs.k8s.io/yaml" ) @@ -23,118 +21,3 @@ func loadRequest(filename string) (*types.CompatibilityRequest, error) { } return &request, nil } - -// Run will create a compatibility artifact based on a request in YAML -func Run(specname string, fields []string, saveto string, allowFail bool) 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(allowFail) - if err != nil { - return err - } - - // Update with custom fields (either new or overwrite) - result.AddCustomFields(fields) - - // The compspec returned is the populated Compatibility request! - compspec, err := PopulateExtractors(&result, request) - if err != nil { - return err - } - - 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) { - - // Every metadata attribute must be known under a schema - schemas := request.Metadata.Schemas - if len(schemas) == 0 { - return nil, fmt.Errorf("the request must have one or more schemas") - } - for i, compat := range request.Compatibilities { - - // The compatibility section name is a schema, and must be defined - url, ok := schemas[compat.Name] - if !ok { - return nil, fmt.Errorf("%s is missing a schema", compat.Name) - } - if url == "" { - return nil, fmt.Errorf("%s has an empty schema", compat.Name) - } - - for key, extractorKey := range compat.Attributes { - - // 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.Attributes[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.Attributes[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.Attributes[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.Attributes[key] = "" - continue - } - - // If we get here - we found it! Hooray! - compat.Attributes[key] = value - } - - // Update the compatibiity - request.Compatibilities[i] = compat - } - - return request, nil -} diff --git a/cmd/compspec/create/nodes.go b/cmd/compspec/create/nodes.go new file mode 100644 index 0000000..256067c --- /dev/null +++ b/cmd/compspec/create/nodes.go @@ -0,0 +1,180 @@ +package create + +import ( + "encoding/json" + "fmt" + "os" + "path/filepath" + "strconv" + + "github.com/compspec/compspec-go/pkg/graph" + "github.com/compspec/compspec-go/pkg/utils" + ep "github.com/compspec/compspec-go/plugins/extractors" +) + +// Nodes will read in one or more node extraction metadata files and generate a single nodes JGF graph +// This is intentended for a registration command. +// TODO this should be converted to a creation (converter) plugin +func Nodes(nodesDir, clusterName, nodeOutFile string) error { + + // Read in each node into a plugins.Result + // Results map[string]extractor.ExtractorData `json:"extractors,omitempty"` + nodes := map[string]ep.Result{} + + nodeFiles, err := os.ReadDir(nodesDir) + if err != nil { + return err + } + for _, f := range nodeFiles { + fmt.Printf("Loading %s\n", f.Name()) + result := ep.Result{} + fullpath := filepath.Join(nodesDir, f.Name()) + + // Be forgiving if extra files are there... + err := result.Load(fullpath) + if err != nil { + fmt.Printf("Warning, filename %s is not in the correct format. Skipping\n", f.Name()) + continue + } + // Add to nodes, if we don't error + nodes[f.Name()] = result + } + + // When we get here, no nodes, no graph + if len(nodes) == 0 { + fmt.Println("There were no nodes for the graph.") + return nil + } + + // Prepare a graph that will describe our cluster + g, err := graph.NewClusterGraph(clusterName) + if err != nil { + return err + } + + // This is the root node, we reference it as a parent to the rack + root := g.Graph.Nodes["0"] + + // Right now assume we have just one rack with all nodes + // https://github.com/flux-framework/flux-sched/blob/master/t/data/resource/jgfs/tiny.json#L4 + // Note that these are flux specific, and we can make them more generic if needed + + // resource (e.g., rack, node) + // name (usually the same as the resource) + // size (usually 1) + // exclusive (usually false) + // unit (usually empty or an amount) + rack := *g.AddNode("rack", "rack", 1, false, "") + + // Connect the rack to the parent, both ways. + // I think this is because fluxion is Depth First and Upwards (dfu) + // "The root cluster contains a rack" + g.AddEdge(root, rack, "contains") + + // "The rack is in a cluster" + g.AddEdge(rack, root, "in") + + // Read in each node and add to the rack. + // There are several levels here: + // /tiny0/rack0/node0/socket0/core1 + for nodeFile, meta := range nodes { + + // We must have extractors, nfd, and sections + nfd, ok := meta.Results["nfd"] + if !ok || len(nfd.Sections) == 0 { + fmt.Printf("node %s is missing extractors->nfd data, skipping\n", nodeFile) + continue + } + + // We also need system -> sections -> processor + system, ok := meta.Results["system"] + if !ok || len(system.Sections) == 0 { + fmt.Printf("node %s is missing extractors->system data, skipping\n", nodeFile) + continue + } + processor, ok := system.Sections["processor"] + if !ok || len(processor) == 0 { + fmt.Printf("node %s is missing extractors->system->processor, skipping\n", nodeFile) + continue + } + cpu, ok := system.Sections["cpu"] + if !ok || len(cpu) == 0 { + fmt.Printf("node %s is missing extractors->system->cpu, skipping\n", nodeFile) + continue + } + + // IMPORTANT: this is runtime nproces, which might be physical and virtual + // we need hwloc for just physical I think + cores, ok := cpu["cores"] + if !ok { + fmt.Printf("node %s is missing extractors->system->cpu->cores, skipping\n", nodeFile) + continue + } + cpuCount, err := strconv.Atoi(cores) + if err != nil { + fmt.Printf("node %s cannot convert cores, skipping\n", nodeFile) + continue + } + + // First add the rack -> node + node := *g.AddNode("node", "node", 1, false, "") + g.AddEdge(rack, node, "contains") + g.AddEdge(node, rack, "in") + + // Now add the socket. We need hwloc for this + // nfd has a socket count, but we can't be sure which CPU are assigned to which? + // This isn't good enough, see https://github.com/compspec/compspec-go/issues/19 + // For the prototype we will use the nfd socket count and split cores across it + // cpu metadata from ndf + socketCount := 1 + + nfdCpu, ok := nfd.Sections["cpu"] + if ok { + sockets, ok := nfdCpu["topology.socket_count"] + if ok { + sCount, err := strconv.Atoi(sockets) + if err == nil { + socketCount = sCount + } + } + } + + // Get the processors, assume we divide between the sockets + // TODO we should also get this in better detail, physical vs logical cores + items := []string{} + for i := 0; i < cpuCount; i++ { + items = append(items, fmt.Sprintf("%s", i)) + } + // Mapping of socket to cores + chunks := utils.Chunkify(items, socketCount) + for _, chunk := range chunks { + + // Create each socket attached to the node + // rack -> node -> socket + socketNode := *g.AddNode("socket", "socket", 1, false, "") + g.AddEdge(node, socketNode, "contains") + g.AddEdge(socketNode, node, "in") + + // Create each core attached to the socket + for _, _ = range chunk { + coreNode := *g.AddNode("core", "core", 1, false, "") + g.AddEdge(socketNode, coreNode, "contains") + g.AddEdge(coreNode, socketNode, "in") + + } + } + } + + // Save graph if given a file + if nodeOutFile != "" { + err = g.SaveGraph(nodeOutFile) + if err != nil { + return err + } + } else { + toprint, _ := json.MarshalIndent(g.Graph, "", "\t") + fmt.Println(string(toprint)) + return nil + } + return nil +} diff --git a/cmd/compspec/extract/extract.go b/cmd/compspec/extract/extract.go index f06b2f4..acf6900 100644 --- a/cmd/compspec/extract/extract.go +++ b/cmd/compspec/extract/extract.go @@ -5,7 +5,7 @@ import ( "os" "runtime" - p "github.com/compspec/compspec-go/plugins" + ep "github.com/compspec/compspec-go/plugins/extractors" ) // Run will run an extraction of host metadata @@ -15,12 +15,12 @@ func Run(filename string, pluginNames []string, allowFail bool) error { // Womp womp, we only support linux! There is no other way. operatingSystem := runtime.GOOS if operatingSystem != "linux" { - return fmt.Errorf("🤓️ Sorry, we only support linux.") + return fmt.Errorf("🤓️ sorry, we only support linux") } // parse [section,...,section] into named plugins and sections // return plugins - plugins, err := p.GetPlugins(pluginNames) + plugins, err := ep.GetPlugins(pluginNames) if err != nil { return err } @@ -37,7 +37,7 @@ func Run(filename string, pluginNames []string, allowFail bool) error { // This returns an array of bytes b, err := result.ToJson() if err != nil { - return fmt.Errorf("There was an issue marshalling to JSON: %s\n", err) + return fmt.Errorf("there was an issue marshalling to JSON: %s", err) } err = os.WriteFile(filename, b, 0644) if err != nil { diff --git a/cmd/compspec/list/list.go b/cmd/compspec/list/list.go index 0af9db5..2ab77df 100644 --- a/cmd/compspec/list/list.go +++ b/cmd/compspec/list/list.go @@ -1,17 +1,25 @@ package list import ( + "github.com/compspec/compspec-go/plugins/extractors" + p "github.com/compspec/compspec-go/plugins" ) // Run will list the extractor names and sections known func Run(pluginNames []string) error { + // parse [section,...,section] into named plugins and sections // return plugins - plugins, err := p.GetPlugins(pluginNames) + plugins, err := extractors.GetPlugins(pluginNames) if err != nil { return err } + // Convert to plugin information + info := []p.PluginInformation{} + for _, p := range plugins { + info = append(info, &p) + } // List plugin table - return plugins.List() + return p.List(info) } diff --git a/docs/README.md b/docs/README.md index 1db043f..f175f68 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,9 +2,9 @@ This is early documentation that will be converted eventually to something prettier. Read more about: - - [Design](design.md) - - [Usage](usage.md) - + - [Design](design.md) of compspec + - [Usage](usage.md) generic use cases + - [Rainbow](rainbow.md) use cases and examples for the rainbow scheduler ## Thanks and Previous Art diff --git a/docs/design.md b/docs/design.md index 3d825bf..0d07d6a 100644 --- a/docs/design.md +++ b/docs/design.md @@ -9,14 +9,16 @@ The compatibility tool is responsible for extracting information about a system, ### Extractor +> The "extract" command + 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. -Examples extractors could be "library" or "system." +Examples extractors could be "library" or "system." You interact with extractor plugins via the "extract" command. -### Section +#### Section A **section** is a group of metadata within an extractor. For example, within "library" a section is for "mpi." This allows a user to specify running the `--name library[mpi]` extractor to ask for the mpi section of the library family. Another example is under kernel. The user might want to ask for more than one group to be extracted and might ask for `--name kernel[boot,config]`. Section basically provides more granularity to an extractor namespace. For the above two examples, the metadata generated would be organized like: @@ -31,12 +33,25 @@ kernel For the above, right now I am implementing extractors generally, or "wild-westy" in the sense that the namespace is oriented toward the extractor name and sections it owns (e.g., no community namespaces like archspec, spack, opencontainers, etc). This is subject to change depending on the design the working group decides on. -### Creator +### Convert + +> The "create" command + +A **converter** is a plugin that knows how to take extracted data and turn it into something else. For example: + +1. We can extract metadata about nodes and convert to Json Graph format to describe a cluster. +2. We can extract metadata about an application and create a compatibility specification. + +You interact with converters via the "create" command. + +#### Create A creator is a plugin that is responsible for creating an artifact that includes some extracted metadata. The creator is agnostic to what it it being asked to generate in the sense that it just needs a mapping. The mapping will be from the extractor namespace to the compatibility artifact namespace. For our first prototype, this just means asking for particular extractor attributes to map to a set of annotations that we want to dump into json. To start there should only be one creator plugin needed, however if there are different structures of artifacts needed, I could imagine more. An example creation specification for a prototype experiment where we care about architecture, MPI, and GPU is provided in [examples](examples). ## Overview +> This was the original proposal and may be out of date. + 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) diff --git a/docs/img/rainbow-scheduler-register.png b/docs/img/rainbow-scheduler-register.png new file mode 100644 index 0000000000000000000000000000000000000000..b547e6b5ee441e16c90991554b7ee4ad24f18724 GIT binary patch literal 77659 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 literal 0 HcmV?d00001 diff --git a/docs/rainbow/README.md b/docs/rainbow/README.md new file mode 100644 index 0000000..4204b10 --- /dev/null +++ b/docs/rainbow/README.md @@ -0,0 +1,48 @@ +# Rainbow Scheduler + +The [rainbow scheduler](https://github.com/converged-computing/rainbow) has a registration step that requires a cluster to send over node metadata. The reason is because when a user sends a request for work, the scheduler needs to understand +how to properly assign it. To do that, it needs to be able to see all the resources (clusters) available to it. + +![../img/rainbow-scheduler-register.png](../img/rainbow-scheduler-register.png) + +For the purposes of compspec here, we care about the registration step. This is what that includes: + +## Registration + +1. At registration, the cluster also sends over metadata about itself (and the nodes it has). This is going to allow for selection for those nodes. +1. When submitting a job, the user no longer is giving an exact command, but a command + an image with compatibility metadata. The compatibility metadata (somehow) needs to be used to inform the cluster selection. +1. At selection, the rainbow schdeuler needs to filter down cluster options, and choose a subset. + - Level 1: Don't ask, just choose the top choice and submit + - Level 2: Ask the cluster for TBA time or cost, choose based on that. + - Job is added to that queue. + +Specifically, this means two steps for compspec go: + +1. A step to ask each node to extract it's own metadata, saved to a directory. +2. A second step to combine those nodes into a graph. + +Likely we will take a simple approach to do an extract for one node that captures it's metadata into Json Graph Format (JGF) and then dumps into a shared directory (we might imagine this being run with a flux job) +and then some combination step. + +## Example + +In the example below, we will extract node level metadata with `compspec extract` and then generate the cluster JGF to send for registration with compspec create-nodes. + +### 1. Extract Metadata + +Let's first generate faux node metadata for a "cluster" - I will just run an extraction a few times and generate equivalent files :) This isn't such a crazy idea because it emulates nodes that are the same! + +```bash +mkdir -p ./docs/rainbow/cluster +compspec extract --name library --name nfd[cpu,memory,network,storage,system] --name system[cpu,processor,arch,memory] --out ./docs/rainbow/cluster/node-1.json +compspec extract --name library --name nfd[cpu,memory,network,storage,system] --name system[cpu,processor,arch,memory] --out ./docs/rainbow/cluster/node-2.json +compspec extract --name library --name nfd[cpu,memory,network,storage,system] --name system[cpu,processor,arch,memory] --out ./docs/rainbow/cluster/node-3.json +``` + +### 2. Create Nodes + +Now we are going to give compspec the directory, and ask it to create nodes. This will be in JSON graph format. This outputs to the terminal: + +```bash +compspec create nodes --cluster-name cluster-red --node-dir ./docs/rainbow/cluster/ +``` \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md index aaf134d..5b5efb6 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -87,11 +87,19 @@ Note that we will eventually add a description column - it's not really warrante ## 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: +The create command handles two kinds of creation (sub-commands): + + - **artifact**: create a compatibility artifact to describe an environment or application + - **nodes** create a json graph format summary of nodes (a directory with one or more extracted metadata JSON files with node metadata) + +The artifact case is described here. For the node case, you can read about it in the [rainbow scheduler](rainbow) documentation. + +### Artifact + +The create artifact 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 +./bin/compspec create artifact --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. @@ -99,7 +107,7 @@ The idea here is that you can add custom metadata fields during your build, whic ```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 +./bin/compspec create artifact --in ./examples/lammps-experiment.yaml -a custom.gpu.available=yes ``` ```console { @@ -143,7 +151,7 @@ Awesome! That, as simple as it is, is our compatibility artifact. I ran the comm 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 +./bin/compspec create artifact --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. diff --git a/pkg/extractor/extractor.go b/pkg/extractor/extractor.go index 22f6686..85e4c5d 100644 --- a/pkg/extractor/extractor.go +++ b/pkg/extractor/extractor.go @@ -15,6 +15,7 @@ type Extractor interface { Extract(interface{}) (ExtractorData, error) Validate() bool Sections() []string + // GetSection(string) ExtractorData } // ExtractorData is returned by an extractor diff --git a/pkg/graph/cluster.go b/pkg/graph/cluster.go new file mode 100644 index 0000000..cde389c --- /dev/null +++ b/pkg/graph/cluster.go @@ -0,0 +1,188 @@ +package graph + +import ( + "encoding/json" + "fmt" + "os" + + "github.com/compspec/compspec-go/pkg/utils" + "github.com/converged-computing/jsongraph-go/jsongraph/metadata" + "github.com/converged-computing/jsongraph-go/jsongraph/v2/graph" + jgf "github.com/converged-computing/jsongraph-go/jsongraph/v2/graph" +) + +// A ClusterGraph is meant to be a plain (flux oriented) JGF to describe a cluster (nodes) +type ClusterGraph struct { + *jgf.JsonGraph + + Name string + + // Top level counter for node labels (JGF v2) that maps to ids (JGF v1) + nodeCounter int32 + + // Counters for specific resource types (e.g., rack, node) + resourceCounters map[string]int32 +} + +// HasNode determines if the graph has a node, named by label +func (c *ClusterGraph) HasNode(name string) bool { + _, ok := c.Graph.Nodes[name] + return ok +} + +// Save graph to a cached file +func (c *ClusterGraph) SaveGraph(path string) error { + exists, err := utils.PathExists(path) + if err != nil { + return err + } + // Don't overwrite if exists + if exists { + fmt.Printf("Graph %s already exists, will not overwrite\n", path) + return nil + } + content, err := json.MarshalIndent(c.Graph, "", " ") + if err != nil { + return err + } + fmt.Printf("Saving graph to %s\n", path) + err = os.WriteFile(path, content, 0644) + if err != nil { + return err + } + return nil +} + +// Path gets a new path +func getNodePath(root, subpath string) string { + if subpath == "" { + return fmt.Sprintf("/%s", root) + } + return fmt.Sprintf("/%s/%s", root, subpath) +} + +// AddNode adds a node to the graph +// g.AddNode("rack", 1, false, "", root) +func (c *ClusterGraph) AddNode( + resource string, + name string, + size int32, + exclusive bool, + unit string, +) *graph.Node { + node := c.getNode(resource, name, size, exclusive, unit) + c.Graph.Nodes[*node.Label] = *node + return node +} + +// Add an edge from source to dest with some relationship +func (c *ClusterGraph) AddEdge(source, dest graph.Node, relation string) { + edge := getEdge(*source.Label, *dest.Label, relation) + c.Graph.Edges = append(c.Graph.Edges, edge) +} + +// getNode is a private shared function that can also be used to generate the root! +func (c *ClusterGraph) getNode( + resource string, + name string, + size int32, + exclusive bool, + unit string, +) *graph.Node { + + // Get the identifier for the resource type + counter, ok := c.resourceCounters[resource] + if !ok { + counter = 0 + } + + // The current count in the graph (global) + count := c.nodeCounter + + // The id in the metadata is the counter for that resource type + resourceCounter := fmt.Sprintf("%d", counter) + + // The resource name is the type + the resource counter + resourceName := fmt.Sprintf("%s%d", name, counter) + + // New Metadata with expected fluxion data + m := metadata.Metadata{} + m.AddElement("type", resource) + m.AddElement("basename", name) + m.AddElement("id", resourceCounter) + m.AddElement("name", resourceName) + + // uniq_id should be the same as the label, but as an integer + m.AddElement("uniq_id", count) + m.AddElement("rank", -1) + m.AddElement("exclusive", exclusive) + m.AddElement("unit", unit) + m.AddElement("size", size) + m.AddElement("paths", map[string]string{"containment": getNodePath(name, "")}) + + // Update the resource counter + counter += 1 + c.resourceCounters[resource] = counter + + // Update the global counter + c.nodeCounter += 1 + + // Assemble the node! + // Label for v2 will be identifier "id" for JGF v1 + label := fmt.Sprintf("%d", count) + node := graph.Node{Label: &label, Metadata: m} + return &node +} + +/* +{ + "id": "1", + "metadata": { + "type": "rack", + "basename": "rack", + "name": "rack0", + "id": 0, + "uniq_id": 1, + "rank": -1, + "exclusive": false, + "unit": "", + "size": 1, + "paths": { + "containment": "/tiny0/rack0" + } + } + },*/ + +// Init a new FlexGraph from a graphml filename +// The cluster root is slightly different so we don't use getNode here +func NewClusterGraph(name string) (ClusterGraph, error) { + + // prepare a graph to load targets into + g := jgf.NewGraph() + + // New Metadata with expected fluxion data + m := metadata.Metadata{} + m.AddElement("type", "cluster") + m.AddElement("basename", name) + m.AddElement("id", 0) + m.AddElement("uniq_id", 0) + m.AddElement("rank", -1) + m.AddElement("exclusive", false) + m.AddElement("unit", "") + m.AddElement("size", 1) + m.AddElement("paths", map[string]string{"containment": getNodePath(name, "")}) + + // Root cluster node + label := "0" + node := graph.Node{Label: &label, Metadata: m} + + // Set the root node + g.Graph.Nodes[label] = node + + // Create a new cluster! + // Start counting at 1 - index 0 is the cluster root + resourceCounters := map[string]int32{"cluster": int32(1)} + cluster := ClusterGraph{g, name, 1, resourceCounters} + + return cluster, nil +} diff --git a/pkg/graph/graph.go b/pkg/graph/compatibility.go similarity index 100% rename from pkg/graph/graph.go rename to pkg/graph/compatibility.go diff --git a/pkg/graph/edges.go b/pkg/graph/edges.go index 6cb463f..056ba03 100644 --- a/pkg/graph/edges.go +++ b/pkg/graph/edges.go @@ -4,7 +4,7 @@ import ( "github.com/converged-computing/jsongraph-go/jsongraph/v2/graph" ) -// Get an edge with a specific containment (typically "contains" or "in") -func getEdge(source string, dest string, containment string) graph.Edge { - return graph.Edge{Source: source, Target: dest, Relation: containment} +// Get an edge with a specific relationship (typically "contains" or "in") +func getEdge(source string, dest string, relation string) graph.Edge { + return graph.Edge{Source: source, Target: dest, Relation: relation} } diff --git a/pkg/utils/utils.go b/pkg/utils/utils.go index a4ec477..80168a2 100644 --- a/pkg/utils/utils.go +++ b/pkg/utils/utils.go @@ -4,6 +4,7 @@ import ( "bufio" "errors" "fmt" + "math" "math/rand" "os" "strings" @@ -21,6 +22,21 @@ func PathExists(path string) (bool, error) { return true, nil } +// chunkify a count of processors across sockets +func Chunkify(items []string, count int) [][]string { + var chunks [][]string + chunkSize := int(math.Ceil(float64(len(items) / count))) + + for i := 0; i < len(items); i += chunkSize { + end := i + chunkSize + if end > len(items) { + end = len(items) + } + chunks = append(chunks, items[i:end]) + } + return chunks +} + // SplitDelimiterList splits a list of items by an additional delimiter func SplitDelimiterList(items []string, delim string) (map[string]string, error) { diff --git a/plugins/extractors/plugins.go b/plugins/extractors/plugins.go new file mode 100644 index 0000000..330016c --- /dev/null +++ b/plugins/extractors/plugins.go @@ -0,0 +1,80 @@ +package extractors + +import ( + "strings" + + "github.com/compspec/compspec-go/plugins" + "github.com/compspec/compspec-go/plugins/extractors/kernel" + "github.com/compspec/compspec-go/plugins/extractors/library" + "github.com/compspec/compspec-go/plugins/extractors/nfd" + "github.com/compspec/compspec-go/plugins/extractors/system" +) + +// Add new plugin names here. They should correspond with the package name, then NewPlugin() +var ( + KernelExtractor = "kernel" + SystemExtractor = "system" + LibraryExtractor = "library" + NFDExtractor = "nfd" + pluginNames = []string{KernelExtractor, SystemExtractor, LibraryExtractor, NFDExtractor} +) + +// Get plugins parses a request and returns a list of plugins +// We honor the order that the plugins and sections are provided in +func GetPlugins(names []string) (PluginsRequest, error) { + + if len(names) == 0 { + names = pluginNames + } + + request := PluginsRequest{} + + // Prepare an extractor for each, and validate the requested sections + // TODO: this could also be done with an init -> Register pattern + for _, name := range names { + + // If we are given a list of section names, parse. + name, sections := plugins.ParseSections(name) + + if strings.HasPrefix(name, KernelExtractor) { + p, err := kernel.NewPlugin(sections) + if err != nil { + return request, err + } + // Save the name, the instantiated interface, and sections + pr := PluginRequest{Name: name, Extractor: p, Sections: sections} + request = append(request, pr) + } + + if strings.HasPrefix(name, NFDExtractor) { + p, err := nfd.NewPlugin(sections) + if err != nil { + return request, err + } + // Save the name, the instantiated interface, and sections + pr := PluginRequest{Name: name, Extractor: p, Sections: sections} + request = append(request, pr) + } + + if strings.HasPrefix(name, SystemExtractor) { + p, err := system.NewPlugin(sections) + if err != nil { + return request, err + } + // Save the name, the instantiated interface, and sections + pr := PluginRequest{Name: name, Extractor: p, Sections: sections} + request = append(request, pr) + } + + if strings.HasPrefix(name, LibraryExtractor) { + p, err := library.NewPlugin(sections) + if err != nil { + return request, err + } + // Save the name, the instantiated interface, and sections + pr := PluginRequest{Name: name, Extractor: p, Sections: sections} + request = append(request, pr) + } + } + return request, nil +} diff --git a/plugins/extractors/request.go b/plugins/extractors/request.go new file mode 100644 index 0000000..ea4acbe --- /dev/null +++ b/plugins/extractors/request.go @@ -0,0 +1,59 @@ +package extractors + +import ( + "fmt" + + "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/plugins" +) + +// A plugin request has a Name and sections +type PluginRequest struct { + Name string + Sections []string + Extractor extractor.Extractor +} + +// These functions make it possible to use the PluginRequest as a PluginInformation interface +func (p *PluginRequest) GetName() string { + return p.Name +} +func (p *PluginRequest) GetType() string { + return "extractor" +} +func (p *PluginRequest) GetDescription() string { + return p.Extractor.Description() +} +func (p *PluginRequest) GetSections() []plugins.PluginSection { + sections := make([]plugins.PluginSection, len(p.Extractor.Sections())) + + for _, section := range p.Extractor.Sections() { + newSection := plugins.PluginSection{Name: section} + sections = append(sections, newSection) + } + return sections +} + +type PluginsRequest []PluginRequest + +// Do the extraction for a plugin request, meaning across a set of plugins +func (r *PluginsRequest) Extract(allowFail bool) (Result, error) { + + // Prepare Result + result := Result{} + results := map[string]extractor.ExtractorData{} + + for _, p := range *r { + r, err := p.Extractor.Extract(p.Sections) + + // We can allow failure + if err != nil && !allowFail { + return result, fmt.Errorf("There was an extraction error for %s: %s\n", p.Name, err) + } else if err != nil && allowFail { + fmt.Printf("Allowing failure - ignoring extraction error for %s: %s\n", p.Name, err) + } + results[p.Name] = r + } + result.Results = results + return result, nil +} diff --git a/plugins/extractors/result.go b/plugins/extractors/result.go new file mode 100644 index 0000000..fde8ca7 --- /dev/null +++ b/plugins/extractors/result.go @@ -0,0 +1,95 @@ +package extractors + +import ( + "encoding/json" + "fmt" + "os" + "strings" + + "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/plugins" +) + +// A Result wraps named extractor data, just for easy dumping to json +type Result struct { + Results map[string]extractor.ExtractorData `json:"extractors,omitempty"` +} + +// Load a filename into the result object! +func (r *Result) Load(filename string) error { + + file, err := os.ReadFile(filename) + if err != nil { + return err + } + err = json.Unmarshal(file, r) + if err != nil { + return err + } + return nil +} + +// ToJson serializes a result to json +func (r *Result) ToJson() ([]byte, error) { + b, err := json.MarshalIndent(r, "", " ") + if err != nil { + return []byte{}, err + } + return b, err +} + +// Print prints the result to the terminal +func (r *Result) Print() { + for name, result := range r.Results { + fmt.Printf(" --Result for %s\n", name) + result.Print() + } +} + +// AddCustomFields adds or updates an existing result with +// custom metadata, either new or to overwrite +func (r *Result) AddCustomFields(fields []string) { + + for _, field := range fields { + if !strings.Contains(field, "=") { + fmt.Printf("warning: field %s does not contain an '=', skipping\n", field) + continue + } + parts := strings.Split(field, "=") + if len(parts) < 2 { + fmt.Printf("warning: field %s has an empty value, skipping\n", field) + continue + } + + // No reason the value cannot have additional = + field = parts[0] + value := strings.Join(parts[1:], "=") + + // Get the extractor, section, and subfield from the field + f, err := plugins.ParseField(field) + if err != nil { + fmt.Printf(err.Error(), field) + continue + } + + // Is the extractor name in the result? + _, ok := r.Results[f.Extractor] + if !ok { + sections := extractor.Sections{} + r.Results[f.Extractor] = extractor.ExtractorData{Sections: sections} + } + data := r.Results[f.Extractor] + + // Is the section name in the extractor data? + _, ok = data.Sections[f.Section] + if !ok { + data.Sections[f.Section] = extractor.ExtractorSection{} + } + section := data.Sections[f.Section] + section[f.Field] = value + + // Wrap it back up! + data.Sections[f.Section] = section + r.Results[f.Extractor] = data + } +} diff --git a/plugins/extractors/system/extractors.go b/plugins/extractors/system/extractors.go index 2229a84..beb9162 100644 --- a/plugins/extractors/system/extractors.go +++ b/plugins/extractors/system/extractors.go @@ -3,6 +3,7 @@ package system import ( "fmt" "os" + "runtime" "strings" "github.com/compspec/compspec-go/pkg/extractor" @@ -111,10 +112,17 @@ func getCpuFeatures(p map[string]string) (string, error) { } // getCPUInformation gets information about the system -// TODO this is not used. func getCPUInformation() (extractor.ExtractorSection, error) { info := extractor.ExtractorSection{} + // This really needs to be better, the hard part is that + // proc/cpuinfo is different between arm and others, + // and arm doesn't show physical/virtual cores + cores := runtime.NumCPU() + + // This is a guess at best + info["cores"] = fmt.Sprintf("%d", cores) + //stat, err := linuxproc.ReadCPUInfo(CpuInfoFile) //if err != nil { // return info, fmt.Errorf("cannot read %s: %s", CpuInfoFile, err) diff --git a/plugins/extractors/system/system.go b/plugins/extractors/system/system.go index bcf2a07..ee6c56b 100644 --- a/plugins/extractors/system/system.go +++ b/plugins/extractors/system/system.go @@ -20,7 +20,7 @@ const ( ) var ( - validSections = []string{ProcessorSection, OsSection, ArchSection, MemorySection} + validSections = []string{ProcessorSection, OsSection, ArchSection, MemorySection, CPUSection} ) type SystemExtractor struct { @@ -70,7 +70,13 @@ func (e SystemExtractor) Extract(interface{}) (extractor.ExtractorData, error) { } sections[OsSection] = section } - + if name == CPUSection { + section, err := getCPUInformation() + if err != nil { + return data, err + } + sections[CPUSection] = section + } if name == ArchSection { section, err := getArchInformation() if err != nil { diff --git a/plugins/field.go b/plugins/field.go index 6326ff2..2c269fc 100644 --- a/plugins/field.go +++ b/plugins/field.go @@ -21,7 +21,7 @@ func ParseField(field string) (Field, error) { // We need at least an extractor name, section, and value if len(parts) < 3 { - return f, fmt.Errorf("warning: field %s value needs to have at least .
.\n", field) + return f, fmt.Errorf("warning: field %s value needs to have at least .
.\n", field) } f.Extractor = parts[0] diff --git a/plugins/list.go b/plugins/list.go index 9883fca..9b00cc0 100644 --- a/plugins/list.go +++ b/plugins/list.go @@ -7,7 +7,7 @@ import ( ) // List plugins available, print in a pretty table! -func (r *PluginsRequest) List() error { +func List(ps []PluginInformation) error { // Write out table with nodes t := table.NewWriter() @@ -18,24 +18,28 @@ func (r *PluginsRequest) List() error { // keep count of plugins (just extractors for now) count := 0 - extractorCount := 0 + pluginCount := 0 - // TODO add description column - for _, p := range *r { - extractorCount += 1 - for i, section := range p.Extractor.Sections() { + // This will iterate across plugin types (e.g., extraction and converter) + for _, p := range ps { + pluginCount += 1 + + // This iterates across plugins in the family + for i, section := range p.GetSections() { // Add the extractor plugin description only for first in the list if i == 0 { t.AppendSeparator() - t.AppendRow(table.Row{p.Extractor.Description(), "", "", ""}) + t.AppendRow(table.Row{p.GetDescription(), "", "", ""}) } + count += 1 - t.AppendRow([]interface{}{"", "extractor", p.Name, section}) + t.AppendRow([]interface{}{"", p.GetType(), section.Name}) } + } t.AppendSeparator() - t.AppendFooter(table.Row{"Total", "", extractorCount, count}) + t.AppendFooter(table.Row{"Total", "", pluginCount, count}) t.SetStyle(table.StyleColoredCyanWhiteOnBlack) t.Render() return nil diff --git a/plugins/plugins.go b/plugins/plugins.go index fbde2bf..b375d1b 100644 --- a/plugins/plugins.go +++ b/plugins/plugins.go @@ -2,25 +2,11 @@ package plugins import ( "strings" - - "github.com/compspec/compspec-go/plugins/extractors/kernel" - "github.com/compspec/compspec-go/plugins/extractors/library" - "github.com/compspec/compspec-go/plugins/extractors/nfd" - "github.com/compspec/compspec-go/plugins/extractors/system" -) - -// Add new plugin names here. They should correspond with the package name, then NewPlugin() -var ( - KernelExtractor = "kernel" - SystemExtractor = "system" - LibraryExtractor = "library" - NFDExtractor = "nfd" - pluginNames = []string{KernelExtractor, SystemExtractor, LibraryExtractor, NFDExtractor} ) // parseSections will return sections from the name string // We could use regex here instead -func parseSections(raw string) (string, []string) { +func ParseSections(raw string) (string, []string) { sections := []string{} @@ -39,63 +25,3 @@ func parseSections(raw string) (string, []string) { sections = strings.Split(raw, ",") return name, sections } - -// Get plugins parses a request and returns a list of plugins -// We honor the order that the plugins and sections are provided in -func GetPlugins(names []string) (PluginsRequest, error) { - - if len(names) == 0 { - names = pluginNames - } - - request := PluginsRequest{} - - // Prepare an extractor for each, and validate the requested sections - // TODO: this could also be done with an init -> Register pattern - for _, name := range names { - - // If we are given a list of section names, parse. - name, sections := parseSections(name) - - if strings.HasPrefix(name, KernelExtractor) { - p, err := kernel.NewPlugin(sections) - if err != nil { - return request, err - } - // Save the name, the instantiated interface, and sections - pr := PluginRequest{Name: name, Extractor: p, Sections: sections} - request = append(request, pr) - } - - if strings.HasPrefix(name, NFDExtractor) { - p, err := nfd.NewPlugin(sections) - if err != nil { - return request, err - } - // Save the name, the instantiated interface, and sections - pr := PluginRequest{Name: name, Extractor: p, Sections: sections} - request = append(request, pr) - } - - if strings.HasPrefix(name, SystemExtractor) { - p, err := system.NewPlugin(sections) - if err != nil { - return request, err - } - // Save the name, the instantiated interface, and sections - pr := PluginRequest{Name: name, Extractor: p, Sections: sections} - request = append(request, pr) - } - - if strings.HasPrefix(name, LibraryExtractor) { - p, err := library.NewPlugin(sections) - if err != nil { - return request, err - } - // Save the name, the instantiated interface, and sections - pr := PluginRequest{Name: name, Extractor: p, Sections: sections} - request = append(request, pr) - } - } - return request, nil -} diff --git a/plugins/request.go b/plugins/request.go index 97447bd..03d9726 100644 --- a/plugins/request.go +++ b/plugins/request.go @@ -1,111 +1,19 @@ package plugins -import ( - "encoding/json" - "fmt" - "strings" - - "github.com/compspec/compspec-go/pkg/extractor" -) - -// A plugin request has a Name and sections -type PluginRequest struct { - Name string - Sections []string - Extractor extractor.Extractor - // TODO add checker here eventually too. -} - -type PluginsRequest []PluginRequest - -// A Result wraps named extractor data, just for easy dumping to json -type Result struct { - Results map[string]extractor.ExtractorData `json:"extractors,omitempty"` -} - -// ToJson serializes a result to json -func (r *Result) ToJson() ([]byte, error) { - b, err := json.MarshalIndent(r, "", " ") - if err != nil { - return []byte{}, err - } - return b, err -} - -// Print prints the result to the terminal -func (r *Result) Print() { - for name, result := range r.Results { - fmt.Printf(" --Result for %s\n", name) - result.Print() - } +// A Plugin(s)Information interface is an easy way to combine plugins across spaces +// primarily to expose metadata, etc. +type PluginsInformation interface { + GetPlugins() []PluginInformation } -// AddCustomFields adds or updates an existing result with -// custom metadata, either new or to overwrite -func (r *Result) AddCustomFields(fields []string) { - - for _, field := range fields { - if !strings.Contains(field, "=") { - fmt.Printf("warning: field %s does not contain an '=', skipping\n", field) - continue - } - parts := strings.Split(field, "=") - if len(parts) < 2 { - fmt.Printf("warning: field %s has an empty value, skipping\n", field) - continue - } - - // No reason the value cannot have additional = - field = parts[0] - value := strings.Join(parts[1:], "=") - - // Get the extractor, section, and subfield from the field - f, err := ParseField(field) - if err != nil { - fmt.Printf(err.Error(), field) - continue - } - - // Is the extractor name in the result? - _, ok := r.Results[f.Extractor] - if !ok { - sections := extractor.Sections{} - r.Results[f.Extractor] = extractor.ExtractorData{Sections: sections} - } - data := r.Results[f.Extractor] - - // Is the section name in the extractor data? - _, ok = data.Sections[f.Section] - if !ok { - data.Sections[f.Section] = extractor.ExtractorSection{} - } - section := data.Sections[f.Section] - section[f.Field] = value - - // Wrap it back up! - data.Sections[f.Section] = section - r.Results[f.Extractor] = data - } +type PluginInformation interface { + GetName() string + GetType() string + GetSections() []PluginSection + GetDescription() string } -// Do the extraction for a plugin request, meaning across a set of plugins -func (r *PluginsRequest) Extract(allowFail bool) (Result, error) { - - // Prepare Result - result := Result{} - results := map[string]extractor.ExtractorData{} - - for _, p := range *r { - r, err := p.Extractor.Extract(p.Sections) - - // We can allow failure - if err != nil && !allowFail { - return result, fmt.Errorf("There was an extraction error for %s: %s\n", p.Name, err) - } else if err != nil && allowFail { - fmt.Printf("Allowing failure - ignoring extraction error for %s: %s\n", p.Name, err) - } - results[p.Name] = r - } - result.Results = results - return result, nil +type PluginSection struct { + Description string + Name string } From 0061aac3d7e45379e9cbf29034d954e34c6789c6 Mon Sep 17 00:00:00 2001 From: vsoch Date: Sat, 24 Feb 2024 20:37:58 -0700 Subject: [PATCH 2/2] feat: add creator plugins Problem: we did not have a way to define a creator as a plugin. Solution: add a plugin interface to create. I originally was going to create separate plugin types, but I like the idea that one plugin family can decide to define both easily. When this is refactored to have a more "register" design (to make it flexible to changing the set available) it will be nice to provide Create/Extract from the same interface and keep the number of interfaces / functions for them minimal. I was going to add hwloc now, but there seems to be a bug so we will need to move forward prototyping with the current proxy for nodes, which is just using the go runtime package. We obviously need to improve upon this. Signed-off-by: vsoch --- .gitignore | 5 +- Makefile.hwloc | 35 +++ README.md | 2 + cmd/compspec/create/artifact.go | 124 ++-------- cmd/compspec/create/create.go | 23 -- cmd/compspec/create/nodes.go | 173 +------------- cmd/compspec/extract/extract.go | 4 +- cmd/compspec/list/list.go | 12 +- docs/design.md | 31 +-- docs/usage.md | 73 +++--- go.mod | 2 +- go.sum | 4 +- pkg/graph/cluster.go | 22 +- {plugins => pkg/plugin}/field.go | 4 +- .../extractor.go => plugin/plugin.go} | 31 ++- {plugins/extractors => pkg/plugin}/result.go | 15 +- pkg/types/version.go | 2 +- plugins/creators/artifact/artifact.go | 191 +++++++++++++++ plugins/creators/cluster/cluster.go | 219 ++++++++++++++++++ plugins/extractors/kernel/extractors.go | 10 +- plugins/extractors/kernel/kernel.go | 20 +- plugins/extractors/library/extractors.go | 6 +- plugins/extractors/library/library.go | 19 +- plugins/extractors/nfd/nfd.go | 21 +- plugins/extractors/plugins.go | 80 ------- plugins/extractors/request.go | 59 ----- plugins/extractors/system/arch.go | 6 +- plugins/extractors/system/extractors.go | 14 +- plugins/extractors/system/memory.go | 6 +- plugins/extractors/system/os.go | 6 +- plugins/extractors/system/system.go | 18 +- plugins/list.go | 69 ++++-- plugins/plugins.go | 111 ++++++++- plugins/request.go | 69 +++++- 34 files changed, 864 insertions(+), 622 deletions(-) create mode 100644 Makefile.hwloc delete mode 100644 cmd/compspec/create/create.go rename {plugins => pkg/plugin}/field.go (91%) rename pkg/{extractor/extractor.go => plugin/plugin.go} (56%) rename {plugins/extractors => pkg/plugin}/result.go (82%) create mode 100644 plugins/creators/artifact/artifact.go create mode 100644 plugins/creators/cluster/cluster.go delete mode 100644 plugins/extractors/plugins.go delete mode 100644 plugins/extractors/request.go diff --git a/.gitignore b/.gitignore index 1589650..5684d8f 100644 --- a/.gitignore +++ b/.gitignore @@ -17,4 +17,7 @@ # Dependency directories (remove the comment below to include it) # vendor/ bin -vendor \ No newline at end of file +vendor +cache +lib +*.json diff --git a/Makefile.hwloc b/Makefile.hwloc new file mode 100644 index 0000000..152f047 --- /dev/null +++ b/Makefile.hwloc @@ -0,0 +1,35 @@ +# This makefile will be used when we can add hwloc - there is currently a bug. +HERE ?= $(shell pwd) +LOCALBIN ?= $(shell pwd)/bin + +# Install hwloc here for use to compile, etc. +LOCALLIB ?= $(shell pwd)/lib +HWLOC_INCLUDE ?= $(LOCALLIB)/include/hwloc.h +BUILDENVVAR=CGO_CFLAGS="-I$(LOCALLIB)/include" CGO_LDFLAGS="-L$(LOCALLIB)/lib -lhwloc" + +.PHONY: all + +all: build + +.PHONY: $(LOCALBIN) +$(LOCALBIN): + mkdir -p $(LOCALBIN) + +.PHONY: $(LOCALLIB) +$(LOCALLIB): + mkdir -p $(LOCALLIB) + +$(HWLOC_INCLUDE): + git clone --depth 1 https://github.com/open-mpi/hwloc /tmp/hwloc || true && \ + cd /tmp/hwloc && ./autogen.sh && \ + ./configure --enable-static --disable-shared LDFLAGS="-static" --prefix=$(LOCALLIB)/ && \ + make LDFLAGS=-all-static && make install + +build: $(LOCALBIN) $(HWLOC_INCLUDE) + GO111MODULE="on" $(BUILDENVVAR) go build -ldflags '-w' -o $(LOCALBIN)/compspec cmd/compspec/compspec.go + +build-arm: $(LOCALBIN) $(HWLOC_INCLUDE) + GO111MODULE="on" $(BUILDENVVAR) GOARCH=arm64 go build -ldflags '-w' -o $(LOCALBIN)/compspec-arm cmd/compspec/compspec.go + +build-ppc: $(LOCALBIN) $(HWLOC_INCLUDE) + GO111MODULE="on" $(BUILDENVVAR) GOARCH=ppc64le go build -ldflags '-w' -o $(LOCALBIN)/compspec-ppc cmd/compspec/compspec.go \ No newline at end of file diff --git a/README.md b/README.md index b06ad2b..863ec32 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ This is a prototype compatibility checking tool. Right now our aim is to use in - I'm starting with just Linux. I know there are those "other" platforms, but if it doesn't run on HPC or Kubernetes easily I'm not super interested (ahem, Mac and Windows)! - not all extractors work in containers (e.g., kernel needs to be on the host) + - The node feature discovery source doesn't provide mapping of socket -> cores, nor does it give details about logical vs. physical CPU. + - We will likely want to add hwloc go bindings, but there is a bug currently. Note that for development we are using nfd-source that does not require kubernetes: diff --git a/cmd/compspec/create/artifact.go b/cmd/compspec/create/artifact.go index 9a98e55..9867927 100644 --- a/cmd/compspec/create/artifact.go +++ b/cmd/compspec/create/artifact.go @@ -1,127 +1,31 @@ package create import ( - "fmt" - "os" + "strings" - "github.com/compspec/compspec-go/pkg/types" - ep "github.com/compspec/compspec-go/plugins/extractors" - - p "github.com/compspec/compspec-go/plugins" + "github.com/compspec/compspec-go/plugins/creators/artifact" ) // Artifact will create a compatibility artifact based on a request in YAML // TODO likely want to refactor this into a proper create plugin func Artifact(specname string, fields []string, saveto string, allowFail bool) 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 := ep.GetPlugins(extractors) - if err != nil { - return err - } - - // Finally, add custom fields and extract metadata - result, err := plugins.Extract(allowFail) - if err != nil { - return err + // This is janky, oh well + allowFailFlag := "false" + if allowFail { + allowFailFlag = "true" } - // Update with custom fields (either new or overwrite) - result.AddCustomFields(fields) - - // The compspec returned is the populated Compatibility request! - compspec, err := PopulateExtractors(&result, request) + // assemble options for node creator + creator, err := artifact.NewPlugin() if err != nil { return err } - - output, err := compspec.ToJson() - if err != nil { - return err + options := map[string]string{ + "specname": specname, + "fields": strings.Join(fields, "||"), + "saveto": saveto, + "allowFail": allowFailFlag, } - 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 *ep.Result, request *types.CompatibilityRequest) (*types.CompatibilityRequest, error) { - - // Every metadata attribute must be known under a schema - schemas := request.Metadata.Schemas - if len(schemas) == 0 { - return nil, fmt.Errorf("the request must have one or more schemas") - } - for i, compat := range request.Compatibilities { - - // The compatibility section name is a schema, and must be defined - url, ok := schemas[compat.Name] - if !ok { - return nil, fmt.Errorf("%s is missing a schema", compat.Name) - } - if url == "" { - return nil, fmt.Errorf("%s has an empty schema", compat.Name) - } - - for key, extractorKey := range compat.Attributes { - - // 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.Attributes[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.Attributes[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.Attributes[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.Attributes[key] = "" - continue - } - - // If we get here - we found it! Hooray! - compat.Attributes[key] = value - } - - // Update the compatibiity - request.Compatibilities[i] = compat - } - - return request, nil + return creator.Create(options) } diff --git a/cmd/compspec/create/create.go b/cmd/compspec/create/create.go deleted file mode 100644 index 7d713e8..0000000 --- a/cmd/compspec/create/create.go +++ /dev/null @@ -1,23 +0,0 @@ -package create - -import ( - "os" - - "github.com/compspec/compspec-go/pkg/types" - "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 -} diff --git a/cmd/compspec/create/nodes.go b/cmd/compspec/create/nodes.go index 256067c..b7a4f54 100644 --- a/cmd/compspec/create/nodes.go +++ b/cmd/compspec/create/nodes.go @@ -1,15 +1,7 @@ package create import ( - "encoding/json" - "fmt" - "os" - "path/filepath" - "strconv" - - "github.com/compspec/compspec-go/pkg/graph" - "github.com/compspec/compspec-go/pkg/utils" - ep "github.com/compspec/compspec-go/plugins/extractors" + "github.com/compspec/compspec-go/plugins/creators/cluster" ) // Nodes will read in one or more node extraction metadata files and generate a single nodes JGF graph @@ -17,164 +9,15 @@ import ( // TODO this should be converted to a creation (converter) plugin func Nodes(nodesDir, clusterName, nodeOutFile string) error { - // Read in each node into a plugins.Result - // Results map[string]extractor.ExtractorData `json:"extractors,omitempty"` - nodes := map[string]ep.Result{} - - nodeFiles, err := os.ReadDir(nodesDir) - if err != nil { - return err - } - for _, f := range nodeFiles { - fmt.Printf("Loading %s\n", f.Name()) - result := ep.Result{} - fullpath := filepath.Join(nodesDir, f.Name()) - - // Be forgiving if extra files are there... - err := result.Load(fullpath) - if err != nil { - fmt.Printf("Warning, filename %s is not in the correct format. Skipping\n", f.Name()) - continue - } - // Add to nodes, if we don't error - nodes[f.Name()] = result - } - - // When we get here, no nodes, no graph - if len(nodes) == 0 { - fmt.Println("There were no nodes for the graph.") - return nil - } - - // Prepare a graph that will describe our cluster - g, err := graph.NewClusterGraph(clusterName) + // assemble options for node creator + creator, err := cluster.NewPlugin() if err != nil { return err } - - // This is the root node, we reference it as a parent to the rack - root := g.Graph.Nodes["0"] - - // Right now assume we have just one rack with all nodes - // https://github.com/flux-framework/flux-sched/blob/master/t/data/resource/jgfs/tiny.json#L4 - // Note that these are flux specific, and we can make them more generic if needed - - // resource (e.g., rack, node) - // name (usually the same as the resource) - // size (usually 1) - // exclusive (usually false) - // unit (usually empty or an amount) - rack := *g.AddNode("rack", "rack", 1, false, "") - - // Connect the rack to the parent, both ways. - // I think this is because fluxion is Depth First and Upwards (dfu) - // "The root cluster contains a rack" - g.AddEdge(root, rack, "contains") - - // "The rack is in a cluster" - g.AddEdge(rack, root, "in") - - // Read in each node and add to the rack. - // There are several levels here: - // /tiny0/rack0/node0/socket0/core1 - for nodeFile, meta := range nodes { - - // We must have extractors, nfd, and sections - nfd, ok := meta.Results["nfd"] - if !ok || len(nfd.Sections) == 0 { - fmt.Printf("node %s is missing extractors->nfd data, skipping\n", nodeFile) - continue - } - - // We also need system -> sections -> processor - system, ok := meta.Results["system"] - if !ok || len(system.Sections) == 0 { - fmt.Printf("node %s is missing extractors->system data, skipping\n", nodeFile) - continue - } - processor, ok := system.Sections["processor"] - if !ok || len(processor) == 0 { - fmt.Printf("node %s is missing extractors->system->processor, skipping\n", nodeFile) - continue - } - cpu, ok := system.Sections["cpu"] - if !ok || len(cpu) == 0 { - fmt.Printf("node %s is missing extractors->system->cpu, skipping\n", nodeFile) - continue - } - - // IMPORTANT: this is runtime nproces, which might be physical and virtual - // we need hwloc for just physical I think - cores, ok := cpu["cores"] - if !ok { - fmt.Printf("node %s is missing extractors->system->cpu->cores, skipping\n", nodeFile) - continue - } - cpuCount, err := strconv.Atoi(cores) - if err != nil { - fmt.Printf("node %s cannot convert cores, skipping\n", nodeFile) - continue - } - - // First add the rack -> node - node := *g.AddNode("node", "node", 1, false, "") - g.AddEdge(rack, node, "contains") - g.AddEdge(node, rack, "in") - - // Now add the socket. We need hwloc for this - // nfd has a socket count, but we can't be sure which CPU are assigned to which? - // This isn't good enough, see https://github.com/compspec/compspec-go/issues/19 - // For the prototype we will use the nfd socket count and split cores across it - // cpu metadata from ndf - socketCount := 1 - - nfdCpu, ok := nfd.Sections["cpu"] - if ok { - sockets, ok := nfdCpu["topology.socket_count"] - if ok { - sCount, err := strconv.Atoi(sockets) - if err == nil { - socketCount = sCount - } - } - } - - // Get the processors, assume we divide between the sockets - // TODO we should also get this in better detail, physical vs logical cores - items := []string{} - for i := 0; i < cpuCount; i++ { - items = append(items, fmt.Sprintf("%s", i)) - } - // Mapping of socket to cores - chunks := utils.Chunkify(items, socketCount) - for _, chunk := range chunks { - - // Create each socket attached to the node - // rack -> node -> socket - socketNode := *g.AddNode("socket", "socket", 1, false, "") - g.AddEdge(node, socketNode, "contains") - g.AddEdge(socketNode, node, "in") - - // Create each core attached to the socket - for _, _ = range chunk { - coreNode := *g.AddNode("core", "core", 1, false, "") - g.AddEdge(socketNode, coreNode, "contains") - g.AddEdge(coreNode, socketNode, "in") - - } - } - } - - // Save graph if given a file - if nodeOutFile != "" { - err = g.SaveGraph(nodeOutFile) - if err != nil { - return err - } - } else { - toprint, _ := json.MarshalIndent(g.Graph, "", "\t") - fmt.Println(string(toprint)) - return nil + options := map[string]string{ + "nodes-dir": nodesDir, + "cluster-name": clusterName, + "node-outfile": nodeOutFile, } - return nil + return creator.Create(options) } diff --git a/cmd/compspec/extract/extract.go b/cmd/compspec/extract/extract.go index acf6900..56e7f3a 100644 --- a/cmd/compspec/extract/extract.go +++ b/cmd/compspec/extract/extract.go @@ -5,7 +5,7 @@ import ( "os" "runtime" - ep "github.com/compspec/compspec-go/plugins/extractors" + p "github.com/compspec/compspec-go/plugins" ) // Run will run an extraction of host metadata @@ -20,7 +20,7 @@ func Run(filename string, pluginNames []string, allowFail bool) error { // parse [section,...,section] into named plugins and sections // return plugins - plugins, err := ep.GetPlugins(pluginNames) + plugins, err := p.GetPlugins(pluginNames) if err != nil { return err } diff --git a/cmd/compspec/list/list.go b/cmd/compspec/list/list.go index 2ab77df..0af9db5 100644 --- a/cmd/compspec/list/list.go +++ b/cmd/compspec/list/list.go @@ -1,25 +1,17 @@ package list import ( - "github.com/compspec/compspec-go/plugins/extractors" - p "github.com/compspec/compspec-go/plugins" ) // Run will list the extractor names and sections known func Run(pluginNames []string) error { - // parse [section,...,section] into named plugins and sections // return plugins - plugins, err := extractors.GetPlugins(pluginNames) + plugins, err := p.GetPlugins(pluginNames) if err != nil { return err } - // Convert to plugin information - info := []p.PluginInformation{} - for _, p := range plugins { - info = append(info, &p) - } // List plugin table - return p.List(info) + return plugins.List() } diff --git a/docs/design.md b/docs/design.md index 0d07d6a..c171f37 100644 --- a/docs/design.md +++ b/docs/design.md @@ -7,20 +7,28 @@ The compatibility tool is responsible for extracting information about a system, ## Definitions -### Extractor +### Plugin -> The "extract" command +A plugin can define one or more functionalities; -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: +- "Extract" is expected to know how to extract metadata about an application or environment +- "Create" is expected to create something from extracted data + +This means that 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. Examples extractors could be "library" or "system." You interact with extractor plugins via the "extract" command. +A **creator** is a plugin that is responsible for creating an artifact that includes some extracted metadata. The creator is agnostic to what it it being asked to generate in the sense that it just needs a mapping. The mapping will be from the extractor namespace to the compatibility artifact namespace. For our first prototype, this just means asking for particular extractor attributes to map to a set of annotations that we want to dump into json. To start there should only be one creator plugin needed, however if there are different structures of artifacts needed, I could imagine more. An example creation specification for a prototype experiment where we care about architecture, MPI, and GPU is provided in [examples](examples). + +Plugins can be one or the other, or both. + #### Section -A **section** is a group of metadata within an extractor. For example, within "library" a section is for "mpi." This allows a user to specify running the `--name library[mpi]` extractor to ask for the mpi section of the library family. Another example is under kernel. +A **section** is a group of metadata typically within an extractor, and could also be defined for creators when we have more use cases. +For example, within "library" a section is for "mpi." This allows a user to specify running the `--name library[mpi]` extractor to ask for the mpi section of the library family. Another example is under kernel. The user might want to ask for more than one group to be extracted and might ask for `--name kernel[boot,config]`. Section basically provides more granularity to an extractor namespace. For the above two examples, the metadata generated would be organized like: ``` @@ -33,21 +41,6 @@ kernel For the above, right now I am implementing extractors generally, or "wild-westy" in the sense that the namespace is oriented toward the extractor name and sections it owns (e.g., no community namespaces like archspec, spack, opencontainers, etc). This is subject to change depending on the design the working group decides on. -### Convert - -> The "create" command - -A **converter** is a plugin that knows how to take extracted data and turn it into something else. For example: - -1. We can extract metadata about nodes and convert to Json Graph format to describe a cluster. -2. We can extract metadata about an application and create a compatibility specification. - -You interact with converters via the "create" command. - -#### Create - -A creator is a plugin that is responsible for creating an artifact that includes some extracted metadata. The creator is agnostic to what it it being asked to generate in the sense that it just needs a mapping. The mapping will be from the extractor namespace to the compatibility artifact namespace. For our first prototype, this just means asking for particular extractor attributes to map to a set of annotations that we want to dump into json. To start there should only be one creator plugin needed, however if there are different structures of artifacts needed, I could imagine more. An example creation specification for a prototype experiment where we care about architecture, MPI, and GPU is provided in [examples](examples). - ## Overview > This was the original proposal and may be out of date. diff --git a/docs/usage.md b/docs/usage.md index 5b5efb6..01d4567 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -14,6 +14,7 @@ This generates the `bin/compspec` that you can use: ./bin/compspec ``` ```console + ┏┏┓┏┳┓┏┓┏┏┓┏┓┏ ┗┗┛┛┗┗┣┛┛┣┛┗ ┗ ┛ ┛ @@ -28,11 +29,16 @@ Commands: version See the version of compspec extract Run one or more extractors + list List plugins and known sections + create Create a compatibility artifact for the current host according to a + definition + match Match a manifest of container images / artifact pairs against a set + of host fields Arguments: -h --help Print help information - -n --name One or more specific extractor plugin names + -n --name One or more specific plugins to target names ``` ## Version @@ -41,53 +47,58 @@ Arguments: $ ./bin/compspec version ``` ```console -⭐️ compspec version 0.1.0-draft +⭐️ compspec version 0.1.1-draft ``` I know, the star should not be there. Fight me. ## List -The list command lists each extractor, and sections available for it. +The list command lists plugins (extractors and creators), and sections available for extractors. ```bash $ ./bin/compspec list ``` ```console - Compatibility Plugins - TYPE NAME SECTION - generic kernel extractor - extractor kernel boot - extractor kernel config - extractor kernel modules ----------------------------------------------------------- - generic system extractor - extractor system processor - extractor system os - extractor system arch - extractor system memory ----------------------------------------------------------- - generic library extractor - extractor library mpi ----------------------------------------------------------- - node feature discovery - extractor nfd cpu - extractor nfd kernel - extractor nfd local - extractor nfd memory - extractor nfd network - extractor nfd pci - extractor nfd storage - extractor nfd system - extractor nfd usb - TOTAL 4 17 + Compatibility Plugins + TYPE NAME SECTION + creation plugins + creator artifact + creator cluster +----------------------------------------------------------- + generic kernel extractor + extractor kernel boot + extractor kernel config + extractor kernel modules +----------------------------------------------------------- + generic system extractor + extractor system processor + extractor system os + extractor system arch + extractor system memory + extractor system cpu +----------------------------------------------------------- + generic library extractor + extractor library mpi +----------------------------------------------------------- + node feature discovery + extractor nfd cpu + extractor nfd kernel + extractor nfd local + extractor nfd memory + extractor nfd network + extractor nfd pci + extractor nfd storage + extractor nfd system + extractor nfd usb + TOTAL 6 20 ``` Note that we will eventually add a description column - it's not really warranted yet! ## Create -The create command handles two kinds of creation (sub-commands): +The create command handles two kinds of creation (sub-commands). Each of these is currently linked to a creation plugin. - **artifact**: create a compatibility artifact to describe an environment or application - **nodes** create a json graph format summary of nodes (a directory with one or more extracted metadata JSON files with node metadata) diff --git a/go.mod b/go.mod index b5d091c..fa2dfa5 100644 --- a/go.mod +++ b/go.mod @@ -4,7 +4,7 @@ go 1.20 require ( github.com/akamensky/argparse v1.4.0 - github.com/converged-computing/jsongraph-go v0.0.0-20231221142916-249fef6889b3 + github.com/converged-computing/jsongraph-go v0.0.0-20240225004212-223ddffb7565 github.com/converged-computing/nfd-source v0.0.0-20240224025007-20d686e64926 github.com/jedib0t/go-pretty/v6 v6.5.4 github.com/moby/moby v25.0.3+incompatible diff --git a/go.sum b/go.sum index 44b9560..377d95e 100644 --- a/go.sum +++ b/go.sum @@ -2,8 +2,8 @@ github.com/akamensky/argparse v1.4.0 h1:YGzvsTqCvbEZhL8zZu2AiA5nq805NZh75JNj4ajn github.com/akamensky/argparse v1.4.0/go.mod h1:S5kwC7IuDcEr5VeXtGPRVZ5o/FdhcMlQz4IZQuw64xA= github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I= github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo= -github.com/converged-computing/jsongraph-go v0.0.0-20231221142916-249fef6889b3 h1:frJJfyARuHmF2eohDCyltBLE6tRJKvA1shuS2aWQaf8= -github.com/converged-computing/jsongraph-go v0.0.0-20231221142916-249fef6889b3/go.mod h1:+DhVyLXGVfBsfta4185jd33jqa94inshCcdvsXK2Irk= +github.com/converged-computing/jsongraph-go v0.0.0-20240225004212-223ddffb7565 h1:ZwJngPrF1yvM4ZGEyoT1b8h5e0qUumOxeDZLN37pPTk= +github.com/converged-computing/jsongraph-go v0.0.0-20240225004212-223ddffb7565/go.mod h1:+DhVyLXGVfBsfta4185jd33jqa94inshCcdvsXK2Irk= github.com/converged-computing/nfd-source v0.0.0-20240224025007-20d686e64926 h1:VZmgK3t4564vdHNpE//q6kuPlugOrojkDHP4Gqd4A1g= github.com/converged-computing/nfd-source v0.0.0-20240224025007-20d686e64926/go.mod h1:I15nBsQqBTUsc3A4a6cuQmZjQ8lYUZSZ2a7UAE5SZ3g= github.com/coreos/go-systemd/v22 v22.3.2 h1:D9/bQk5vlXQFZ6Kwuu6zaiXJ9oTPe68++AzAJc1DzSI= diff --git a/pkg/graph/cluster.go b/pkg/graph/cluster.go index cde389c..1724fb9 100644 --- a/pkg/graph/cluster.go +++ b/pkg/graph/cluster.go @@ -134,25 +134,6 @@ func (c *ClusterGraph) getNode( return &node } -/* -{ - "id": "1", - "metadata": { - "type": "rack", - "basename": "rack", - "name": "rack0", - "id": 0, - "uniq_id": 1, - "rank": -1, - "exclusive": false, - "unit": "", - "size": 1, - "paths": { - "containment": "/tiny0/rack0" - } - } - },*/ - // Init a new FlexGraph from a graphml filename // The cluster root is slightly different so we don't use getNode here func NewClusterGraph(name string) (ClusterGraph, error) { @@ -160,10 +141,13 @@ func NewClusterGraph(name string) (ClusterGraph, error) { // prepare a graph to load targets into g := jgf.NewGraph() + clusterName := fmt.Sprintf("%s0", name) + // New Metadata with expected fluxion data m := metadata.Metadata{} m.AddElement("type", "cluster") m.AddElement("basename", name) + m.AddElement("name", clusterName) m.AddElement("id", 0) m.AddElement("uniq_id", 0) m.AddElement("rank", -1) diff --git a/plugins/field.go b/pkg/plugin/field.go similarity index 91% rename from plugins/field.go rename to pkg/plugin/field.go index 2c269fc..005433e 100644 --- a/plugins/field.go +++ b/pkg/plugin/field.go @@ -1,4 +1,4 @@ -package plugins +package plugin import ( "fmt" @@ -21,7 +21,7 @@ func ParseField(field string) (Field, error) { // We need at least an extractor name, section, and value if len(parts) < 3 { - return f, fmt.Errorf("warning: field %s value needs to have at least .
.\n", field) + return f, fmt.Errorf("warning: field %s value needs to have at least .
.\n", field) } f.Extractor = parts[0] diff --git a/pkg/extractor/extractor.go b/pkg/plugin/plugin.go similarity index 56% rename from pkg/extractor/extractor.go rename to pkg/plugin/plugin.go index 85e4c5d..c53833e 100644 --- a/pkg/extractor/extractor.go +++ b/pkg/plugin/plugin.go @@ -1,31 +1,40 @@ -package extractor +package plugin import ( "encoding/json" "fmt" ) -// An Extractor interface has: +// A Plugin interface can define any of the following: // // an Extract function to return extractor data across sections // a validate function to typically check that the plugin is valid -type Extractor interface { +// a Creation interface that can use extractor data to generate something new +type PluginInterface interface { Name() string Description() string - Extract(interface{}) (ExtractorData, error) + + // This is probably a dumb way to do it, but it works + IsExtractor() bool + IsCreator() bool + + // Extractors + Extract(interface{}) (PluginData, error) Validate() bool Sections() []string - // GetSection(string) ExtractorData + + // Creators take a map of named options + Create(map[string]string) error } // ExtractorData is returned by an extractor -type ExtractorData struct { +type PluginData struct { Sections Sections `json:"sections,omitempty"` } -type Sections map[string]ExtractorSection +type Sections map[string]PluginSection // Print extractor data to the console -func (e *ExtractorData) Print() { +func (e *PluginData) Print() { for name, section := range e.Sections { fmt.Printf(" -- Section %s\n", name) for key, value := range section { @@ -36,7 +45,7 @@ func (e *ExtractorData) Print() { } // ToJson serializes to json -func (e *ExtractorData) ToJson() (string, error) { +func (e *PluginData) ToJson() (string, error) { b, err := json.MarshalIndent(e, "", " ") if err != nil { return "", err @@ -45,7 +54,7 @@ func (e *ExtractorData) ToJson() (string, error) { } // An extractor section corresponds to a named group of attributes -type ExtractorSection map[string]string +type PluginSection map[string]string // Extractors is a lookup of registered extractors by name -type Extractors map[string]Extractor +type Plugins map[string]PluginInterface diff --git a/plugins/extractors/result.go b/pkg/plugin/result.go similarity index 82% rename from plugins/extractors/result.go rename to pkg/plugin/result.go index fde8ca7..0b84d51 100644 --- a/plugins/extractors/result.go +++ b/pkg/plugin/result.go @@ -1,18 +1,15 @@ -package extractors +package plugin import ( "encoding/json" "fmt" "os" "strings" - - "github.com/compspec/compspec-go/pkg/extractor" - "github.com/compspec/compspec-go/plugins" ) // A Result wraps named extractor data, just for easy dumping to json type Result struct { - Results map[string]extractor.ExtractorData `json:"extractors,omitempty"` + Results map[string]PluginData `json:"results,omitempty"` } // Load a filename into the result object! @@ -66,7 +63,7 @@ func (r *Result) AddCustomFields(fields []string) { value := strings.Join(parts[1:], "=") // Get the extractor, section, and subfield from the field - f, err := plugins.ParseField(field) + f, err := ParseField(field) if err != nil { fmt.Printf(err.Error(), field) continue @@ -75,15 +72,15 @@ func (r *Result) AddCustomFields(fields []string) { // Is the extractor name in the result? _, ok := r.Results[f.Extractor] if !ok { - sections := extractor.Sections{} - r.Results[f.Extractor] = extractor.ExtractorData{Sections: sections} + sections := Sections{} + r.Results[f.Extractor] = PluginData{Sections: sections} } data := r.Results[f.Extractor] // Is the section name in the extractor data? _, ok = data.Sections[f.Section] if !ok { - data.Sections[f.Section] = extractor.ExtractorSection{} + data.Sections[f.Section] = PluginSection{} } section := data.Sections[f.Section] section[f.Field] = value diff --git a/pkg/types/version.go b/pkg/types/version.go index cd34d7b..65b41db 100644 --- a/pkg/types/version.go +++ b/pkg/types/version.go @@ -10,7 +10,7 @@ const ( VersionMinor = 1 // VersionPatch is for backwards-compatible bug fixes - VersionPatch = 0 + VersionPatch = 1 // VersionDraft indicates development branch. Releases will be empty string. VersionDraft = "-draft" diff --git a/plugins/creators/artifact/artifact.go b/plugins/creators/artifact/artifact.go new file mode 100644 index 0000000..a7bdf63 --- /dev/null +++ b/plugins/creators/artifact/artifact.go @@ -0,0 +1,191 @@ +package artifact + +import ( + "fmt" + "os" + "strings" + + "github.com/compspec/compspec-go/pkg/plugin" + "github.com/compspec/compspec-go/pkg/types" + p "github.com/compspec/compspec-go/plugins" + "sigs.k8s.io/yaml" +) + +const ( + CreatorName = "artifact" + CreatorDescription = "describe an application or environment" +) + +type ArtifactCreator struct{} + +func (c ArtifactCreator) Description() string { + return CreatorDescription +} + +func (c ArtifactCreator) Name() string { + return CreatorName +} + +func (c ArtifactCreator) Sections() []string { + return []string{} +} + +func (c ArtifactCreator) Extract(interface{}) (plugin.PluginData, error) { + return plugin.PluginData{}, nil +} +func (c ArtifactCreator) IsCreator() bool { return true } +func (c ArtifactCreator) IsExtractor() bool { return false } + +// Create generates the desired output +func (c ArtifactCreator) Create(options map[string]string) error { + + // unwrap options (we can be sure they are at least provided) + specname := options["specname"] + saveto := options["saveto"] + fieldsCombined := options["fields"] + fields := strings.Split(fieldsCombined, "||") + + // This is uber janky. We could use interfaces + // But I just feel so lazy right now + allowFailFlag := options["allowFail"] + allowFail := false + if allowFailFlag == "true" { + allowFail = true + } + + // 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(allowFail) + if err != nil { + return err + } + + // Update with custom fields (either new or overwrite) + result.AddCustomFields(fields) + + // The compspec returned is the populated Compatibility request! + compspec, err := PopulateExtractors(&result, request) + if err != nil { + return err + } + + 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 +} + +// 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 +} + +// 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 *plugin.Result, request *types.CompatibilityRequest) (*types.CompatibilityRequest, error) { + + // Every metadata attribute must be known under a schema + schemas := request.Metadata.Schemas + if len(schemas) == 0 { + return nil, fmt.Errorf("the request must have one or more schemas") + } + for i, compat := range request.Compatibilities { + + // The compatibility section name is a schema, and must be defined + url, ok := schemas[compat.Name] + if !ok { + return nil, fmt.Errorf("%s is missing a schema", compat.Name) + } + if url == "" { + return nil, fmt.Errorf("%s has an empty schema", compat.Name) + } + + for key, extractorKey := range compat.Attributes { + + // Get the extractor, section, and subfield from the extractor lookup key + f, err := plugin.ParseField(extractorKey) + if err != nil { + fmt.Printf("warning: cannot parse %s: %s, setting to empty\n", key, extractorKey) + compat.Attributes[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.Attributes[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.Attributes[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.Attributes[key] = "" + continue + } + + // If we get here - we found it! Hooray! + compat.Attributes[key] = value + } + + // Update the compatibiity + request.Compatibilities[i] = compat + } + + return request, nil +} + +func (c ArtifactCreator) Validate() bool { + return true +} + +// NewPlugin creates a new ArtifactCreator +func NewPlugin() (plugin.PluginInterface, error) { + c := ArtifactCreator{} + return c, nil +} diff --git a/plugins/creators/cluster/cluster.go b/plugins/creators/cluster/cluster.go new file mode 100644 index 0000000..622f47a --- /dev/null +++ b/plugins/creators/cluster/cluster.go @@ -0,0 +1,219 @@ +package cluster + +import ( + "encoding/json" + "fmt" + "os" + "path/filepath" + "strconv" + + "github.com/compspec/compspec-go/pkg/graph" + "github.com/compspec/compspec-go/pkg/plugin" + "github.com/compspec/compspec-go/pkg/utils" +) + +const ( + CreatorName = "cluster" + CreatorDescription = "create cluster of nodes" +) + +type ClusterCreator struct{} + +func (c ClusterCreator) Description() string { + return CreatorDescription +} + +func (c ClusterCreator) Name() string { + return CreatorName +} + +func (c ClusterCreator) Sections() []string { + return []string{} +} + +func (c ClusterCreator) Extract(interface{}) (plugin.PluginData, error) { + return plugin.PluginData{}, nil +} +func (c ClusterCreator) IsCreator() bool { return true } +func (c ClusterCreator) IsExtractor() bool { return false } + +// Create generates the desired output +func (c ClusterCreator) Create(options map[string]string) error { + + // unwrap options (we can be sure they are at least provided) + nodesDir := options["nodes-dir"] + clusterName := options["cluster-name"] + nodeOutFile := options["node-outfile"] + + // Read in each node into a plugins.Result + // Results map[string]plugin.PluginData `json:"extractors,omitempty"` + nodes := map[string]plugin.Result{} + + nodeFiles, err := os.ReadDir(nodesDir) + if err != nil { + return err + } + for _, f := range nodeFiles { + fmt.Printf("Loading %s\n", f.Name()) + result := plugin.Result{} + fullpath := filepath.Join(nodesDir, f.Name()) + + // Be forgiving if extra files are there... + err := result.Load(fullpath) + if err != nil { + fmt.Printf("Warning, filename %s is not in the correct format. Skipping\n", f.Name()) + continue + } + // Add to nodes, if we don't error + nodes[f.Name()] = result + } + + // When we get here, no nodes, no graph + if len(nodes) == 0 { + fmt.Println("There were no nodes for the graph.") + return nil + } + + // Prepare a graph that will describe our cluster + g, err := graph.NewClusterGraph(clusterName) + if err != nil { + return err + } + + // This is the root node, we reference it as a parent to the rack + root := g.Graph.Nodes["0"] + + // Right now assume we have just one rack with all nodes + // https://github.com/flux-framework/flux-sched/blob/master/t/data/resource/jgfs/tiny.json#L4 + // Note that these are flux specific, and we can make them more generic if needed + + // resource (e.g., rack, node) + // name (usually the same as the resource) + // size (usually 1) + // exclusive (usually false) + // unit (usually empty or an amount) + rack := *g.AddNode("rack", "rack", 1, false, "") + + // Connect the rack to the parent, both ways. + // I think this is because fluxion is Depth First and Upwards (dfu) + // "The root cluster contains a rack" + g.AddEdge(root, rack, "contains") + + // "The rack is in a cluster" + g.AddEdge(rack, root, "in") + + // Read in each node and add to the rack. + // There are several levels here: + // /tiny0/rack0/node0/socket0/core1 + for nodeFile, meta := range nodes { + + // We must have extractors, nfd, and sections + nfd, ok := meta.Results["nfd"] + if !ok || len(nfd.Sections) == 0 { + fmt.Printf("node %s is missing extractors->nfd data, skipping\n", nodeFile) + continue + } + + // We also need system -> sections -> processor + system, ok := meta.Results["system"] + if !ok || len(system.Sections) == 0 { + fmt.Printf("node %s is missing extractors->system data, skipping\n", nodeFile) + continue + } + processor, ok := system.Sections["processor"] + if !ok || len(processor) == 0 { + fmt.Printf("node %s is missing extractors->system->processor, skipping\n", nodeFile) + continue + } + cpu, ok := system.Sections["cpu"] + if !ok || len(cpu) == 0 { + fmt.Printf("node %s is missing extractors->system->cpu, skipping\n", nodeFile) + continue + } + + // IMPORTANT: this is runtime nproces, which might be physical and virtual + // we need hwloc for just physical I think + cores, ok := cpu["cores"] + if !ok { + fmt.Printf("node %s is missing extractors->system->cpu->cores, skipping\n", nodeFile) + continue + } + cpuCount, err := strconv.Atoi(cores) + if err != nil { + fmt.Printf("node %s cannot convert cores, skipping\n", nodeFile) + continue + } + + // First add the rack -> node + node := *g.AddNode("node", "node", 1, false, "") + g.AddEdge(rack, node, "contains") + g.AddEdge(node, rack, "in") + + // Now add the socket. We need hwloc for this + // nfd has a socket count, but we can't be sure which CPU are assigned to which? + // This isn't good enough, see https://github.com/compspec/compspec-go/issues/19 + // For the prototype we will use the nfd socket count and split cores across it + // cpu metadata from ndf + socketCount := 1 + + nfdCpu, ok := nfd.Sections["cpu"] + if ok { + sockets, ok := nfdCpu["topology.socket_count"] + if ok { + sCount, err := strconv.Atoi(sockets) + if err == nil { + socketCount = sCount + } + } + } + + // Get the processors, assume we divide between the sockets + // TODO we should also get this in better detail, physical vs logical cores + items := []string{} + for i := 0; i < cpuCount; i++ { + items = append(items, fmt.Sprintf("%s", i)) + } + // Mapping of socket to cores + chunks := utils.Chunkify(items, socketCount) + for _, chunk := range chunks { + + // Create each socket attached to the node + // rack -> node -> socket + socketNode := *g.AddNode("socket", "socket", 1, false, "") + g.AddEdge(node, socketNode, "contains") + g.AddEdge(socketNode, node, "in") + + // Create each core attached to the socket + for _, _ = range chunk { + coreNode := *g.AddNode("core", "core", 1, false, "") + g.AddEdge(socketNode, coreNode, "contains") + g.AddEdge(coreNode, socketNode, "in") + + } + } + } + + // Save graph if given a file + if nodeOutFile != "" { + err = g.SaveGraph(nodeOutFile) + if err != nil { + return err + } + } else { + toprint, _ := json.MarshalIndent(g.Graph, "", "\t") + fmt.Println(string(toprint)) + return nil + } + return nil + +} + +func (c ClusterCreator) Validate() bool { + return true +} + +// NewPlugin creates a new ClusterCreator +func NewPlugin() (plugin.PluginInterface, error) { + c := ClusterCreator{} + return c, nil +} diff --git a/plugins/extractors/kernel/extractors.go b/plugins/extractors/kernel/extractors.go index 667e2de..5e4f9bf 100644 --- a/plugins/extractors/kernel/extractors.go +++ b/plugins/extractors/kernel/extractors.go @@ -5,7 +5,7 @@ import ( "os" "strings" - "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/pkg/plugin" "github.com/compspec/compspec-go/pkg/utils" kernelParser "github.com/moby/moby/pkg/parsers/kernel" ) @@ -24,7 +24,7 @@ const ( ) // getKernelBootParams loads parameters given to the kernel at boot time -func getKernelBootParams() (extractor.ExtractorSection, error) { +func getKernelBootParams() (plugin.PluginSection, error) { raw, err := os.ReadFile(kernelBootFile) if err != nil { @@ -36,7 +36,7 @@ func getKernelBootParams() (extractor.ExtractorSection, error) { } // getKernelBootConfig loads key value pairs from the kernel config -func getKernelBootConfig() (extractor.ExtractorSection, error) { +func getKernelBootConfig() (plugin.PluginSection, error) { version, err := kernelParser.GetKernelVersion() if err != nil { @@ -50,7 +50,7 @@ func getKernelBootConfig() (extractor.ExtractorSection, error) { // getKernelModules flattens the list of kernel modules (drivers) into // the name (and if enabled) and version. I don't know if we need more than that. -func getKernelModules() (extractor.ExtractorSection, error) { +func getKernelModules() (plugin.PluginSection, error) { version, err := kernelParser.GetKernelVersion() if err != nil { return nil, err @@ -66,7 +66,7 @@ func getKernelModules() (extractor.ExtractorSection, error) { // module. = // module.parameter. = value // TODO will this work? - modules := extractor.ExtractorSection{} + modules := plugin.PluginSection{} for _, moduleDir := range moduleDirs { // Don't look unless it's a directory diff --git a/plugins/extractors/kernel/kernel.go b/plugins/extractors/kernel/kernel.go index 4a8c241..ad7ceed 100644 --- a/plugins/extractors/kernel/kernel.go +++ b/plugins/extractors/kernel/kernel.go @@ -3,7 +3,7 @@ package kernel import ( "fmt" - "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/pkg/plugin" "github.com/compspec/compspec-go/pkg/utils" ) @@ -27,6 +27,12 @@ func (e KernelExtractor) Description() string { return ExtractorDescription } +func (e KernelExtractor) Create(options map[string]string) error { + return nil +} +func (e KernelExtractor) IsCreator() bool { return false } +func (e KernelExtractor) IsExtractor() bool { return true } + func (e KernelExtractor) Sections() []string { return e.sections } @@ -48,10 +54,10 @@ func (c KernelExtractor) Validate() bool { // Extract returns kernel metadata, for a set of named sections // TODO eventually the user could select which sections they want -func (c KernelExtractor) Extract(interface{}) (extractor.ExtractorData, error) { +func (c KernelExtractor) Extract(interface{}) (plugin.PluginData, error) { - sections := map[string]extractor.ExtractorSection{} - data := extractor.ExtractorData{} + sections := map[string]plugin.PluginSection{} + data := plugin.PluginData{} // Only extract the sections we asked for for _, name := range c.sections { @@ -87,14 +93,14 @@ func (c KernelExtractor) Extract(interface{}) (extractor.ExtractorData, error) { return data, nil } -// NewPlugin validates and returns a new kernel plugin -func NewPlugin(sections []string) (extractor.Extractor, error) { +// NewPlugin validates and returns a new kernel plugins +func NewPlugin(sections []string) (plugin.PluginInterface, error) { if len(sections) == 0 { sections = validSections } e := KernelExtractor{sections: sections} if !e.Validate() { - return nil, fmt.Errorf("plugin %s is not valid\n", e.Name()) + return nil, fmt.Errorf("plugin %s is not valid", e.Name()) } return e, nil } diff --git a/plugins/extractors/library/extractors.go b/plugins/extractors/library/extractors.go index 3dab797..573cace 100644 --- a/plugins/extractors/library/extractors.go +++ b/plugins/extractors/library/extractors.go @@ -6,7 +6,7 @@ import ( "regexp" "strings" - "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/pkg/plugin" "github.com/compspec/compspec-go/pkg/utils" ) @@ -20,8 +20,8 @@ var ( // getMPIInformation returns info on mpi versions and variant // yes, fairly janky, please improve upon! This is for a prototype -func getMPIInformation() (extractor.ExtractorSection, error) { - info := extractor.ExtractorSection{} +func getMPIInformation() (plugin.PluginSection, error) { + info := plugin.PluginSection{} // Do we even have mpirun? path, err := exec.LookPath(MPIRunExec) diff --git a/plugins/extractors/library/library.go b/plugins/extractors/library/library.go index 2bb3df2..ae4236e 100644 --- a/plugins/extractors/library/library.go +++ b/plugins/extractors/library/library.go @@ -3,7 +3,7 @@ package library import ( "fmt" - "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/pkg/plugin" "github.com/compspec/compspec-go/pkg/utils" ) @@ -33,6 +33,13 @@ func (e LibraryExtractor) Description() string { return ExtractorDescription } +func (e LibraryExtractor) Create(options map[string]string) error { + return nil +} + +func (e LibraryExtractor) IsCreator() bool { return false } +func (e LibraryExtractor) IsExtractor() bool { return true } + // Validate ensures that the sections provided are in the list we know func (e LibraryExtractor) Validate() bool { invalids, valid := utils.StringArrayIsSubset(e.sections, validSections) @@ -43,10 +50,10 @@ func (e LibraryExtractor) Validate() bool { } // Extract returns library metadata, for a set of named sections -func (e LibraryExtractor) Extract(interface{}) (extractor.ExtractorData, error) { +func (e LibraryExtractor) Extract(interface{}) (plugin.PluginData, error) { - sections := map[string]extractor.ExtractorSection{} - data := extractor.ExtractorData{} + sections := map[string]plugin.PluginSection{} + data := plugin.PluginData{} // Only extract the sections we asked for for _, name := range e.sections { @@ -63,13 +70,13 @@ func (e LibraryExtractor) Extract(interface{}) (extractor.ExtractorData, error) } // NewPlugin validates and returns a new plugin -func NewPlugin(sections []string) (extractor.Extractor, error) { +func NewPlugin(sections []string) (plugin.PluginInterface, error) { if len(sections) == 0 { sections = validSections } e := LibraryExtractor{sections: sections} if !e.Validate() { - return nil, fmt.Errorf("plugin %s is not valid\n", e.Name()) + return nil, fmt.Errorf("plugin %s is not valid", e.Name()) } return e, nil } diff --git a/plugins/extractors/nfd/nfd.go b/plugins/extractors/nfd/nfd.go index 0afd16c..bdc9314 100644 --- a/plugins/extractors/nfd/nfd.go +++ b/plugins/extractors/nfd/nfd.go @@ -16,7 +16,7 @@ import ( _ "github.com/converged-computing/nfd-source/source/system" _ "github.com/converged-computing/nfd-source/source/usb" - "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/pkg/plugin" "github.com/compspec/compspec-go/pkg/utils" ) @@ -69,6 +69,13 @@ func (e NFDExtractor) Description() string { return ExtractorDescription } +func (e NFDExtractor) Create(options map[string]string) error { + return nil +} + +func (e NFDExtractor) IsCreator() bool { return false } +func (e NFDExtractor) IsExtractor() bool { return true } + // Validate ensures that the sections provided are in the list we know func (e NFDExtractor) Validate() bool { invalids, valid := utils.StringArrayIsSubset(e.sections, validSections) @@ -79,10 +86,10 @@ func (e NFDExtractor) Validate() bool { } // Extract returns system metadata, for a set of named sections -func (e NFDExtractor) Extract(interface{}) (extractor.ExtractorData, error) { +func (e NFDExtractor) Extract(interface{}) (plugin.PluginData, error) { - sections := map[string]extractor.ExtractorSection{} - data := extractor.ExtractorData{} + sections := map[string]plugin.PluginSection{} + data := plugin.PluginData{} // Get all registered feature sources sources := source.GetAllFeatureSources() @@ -105,7 +112,7 @@ func (e NFDExtractor) Extract(interface{}) (extractor.ExtractorData, error) { // Create a new section for the group // For each of the below, "fs" is a feature set // AttributeFeatureSet - section := extractor.ExtractorSection{} + section := plugin.PluginSection{} features := discovery.GetFeatures() for k, fs := range features.Attributes { for fName, feature := range fs.Elements { @@ -140,13 +147,13 @@ func (e NFDExtractor) Extract(interface{}) (extractor.ExtractorData, error) { } // NewPlugin validates and returns a new kernel plugin -func NewPlugin(sections []string) (extractor.Extractor, error) { +func NewPlugin(sections []string) (plugin.PluginInterface, error) { if len(sections) == 0 { sections = validSections } e := NFDExtractor{sections: sections} if !e.Validate() { - return nil, fmt.Errorf("plugin %s is not valid\n", e.Name()) + return nil, fmt.Errorf("plugin %s is not valid", e.Name()) } return e, nil } diff --git a/plugins/extractors/plugins.go b/plugins/extractors/plugins.go deleted file mode 100644 index 330016c..0000000 --- a/plugins/extractors/plugins.go +++ /dev/null @@ -1,80 +0,0 @@ -package extractors - -import ( - "strings" - - "github.com/compspec/compspec-go/plugins" - "github.com/compspec/compspec-go/plugins/extractors/kernel" - "github.com/compspec/compspec-go/plugins/extractors/library" - "github.com/compspec/compspec-go/plugins/extractors/nfd" - "github.com/compspec/compspec-go/plugins/extractors/system" -) - -// Add new plugin names here. They should correspond with the package name, then NewPlugin() -var ( - KernelExtractor = "kernel" - SystemExtractor = "system" - LibraryExtractor = "library" - NFDExtractor = "nfd" - pluginNames = []string{KernelExtractor, SystemExtractor, LibraryExtractor, NFDExtractor} -) - -// Get plugins parses a request and returns a list of plugins -// We honor the order that the plugins and sections are provided in -func GetPlugins(names []string) (PluginsRequest, error) { - - if len(names) == 0 { - names = pluginNames - } - - request := PluginsRequest{} - - // Prepare an extractor for each, and validate the requested sections - // TODO: this could also be done with an init -> Register pattern - for _, name := range names { - - // If we are given a list of section names, parse. - name, sections := plugins.ParseSections(name) - - if strings.HasPrefix(name, KernelExtractor) { - p, err := kernel.NewPlugin(sections) - if err != nil { - return request, err - } - // Save the name, the instantiated interface, and sections - pr := PluginRequest{Name: name, Extractor: p, Sections: sections} - request = append(request, pr) - } - - if strings.HasPrefix(name, NFDExtractor) { - p, err := nfd.NewPlugin(sections) - if err != nil { - return request, err - } - // Save the name, the instantiated interface, and sections - pr := PluginRequest{Name: name, Extractor: p, Sections: sections} - request = append(request, pr) - } - - if strings.HasPrefix(name, SystemExtractor) { - p, err := system.NewPlugin(sections) - if err != nil { - return request, err - } - // Save the name, the instantiated interface, and sections - pr := PluginRequest{Name: name, Extractor: p, Sections: sections} - request = append(request, pr) - } - - if strings.HasPrefix(name, LibraryExtractor) { - p, err := library.NewPlugin(sections) - if err != nil { - return request, err - } - // Save the name, the instantiated interface, and sections - pr := PluginRequest{Name: name, Extractor: p, Sections: sections} - request = append(request, pr) - } - } - return request, nil -} diff --git a/plugins/extractors/request.go b/plugins/extractors/request.go deleted file mode 100644 index ea4acbe..0000000 --- a/plugins/extractors/request.go +++ /dev/null @@ -1,59 +0,0 @@ -package extractors - -import ( - "fmt" - - "github.com/compspec/compspec-go/pkg/extractor" - "github.com/compspec/compspec-go/plugins" -) - -// A plugin request has a Name and sections -type PluginRequest struct { - Name string - Sections []string - Extractor extractor.Extractor -} - -// These functions make it possible to use the PluginRequest as a PluginInformation interface -func (p *PluginRequest) GetName() string { - return p.Name -} -func (p *PluginRequest) GetType() string { - return "extractor" -} -func (p *PluginRequest) GetDescription() string { - return p.Extractor.Description() -} -func (p *PluginRequest) GetSections() []plugins.PluginSection { - sections := make([]plugins.PluginSection, len(p.Extractor.Sections())) - - for _, section := range p.Extractor.Sections() { - newSection := plugins.PluginSection{Name: section} - sections = append(sections, newSection) - } - return sections -} - -type PluginsRequest []PluginRequest - -// Do the extraction for a plugin request, meaning across a set of plugins -func (r *PluginsRequest) Extract(allowFail bool) (Result, error) { - - // Prepare Result - result := Result{} - results := map[string]extractor.ExtractorData{} - - for _, p := range *r { - r, err := p.Extractor.Extract(p.Sections) - - // We can allow failure - if err != nil && !allowFail { - return result, fmt.Errorf("There was an extraction error for %s: %s\n", p.Name, err) - } else if err != nil && allowFail { - fmt.Printf("Allowing failure - ignoring extraction error for %s: %s\n", p.Name, err) - } - results[p.Name] = r - } - result.Results = results - return result, nil -} diff --git a/plugins/extractors/system/arch.go b/plugins/extractors/system/arch.go index 113037b..3cba3a2 100644 --- a/plugins/extractors/system/arch.go +++ b/plugins/extractors/system/arch.go @@ -4,7 +4,7 @@ import ( "fmt" "os/exec" - "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/pkg/plugin" "github.com/compspec/compspec-go/pkg/utils" ) @@ -35,8 +35,8 @@ func getOsArch() (string, error) { } // getArchInformation gets architecture information -func getArchInformation() (extractor.ExtractorSection, error) { - info := extractor.ExtractorSection{} +func getArchInformation() (plugin.PluginSection, error) { + info := plugin.PluginSection{} // Read in architectures arch, err := getOsArch() diff --git a/plugins/extractors/system/extractors.go b/plugins/extractors/system/extractors.go index beb9162..448470e 100644 --- a/plugins/extractors/system/extractors.go +++ b/plugins/extractors/system/extractors.go @@ -6,7 +6,7 @@ import ( "runtime" "strings" - "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/pkg/plugin" "github.com/compspec/compspec-go/pkg/utils" ) @@ -112,12 +112,10 @@ func getCpuFeatures(p map[string]string) (string, error) { } // getCPUInformation gets information about the system -func getCPUInformation() (extractor.ExtractorSection, error) { - info := extractor.ExtractorSection{} +// TODO this is not used. +func getCPUInformation() (plugin.PluginSection, error) { + info := plugin.PluginSection{} - // This really needs to be better, the hard part is that - // proc/cpuinfo is different between arm and others, - // and arm doesn't show physical/virtual cores cores := runtime.NumCPU() // This is a guess at best @@ -137,8 +135,8 @@ func getCPUInformation() (extractor.ExtractorSection, error) { } // getProcessorInformation returns details about each processor -func getProcessorInformation() (extractor.ExtractorSection, error) { - info := extractor.ExtractorSection{} +func getProcessorInformation() (plugin.PluginSection, error) { + info := plugin.PluginSection{} raw, err := os.ReadFile(CpuInfoFile) if err != nil { diff --git a/plugins/extractors/system/memory.go b/plugins/extractors/system/memory.go index db9b283..fb2bb92 100644 --- a/plugins/extractors/system/memory.go +++ b/plugins/extractors/system/memory.go @@ -4,7 +4,7 @@ import ( "os" "strings" - "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/pkg/plugin" ) const ( @@ -12,8 +12,8 @@ const ( ) // getMemoryInformation parses /proc/meminfo to get node memory metadata -func getMemoryInformation() (extractor.ExtractorSection, error) { - info := extractor.ExtractorSection{} +func getMemoryInformation() (plugin.PluginSection, error) { + info := plugin.PluginSection{} raw, err := os.ReadFile(memoryInfoFile) if err != nil { diff --git a/plugins/extractors/system/os.go b/plugins/extractors/system/os.go index 38fd597..4af0679 100644 --- a/plugins/extractors/system/os.go +++ b/plugins/extractors/system/os.go @@ -11,7 +11,7 @@ import ( "regexp" "strings" - "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/pkg/plugin" ) const ( @@ -124,8 +124,8 @@ func readOsRelease(prettyName string, vendor string) (string, error) { } // getOSInformation gets operating system level metadata -func getOsInformation() (extractor.ExtractorSection, error) { - info := extractor.ExtractorSection{} +func getOsInformation() (plugin.PluginSection, error) { + info := plugin.PluginSection{} // Get the name, version, and vendor name, version, vendor, err := parseOsRelease() diff --git a/plugins/extractors/system/system.go b/plugins/extractors/system/system.go index ee6c56b..208f2ad 100644 --- a/plugins/extractors/system/system.go +++ b/plugins/extractors/system/system.go @@ -3,7 +3,7 @@ package system import ( "fmt" - "github.com/compspec/compspec-go/pkg/extractor" + "github.com/compspec/compspec-go/pkg/plugin" "github.com/compspec/compspec-go/pkg/utils" ) @@ -39,6 +39,13 @@ func (e SystemExtractor) Sections() []string { return e.sections } +func (e SystemExtractor) Create(options map[string]string) error { + return nil +} + +func (e SystemExtractor) IsCreator() bool { return false } +func (e SystemExtractor) IsExtractor() bool { return true } + // Validate ensures that the sections provided are in the list we know func (e SystemExtractor) Validate() bool { invalids, valid := utils.StringArrayIsSubset(e.sections, validSections) @@ -49,10 +56,10 @@ func (e SystemExtractor) Validate() bool { } // Extract returns system metadata, for a set of named sections -func (e SystemExtractor) Extract(interface{}) (extractor.ExtractorData, error) { +func (e SystemExtractor) Extract(interface{}) (plugin.PluginData, error) { - sections := map[string]extractor.ExtractorSection{} - data := extractor.ExtractorData{} + sections := map[string]plugin.PluginSection{} + data := plugin.PluginData{} // Only extract the sections we asked for for _, name := range e.sections { @@ -70,6 +77,7 @@ func (e SystemExtractor) Extract(interface{}) (extractor.ExtractorData, error) { } sections[OsSection] = section } + if name == CPUSection { section, err := getCPUInformation() if err != nil { @@ -99,7 +107,7 @@ func (e SystemExtractor) Extract(interface{}) (extractor.ExtractorData, error) { } // NewPlugin validates and returns a new kernel plugin -func NewPlugin(sections []string) (extractor.Extractor, error) { +func NewPlugin(sections []string) (plugin.PluginInterface, error) { if len(sections) == 0 { sections = validSections } diff --git a/plugins/list.go b/plugins/list.go index 9b00cc0..67cffa2 100644 --- a/plugins/list.go +++ b/plugins/list.go @@ -6,8 +6,20 @@ import ( "github.com/jedib0t/go-pretty/v6/table" ) +// getPluginType returns a string to describe the plugin type +func getPluginType(p PluginRequest) string { + + if p.Plugin.IsCreator() && p.Plugin.IsExtractor() { + return "extractor and creator" + } + if p.Plugin.IsExtractor() { + return "extractor" + } + return "creator" +} + // List plugins available, print in a pretty table! -func List(ps []PluginInformation) error { +func (r *PluginsRequest) List() error { // Write out table with nodes t := table.NewWriter() @@ -16,30 +28,59 @@ func List(ps []PluginInformation) error { t.AppendHeader(table.Row{"", "Type", "Name", "Section"}) t.AppendSeparator() - // keep count of plugins (just extractors for now) + // keep count of plugins, total, and for each kind count := 0 - pluginCount := 0 + extractorCount := 0 + creatorCount := 0 - // This will iterate across plugin types (e.g., extraction and converter) - for _, p := range ps { - pluginCount += 1 + // Do creators first in one section (only a few) + t.AppendSeparator() + t.AppendRow(table.Row{"creation plugins", "", "", ""}) + + // TODO add description column + for _, p := range *r { - // This iterates across plugins in the family - for i, section := range p.GetSections() { + if !p.Plugin.IsCreator() { + continue + } + pluginType := getPluginType(p) + + // Creators don't have sections necessarily + creatorCount += 1 + count += 1 + + // Allow plugins to serve dual purposes + // TODO what should sections be used for? + t.AppendRow([]interface{}{"", pluginType, p.Name, ""}) + } + + // TODO add description column + for _, p := range *r { + + if p.Plugin.IsExtractor() { + extractorCount += 1 + } + + newPlugin := true + pluginType := getPluginType(p) + + // Extractors are parsed by sections + for _, section := range p.Plugin.Sections() { // Add the extractor plugin description only for first in the list - if i == 0 { + if newPlugin { t.AppendSeparator() - t.AppendRow(table.Row{p.GetDescription(), "", "", ""}) + t.AppendRow(table.Row{p.Plugin.Description(), "", "", ""}) + newPlugin = false } - count += 1 - t.AppendRow([]interface{}{"", p.GetType(), section.Name}) - } + // Allow plugins to serve dual purposes + t.AppendRow([]interface{}{"", pluginType, p.Name, section}) + } } t.AppendSeparator() - t.AppendFooter(table.Row{"Total", "", pluginCount, count}) + t.AppendFooter(table.Row{"Total", "", extractorCount + creatorCount, count}) t.SetStyle(table.StyleColoredCyanWhiteOnBlack) t.Render() return nil diff --git a/plugins/plugins.go b/plugins/plugins.go index b375d1b..521ef15 100644 --- a/plugins/plugins.go +++ b/plugins/plugins.go @@ -2,11 +2,40 @@ package plugins import ( "strings" + + "github.com/compspec/compspec-go/plugins/extractors/kernel" + "github.com/compspec/compspec-go/plugins/extractors/library" + "github.com/compspec/compspec-go/plugins/extractors/nfd" + "github.com/compspec/compspec-go/plugins/extractors/system" + + "github.com/compspec/compspec-go/plugins/creators/cluster" +) + +// Add new plugin names here. They should correspond with the package name, then NewPlugin() +var ( + // Explicitly extractors + KernelExtractor = "kernel" + SystemExtractor = "system" + LibraryExtractor = "library" + NFDExtractor = "nfd" + + // Explicitly creators + ClusterCreator = "cluster" + ArtifactCreator = "artifact" + + pluginNames = []string{ + ArtifactCreator, + ClusterCreator, + KernelExtractor, + SystemExtractor, + LibraryExtractor, + NFDExtractor, + } ) // parseSections will return sections from the name string // We could use regex here instead -func ParseSections(raw string) (string, []string) { +func parseSections(raw string) (string, []string) { sections := []string{} @@ -25,3 +54,83 @@ func ParseSections(raw string) (string, []string) { sections = strings.Split(raw, ",") return name, sections } + +// Get plugins parses a request and returns a list of extractor plugins +// We honor the order that the plugins and sections are provided in +func GetPlugins(names []string) (PluginsRequest, error) { + + if len(names) == 0 { + names = pluginNames + } + + request := PluginsRequest{} + + // Prepare an extractor for each, and validate the requested sections + // TODO: this could also be done with an init -> Register pattern + for _, name := range names { + + // If we are given a list of section names, parse. + name, sections := parseSections(name) + + if strings.HasPrefix(name, KernelExtractor) { + p, err := kernel.NewPlugin(sections) + if err != nil { + return request, err + } + // Save the name, the instantiated interface, and sections + pr := PluginRequest{Name: name, Plugin: p, Sections: sections} + request = append(request, pr) + } + + // Cluster and artifact creators + if strings.HasPrefix(name, ClusterCreator) { + p, err := cluster.NewPlugin() + if err != nil { + return request, err + } + // Save the name, the instantiated interface, and sections + pr := PluginRequest{Name: name, Plugin: p} + request = append(request, pr) + } + if strings.HasPrefix(name, ArtifactCreator) { + p, err := cluster.NewPlugin() + if err != nil { + return request, err + } + // Save the name, the instantiated interface, and sections + pr := PluginRequest{Name: name, Plugin: p} + request = append(request, pr) + } + + if strings.HasPrefix(name, NFDExtractor) { + p, err := nfd.NewPlugin(sections) + if err != nil { + return request, err + } + // Save the name, the instantiated interface, and sections + pr := PluginRequest{Name: name, Plugin: p, Sections: sections} + request = append(request, pr) + } + + if strings.HasPrefix(name, SystemExtractor) { + p, err := system.NewPlugin(sections) + if err != nil { + return request, err + } + // Save the name, the instantiated interface, and sections + pr := PluginRequest{Name: name, Plugin: p, Sections: sections} + request = append(request, pr) + } + + if strings.HasPrefix(name, LibraryExtractor) { + p, err := library.NewPlugin(sections) + if err != nil { + return request, err + } + // Save the name, the instantiated interface, and sections + pr := PluginRequest{Name: name, Plugin: p, Sections: sections} + request = append(request, pr) + } + } + return request, nil +} diff --git a/plugins/request.go b/plugins/request.go index 03d9726..b909a07 100644 --- a/plugins/request.go +++ b/plugins/request.go @@ -1,19 +1,64 @@ package plugins -// A Plugin(s)Information interface is an easy way to combine plugins across spaces -// primarily to expose metadata, etc. -type PluginsInformation interface { - GetPlugins() []PluginInformation +import ( + "fmt" + + pg "github.com/compspec/compspec-go/pkg/plugin" +) + +// A plugin request has a Name and sections +type PluginRequest struct { + Name string + Sections []string + Plugin pg.PluginInterface } -type PluginInformation interface { - GetName() string - GetType() string - GetSections() []PluginSection - GetDescription() string +type PluginsRequest []PluginRequest + +// Do the extraction for a plugin request, meaning across a set of plugins +func (r *PluginsRequest) Extract(allowFail bool) (pg.Result, error) { + + // Prepare Result + result := pg.Result{} + results := map[string]pg.PluginData{} + + for _, p := range *r { + + // Skip plugins that don't define extraction + if !p.Plugin.IsExtractor() { + continue + } + r, err := p.Plugin.Extract(p.Sections) + + // We can allow failure + if err != nil && !allowFail { + return result, fmt.Errorf("there was an extraction error for %s: %s", p.Name, err) + } else if err != nil && allowFail { + fmt.Printf("Allowing failure - ignoring extraction error for %s: %s\n", p.Name, err) + } + results[p.Name] = r + } + result.Results = results + return result, nil } -type PluginSection struct { - Description string - Name string +// Do creation +func (r *PluginsRequest) Create() (pg.Result, error) { + + // Prepare Result + result := pg.Result{} + + for _, p := range *r { + + // Skip plugins that don't define extraction + if !p.Plugin.IsCreator() { + continue + } + err := p.Plugin.Create(nil) + if err != nil { + return result, err + } + + } + return result, nil }