docs: Add executor readiness gating to /v1/ready endpoint

website/docs/api/HTTP/ready.ParamsDetails.json

@@ -0,0 +1 @@
+{"parameters":[{"name":"min_ready_executors","in":"query","description":"Minimum number of currently-ready executors required for the probe to succeed. A ready executor has a live FlightSQL client that the scheduler can route queries to. A value of 0 is treated as disabled. Requires scheduler role; a non-zero value outside scheduler role returns 400.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"min_ready_executors_percent","in":"query","description":"Minimum percentage (0-100) of currently-ready executors relative to the number of registered executors. A value of 0 is treated as disabled. Values above 100 return 400. Requires scheduler role; a non-zero value outside scheduler role returns 400.","required":false,"schema":{"type":"integer","format":"int32","minimum":0,"maximum":100}},{"name":"verbose","in":"query","description":"When true, the response body becomes a multi-line diagnostic listing the result of each gate. The HTTP status code is unchanged.","required":false,"schema":{"type":"boolean","default":false}}]}

website/docs/api/HTTP/ready.RequestSchema.json

@@ -0,0 +1 @@
+{"title":"Body"}

website/docs/api/HTTP/ready.StatusCodes.json

@@ -0,0 +1 @@
+{"responses":{"200":{"description":"Service is ready","content":{"text/plain":{"schema":{"type":"string"},"example":"ready"}}},"400":{"description":"Invalid query parameter or executor gate requested outside scheduler role","content":{"text/plain":{"schema":{"type":"string"},"example":"min_ready_executors_percent must be between 0 and 100"}}},"503":{"description":"Service is not ready","content":{"text/plain":{"schema":{"type":"string"},"example":"not ready"}}}}}

website/docs/api/HTTP/ready.api.mdx

@@ -5,7 +5,7 @@ description: "Check the runtime status of all the components of the runtime. If
 sidebar_label: "Check Readiness"
 hide_title: true
 hide_table_of_contents: true
-api: eJztVk1v20YQ/SuD8aUFKFFyEKDlLUiD1GgPRu2eLCEaLYfiIuTudneoRBD434tZyrKsArn06pPIGc578/mgIwrtElZP+BdTfcB1gTUnE20Q6x1W+LFl8xWkZYiDE9szJCEZEvgGqOuyx/g+eMdOsvXi2zncTe+J494aBpsgKk8BViCyDNElIAe/Pz7ew+1i8Qz+zUqbA3tOiXYMK8xxK8yQzstrBHi/ePeDWOcFnuNXbuUeW4Ytt7S3PkLjI3xr2WkeZAx3HEm4hpqEEovmbLxLtubI9QRzsjV2N0Tadgx7S5lyk91fNBPeQKBIPQvHOTwww9NvJASRm8ipXf/UioRUlWUK1jDZuY+7svYmlS/tLDWH2TkpH0+WE8ZNZptltp9zHb2PDDUL2S7lSm9ubkAnax2nBPfRb3nl7hyE6OvB6Iyh5tD5Q698RS6i3C/LqUx2dfDWCRhysGUYEtdA2u94xgyKmckJHrSUC0AQD+zSEBkkUtNYkzfAD9pf8ZltinleLu+6A1AjHPN2nWaQoKU9Q2OdTS3X0Hll3+UKP32nPnQMfwxbjo6F03Vy1cptNpsD9d3KnV33Jw/oGD6z6CNAIGmrlwZMNh+lgl8Wvy4yDhbog07DendXYzUtJhYYOQXvEiesjni7WOjP61t6uLoCLNB4J+xEvxX+LmXoyDp9S6blnrL9EBgrTBKt2+FYIE8Vn6nHcSzw/eLdDwnPJ/C/SV+Qxszcs7ReG7FjwQK1hVjhuYdYoF4/R1WZIw6xwwq16VVZdt5Q1/oklbYXr7XnT3VDzXvufMj7NCHN4ePp+Hi69s1spoibOY5rpTNDtHLIfBTsl6+sz2v1Wdf4XJ+VqYPT3v2HWhUiH2YNL5901rBLrPGOeg3/EMi0PLuda/K2Zie2sRxfe8YCtfwJeDlfLueL2eCSqHKoM/gkPbkL2El0z3d7nd3xZYJv+vymz2/6fKXPJ/G60LaxmITneJKnJ9wvs2Sf/vOoBqn1eNxS4r9jN45q/mfgmKWjwD1Fmw9WhaTAlqnWO386YlYX/GAMB9W/PXXDNfv6QiU/f3rEcfwXuHdVyw==
+api: eJztWNtu20YQ/ZUFDRQ2oAudpECqIijSNE2NpIAbu+1DbFhLckQuQu4yu0vZqqB/75klJcqOrObyEqB+MMy9zcyeOXNZLSMvcxdN3kVvSWaL6HIQZeRSq2qvjI4m0YuC0vfCFyRso72qSDgvfeOEmQlZlmElNVVtNGkfZrf2jsRJO3Zk5yoloZywrGcglMeXb6x2Qmrx2/n5qXgUx2vh18oX4WBFzsmcxEUUzl1EQaQ2/rYE8X38eM9Z7Bfr8xf6Qp9jNaFCzpWxYoa/64I02yHTlEqy0lMmMumlI882p0Y7lZHFbBDTzc1U3liZlCTmSgaV07B8xZbQVNTSyoo82ZE4IxLvfoFECJhZcsXlYeF97SbjsauBjFQjY/NxZlI37uEcsw3DjVHGdjOdjIOgbRi0HYV7VMaSyMhLVbpw0xMtMuW8VUnDdzp0aUFZA2lH2JtR6yxIURpg4ctBs4NHGYssU0wCeHkBtEQeUDFa0A2lDYwRcg49MlGl8osegkrpqxaG9UY3BbbZzpWrmmyKq07Fh4bsoofMicPEwJGmbm04GomfecxWOFE1zmMvTA6ec01dl4qykTjluemcbGIcPfO2gRu8ETn8KHGq9GpY4q4ARebaOK9SkRg4lG7qUiqtdC5Ipq2aAODBwYF4uwHo1JqEAqq1NVmTsm3Auy7NomKHDQIE4/nxuOUJ6aw2SvsAKDBsHCCUTNge9JplBu9JccZc2BLItpN2DbzqrZzNYC6HkAnOxBpra8+so9NoeEvOgGAIz47EToDsUIIbOhBAlIa15+GGL29kVYPDr5uErCaG945xkws9nU4Xsiov9GbptFsRzONX5PlTwCe+mPQAtHPG+ol4Gv8QBznbOkOsbvgE0NkBPUlx05KOvlz9TzsY9+zxd3t4+OxpvMvmaBCZmkMQ/j7JkBbDccz2fEUOXUYaA6zuUIC9ivNpoHl0N8v+DsdUTSV0U8EJnEXTxlrYUy6GHZPWguCcD43iVMSUYQK0BAIbXINMwVHwXNw+BO8z50oFDvxaqrzwZ3+8ESlChilWSN8m6Q3szNZAshCVCozwhqXOZdkQWxczDT2U+JbPyDGcB6H6bWudE7ed+CPUa6OH/5A1azGN56R6Z+Mmpz+J4xFwWt82msxk6WgQ8fZKRpNl5Bc1g43wopws9gKQSvp26vEjTFQtrNEkXq0G+7yzdv+neanbzLXlMB4ex/HRf3msBHPmtI7Y3suWcmTnUFg22z8R6L94C7yaGAiGDR1wAbdv1Qv4ljftNyze9kmXsffj/zfnes7pg65uddUqZPCEUDcZkHvSfAmgObt0J7GH8e2TveCmIPQhXR+Rcn0E+o1OC6lzYP5JQCQG+EkdjJ9JqOm2rlaXfLw12fEB9Dv87/Ydz+50SpCDTsMzN1kH3fhxqFQ8+kg3F3qdR6tBRG2C3WSqFcCOnuxSeKJBBJXdrb8CWWM7MVPIO+RCD7CTM19t6Z64bAt+wl2bvyawIA4dBUjU3gzt314oNw3gVxvZS1oFzQCrMFwR0GKEeuALDDYVCFPc+67rQ2NLrHLJQuNXmlSWBdg54TrzEdvf8DJ6gTmVpg7NQCtpJF50rWdXP6fDIUucjiKmmAN0Fg1Z0CdrdfWe+PuS15SemXA/5VtutE3DR6o5FEJbmol+S4kxqMvnu6B9XiN6aPhoxMaDENg5U8gBt1aAEV+/FXw8Oj4excNGI8aQxnixBgCV1Fti2yfHpum6a92y9+DD6+ThdfLwOnl4nTy8TrqKtVXQkFpDtVl2NeldND8ODUz3Mw8XHp5dLhP44E9brlY83XZeXDvWream1bk3Cz+8Xu7rm3e6JRTke96IQThWI+6NP98D/7+XyechvPXO+0Kkv4E3yJ4r98+o/nqXPLAq9FvcByL0AQq3aQjy9thzRF69Dcq27MutJvfVy3P0vf8CAmPoJA==
 sidebar_class_name: "get api-method"
 info_path: docs/api/HTTP/runtime
 custom_edit_url: null
@@ -19,6 +19,7 @@ import StatusCodes from "@theme/StatusCodes";
 import OperationTabs from "@theme/OperationTabs";
 import TabItem from "@theme/TabItem";
 import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
 
 <Heading
   as={"h1"}
@@ -41,6 +42,8 @@ Check the runtime status of all the components of the runtime. If the service is
 
 The behavior for when an accelerated dataset is considered ready is configurable via the `ready_state` parameter. See [Data refresh](https://spiceai.org/docs/components/data-accelerators/data-refresh#ready-state) for more details.
 
+In distributed (scheduler) mode the readiness response can additionally be gated on executor availability via the `min_ready_executors` and `min_ready_executors_percent` query parameters (both optional). Both gates must pass when supplied. Pass `verbose=true` to get a multi-line diagnostic body explaining each gate.
+
 ### Readiness Probe
 In production deployments, the /v1/ready endpoint can be used as a readiness probe for a Spice deployment to ensure traffic is routed to the Spice runtime only after all datasets have finished loading.
 
@@ -52,23 +55,36 @@ readinessProbe:
    port: 8090
 ```
 
+Example with executor gating (scheduler role):
+```yaml
+readinessProbe:
+ httpGet:
+   path: /v1/ready?min_ready_executors=3&min_ready_executors_percent=80
+   port: 8090
+```
+
+<Heading
+  id={"request"}
+  as={"h2"}
+  className={"openapi-tabs__heading"}
+>
+  <Translate id="theme.openapi.request.title">Request</Translate>
+</Heading>
+
 <ParamsDetails
-  parameters={undefined}
+  {...require("./ready.ParamsDetails.json")}
 >
 
 </ParamsDetails>
 
 <RequestSchema
-  title={"Body"}
-  body={undefined}
+  {...require("./ready.RequestSchema.json")}
 >
 
 </RequestSchema>
 
 <StatusCodes
-  id={undefined}
-  label={undefined}
-  responses={{"200":{"description":"Service is ready","content":{"text/plain":{"schema":{"type":"string"},"example":"ready"}}},"503":{"description":"Service is not ready","content":{"text/plain":{"schema":{"type":"string"},"example":"not ready"}}}}}
+  {...require("./ready.StatusCodes.json")}
 >
 
 </StatusCodes>

website/public/openapi.json

@@ -1243,8 +1243,43 @@
           "Ready"
         ],
         "summary": "Check Readiness",
-        "description": "Check the runtime status of all the components of the runtime. If the service is ready, it returns an HTTP 200 status with the message \"ready\". If not, it returns a 503 status with the message \"not ready\".\n\nThe behavior for when an accelerated dataset is considered ready is configurable via the `ready_state` parameter. See [Data refresh](https://spiceai.org/docs/components/data-accelerators/data-refresh#ready-state) for more details.\n\n### Readiness Probe\nIn production deployments, the /v1/ready endpoint can be used as a readiness probe for a Spice deployment to ensure traffic is routed to the Spice runtime only after all datasets have finished loading.\n\nExample Kubernetes readiness probe:\n```yaml\nreadinessProbe:\n httpGet:\n   path: /v1/ready\n   port: 8090\n```",
+        "description": "Check the runtime status of all the components of the runtime. If the service is ready, it returns an HTTP 200 status with the message \"ready\". If not, it returns a 503 status with the message \"not ready\".\n\nThe behavior for when an accelerated dataset is considered ready is configurable via the `ready_state` parameter. See [Data refresh](https://spiceai.org/docs/components/data-accelerators/data-refresh#ready-state) for more details.\n\nIn distributed (scheduler) mode the readiness response can additionally be gated on executor availability via the `min_ready_executors` and `min_ready_executors_percent` query parameters (both optional). Both gates must pass when supplied. Pass `verbose=true` to get a multi-line diagnostic body explaining each gate.\n\n### Readiness Probe\nIn production deployments, the /v1/ready endpoint can be used as a readiness probe for a Spice deployment to ensure traffic is routed to the Spice runtime only after all datasets have finished loading.\n\nExample Kubernetes readiness probe:\n```yaml\nreadinessProbe:\n httpGet:\n   path: /v1/ready\n   port: 8090\n```\n\nExample with executor gating (scheduler role):\n```yaml\nreadinessProbe:\n httpGet:\n   path: /v1/ready?min_ready_executors=3&min_ready_executors_percent=80\n   port: 8090\n```",
         "operationId": "ready",
+        "parameters": [
+          {
+            "name": "min_ready_executors",
+            "in": "query",
+            "description": "Minimum number of currently-ready executors required for the probe to succeed. A ready executor has a live FlightSQL client that the scheduler can route queries to. A value of 0 is treated as disabled. Requires scheduler role; a non-zero value outside scheduler role returns 400.",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "minimum": 0
+            }
+          },
+          {
+            "name": "min_ready_executors_percent",
+            "in": "query",
+            "description": "Minimum percentage (0-100) of currently-ready executors relative to the number of registered executors. A value of 0 is treated as disabled. Values above 100 return 400. Requires scheduler role; a non-zero value outside scheduler role returns 400.",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "minimum": 0,
+              "maximum": 100
+            }
+          },
+          {
+            "name": "verbose",
+            "in": "query",
+            "description": "When true, the response body becomes a multi-line diagnostic listing the result of each gate. The HTTP status code is unchanged.",
+            "required": false,
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        ],
         "responses": {
           "200": {
             "description": "Service is ready",
@@ -1257,6 +1292,17 @@
               }
             }
           },
+          "400": {
+            "description": "Invalid query parameter or executor gate requested outside scheduler role",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string"
+                },
+                "example": "min_ready_executors_percent must be between 0 and 100"
+              }
+            }
+          },
           "503": {
             "description": "Service is not ready",
             "content": {