From 67a50a695411d27d6f386814c70640755bf94762 Mon Sep 17 00:00:00 2001 From: claudespice Date: Mon, 18 May 2026 08:06:32 -0700 Subject: [PATCH] docs: Add executor readiness gating to /v1/ready endpoint Update OpenAPI spec and API docs for the new /v1/ready query parameters that gate readiness on executor availability in distributed (scheduler) mode: min_ready_executors, min_ready_executors_percent, and verbose. --- .../docs/api/HTTP/ready.ParamsDetails.json | 1 + .../docs/api/HTTP/ready.RequestSchema.json | 1 + website/docs/api/HTTP/ready.StatusCodes.json | 1 + website/docs/api/HTTP/ready.api.mdx | 30 +++++++++--- website/public/openapi.json | 48 ++++++++++++++++++- 5 files changed, 73 insertions(+), 8 deletions(-) create mode 100644 website/docs/api/HTTP/ready.ParamsDetails.json create mode 100644 website/docs/api/HTTP/ready.RequestSchema.json create mode 100644 website/docs/api/HTTP/ready.StatusCodes.json diff --git a/website/docs/api/HTTP/ready.ParamsDetails.json b/website/docs/api/HTTP/ready.ParamsDetails.json new file mode 100644 index 000000000..f712206c6 --- /dev/null +++ b/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}}]} \ No newline at end of file diff --git a/website/docs/api/HTTP/ready.RequestSchema.json b/website/docs/api/HTTP/ready.RequestSchema.json new file mode 100644 index 000000000..c96bcede2 --- /dev/null +++ b/website/docs/api/HTTP/ready.RequestSchema.json @@ -0,0 +1 @@ +{"title":"Body"} \ No newline at end of file diff --git a/website/docs/api/HTTP/ready.StatusCodes.json b/website/docs/api/HTTP/ready.StatusCodes.json new file mode 100644 index 000000000..4b6682ae8 --- /dev/null +++ b/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"}}}}} \ No newline at end of file diff --git a/website/docs/api/HTTP/ready.api.mdx b/website/docs/api/HTTP/ready.api.mdx index 9dfdbfd8b..a6fe1ac4a 100644 --- a/website/docs/api/HTTP/ready.api.mdx +++ b/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"; + Request + + diff --git a/website/public/openapi.json b/website/public/openapi.json index 09c3dbabc..03ddbcfc8 100644 --- a/website/public/openapi.json +++ b/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": {