feat: state endpoint

Problem: we want to be able to select a final cluster based on state
Solution: while a cluster will likely send back state when accepting jobs,
for the time being we are providing a one off endpoint for a cluster to
send state data, and it requires the cluster to authenticate with the name
and secret. For now the state date is key value pairs of compatibility
metadata, and the values can be anything (interface) as we are expecting
the selection algorithms that use them to know the type for a specific key.
I will be added selection algorithms after this first stage that I intend
to use in scheduler simulation - namely a post filter that serves as
additional constraints that can be chosen (max jobs a cluster can accept
and a cost value that can be minimized.

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

Makefile

@@ -79,6 +79,10 @@ test: tidy ## Runs unit tests
 server: ## Runs uncompiled version of the server
 	go run cmd/server/server.go --global-token rainbow
 
+.PHONY: server-verbose
+server-verbose: ## Runs uncompiled version of the server
+	go run cmd/server/server.go --loglevel 6 --global-token rainbow
+
 .PHONY: stream
 stream: ## Runs the interface client
 	go run cmd/stream/stream.go
@@ -88,9 +92,13 @@ register: ## Run mock registration
 	go run cmd/rainbow/rainbow.go register cluster --cluster-name keebler --nodes-json ./docs/examples/scheduler/cluster-nodes.json --config-path ./docs/examples/scheduler/rainbow-config.yaml --save
 
 .PHONY: subsystem
-subsystem: ## Run mock registration
+subsystem: ## Register subsystem
 	go run cmd/rainbow/rainbow.go register subsystem --subsystem io --nodes-json ./docs/examples/scheduler/cluster-io-subsystem.json --config-path ./docs/examples/scheduler/rainbow-config.yaml
 
+.PHONY: update-state
+update-state: ## Update state
+	go run cmd/rainbow/rainbow.go update state --state-file ./docs/examples/scheduler/cluster-state.json --config-path ./docs/examples/scheduler/rainbow-config.yaml
+
 .PHONY: tag
 tag: ## Creates release tag
 	git tag -s -m "version bump to $(VERSION)" $(VERSION)

api/v1/rainbow.proto

@@ -18,6 +18,10 @@ service RainbowScheduler {
   // Job Submission - request for submitting a job to a named cluster
   rpc SubmitJob(SubmitJobRequest) returns (SubmitJobResponse);
 
+  // Update State - allow a cluster to provide state metadata
+  // This is intended for use by a selection algorithm
+  rpc UpdateState(UpdateStateRequest) returns (UpdateStateResponse);
+
   // Request Job - ask the rainbow scheduler for up to max jobs
   rpc ReceiveJobs(ReceiveJobsRequest) returns (ReceiveJobsResponse);
 
@@ -37,6 +41,29 @@ message RegisterRequest {
   google.protobuf.Timestamp sent = 5;
 }
 
+// UpdateStateRequests allows a cluster to set arbitrary metadata
+// for its state. State metadata is used for selection algorithms
+message UpdateStateRequest {
+  string cluster = 1;
+  string secret = 2;
+
+  // We are generous that the payload can be a flat
+  // set of key value pairs, and will be parsed into
+  // types within the graph database
+  string payload = 3;
+}
+
+message UpdateStateResponse {
+  enum ResultType {
+    UPDATE_STATE_UNSPECIFIED = 0;
+    UPDATE_STATE_PARTIAL = 1;
+    UPDATE_STATE_SUCCESS = 2;
+    UPDATE_STATE_ERROR = 3;
+  }
+  ResultType status = 1;
+}
+
+
 // SubmitJobRequest takes a job name, cluster name
 // and requires the cluster token. Since we want to be generic,
 // we currently accept nodes, tasks, and the command

cmd/rainbow/rainbow.go

@@ -10,6 +10,7 @@ import (
 	"github.com/converged-computing/rainbow/cmd/rainbow/receive"
 	"github.com/converged-computing/rainbow/cmd/rainbow/register"
 	"github.com/converged-computing/rainbow/cmd/rainbow/submit"
+	"github.com/converged-computing/rainbow/cmd/rainbow/update"
 	"github.com/converged-computing/rainbow/pkg/types"
 
 	// Register database backends and selection algorithms
@@ -41,6 +42,7 @@ func main() {
 	submitCmd := parser.NewCommand("submit", "Submit a job to a rainbow scheduler")
 	receiveCmd := parser.NewCommand("receive", "Receive and accept jobs")
 	registerClusterCmd := registerCmd.NewCommand("cluster", "Register a new cluster")
+	updateCmd := parser.NewCommand("update", "Update a cluster")
 
 	// Configuration
 	configCmd := parser.NewCommand("config", "Interact with rainbow configs")
@@ -69,6 +71,10 @@ func main() {
 	// Register subsystem (requires config file for authentication)
 	subsysCmd := registerCmd.NewCommand("subsystem", "Register a new subsystem")
 
+	// Update subcommands - currently just supported are state
+	stateCmd := updateCmd.NewCommand("state", "Update the state for a known cluster")
+	stateFile := stateCmd.String("", "state-file", &argparse.Options{Help: "JSON file with key, value attributes for the cluster"})
+
 	// Submit (note that command for now needs to be in quotes to get the whole thing)
 	token := submitCmd.String("", "token", &argparse.Options{Default: defaultSecret, Help: "Client token to submit jobs with."})
 	nodes := submitCmd.Int("n", "nodes", &argparse.Options{Default: 1, Help: "Number of nodes to request"})
@@ -91,6 +97,17 @@ func main() {
 			log.Fatalf("Issue with config: %s\n", err)
 		}
 
+	} else if stateCmd.Happened() {
+		err := update.UpdateState(
+			*host,
+			*clusterName,
+			*stateFile,
+			*cfg,
+		)
+		if err != nil {
+			log.Fatalf("Issue with register subsystem: %s\n", err)
+		}
+
 	} else if registerCmd.Happened() {
 
 		if subsysCmd.Happened() {

cmd/rainbow/update/state.go

@@ -0,0 +1,51 @@
+package update
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/converged-computing/rainbow/pkg/client"
+	"github.com/converged-computing/rainbow/pkg/config"
+)
+
+// UpdateState updates state for a cluster
+func UpdateState(
+	host,
+	clusterName,
+	stateFile,
+	cfgFile string,
+) error {
+
+	c, err := client.NewClient(host)
+	if err != nil {
+		return err
+	}
+
+	// A config file is required here
+	if cfgFile == "" {
+		return fmt.Errorf("an existing configuration file is required to update an existing cluster")
+	}
+	if stateFile == "" {
+		return fmt.Errorf("a state file (json with key value pairs) is required to update state")
+	}
+	// Read in the config, if provided, command line takes preference
+	cfg, err := config.NewRainbowClientConfig(cfgFile, "", "", "", "", "")
+	if err != nil {
+		return err
+	}
+
+	log.Printf("updating state for cluster: %s", cfg.Scheduler.Name)
+
+	// Last argument is subsystem name, which we can derive from graph
+	response, err := c.UpdateState(
+		context.Background(),
+		cfg.Cluster.Name,
+		cfg.Cluster.Secret,
+		stateFile,
+	)
+	// If we get here, success! Dump all the stuff.
+	log.Printf("%s", response)
+	return err
+
+}

docs/commands.md

@@ -7,7 +7,11 @@ The following commands are currently supported. For Python, see the [README](htt
 You can run the server (with defaults) as follows:
 
 ```bash
+# Regular logging
 make server
+
+# Verbose logging
+make server-verbose
 ```
 ```console
 go run cmd/server/server.go --global-token rainbow
@@ -180,6 +184,40 @@ the following reasons:
 In Computer Science I think they are used interchangeably. For next steps we will be updating the memory graph database to be a little more meaty (adding proper metadata and likely a summary of resources at the top as a quick "does it satisfy" heuristic)
 and then working on the next interaction, the client submit command, which is going to hit the `Satisfies` endpoint. I will write up more about the database and submit design after that.
 
+## Update State
+
+A cluster state is intended to be a superficial view of the cluster status. It's not considered a subsystem because (for the time being) we are only considering a flat listing of key value pairs that describe a cluster. The data is also intended to be small so it can be provided via this update endpoint more frequently. As an example, an update payload may look like the following:
+
+```json
+{
+  "cost-per-node": 12,
+  "nodes-free": 100
+}
+```
+
+While the above would not be suited for a real-world deployment (for example, there are many more costs than per node, and occupancy goes beyond nodes free)
+but this will be appropriate for small tests and simulations. The metadata above will be provided, on a cluster level, for a final selection algorithm (to use or not). So after you've created your cluster, let's update the state.
+
+```bash
+make update-state
+```
+```console
+Adding edge from socket -contains-> core
+Adding edge from socket -contains-> core
+2024/04/05 18:38:13 We have made an in memory graph (subsystem cluster) with 45 vertices!
+Metrics for subsystem cluster{
+ "cluster": 1,
+ "core": 36,
+ "node": 3,
+ "rack": 1,
+ "socket": 3
+}
+2024/04/05 18:38:16 📝️ received state update: keebler
+Updating state cost-per-node to 12
+Updating state max-jobs to 100
+```
+In debug logging mode (`make server-debug`) you will see the values updated, as shown above. They are also in blue, which you can't see! Note that this state metadata is provided to a selection algorithm, and we will be added more interesting ones soon for experiments!
+
 ## Register Subsystem
 
 Adding a subsystem means adding another graph that has nodes with edges that connect (in some meaningful way) to the dominant subsystem.

docs/examples/scheduler/cluster-state.json

@@ -0,0 +1,4 @@
+{
+    "cost-per-node": 12,
+    "max-jobs": 100
+}

docs/examples/scheduler/rainbow-config.yaml

@@ -8,7 +8,7 @@ scheduler:
             name: match
 cluster:
     name: keebler
-    secret: 79643f8e-6408-4cd1-bd1a-76aa499d5864
+    secret: 76948f58-8655-48c1-aaab-fccedf2bb383
 graphdatabase:
     name: memory
     host: 127.0.0.1:50051