Reconcile differences between fulfillment API and clusterorder API

[larsks]

Our fulfillment api and our clusterorder api are diverging in ways that will be confusing and surprising to consumers of this solution. Things I've noticed recently:

• The api has introduced the concept of "cluster sets". It looks like this parallels what in the clusterorder api we called "node requests"; is there a particular reason to introduce a new term here? Can we just make these match so we're not using different words in different places to describe the same thing?

• Node requests consist of an array of maps, whereas here you have a map of maps. I saw this comment, but I don't think using names here makes sense: I don't think we want to have the user name these groups, and I don't think we can generate names ourselves. If gRPC really forces us to use a map here, then we should simply use sequential integer keys rather than names.

[jhernand]

The concept in the fulfillment API is "node sets". I believe that is slightly better than "node requests" because it can be used in both the spec and the status. On the other hand "node requests" would make sense in a "spec", but a little bit less in the "status", because the "status" doesn't reflect anything requested by the user, it reflect the actual status.

The reason to not use an array of objects is that the recommended way to update an object in gRPC is to use a field mask. For example, if you have an object that represents a person, with fields name and address and you want to update only the address, then you send a request like this:

{
  "object": {
    "name": "Kermit",
    "address": "123 Sesame Street"
  },
  "update_mask": {
    "paths": [
      "address"
    ]
  }
}

In that example the client is saying that she wants to update only the address, so the server will ignore the name.

If we represent the node sets as an array of objects, then there is no way for the user to encode in the field mask something like "I only want to update the node set whose name is GPU". The closest we could do is teach the server that when a node set is updated it has first to look for a matching node set, and update it. We would then need to specify what "matching" means. That is what the name of the node set is for: the user needs to explicitly provide the name of the node set and the values of the other fields that she wants to change. Using a map of objects has the advantage that that can be represented using a field mask. For example, to update only the size of the GPU node set of a cluster:

{
  "object": {
    "spec": {
      "node_sets": {
        "gpu": {
          "host_class": "acme_1tb_h100",
          "size": 3,
        },
        "compute": {
          "host_class": "acme_1tb",
          "size": 1
        }
      }
    }
  },
  "update_mask": {
    "paths": [
      "spec.node_sets.gpu.size"
    ]
  }
}

gRPC doesn't force any of this, it is only the recommended way to do things. In addition the REST gateway assumes that this is how the API works when it finds a "udate_mask" field of type FieldMask, and uses it to automatically translate PATCH requests into the corresponding field mask.

I tried to explain in the API that the user doesn't select those gpu and compute names: the system does. The user only uses them to match her changes to the right node set.

Using indexes instead of names is also possible. I'd say that names are better because they can convey meaning better than numbers, and because they work without requiring an explicit order.

All that said, if we still want to rename the "node set" thing, and use an array I won't object.