{ "openapi": "3.0.3", "info": { "title": "drydock API", "version": "1.0.0", "description": "The JSON contract between the drydock server and its dashboard.\n\nThe contract between the Gleam server (`apps/server`) and the dashboard (`apps/dashboard`). This document is the contract: the dashboard's TypeScript types are generated from it, and CI validates responses captured from the real server against it.\n\nTwo conventions are fixed and expensive to retrofit. The path is versioned, because the two tiers do not deploy together and a dashboard may lag the cluster it points at. And raw Kubernetes objects are not passed through — they are large, they carry fields users have no business seeing, and shipping them would make the dashboard depend on the Kubernetes schema.\n\nField names are snake_case unless the value *is* a Kubernetes field, in which case it keeps the spelling Kubernetes gives it, so that nobody has to learn a second name for something `kubectl` also prints.\n\nA request to a path this document does not list is answered 404 with the code `unknown_endpoint`, which is distinct from the `not_found` a missing resource gets.", "license": { "name": "Apache-2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" } }, "paths": { "/api/v1/access/grants": { "get": { "operationId": "listGrants", "summary": "Every AccessGrant, read as the calling user", "description": "Read as the caller, so this returns what that user is allowed to see. Not licence-gated: no read is.", "tags": [ "access" ], "responses": { "200": { "description": "The grants.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessGrantList" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] }, "post": { "operationId": "createGrant", "summary": "Grant a role to subjects, cluster-wide or in named namespaces", "description": "Sent with the caller's own token, so Kubernetes' escalation prevention applies: a 403 here is the apiserver refusing to let this user bind a role they could not bind themselves. That is an answer about the user, not a fault. The role must be one of `AccessGrantList.roles`, granted cluster-wide; anything else answers 422 before the apiserver is asked.", "tags": [ "access" ], "requestBody": { "required": true, "description": "The grant to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRequest" } } } }, "responses": { "201": { "description": "The created grant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessGrant" } } }, "headers": { "location": { "description": "Where the created object can now be read, as a path under this API.", "schema": { "type": "string" }, "required": true } } }, "400": { "$ref": "#/components/responses/MalformedBody" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } } }, "/api/v1/access/grants/{name}": { "patch": { "operationId": "patchGrant", "summary": "Change a grant's subjects, role or scope, or suspend it", "description": "Sent with the caller's own token, with the same escalation rules as creation. A body carrying only `suspended` suspends or resumes without touching the rest.", "tags": [ "access" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The object's metadata.name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "The fields to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantPatch" } } } }, "responses": { "204": { "description": "Applied. No body, as with every other write here.", "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "400": { "$ref": "#/components/responses/MalformedBody" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } }, "delete": { "operationId": "deleteGrant", "summary": "Revoke a grant", "description": "Deletes the AccessGrant; the controller removes the bindings it created.", "tags": [ "access" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The object's metadata.name.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } } }, "/api/v1/backups": { "get": { "operationId": "getBackups", "summary": "The backups drydock has taken", "description": "The Backup objects in drydock's namespace, read as the caller, with each one attributed to the node — and the upgrade, for one taken before an upgrade — it came from where the name allows it. The orchestrator keeps these objects matching the bucket; this endpoint does not open the bucket.", "tags": [ "backups" ], "responses": { "200": { "description": "The backups. `target` is null when none is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Backups" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/backups/config": { "get": { "operationId": "getBackupConfiguration", "summary": "How backups are configured", "description": "The BackupConfig drydock backs up with, read as the caller, and what it last did with it. Read-only: the configuration is edited on the BackupConfig itself, with kubectl or GitOps, never here.", "tags": [ "backups" ], "responses": { "200": { "description": "The configuration. `config` is null when none is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupConfiguration" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/openapi.json": { "get": { "operationId": "getOpenApiDocument", "summary": "This document", "description": "The OpenAPI document the server was built against, byte for byte. Read it from the server rather than from a copy: a dashboard may lag the cluster it points at, and this is the API that cluster actually speaks. Unauthenticated: it describes the API, not the caller.", "tags": [ "contract" ], "responses": { "200": { "description": "This document.", "content": { "application/json": { "schema": { "type": "object", "description": "An OpenAPI 3.0.3 document: this one." } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/Crashed" } }, "security": [], "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/auth/providers": { "get": { "operationId": "getAuthProviders", "summary": "Which sign-in methods this install offers", "description": "Unauthenticated, because the sign-in page needs it before there is a token. Only providers that are usable are listed.", "tags": [ "auth" ], "responses": { "200": { "description": "The offered methods.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthProviders" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "security": [], "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/auth/oidc/token": { "post": { "operationId": "exchangeOidcToken", "summary": "Redeem a code or a refresh token", "description": "Performed by the server, not the browser, so that the client secret never leaves the cluster.", "tags": [ "auth" ], "requestBody": { "required": true, "description": "Which provider, and which grant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "The issuer's tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenAnswer" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "400": { "$ref": "#/components/responses/ExchangeRefused" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "500": { "$ref": "#/components/responses/Crashed" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" } }, "security": [] } }, "/api/v1/auth/login": { "post": { "operationId": "login", "summary": "Sign in as a local user", "description": "One answer for every reason a sign-in fails, and a password derivation is burned even for a user that does not exist, so neither the body nor the response time says whether the account is real.", "tags": [ "auth" ], "requestBody": { "required": true, "description": "The credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "A minted session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAnswer" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "400": { "$ref": "#/components/responses/MalformedBody" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "500": { "$ref": "#/components/responses/Crashed" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" } }, "security": [] } }, "/api/v1/auth/logout": { "post": { "operationId": "logout", "summary": "End the session", "description": "Answers 204 and holds no server-side state: a session token is self-contained and expires on its own, so this exists for the client to have something to call.", "tags": [ "auth" ], "responses": { "204": { "description": "Signed out.", "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } } }, "/api/v1/identity/users": { "get": { "operationId": "listLocalUsers", "summary": "Every local user", "description": "Reads the LocalUser objects. No verifier or secret contents are ever included.", "tags": [ "identity" ], "responses": { "200": { "description": "The users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalUserList" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] }, "post": { "operationId": "createLocalUser", "summary": "Create a local user", "description": "Needs somewhere to put a password verifier, which is a deployment fact — hence the 501 when local sign-in is not configured.", "tags": [ "identity" ], "requestBody": { "required": true, "description": "The user to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalUserRequest" } } } }, "responses": { "201": { "description": "The created user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalUser" } } }, "headers": { "location": { "description": "Where the created object can now be read, as a path under this API.", "schema": { "type": "string" }, "required": true } } }, "400": { "$ref": "#/components/responses/MalformedBody" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } } }, "/api/v1/identity/users/{name}": { "patch": { "operationId": "patchLocalUser", "summary": "Change a local user, or just switch it off, or just set a password", "description": "The path name wins over any `name` in the body.", "tags": [ "identity" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The object's metadata.name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "One of three shapes; see the schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalUserPatch" } } } }, "responses": { "204": { "description": "Updated. No body.", "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "400": { "$ref": "#/components/responses/MalformedBody" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } }, "delete": { "operationId": "deleteLocalUser", "summary": "Delete a local user", "description": "Removes the object and the Secret holding its verifier.", "tags": [ "identity" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The object's metadata.name.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } } }, "/api/v1/identity/users/{name}/tokens": { "get": { "operationId": "listApiTokens", "summary": "A user's API tokens", "description": "The API tokens that act as this user, read as the caller: identity-admins may read them. Never the secret — that is shown once, when the token is created.", "tags": [ "identity" ], "responses": { "200": { "description": "The tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTokenList" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "name", "in": "path", "required": true, "description": "The LocalUser's metadata.name: the user the tokens act as.", "schema": { "type": "string" } } ] }, "post": { "operationId": "createApiToken", "summary": "Create an API token", "description": "A token a script sends as its bearer token, acting as this user: it can do exactly what the user can, and stops when the user is disabled or deleted. The caller must be allowed to create apitokens and to assign every group the user holds — the same rule as creating the user.", "tags": [ "identity" ], "requestBody": { "required": true, "description": "The token to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTokenRequest" } } } }, "responses": { "201": { "description": "The created token, with its secret. The secret is never shown again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTokenCreated" } } }, "headers": { "location": { "description": "Where the created object can now be read, as a path under this API.", "schema": { "type": "string" }, "required": true } } }, "400": { "$ref": "#/components/responses/MalformedBody" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The LocalUser's metadata.name: the user the tokens act as.", "schema": { "type": "string" } } ] } }, "/api/v1/identity/users/{name}/tokens/{id}": { "delete": { "operationId": "deleteApiToken", "summary": "Revoke an API token", "description": "Deletes the token. A request already holding it is refused from the next one on.", "tags": [ "identity" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The LocalUser's metadata.name: the user the tokens act as.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The token's id, the part of the token before the dot after `ddk_`.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Revoked.", "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } } }, "/api/v1/identity/providers": { "get": { "operationId": "listIdentityProviders", "summary": "Every configured identity provider", "description": "The authenticated view, which carries more than the sign-in page's: the claim names, and whether a client secret is configured.", "tags": [ "identity" ], "responses": { "200": { "description": "The providers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderList" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] }, "post": { "operationId": "createIdentityProvider", "summary": "Configure an identity provider", "description": "Writes the client secret into a Secret first and then the object referencing it, so a failure part-way leaves a secret nothing points at rather than an object pointing at nothing.", "tags": [ "identity" ], "requestBody": { "required": true, "description": "The provider to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderRequest" } } } }, "responses": { "201": { "description": "The created provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProvider" } } }, "headers": { "location": { "description": "Where the created object can now be read, as a path under this API.", "schema": { "type": "string" }, "required": true } } }, "400": { "$ref": "#/components/responses/MalformedBody" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } } }, "/api/v1/identity/providers/{name}": { "patch": { "operationId": "patchIdentityProvider", "summary": "Change a provider, or just switch it off", "description": "A blank `clientSecret` keeps the existing reference rather than clearing it; `publicClient` is how a reference is removed.", "tags": [ "identity" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The object's metadata.name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "One of two shapes; see the schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderPatch" } } } }, "responses": { "204": { "description": "Updated. No body.", "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "400": { "$ref": "#/components/responses/MalformedBody" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } }, "delete": { "operationId": "deleteIdentityProvider", "summary": "Remove a provider", "description": "Deletes the object and any Secret it owned.", "tags": [ "identity" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The object's metadata.name.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } } }, "/api/v1/inventory": { "get": { "operationId": "getInventory", "summary": "Every node, as the dashboard's table needs it", "description": "One row per node: identity, OS, readiness, what drydock can do to it, and what would block draining it.", "tags": [ "inventory" ], "responses": { "200": { "description": "The cluster's nodes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inventory" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/license": { "get": { "operationId": "getLicense", "summary": "Licence state, limits and current usage", "description": "Signed-in callers only. A drydock session or an identity-provider token is verified here; any other bearer token is answered once the apiserver has authenticated it with a SelfSubjectReview, because no other request on this route would test it. Authentication only: no RBAC is needed to read the licence. Answered from the server's own state otherwise. Every field is present in every state, with the claim-derived ones null when there is no licence.", "tags": [ "license" ], "responses": { "200": { "description": "The licence state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/License" }, "examples": { "licensed": { "summary": "Active, and within its limits", "value": { "status": "active", "allows_writes": true, "detail": null, "id": "lic_0WM0ik5Db6cZYoYk", "expires_at": 1793315320, "grace_ends_at": 1794524920, "days_left": 90, "cluster_id": null, "data": { "customer": "asergo", "tier": "enterprise" }, "limits": { "max_worker_nodes": 10, "max_control_plane_nodes": 3 }, "usage": { "worker_nodes": 6, "control_plane_nodes": 3, "observed_at": 1793314000 }, "compliant": true } }, "over_limit": { "summary": "Active, but the cluster exceeds a licensed limit", "description": "`compliant` is false while `status` is still active. The two are separate questions: the key is valid, and the cluster is too big for it.", "value": { "status": "active", "allows_writes": true, "detail": null, "id": "lic_0WM0ik5Db6cZYoYk", "expires_at": 1793315320, "grace_ends_at": 1794524920, "days_left": 90, "cluster_id": "8f3c1d2e-1a4b-4c9d-9e77-2b1f0a6c5d31", "data": { "customer": "asergo" }, "limits": { "max_worker_nodes": 10, "max_control_plane_nodes": 3 }, "usage": { "worker_nodes": 14, "control_plane_nodes": 3, "observed_at": 1793314000 }, "compliant": false } }, "unlicensed": { "summary": "No key configured — every claim-derived field is null", "value": { "status": "unlicensed", "allows_writes": false, "detail": "no license key is configured", "id": null, "expires_at": null, "grace_ends_at": null, "days_left": null, "cluster_id": null, "data": {}, "limits": { "max_worker_nodes": null, "max_control_plane_nodes": null }, "usage": null, "compliant": null } } } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/risk": { "get": { "operationId": "getRisk", "summary": "Whether losing a node would displace workloads", "description": "A per-node assessment of what a drain would move, what it could not move, and whether the remaining nodes have room for it.", "tags": [ "risk" ], "responses": { "200": { "description": "The risk assessment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskAssessment" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/upgrades": { "get": { "operationId": "listUpgrades", "summary": "Every ClusterUpgrade, and whether one is executing", "description": "Supports conditional requests: the response carries an `etag`, and a matching `if-none-match` is answered 304 with no body. `poll_after_seconds` is the reconcile interval, so a client need not guess a polling rate.", "tags": [ "upgrades" ], "responses": { "200": { "description": "The upgrades.", "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeList" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] }, "post": { "operationId": "createUpgrade", "summary": "Start an OS upgrade across named nodes", "description": "Creates a ClusterUpgrade. The nodes are named explicitly; there is no selector.", "tags": [ "upgrades" ], "requestBody": { "required": true, "description": "The upgrade to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeRequest" } } } }, "responses": { "201": { "description": "The created upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterUpgrade" } } }, "headers": { "location": { "description": "Where the created object can now be read, as a path under this API.", "schema": { "type": "string" }, "required": true } } }, "400": { "$ref": "#/components/responses/MalformedBody" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } } }, "/api/v1/upgrades/{name}": { "patch": { "operationId": "patchUpgrade", "summary": "Pause or resume an upgrade", "description": "The only mutable field is `paused`. Pausing stops the reconciler before the next step; it does not interrupt a step already running.", "tags": [ "upgrades" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The object's metadata.name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "The fields to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradePatch" } } } }, "responses": { "204": { "description": "Applied. No body, as with every other write here.", "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "400": { "$ref": "#/components/responses/MalformedBody" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } }, "delete": { "operationId": "deleteUpgrade", "summary": "Cancel an upgrade", "description": "Deletes the ClusterUpgrade. Work already done to a node is not reversed.", "tags": [ "upgrades" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The object's metadata.name.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } } } }, "/api/v1/uptime": { "get": { "operationId": "getUptime", "summary": "Per-node availability over the retained window", "description": "Daily rollups and incidents, attributed to a drydock upgrade where one explains the downtime. With `period`, one month; without it, the whole retained record. Incidents are built from the outages each month keeps for its whole life, so they last as long as the record does.", "tags": [ "uptime" ], "responses": { "200": { "description": "The uptime record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Uptime" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "period", "in": "query", "required": false, "description": "A UTC month, `YYYY-MM`. The answer then covers that month only: its days, and the incidents from its outages. Absent, the answer covers the whole retained record, as before.", "schema": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" } } ] } }, "/api/v1/uptime/months": { "get": { "operationId": "getUptimeMonths", "summary": "Availability per month over the retained record", "description": "One entry per UTC month the record holds: observed and unobserved time, downtime split by cause, and the count of unplanned outages and flap episodes. Small enough to draw thirteen months at once, which is what a month selector needs before it fetches one.", "tags": [ "uptime" ], "responses": { "200": { "description": "Availability per month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UptimeMonths" } } }, "headers": { "cache-control": { "description": "`private, no-cache`. The answer is about one caller, and a client must revalidate before reusing it — `no-cache` rather than `no-store` precisely so it MAY keep the validator a 304 depends on.", "schema": { "type": "string" }, "required": true }, "vary": { "description": "`authorization`. What the representation is selected by.", "schema": { "type": "string" }, "required": true }, "etag": { "description": "An opaque strong validator for this representation. Send it back as `if-none-match`. Derived from the bytes, except on the upgrades list, where the collection's `resourceVersion` lets the 304 be decided before the body is built.", "schema": { "type": "string" }, "required": true } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/Crashed" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/IdentityUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] } } }, "components": { "schemas": { "AccessGrant": { "type": "object", "required": [ "name", "suspended", "role", "subjects", "scope", "reconciled", "status" ], "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The object name. Lowercase letters, digits, '-' and '.' — note this is NOT the group name, which may contain characters an object name cannot." }, "suspended": { "type": "boolean", "description": "Reconciliation is stopped. Break-glass, and NOT revocation: existing bindings are left exactly where they are and simply stop being repaired or pruned. A UI that renders this as 'revoked' or 'disabled' is telling the operator the access is gone when it is not. Revoking is deleting the grant. Grants seeded at startup all begin suspended, so this is the normal state of a fresh install rather than an exceptional one." }, "role": { "$ref": "#/components/schemas/GrantRoleRef" }, "subjects": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/GrantSubject" }, "description": "Never empty. The minimum is enforced by the CustomResourceDefinition, so the apiserver refuses an object that would violate it; the server does not re-check it on the way out." }, "scope": { "$ref": "#/components/schemas/GrantScope" }, "reconciled": { "type": "boolean", "description": "Whether the controller has fully reconciled THIS version of the spec (status.observedGeneration == metadata.generation). It is what tells 'not acted on yet' apart from 'acted on, and the result is what status says'. A grant with an empty status and reconciled=false has not been reached; the same grant with reconciled=true has been reached and produced nothing, which is a different and much more interesting fact." }, "status": { "$ref": "#/components/schemas/GrantStatus" } } }, "AccessGrantList": { "description": "AccessGrant objects, read as the calling user. A grant is one subject list, one role and one scope; the server reconciles it into the Cluster/RoleBindings that implement it. Writes to this collection are the permission to GRANT ACCESS: every write is sent with the caller's own token, so Kubernetes' escalation prevention applies and a 403 here is the apiserver refusing to let this user bind a role they could not bind themselves. That is a real answer about the signed-in user, not a failure. There is no rule authoring anywhere in this contract — a grant names a role that must already exist.", "type": "object", "required": [ "grants", "roles" ], "additionalProperties": false, "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/AccessGrant" } }, "roles": { "type": "array", "description": "The ClusterRoles a grant may name, cluster-wide: drydock's viewer, upgrade-requester, identity-admin and drydock-admin, as this install names them. Any other role, and any namespace scope, is refused at creation and reported Denied on a grant that already exists.", "items": { "type": "string" } } } }, "ApiToken": { "type": "object", "description": "An API token, without its secret.", "required": [ "id", "user", "description", "createdAt", "expiresAt" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Names the token; not secret. The part of the token between `ddk_` and the dot." }, "user": { "type": "string", "description": "The LocalUser it acts as." }, "description": { "type": "string", "description": "What it is for, as its creator wrote it." }, "createdAt": { "type": "integer", "description": "Unix seconds." }, "expiresAt": { "type": "integer", "description": "Unix seconds. Refused from then on." } } }, "ApiTokenCreated": { "type": "object", "required": [ "token", "apiToken" ], "additionalProperties": false, "properties": { "token": { "type": "string", "description": "The bearer token, `ddk_.`. Shown once: only a hash of it is kept." }, "apiToken": { "$ref": "#/components/schemas/ApiToken" } } }, "ApiTokenList": { "type": "object", "required": [ "tokens" ], "additionalProperties": false, "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ApiToken" } } } }, "ApiTokenRequest": { "type": "object", "description": "A token to create.", "required": [ "description", "expiresInDays" ], "additionalProperties": false, "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 200, "description": "What it is for: the script or job that holds it." }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 365, "description": "How long it lasts. The install's maximum (identity.apiTokens.maxLifetimeDays, 90 by default) is enforced too, with a 422 above it." } } }, "AuthProviders": { "type": "object", "description": "What sign-in methods this install offers. Unauthenticated: the page needs it before there is a token.", "required": [ "providers", "localUsers" ], "additionalProperties": false, "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/PublicProvider" } }, "localUsers": { "type": "boolean", "description": "Whether this install has local user sign-in configured at all." } } }, "AuthorizationCodeGrant": { "type": "object", "description": "Redeem an authorization code. PKCE is not optional here.", "required": [ "provider", "grantType", "code", "codeVerifier", "redirectUri" ], "additionalProperties": false, "properties": { "provider": { "type": "string", "description": "Which configured provider to redeem against." }, "grantType": { "type": "string", "enum": [ "authorization_code" ] }, "code": { "type": "string" }, "codeVerifier": { "type": "string" }, "redirectUri": { "type": "string" } } }, "BackupConfig": { "type": "object", "required": [ "name", "namespace", "endpoint", "bucket", "region", "scheme", "port", "private_ca", "secret_name", "folder", "type", "interval", "ttl", "upload", "restore_test", "last_upload", "last_restore_test", "last_passed_restore_test_at" ], "additionalProperties": false, "properties": { "name": { "description": "The BackupConfig's name. drydock reads the one called default.", "type": "string", "example": "default" }, "namespace": { "type": "string", "example": "drydock-system" }, "endpoint": { "description": "The store's host.", "type": "string", "example": "s3.example.com" }, "bucket": { "type": "string", "example": "cluster-backups" }, "region": { "type": "string", "example": "us-east-1" }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "port": { "description": "Absent on the BackupConfig means the scheme's default.", "type": "integer", "nullable": true }, "private_ca": { "description": "True when the BackupConfig carries a caBundle to verify the endpoint against, rather than the system trust store.", "type": "boolean" }, "secret_name": { "description": "The Secret holding the upload credential. Named, never read for this answer.", "type": "string", "example": "drydock-backup-credentials" }, "folder": { "description": "Where this cluster's backups live in the bucket: drydock/backup//. Not configurable — the cluster ID is the kube-system namespace's UID.", "type": "string", "example": "drydock/backup/9f2c1e4a-5b7d-4c3e-8a1f-2d6b0e9c7a53/" }, "type": { "description": "What is backed up.", "type": "string", "enum": [ "etcd" ] }, "interval": { "description": "How often a backup is taken, as the BackupConfig spells it.", "type": "string", "example": "1d" }, "ttl": { "description": "How long a backup is kept. The newest backup is never deleted, whatever its age.", "type": "string", "example": "10d" }, "upload": { "$ref": "#/components/schemas/BackupUploadPolicy" }, "restore_test": { "$ref": "#/components/schemas/BackupRestoreTestPolicy" }, "last_upload": { "description": "The last attempt to put a backup in the bucket, successful or not. Null when none has been made.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BackupLastUpload" } ] }, "last_restore_test": { "description": "The newest restore test, passed or failed. Null when none has run.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BackupLastRestoreTest" } ] }, "last_passed_restore_test_at": { "description": "Unix seconds when the newest PASSED restore test started. Null when none has passed — which is the state an auditor asks about.", "type": "integer", "nullable": true } } }, "BackupConfiguration": { "type": "object", "description": "The BackupConfig drydock backs up with, as the caller may read it. Nothing secret crosses: the Secret is named, never read for this answer.", "required": [ "config" ], "additionalProperties": false, "properties": { "config": { "description": "The configuration, or null if drydock has nowhere to back up to — backups switched off in the chart. Null is an ANSWER and must render as 'backups are not configured', never as an error.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BackupConfig" } ] } } }, "BackupLastRestoreTest": { "type": "object", "required": [ "snapshot_key", "at", "outcome", "rung", "reason" ], "additionalProperties": false, "properties": { "snapshot_key": { "description": "The backup that was tested.", "type": "string" }, "at": { "description": "Unix seconds when the test started.", "type": "integer" }, "outcome": { "type": "string", "enum": [ "passed", "failed" ] }, "rung": { "description": "How far the test got: fetched and its ETag checked, status read by etcdutl, restored, then served by a throwaway etcd. none when it failed before the download finished.", "type": "string", "enum": [ "none", "fetched", "status", "restored", "served" ] }, "reason": { "description": "Why it failed. Empty otherwise.", "type": "string" } } }, "BackupLastUpload": { "type": "object", "required": [ "key", "at", "outcome", "reason" ], "additionalProperties": false, "properties": { "key": { "type": "string" }, "at": { "description": "Unix seconds.", "type": "integer" }, "outcome": { "type": "string", "enum": [ "succeeded", "failed" ] }, "reason": { "description": "Why it failed. Empty otherwise.", "type": "string" } } }, "BackupObject": { "type": "object", "required": [ "name", "key", "etag", "phase", "reason", "started_at", "backed_up_at", "ttl", "expires_at", "last_restore", "status" ], "additionalProperties": false, "properties": { "name": { "description": "The Backup object's name.", "type": "string", "example": "etcd-cp-1-20260928t120000z" }, "key": { "description": "The object key in the bucket: drydock/backup///-