Update: Document Admin API endpoints used by decK (#6817)

* add deck endpoints * list endpoints used by deck to communicate with gateway * include workspace-less option * Apply suggestions from code review Co-authored-by: Angel <[email protected]> --------- Co-authored-by: Angel <[email protected]>
Kong · Jun 7, 2024 · e8da147 · e8da147
1 parent 6ad4316
commit e8da147
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 0 deletions.
diff --git a/app/_src/deck/guides/kong-enterprise.md b/app/_src/deck/guides/kong-enterprise.md
@@ -45,6 +45,56 @@ It is advised that you do not use an RBAC token with super admin privileges
 with decK, and always scope down the exact permissions you need to give
 decK.
 
+### Endpoints used by decK
+
+decK uses Kong's Admin API to communicate with {{site.base_gateway}}. 
+If you have RBAC enabled, you need to give decK permissions to perform operations, or use an admin account that has these permissions. 
+
+Here are some common endpoints hit by decK for normal operations:
+
+* `GET, POST, PATCH, PUT, DELETE /{entityType}` or `GET, POST, PATCH, PUT, DELETE /{workspace}/{entityType}`: Perform read and write operations on entities.
+
+   If you are running {{site.ee_product_name}}, then decK interacts with entities inside workspaces. 
+   See the [Entities managed by decK](/deck/{{page.release}}/reference/entities/) reference for the full list.
+
+   Note that decK also performs operations on entities enabled by plugins, such as `/basic-auths`, `/jwts`, and so on.
+* `GET /`: Get the {{site.base_gateway}} version.
+* `GET /{workspace}/kong`: Get entities in a workspace.
+* `GET /{workspace}/workspaces/{entityType}`: Check whether the workspace or other entity exists or not.
+* `GET /{workspace}/schemas/{entityType}`: Retrieves the schema for a specified entity type within a workspace and applies default settings.
+* `GET /{workspace}/schemas/plugins/{pluginName}`: Retrieves the schema for a specified plugin within a workspace and applies default settings.
+* `POST /workspaces`: Create missing workspaces.
+
+To find out which endpoints your instance of decK is hitting, execute any decK command with the `--verbose 1` flag. 
+This outputs all of the queries being made. For example, here's a snippet from `deck gateway dump --verbose 1`:
+
+```sh
+...
+GET /routes?size=1000 HTTP/1.1
+Host: localhost:8001
+User-Agent: Go-http-client/1.1
+Accept-Encoding: gzip
+
+
+GET /consumers?size=1000 HTTP/1.1
+Host: localhost:8001
+User-Agent: Go-http-client/1.1
+Accept-Encoding: gzip
+
+
+GET /mtls-auths?size=1000 HTTP/1.1
+Host: localhost:8001
+User-Agent: Go-http-client/1.1
+Accept-Encoding: gzip
+
+
+GET /snis?size=1000 HTTP/1.1
+Host: localhost:8001
+User-Agent: Go-http-client/1.1
+Accept-Encoding: gzip
+...
+```
+
 ## Workspaces
 
 decK is workspace-aware, meaning it can interact with multiple workspaces.

diff --git a/app/_src/deck/reference/entities.md b/app/_src/deck/reference/entities.md
@@ -47,3 +47,7 @@ See [Manage multiple workspaces](/deck/{{page.release}}/guides/kong-enterprise/#
 While deck can manage a majority of {{site.base_gateway}}'s configuration, we recommend additional arrangements for deployment, backup, and restoring unmanaged entities for a more comprehensive approach.
 
 In the event that the data plane loses connection to the control plane in hybrid mode, the data plane can continue to function using a [backup declarative configuration file](/gateway/latest/reference/configuration/#declarative_config). This feature is not available if you have any unmanaged entities configured.
+
+## See also
+
+* [Kong Admin API endpoints used by decK](/deck/{{page.release}}/guides/kong-enterprise/#endpoints-used-by-deck)