dongjoon-hyun opened a new pull request, #59176: URL: https://github.com/apache/spark/pull/59176
### What changes were proposed in this pull request? This PR documents how to hold and resume an application through scripted HTTP requests (e.g. `curl`). The endpoints are the same ones the **Hold**/**Resume** buttons already submit to: - `docs/web-ui.md`: the driver web UI endpoints `/jobs/hold/` and `/jobs/resume/`, plus the existing `holdstatus` REST API for checking the result. - `docs/spark-standalone.md` (**Held Applications**): the Master web UI endpoints `/app/hold/` and `/app/resume/`, and the `held`/`draining` fields of `/json/` for checking the result, since the Master forwards the request to the driver asynchronously. For each endpoint, the docs describe: - the request must be a POST (on the driver UI, GET is also accepted when `spark.ui.actionsViaGetEnabled` is on); - it must carry the per-UI `csrfToken`, which is the value of the hidden `csrfToken` field on the corresponding page and stays fixed for the lifetime of that UI; - the trailing slash is required: without it, the request is only redirected and does not take effect; - a request without a valid token is rejected with 403; - when the UI requires authentication, reading the token and sending the request both need the same credentials. The examples use placeholders (`<csrf-token>`, `<app-id>`) in the same style as the existing REST API examples. ```bash curl -X POST -d "csrfToken=<csrf-token>" http://<driver-host>:4040/jobs/hold/ curl -X POST -d "id=<app-id>" -d "csrfToken=<csrf-token>" http://<master-host>:8080/app/hold/ ``` ### Why are the changes needed? Since SPARK-59353 (#58640), state-changing UI endpoints accept only POST requests that carry a per-UI CSRF token. The token check cannot be disabled. So the plain calls operators used before, such as `curl -X POST http://<driver-host>:4040/jobs/hold`, now fail with 403, and nothing in the hold/resume docs explains how to call these endpoints from a script. `docs/configuration.md` only says "Scripted clients can read the token from the jobs page". This PR fills that gap without weakening the CSRF protection: no token-less endpoint is added, and the endpoints behave exactly as they do today. ### Does this PR introduce _any_ user-facing change? No. This is a documentation-only change. ### How was this patch tested? I manually checked the documented requests on a local Standalone cluster: one Master, one Worker with `spark.shuffle.service.enabled=true`, and a `spark-shell` application with `spark.decommission.enabled=true`. | Request | Driver UI | Master UI | |---|---|---| | POST with a valid `csrfToken` | 302, then `holdstatus` shows `held: true` | 302, then `/json/` shows `held` toggled by resume/hold | | POST without a token | 403 | 403 | | POST with a wrong token | 403 | - | | POST without the trailing slash | 301, no effect | 301, no effect | I also built the docs locally and checked that the new sections render correctly. ### Was this patch authored or co-authored using generative AI tooling? Generated-by: Claude Opus 5.5 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
