diff --git a/docs/how-to/troubleshooting.md b/docs/how-to/troubleshooting.md index 66e22c618..738490b94 100644 --- a/docs/how-to/troubleshooting.md +++ b/docs/how-to/troubleshooting.md @@ -170,7 +170,7 @@ A `list` in one namespace that contains no `CoderControlPlane` at all does not r The logs show which provider configuration the server used. -## Aggregated reads return `multiple eligible CoderControlPlane ...` +## Aggregated reads return `multiple eligible CoderControlPlane instances` The server expects one eligible control plane for each request scope. If more than one control plane is eligible, do one of these steps: @@ -280,7 +280,7 @@ CAUTION: Delete the workspace in Coder before you remove the finalizer. Otherwis ## A namespace stays `Terminating` 1. Tests in the namespace wait for their cleanup. List them with `kubectl get codertemplatetests -n `, then see [A `CoderTemplateTest` does not finish deleting](#a-codertemplatetest-does-not-finish-deleting). -2. If the namespace condition `NamespaceDeletionContentFailure` is `True`, read its message. It contains the error that the aggregated API returned when the namespace controller listed its resources, for example a `503` or a `400`. For what each error means, see [Namespaces without a Coder backend](../reference/aggregated-api-behavior.md#namespaces-without-a-coder-backend) and [Aggregated reads return `ServiceUnavailable`](#aggregated-reads-return-serviceunavailable). If a `CoderControlPlane` is still in the namespace, check its finalizers, for example `coder.com/workspace-rbac-cleanup`, and the controller logs. +2. If the namespace condition `NamespaceDeletionContentFailure` is `True`, read its message. Kubernetes sets this condition when any API fails while the namespace controller removes the resources of the namespace. If the message names `aggregation.coder.com`, it contains the error that the aggregated API returned when the namespace controller listed its resources, for example a `503` or a `400`. For a `503`, see [Namespaces without a Coder backend](../reference/aggregated-api-behavior.md#namespaces-without-a-coder-backend) and [Aggregated reads return `ServiceUnavailable`](#aggregated-reads-return-serviceunavailable). For a `400` that says `multiple eligible CoderControlPlane instances`, see [Aggregated reads return `multiple eligible CoderControlPlane instances`](#aggregated-reads-return-multiple-eligible-codercontrolplane-instances). If the message names another API, examine that API instead. If a `CoderControlPlane` is still in the namespace, check its finalizers, for example `coder.com/workspace-rbac-cleanup`, and the controller logs. ```bash kubectl get namespace -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.message}{"\n"}{end}' diff --git a/docs/reference/aggregated-api-behavior.md b/docs/reference/aggregated-api-behavior.md index d6f6d928b..9fc092295 100644 --- a/docs/reference/aggregated-api-behavior.md +++ b/docs/reference/aggregated-api-behavior.md @@ -17,7 +17,7 @@ The aggregated API server serves `coderworkspaces`, `codertemplates` and `codert | [Template versions](#template-versions) | Read-only: `get` and `list`, no watch. Reads never download template source. | | [Promote a template version](#promote-a-template-version) | `codertemplates//promote` (`create`) makes a version active. A rollback promotes an older version. It needs its own RBAC grant. `dryRun=All` previews it. An unconfirmed result returns `503`, and a concurrent change returns `409`. | | [Template builds](#template-builds) | Create and update with `spec.files` wait until Coder completes the import. The full request must complete within 34 seconds. | -| [Coder timeouts](#coder-timeouts) | A Coder call that runs out of time returns `504` on every resource. Most broken `2xx` answers to a create also return `504`. After a `504` on a write, re-read before you retry. | +| [Coder timeouts](#coder-timeouts) | A Coder call that runs out of time returns `504` on every resource. A create that gets a broken `2xx` answer returns `504` or `500`. After a `504` on a write, re-read before you retry. | | [Workspace build log](#workspace-build-log) | `coderworkspaces/log` returns the latest build log as text. It needs its own RBAC grant and has fixed size, time, and concurrency limits. | | [Start and stop](#start-and-stop) | `coderworkspaces/start` and `coderworkspaces/stop` start or stop a workspace. Each needs its own RBAC grant. A repeated request does not queue a second build while one is active. | @@ -225,7 +225,12 @@ A Coder call that runs out of time returns `504 Gateway Timeout` on every aggreg - the request deadline ends first (see [The 34-second write budget](#the-34-second-write-budget), the [log limits](#workspace-build-log), and the [start and stop budget](#time-limit-and-retries)), or - Coder itself answers `504`. -A create of a workspace or a template also returns `504` when the answer to the create request has a `2xx` status, but is not the answer that Coder sends. For example, a proxy in front of Coder sends an HTML page, an empty body, or a status other than `201`. Coder can have created the object, so the message says that the result is uncertain. Some broken `2xx` answers still return `500`: a `200` with malformed JSON, and a connection that breaks while the server reads the answer. Coder can have created the object in these cases too, so re-read before you retry. +A create of a workspace or a template can also get a broken `2xx` answer, for example from a proxy in front of Coder. Coder can have created the object. The server returns `504` for some of these answers and `500` for others: + +- `504`, with a message that says that the result is uncertain. Examples are a `201` with an HTML page, an empty body, invalid JSON, or a JSON array, and a `200` with an HTML page or with the JSON of Coder. +- `500`. Examples are a `200` with the type `application/json` and invalid JSON or a JSON array, a `201` with `{}` or `null`, and a connection that breaks while the server reads the answer. + +After a `504` or a `500` on a create, re-read the object before you retry. The message does not include the Coder URL.