From 52acdf8697aa1a800aeac055482afb28cd729758 Mon Sep 17 00:00:00 2001 From: Angel Date: Thu, 19 Sep 2024 18:41:57 -0400 Subject: [PATCH] Chore: Clustering endpoints (#7935) * clustering endpoint * cache endpoints * Apply suggestions from code review Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> * caps * missed one * Apply suggestions from code review Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> --------- Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> --- api-specs/Gateway-EE/3.6/kong-ee-3.6.yaml | 200 +++++++++++++++++++- api-specs/Gateway-EE/3.7/kong-ee-3.7.yaml | 199 ++++++++++++++++++- api-specs/Gateway-EE/latest/kong-ee.yaml | 199 ++++++++++++++++++- api-specs/Gateway-OSS/3.6/kong-oss-3.6.yaml | 199 ++++++++++++++++++- api-specs/Gateway-OSS/3.7/kong-oss-3.7.yaml | 199 ++++++++++++++++++- api-specs/Gateway-OSS/latest/kong-oss.yaml | 199 ++++++++++++++++++- 6 files changed, 1189 insertions(+), 6 deletions(-) diff --git a/api-specs/Gateway-EE/3.6/kong-ee-3.6.yaml b/api-specs/Gateway-EE/3.6/kong-ee-3.6.yaml index e7e83a5315e2..a5c5ed30c93e 100644 --- a/api-specs/Gateway-EE/3.6/kong-ee-3.6.yaml +++ b/api-specs/Gateway-EE/3.6/kong-ee-3.6.yaml @@ -15192,6 +15192,198 @@ paths: fips_disabled: value: {"active": false, "version": "unknown"} summary: FIPS mode is disabled or not supported. This may be the default state or result from a license configuration that does not enable FIPS mode. + '/clustering/data-planes': + get: + summary: Retrieve connected data planes + description: > + Retrieve a list of all data planes connected to the control plane. This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlanes + responses: + '200': + description: A list of connected data planes. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address of the data plane. + updated_at: + type: integer + description: Unix timestamp of the last update. + config_hash: + type: string + description: The hash of the current configuration on the data plane. + sync_status: + type: string + description: The sync status of the data plane. + version: + type: string + description: The version of Kong running on the data plane. + id: + type: string + description: Unique identifier of the data plane. + hostname: + type: string + description: The hostname of the data plane. + ttl: + type: integer + description: Time-to-live for the connection. + last_seen: + type: integer + description: Unix timestamp when the data plane was last seen by the control plane. + labels: + type: object + description: Metadata labels attached to the data plane. + properties: + deployment: + type: string + description: The deployment name. + region: + type: string + description: The region of the data plane. + cert_details: + type: object + properties: + expiry_timestamp: + type: integer + description: Timestamp for when the certificate expires. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is configured to run as a control plane for the cluster. + tags: + - clustering + + '/clustering/status': + get: + summary: Retrieve the status of connected data planes + description: > + Retrieve a status report for all data planes connected to the control plane. It includes information like the config hash, hostname, IP address, and last seen timestamp. + This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlaneStatus + responses: + '200': + description: The status of all connected data planes. + headers: + Deprecation: + description: > + Indicates that the endpoint may be deprecated in the future. + schema: + type: string + content: + application/json: + schema: + type: object + additionalProperties: + type: object + properties: + config_hash: + type: string + description: Hash of the configuration running on the data plane. + hostname: + type: string + description: Hostname of the data plane. + ip: + type: string + description: The IP address of the data plane. + last_seen: + type: integer + description: Unix timestamp of the last interaction between the data plane and control plane. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is configured to run as a control plane for the cluster. + tags: + - clustering + '/cache/{key}': + get: + summary: Get cache value by key + description: > + Retrieve the cached value for a specific key. This endpoint probes both `kong.cache` and `kong.core_cache`. + If the key exists, it returns the associated value and TTL. If not found, it returns a 404. + operationId: getCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to retrieve. + schema: + type: string + responses: + '200': + description: Cached value found. + content: + application/json: + schema: + type: object + properties: + ttl: + type: integer + description: Time-to-live (TTL) of the cached entry. + message: + type: string + description: Cached value or a message. + '404': + description: Cache key not found. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: Not found + tags: + - cache + delete: + summary: Invalidate cache by key + description: > + Invalidate the cache for a specific key in both `kong.cache` and `kong.core_cache`. + operationId: deleteCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to invalidate. + schema: + type: string + responses: + '204': + description: Cache invalidated successfully. + tags: + - cache + + '/cache': + delete: + summary: Purge all cache entries + description: > + Purge all cache entries in both `kong.cache` and `kong.core_cache`. + operationId: purgeAllCache + responses: + '204': + description: All cache entries purged successfully. + tags: + - cache + servers: - description: Default Admin API URL @@ -15359,4 +15551,10 @@ tags:

Event hooks do not work with Konnect yet.

- name: Event-hooks \ No newline at end of file + name: Event-hooks + - description: | + Retrieve information about the status of data planes when Kong Gateway is running in hybrid mode. + name: clustering + - description: | + Querying and managing cache entries. + name: cache \ No newline at end of file diff --git a/api-specs/Gateway-EE/3.7/kong-ee-3.7.yaml b/api-specs/Gateway-EE/3.7/kong-ee-3.7.yaml index 1d261aff5e92..8eb973f8bf23 100644 --- a/api-specs/Gateway-EE/3.7/kong-ee-3.7.yaml +++ b/api-specs/Gateway-EE/3.7/kong-ee-3.7.yaml @@ -15382,6 +15382,197 @@ paths: summary: Associate a role with a group tags: - Workspaces + '/clustering/data-planes': + get: + summary: Retrieve connected data planes + description: > + Retrieve a list of all data planes connected to the control plane. This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlanes + responses: + '200': + description: A list of connected data planes. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address of the data plane. + updated_at: + type: integer + description: Unix timestamp of the last update. + config_hash: + type: string + description: The hash of the current configuration on the data plane. + sync_status: + type: string + description: The sync status of the data plane. + version: + type: string + description: The version of Kong running on the data plane. + id: + type: string + description: Unique identifier of the data plane. + hostname: + type: string + description: The hostname of the data plane. + ttl: + type: integer + description: Time-to-live for the connection. + last_seen: + type: integer + description: Unix timestamp when the data plane was last seen by the control plane. + labels: + type: object + description: Metadata labels attached to the data plane. + properties: + deployment: + type: string + description: The deployment name. + region: + type: string + description: The region of the data plane. + cert_details: + type: object + properties: + expiry_timestamp: + type: integer + description: Timestamp for when the certificate expires. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong Gateway is running as a control plane for the cluster. + tags: + - clustering + + '/clustering/status': + get: + summary: Retrieve the status of connected data planes + description: > + Retrieve a status report for all data planes connected to the control plane. It includes information like the config hash, hostname, IP address, and last seen timestamp. + This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlaneStatus + responses: + '200': + description: The status of all connected data planes. + headers: + Deprecation: + description: > + Indicates that the endpoint may be deprecated in the future. + schema: + type: string + content: + application/json: + schema: + type: object + additionalProperties: + type: object + properties: + config_hash: + type: string + description: Hash of the configuration running on the data plane. + hostname: + type: string + description: Hostname of the data plane. + ip: + type: string + description: The IP address of the data plane. + last_seen: + type: integer + description: Unix timestamp of the last interaction between the data plane and control plane. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + '/cache/{key}': + get: + summary: Get cache value by key + description: > + Retrieve the cached value for a specific key. This endpoint probes both `kong.cache` and `kong.core_cache`. + If the key exists, it returns the associated value and TTL. If not found, it returns a 404. + operationId: getCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to retrieve. + schema: + type: string + responses: + '200': + description: Cached value found. + content: + application/json: + schema: + type: object + properties: + ttl: + type: integer + description: Time-to-live (TTL) of the cached entry. + message: + type: string + description: Cached value or a message. + '404': + description: Cache key not found. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: Not found + tags: + - cache + delete: + summary: Invalidate cache by key + description: > + Invalidate the cache for a specific key in both `kong.cache` and `kong.core_cache`. + operationId: deleteCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to invalidate. + schema: + type: string + responses: + '204': + description: Cache invalidated successfully. + tags: + - cache + + '/cache': + delete: + summary: Purge all cache entries + description: > + Purge all cache entries in both `kong.cache` and `kong.core_cache`. + operationId: purgeAllCache + responses: + '204': + description: All cache entries purged successfully. + tags: + - cache servers: - description: Default Admin API URL @@ -15553,4 +15744,10 @@ tags:

Event hooks do not work with Konnect yet.

- name: Event-hooks \ No newline at end of file + name: Event-hooks + - description: | + Retrieve information about the status of data planes when Kong Gateway is running in hybrid mode. + name: clustering + - description: | + Querying and managing cache entries. + name: cache \ No newline at end of file diff --git a/api-specs/Gateway-EE/latest/kong-ee.yaml b/api-specs/Gateway-EE/latest/kong-ee.yaml index bf143cdb1ece..02469b5bc721 100644 --- a/api-specs/Gateway-EE/latest/kong-ee.yaml +++ b/api-specs/Gateway-EE/latest/kong-ee.yaml @@ -15921,6 +15921,197 @@ paths: summary: Associate a role with a group tags: - Workspaces + '/clustering/data-planes': + get: + summary: Retrieve connected data planes + description: > + Retrieve a list of all data planes connected to the control plane. This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlanes + responses: + '200': + description: A list of connected data planes. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address of the data plane. + updated_at: + type: integer + description: Unix timestamp of the last update. + config_hash: + type: string + description: The hash of the current configuration on the data plane. + sync_status: + type: string + description: The sync status of the data plane. + version: + type: string + description: The version of Kong running on the data plane. + id: + type: string + description: Unique identifier of the data plane. + hostname: + type: string + description: The hostname of the data plane. + ttl: + type: integer + description: Time-to-live for the connection. + last_seen: + type: integer + description: Unix timestamp when the data plane was last seen by the control plane. + labels: + type: object + description: Metadata labels attached to the data plane. + properties: + deployment: + type: string + description: The deployment name. + region: + type: string + description: The region of the data plane. + cert_details: + type: object + properties: + expiry_timestamp: + type: integer + description: Timestamp for when the certificate expires. + '400': + description: Kong Gatewat is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + + '/clustering/status': + get: + summary: Retrieve the status of connected data planes + description: > + Retrieve a status report for all data planes connected to the control plane. It includes information like the config hash, hostname, IP address, and last seen timestamp. + This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlaneStatus + responses: + '200': + description: The status of all connected data planes. + headers: + Deprecation: + description: > + Indicates that the endpoint may be deprecated in the future. + schema: + type: string + content: + application/json: + schema: + type: object + additionalProperties: + type: object + properties: + config_hash: + type: string + description: Hash of the configuration running on the data plane. + hostname: + type: string + description: Hostname of the data plane. + ip: + type: string + description: The IP address of the data plane. + last_seen: + type: integer + description: Unix timestamp of the last interaction between the data plane and control plane. + '400': + description: Kong Gatewat is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + '/cache/{key}': + get: + summary: Get cache value by key + description: > + Retrieve the cached value for a specific key. This endpoint probes both `kong.cache` and `kong.core_cache`. + If the key exists, it returns the associated value and TTL. If not found, it returns a 404. + operationId: getCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to retrieve. + schema: + type: string + responses: + '200': + description: Cached value found. + content: + application/json: + schema: + type: object + properties: + ttl: + type: integer + description: Time-to-live (TTL) of the cached entry. + message: + type: string + description: Cached value or a message. + '404': + description: Cache key not found. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: Not found + tags: + - cache + delete: + summary: Invalidate cache by key + description: > + Invalidate the cache for a specific key in both `kong.cache` and `kong.core_cache`. + operationId: deleteCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to invalidate. + schema: + type: string + responses: + '204': + description: Cache invalidated successfully. + tags: + - cache + + '/cache': + delete: + summary: Purge all cache entries + description: > + Purge all cache entries in both `kong.cache` and `kong.core_cache`. + operationId: purgeAllCache + responses: + '204': + description: All cache entries purged successfully. + tags: + - cache servers: - description: Default Admin API URL @@ -16101,4 +16292,10 @@ tags:

Event hooks do not work with Konnect yet.

- name: Event-hooks \ No newline at end of file + name: Event-hooks + - description: | + Retrieve information about the status of data planes when Kong Gateway is running in hybrid mode. + name: clustering + - description: | + Querying and managing cache entries. + name: cache \ No newline at end of file diff --git a/api-specs/Gateway-OSS/3.6/kong-oss-3.6.yaml b/api-specs/Gateway-OSS/3.6/kong-oss-3.6.yaml index 55f3dd5d009a..3e2271a90baa 100644 --- a/api-specs/Gateway-OSS/3.6/kong-oss-3.6.yaml +++ b/api-specs/Gateway-OSS/3.6/kong-oss-3.6.yaml @@ -7370,6 +7370,197 @@ paths: description: No vault named operationId: get-schemas-vaults-vault_name description: Retrieve the schema of a vault. + '/clustering/data-planes': + get: + summary: Retrieve connected data planes + description: > + Retrieve a list of all data planes connected to the control plane. This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlanes + responses: + '200': + description: A list of connected data planes. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address of the data plane. + updated_at: + type: integer + description: Unix timestamp of the last update. + config_hash: + type: string + description: The hash of the current configuration on the data plane. + sync_status: + type: string + description: The sync status of the data plane. + version: + type: string + description: The version of Kong running on the data plane. + id: + type: string + description: Unique identifier of the data plane. + hostname: + type: string + description: The hostname of the data plane. + ttl: + type: integer + description: Time-to-live for the connection. + last_seen: + type: integer + description: Unix timestamp when the data plane was last seen by the control plane. + labels: + type: object + description: Metadata labels attached to the data plane. + properties: + deployment: + type: string + description: The deployment name. + region: + type: string + description: The region of the data plane. + cert_details: + type: object + properties: + expiry_timestamp: + type: integer + description: Timestamp for when the certificate expires. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + + '/clustering/status': + get: + summary: Retrieve the status of connected data planes + description: > + Retrieve a status report for all data planes connected to the control plane. It includes information like the config hash, hostname, IP address, and last seen timestamp. + This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlaneStatus + responses: + '200': + description: The status of all connected data planes. + headers: + Deprecation: + description: > + Indicates that the endpoint may be deprecated in the future. + schema: + type: string + content: + application/json: + schema: + type: object + additionalProperties: + type: object + properties: + config_hash: + type: string + description: Hash of the configuration running on the data plane. + hostname: + type: string + description: Hostname of the data plane. + ip: + type: string + description: The IP address of the data plane. + last_seen: + type: integer + description: Unix timestamp of the last interaction between the data plane and control plane. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + '/cache/{key}': + get: + summary: Get cache value by key + description: > + Retrieve the cached value for a specific key. This endpoint probes both `kong.cache` and `kong.core_cache`. + If the key exists, it returns the associated value and TTL. If not found, it returns a 404. + operationId: getCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to retrieve. + schema: + type: string + responses: + '200': + description: Cached value found. + content: + application/json: + schema: + type: object + properties: + ttl: + type: integer + description: Time-to-live (TTL) of the cached entry. + message: + type: string + description: Cached value or a message. + '404': + description: Cache key not found. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: Not found + tags: + - cache + delete: + summary: Invalidate cache by key + description: > + Invalidate the cache for a specific key in both `kong.cache` and `kong.core_cache`. + operationId: deleteCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to invalidate. + schema: + type: string + responses: + '204': + description: Cache invalidated successfully. + tags: + - cache + + '/cache': + delete: + summary: Purge all cache entries + description: > + Purge all cache entries in both `kong.cache` and `kong.core_cache`. + operationId: purgeAllCache + responses: + '204': + description: All cache entries purged successfully. + tags: + - cache servers: - description: Default Admin API URL url: '{protocol}://{hostname}:{port}{path}' @@ -7484,4 +7675,10 @@ tags: Tags are strings associated to entities in Kong Gateway. Tags can contain almost all UTF-8 characters, with the following exceptions: `,`,`/`, and non-printable ASCII (for example, the space character).

Most core entities can be tagged via the tags attribute upon creation or modification. - name: Tags \ No newline at end of file + name: Tags + - description: | + Retrieve information about the status of data planes when Kong Gateway is running in hybrid mode. + name: clustering + - description: | + Querying and managing cache entries. + name: cache \ No newline at end of file diff --git a/api-specs/Gateway-OSS/3.7/kong-oss-3.7.yaml b/api-specs/Gateway-OSS/3.7/kong-oss-3.7.yaml index dc16a78475ff..122e7e78ac82 100644 --- a/api-specs/Gateway-OSS/3.7/kong-oss-3.7.yaml +++ b/api-specs/Gateway-OSS/3.7/kong-oss-3.7.yaml @@ -7280,7 +7280,7 @@ paths: '401': $ref: '#/components/responses/HTTP401Error' description: | - Change the log level of all Control Plane nodes deployed in Hybrid (CP/DP) cluster. + Change the log level of all control plane nodes deployed in a hybrid (CP/DP) cluster. See the [NGINX docs](http://nginx.org/en/docs/ngx_core_module.html#error_log) for a list of accepted values. @@ -7718,6 +7718,197 @@ paths: Delete filter chain associated to a specific service. tags: - filter-chains + '/clustering/data-planes': + get: + summary: Retrieve connected data planes + description: > + Retrieve a list of all data planes connected to the control plane. This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlanes + responses: + '200': + description: A list of connected data planes. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address of the data plane. + updated_at: + type: integer + description: Unix timestamp of the last update. + config_hash: + type: string + description: The hash of the current configuration on the data plane. + sync_status: + type: string + description: The sync status of the data plane. + version: + type: string + description: The version of Kong running on the data plane. + id: + type: string + description: Unique identifier of the data plane. + hostname: + type: string + description: The hostname of the data plane. + ttl: + type: integer + description: Time-to-live for the connection. + last_seen: + type: integer + description: Unix timestamp when the data plane was last seen by the control plane. + labels: + type: object + description: Metadata labels attached to the data plane. + properties: + deployment: + type: string + description: The deployment name. + region: + type: string + description: The region of the data plane. + cert_details: + type: object + properties: + expiry_timestamp: + type: integer + description: Timestamp for when the certificate expires. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + + '/clustering/status': + get: + summary: Retrieve the status of connected data planes + description: > + Retrieve a status report for all data planes connected to the control plane. It includes information like the config hash, hostname, IP address, and last seen timestamp. + This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlaneStatus + responses: + '200': + description: The status of all connected data planes. + headers: + Deprecation: + description: > + Indicates that the endpoint may be deprecated in the future. + schema: + type: string + content: + application/json: + schema: + type: object + additionalProperties: + type: object + properties: + config_hash: + type: string + description: Hash of the configuration running on the data plane. + hostname: + type: string + description: Hostname of the data plane. + ip: + type: string + description: The IP address of the data plane. + last_seen: + type: integer + description: Unix timestamp of the last interaction between the data plane and control plane. + '400': + description: Kong Gateway is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + '/cache/{key}': + get: + summary: Get cache value by key + description: > + Retrieve the cached value for a specific key. This endpoint probes both `kong.cache` and `kong.core_cache`. + If the key exists, it returns the associated value and TTL. If not found, it returns a 404. + operationId: getCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to retrieve. + schema: + type: string + responses: + '200': + description: Cached value found. + content: + application/json: + schema: + type: object + properties: + ttl: + type: integer + description: Time-to-live (TTL) of the cached entry. + message: + type: string + description: Cached value or a message. + '404': + description: Cache key not found. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: Not found + tags: + - cache + delete: + summary: Invalidate cache by key + description: > + Invalidate the cache for a specific key in both `kong.cache` and `kong.core_cache`. + operationId: deleteCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to invalidate. + schema: + type: string + responses: + '204': + description: Cache invalidated successfully. + tags: + - cache + + '/cache': + delete: + summary: Purge all cache entries + description: > + Purge all cache entries in both `kong.cache` and `kong.core_cache`. + operationId: purgeAllCache + responses: + '204': + description: All cache entries purged successfully. + tags: + - cache servers: - description: Default Admin API URL url: '{protocol}://{hostname}:{port}{path}' @@ -7833,3 +8024,9 @@ tags:

Most core entities can be tagged via the tags attribute upon creation or modification. name: Tags + - description: | + Retreieve information about the status of data planes when Kong Gateway is configured in hybrid mode. + name: clustering + - description: | + Querying and managing cache entries. + name: cache diff --git a/api-specs/Gateway-OSS/latest/kong-oss.yaml b/api-specs/Gateway-OSS/latest/kong-oss.yaml index 6aa5a0fcb0c9..0a914d473fe2 100644 --- a/api-specs/Gateway-OSS/latest/kong-oss.yaml +++ b/api-specs/Gateway-OSS/latest/kong-oss.yaml @@ -7331,7 +7331,7 @@ paths: '401': $ref: '#/components/responses/HTTP401Error' description: | - Change the log level of all Control Plane nodes deployed in Hybrid (CP/DP) cluster. + Change the log level of all control plane nodes deployed in a hybrid (CP/DP) cluster. See the [NGINX docs](http://nginx.org/en/docs/ngx_core_module.html#error_log) for a list of accepted values. @@ -7769,6 +7769,197 @@ paths: Delete filter chain associated to a specific service. tags: - filter-chains + '/clustering/data-planes': + get: + summary: Retrieve connected data planes + description: > + Retrieve a list of all data planes connected to the control plane. This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlanes + responses: + '200': + description: A list of connected data planes. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address of the data plane. + updated_at: + type: integer + description: Unix timestamp of the last update. + config_hash: + type: string + description: The hash of the current configuration on the data plane. + sync_status: + type: string + description: The sync status of the data plane. + version: + type: string + description: The version of Kong running on the data plane. + id: + type: string + description: Unique identifier of the data plane. + hostname: + type: string + description: The hostname of the data plane. + ttl: + type: integer + description: Time-to-live for the connection. + last_seen: + type: integer + description: Unix timestamp when the data plane was last seen by the control plane. + labels: + type: object + description: Metadata labels attached to the data plane. + properties: + deployment: + type: string + description: The deployment name. + region: + type: string + description: The region of the data plane. + cert_details: + type: object + properties: + expiry_timestamp: + type: integer + description: Timestamp for when the certificate expires. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + + '/clustering/status': + get: + summary: Retrieve the status of connected data planes + description: > + Retrieve a status report for all data planes connected to the control plane. It includes information like the config hash, hostname, IP address, and last seen timestamp. + This endpoint is only accessible when Kong Gateway is running in hybrid mode. + operationId: getDataPlaneStatus + responses: + '200': + description: The status of all connected data planes. + headers: + Deprecation: + description: > + Indicates that the endpoint may be deprecated in the future. + schema: + type: string + content: + application/json: + schema: + type: object + additionalProperties: + type: object + properties: + config_hash: + type: string + description: Hash of the configuration running on the data plane. + hostname: + type: string + description: Hostname of the data plane. + ip: + type: string + description: The IP address of the data plane. + last_seen: + type: integer + description: Unix timestamp of the last interaction between the data plane and control plane. + '400': + description: Kong is not running as a control plane. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: This endpoint is only available when Kong is running as a control plane for the cluster. + tags: + - clustering + '/cache/{key}': + get: + summary: Get cache value by key + description: > + Retrieve the cached value for a specific key. This endpoint probes both `kong.cache` and `kong.core_cache`. + If the key exists, it returns the associated value and TTL. If not found, it returns a 404. + operationId: getCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to retrieve. + schema: + type: string + responses: + '200': + description: Cached value found. + content: + application/json: + schema: + type: object + properties: + ttl: + type: integer + description: Time-to-live (TTL) of the cached entry. + message: + type: string + description: Cached value or a message. + '404': + description: Cache key not found. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: Not found + tags: + - cache + delete: + summary: Invalidate cache by key + description: > + Invalidate the cache for a specific key in both `kong.cache` and `kong.core_cache`. + operationId: deleteCacheByKey + parameters: + - name: key + in: path + required: true + description: The cache key to invalidate. + schema: + type: string + responses: + '204': + description: Cache invalidated successfully. + tags: + - cache + + '/cache': + delete: + summary: Purge all cache entries + description: > + Purge all cache entries in both `kong.cache` and `kong.core_cache`. + operationId: purgeAllCache + responses: + '204': + description: All cache entries purged successfully. + tags: + - cache servers: - description: Default Admin API URL url: '{protocol}://{hostname}:{port}{path}' @@ -7884,3 +8075,9 @@ tags:

Most core entities can be tagged via the tags attribute upon creation or modification. name: Tags + - description: | + Retreieve information about the status of data planes when Kong Gateway is configured in hybrid mode. + name: clustering + - description: | + Querying and managing cache entries. + name: cache