API: add worker clusters to the API

Worker Clusters can be managed via the API, workers can be assigned to
any number of clusters (if not assigned to any, they'll pick up any task).

Jobs can be submitted with a cluster ID, in which case only workers that
are in that cluster or are clusterless will pick up its tasks.

pkg/api/flamenco-openapi.yaml

@@ -534,6 +534,33 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
+  /api/v3/worker-mgt/workers/{worker_id}/setclusters:
+    summary: Update the cluster membership of this Worker.
+    post:
+      operationId: setWorkerClusters
+      tags: [worker-mgt]
+      parameters:
+        - name: worker_id
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      requestBody:
+        description: The list of cluster IDs this worker should be a member of.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/WorkerClusterChangeRequest"
+      responses:
+        "204":
+          description: Status change was accepted.
+        default:
+          description: Unexpected error.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
   /api/v3/worker-mgt/workers/{worker_id}/sleep-schedule:
     summary: Get or update the worker's sleep schedule.
     get:
@@ -584,6 +611,88 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
+  /api/v3/worker-mgt/clusters:
+    summary: Manage worker clusters.
+    get:
+      operationId: fetchWorkerClusters
+      summary: Get list of worker clusters.
+      tags: [worker-mgt]
+      responses:
+        "200":
+          description: Worker clusters.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/WorkerClusterList" }
+    post:
+      operationId: createWorkerCluster
+      summary: Create a new worker cluster.
+      tags: [worker-mgt]
+      requestBody:
+        description: The worker cluster.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/WorkerCluster"
+      responses:
+        "204":
+          description: The cluster was created.
+        default:
+          description: Error message
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
+
+  /api/v3/worker-mgt/cluster/{cluster_id}:
+    summary: Get, update, or delete a worker cluster.
+    parameters:
+      - name: cluster_id
+        in: path
+        required: true
+        schema: { type: string, format: uuid }
+    get:
+      operationId: fetchWorkerCluster
+      summary: Get a single worker cluster.
+      tags: [worker-mgt]
+      responses:
+        "200":
+          description: The worker cluster.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/WorkerCluster" }
+    put:
+      operationId: updateWorkerCluster
+      summary: Update an existing worker cluster.
+      tags: [worker-mgt]
+      requestBody:
+        description: The updated worker cluster.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/WorkerCluster"
+      responses:
+        "204":
+          description: The cluster update has been stored.
+        default:
+          description: Error message
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
+    delete:
+      operationId: deleteWorkerCluster
+      summary: Remove this worker cluster. This unassigns all workers from the cluster and removes it.
+      tags: [worker-mgt]
+      responses:
+        "204":
+          description: The cluster has been removed.
+        default:
+          description: Unexpected error.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
   ## Jobs
 
   /api/v3/jobs/types:
@@ -1363,6 +1472,12 @@ components:
           type: array
           items: { type: string }
         name: { type: string }
+      example:
+        "name": "example-worker"
+        "secret": "do-not-tell-anyone"
+        "platform": "linux"
+        "software": "3.2"
+        "supported_task_types": ["blender", "ffmpeg", "file-management", "misc"]
 
     RegisteredWorker:
       type: object
@@ -1636,6 +1751,13 @@ components:
             test/debug scripts easier, as they can use a static document on all
             platforms.
         "storage": { $ref: "#/components/schemas/JobStorageInfo" }
+        "worker_cluster":
+          type: string
+          format: uuid
+          description: >
+            Worker Cluster that should execute this job. When a cluster ID is
+            given, only Workers in that cluster will be scheduled to work on it.
+            If empty or ommitted, all workers can work on this job.
       required: [name, type, priority, submitter_platform]
       example:
         type: "simple-blender-render"
@@ -1749,7 +1871,7 @@ components:
           description: Filter by job settings, using `LIKE` notation.
       example:
         "limit": 5
-        "order_by": ["updated", "status"]
+        "order_by": ["updated_at", "status"]
         "status_in": ["active", "queued", "failed"]
         "metadata": { project: "Sprite Fright" }
 
@@ -2235,6 +2357,10 @@ components:
               type: array
               items: { type: string }
             "task": { $ref: "#/components/schemas/WorkerTask" }
+            "clusters":
+              type: array
+              items: { $ref: "#/components/schemas/WorkerCluster" }
+              description: Clusters of which this Worker is a member.
           required:
             - id
             - name
@@ -2288,6 +2414,45 @@ components:
         start_time: "09:00"
         end_time: "18:00"
 
+    WorkerCluster:
+      type: object
+      description: >
+        Cluster of workers. A job can optionally specify which cluster it should
+        be limited to. Workers can be part of multiple clusters simultaneously.
+      properties:
+        "id":
+          type: string
+          format: uuid
+        "name":
+          type: string
+        "description":
+          type: string
+      required: [id, name]
+      example:
+        id: 4312d68c-ea6d-4566-9bf6-e9f09be48ceb
+        name: GPU-EEVEE
+        description: All workers that can do GPU rendering with EEVEE.
+
+    WorkerClusterList:
+      type: object
+      properties:
+        "clusters":
+          type: array
+          items: { $ref: "#/components/schemas/WorkerCluster" }
+
+    WorkerClusterChangeRequest:
+      type: object
+      description: Request to change which clusters this Worker is assigned to.
+      properties:
+        "cluster_ids":
+          type: array
+          items:
+            type: string
+            format: uuid
+      required: [cluster_ids]
+      example:
+        "cluster_ids": ["4312d68c-ea6d-4566-9bf6-e9f09be48ceb"]
+
   securitySchemes:
     worker_auth:
       description: Username is the worker ID, password is the secret given at worker registration.