From 4d03f74bb5bd157fb8ee40e710815ae2cefc99c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hans=20H=C3=BCbner?= Date: Mon, 12 Sep 2022 12:24:01 +0000 Subject: [PATCH 1/4] docs(changelog) add 3.0.0 changes --- CHANGELOG.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dadd6b6662d6..12ebde3b425e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Table of Contents -- [3.0.0-alpha.1](#300-alpha1) +- [3.0.0](#300) - [2.8.1](#281) - [2.8.0](#280) - [2.7.1](#271) @@ -67,12 +67,18 @@ ## Unreleased -## [3.0.0-alpha.1] +## [3.0.0] -> Released 2022/08/23 +> Released 2022/09/12 -### Breaking Changes +This major release adds a new router written in Rust and a tracing API +that is compatible with the OpenTelemetry API spec. Furthermore, +various internal changes have been made to improve Kong's performance +and memory consumption. As it is a major release, users are advised +to review the list of braking changes to determine whether +configuration changes are needed when upgrading. +### Breaking Changes #### Deployment @@ -7412,7 +7418,7 @@ First version running with Cassandra. [Back to TOC](#table-of-contents) -[3.0.0-alpha.1]: https://github.com/Kong/kong/compare/2.8.1...3.0.0-alpha.1 +[3.0.0]: https://github.com/Kong/kong/compare/2.8.1...3.0.0 [2.8.1]: https://github.com/Kong/kong/compare/2.8.0...2.8.1 [2.8.0]: https://github.com/Kong/kong/compare/2.7.0...2.8.0 [2.7.1]: https://github.com/Kong/kong/compare/2.7.0...2.7.1 From f0c178cb3c92f0cc523d303201ada9bca56d5fd3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hans=20H=C3=BCbner?= Date: Mon, 12 Sep 2022 12:25:40 +0000 Subject: [PATCH 2/4] docs(COPYRIGHT) update copyright for 3.0.0 --- COPYRIGHT | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/COPYRIGHT b/COPYRIGHT index 4b587375289a..18471727205d 100644 --- a/COPYRIGHT +++ b/COPYRIGHT @@ -1812,7 +1812,8 @@ LuaRocks https://luarocks.org https://github.com/luarocks/luarocks/blob/master/COPYING -Copyright 2007-2018 Kepler Project. +Copyright 2007-2011, Kepler Project. +Copyright 2011-2022, the LuaRocks project authors. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal From 282149f4fd2e551eaa5b04d2621b7fd539b36c1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hans=20H=C3=BCbner?= Date: Mon, 12 Sep 2022 12:25:49 +0000 Subject: [PATCH 3/4] docs(kong-admin-api.yml) update Admin API definition for 3.0.0 --- kong-admin-api.yml | 864 +++++++++++++++++++++++---------------------- 1 file changed, 439 insertions(+), 425 deletions(-) diff --git a/kong-admin-api.yml b/kong-admin-api.yml index 7a7aed505881..53c4ef1f7c9b 100644 --- a/kong-admin-api.yml +++ b/kong-admin-api.yml @@ -1,257 +1,75 @@ -openapi: 3.1.0 +info: + contact: + url: https://github.com/Kong/kong + name: Kong + version: 3.0.0.0-enterprise-edition + title: Kong Admin API + summary: Kong RESTful Admin API for administration purposes. + description: " {{site.base_gateway}} comes with an **internal** RESTful Admin + API for administration purposes.\n Requests to the Admin API can be sent + to any node in the cluster, and Kong will\n keep the configuration consistent + across all nodes.\n\n - `8001` is the default port on which the Admin API + listens.\n - `8444` is the default port for HTTPS traffic to the Admin + API.\n\n This API is designed for internal use and provides full control + over Kong, so\n care should be taken when setting up Kong environments + to avoid undue public\n exposure of this API. See [this document][secure-admin-api] + for a discussion\n of methods to secure the Admin API.\n " + license: + url: https://github.com/Kong/kong/blob/master/LICENSE + name: Apache 2.0 components: schemas: - upstreams: - type: object - properties: - slots: - type: integer - default: 10000 - algorithm: - type: string - default: round-robin - hash_on: - type: string - default: none - hash_fallback: - type: string - default: none - hash_on_header: - type: string - hash_fallback_header: - type: string - hash_on_cookie: - type: string - hash_on_cookie_path: - type: string - default: / - hash_on_query_arg: - type: string - name: - type: string - hash_on_uri_capture: - type: string - client_certificate: - $ref: '#/components/schemas/certificates' - hash_fallback_uri_capture: - type: string - tags: - type: array - host_header: - type: string - id: - type: string - format: uuid - healthchecks: - type: array - default: - passive: - type: http - healthy: - successes: 0 - http_statuses: - - 200 - - 201 - - 202 - - 203 - - 204 - - 205 - - 206 - - 207 - - 208 - - 226 - - 300 - - 301 - - 302 - - 303 - - 304 - - 305 - - 306 - - 307 - - 308 - unhealthy: - tcp_failures: 0 - timeouts: 0 - http_failures: 0 - http_statuses: - - 429 - - 500 - - 503 - active: - timeout: 1 - type: http - concurrency: 10 - http_path: / - healthy: - successes: 0 - interval: 0 - http_statuses: - - 200 - - 302 - https_verify_certificate: true - unhealthy: - tcp_failures: 0 - timeouts: 0 - http_failures: 0 - interval: 0 - http_statuses: - - 429 - - 404 - - 500 - - 501 - - 502 - - 503 - - 504 - - 505 - created_at: - type: integer - format: int32 - hash_fallback_query_arg: - type: string - required: - - name - clustering_data_planes: - type: object - properties: - ip: - type: string - sync_status: - type: string - default: unknown - hostname: - type: string - version: - type: string - last_seen: - type: integer - format: int32 - config_hash: - type: string - id: - type: string - required: - - id - - ip - - hostname - - sync_status - parameters: - type: object - properties: - key: - type: string - created_at: - type: integer - format: int32 - value: - type: string - required: - - key - - value tags: type: object properties: entity_name: type: string - tag: - type: string entity_id: type: string + tag: + type: string required: - tag - entity_name - entity_id - vaults: - type: object - properties: - config: - type: array - description: - type: string - updated_at: - type: integer - format: int32 - tags: - type: array - created_at: - type: integer - format: int32 - name: - type: string - prefix: - type: string - id: - type: string - format: uuid - required: - - prefix - - name - targets: + services: type: object properties: - upstream: - $ref: '#/components/schemas/upstreams' - target: + path: type: string - tags: - type: array - weight: - type: integer - default: 100 - created_at: - type: number - format: float id: type: string format: uuid - required: - - upstream - - target - workspaces: - type: object - properties: - config: - type: array - meta: - type: array - comment: - type: string - name: - type: string created_at: type: integer format: int32 - id: - type: string - format: uuid - required: - - name - services: - type: object - properties: + updated_at: + type: integer + format: int32 protocol: type: string default: http - tags: + ca_certificates: type: array - path: + host: type: string - id: + port: + type: integer + default: 80 + name: type: string - format: uuid retries: type: integer default: 5 connect_timeout: type: integer default: 60000 - host: - type: string write_timeout: type: integer default: 60000 - port: + read_timeout: type: integer - default: 80 + default: 60000 client_certificate: $ref: '#/components/schemas/certificates' tls_verify: @@ -260,84 +78,93 @@ components: type: integer nullable: true default: ~ + tags: + type: array enabled: type: boolean default: true - ca_certificates: - type: array - name: - type: string - read_timeout: - type: integer - default: 60000 - created_at: - type: integer - format: int32 - updated_at: - type: integer - format: int32 required: - protocol - host - port - enabled - routes: + workspaces: type: object properties: - sources: + id: + type: string + format: uuid + config: type: array + comment: + type: string + meta: + type: array + created_at: + type: integer + format: int32 + name: + type: string + required: + - name + routes: + type: object + properties: tags: type: array id: type: string format: uuid + created_at: + type: integer + format: int32 + updated_at: + type: integer + format: int32 + snis: + type: array + name: + type: string + regex_priority: + type: integer + default: 0 strip_path: type: boolean default: true path_handling: type: string default: v0 + service: + $ref: '#/components/schemas/services' preserve_host: type: boolean default: false + destinations: + type: array request_buffering: type: boolean default: true + headers: + type: array response_buffering: type: boolean default: true - regex_priority: - type: integer - default: 0 - service: - $ref: '#/components/schemas/services' - https_redirect_status_code: - type: integer - default: 426 - name: - type: string + methods: + type: array + paths: + type: array protocols: type: array default: - http - https - snis: - type: array - destinations: + https_redirect_status_code: + type: integer + default: 426 + sources: type: array - paths: [] hosts: type: array - headers: - type: array - methods: - type: array - created_at: - type: integer - format: int32 - updated_at: - type: integer - format: int32 required: - protocols - https_redirect_status_code @@ -348,239 +175,403 @@ components: consumers: type: object properties: - username: + type: + type: integer + default: 0 + id: + type: string + format: uuid + username_lower: type: string + created_at: + type: integer + format: int32 + tags: + type: array custom_id: type: string + username: + type: string + required: + - type + plugins: + type: object + properties: tags: type: array + id: + type: string + format: uuid + ordering: [] + config: + type: array + enabled: + type: boolean + default: true created_at: type: integer format: int32 + service: + nullable: true + $ref: '#/components/schemas/services' + default: ~ + protocols: + type: array + enum: + - http + - https + - tcp + - tls + - udp + - grpc + - grpcs + default: + - grpc + - grpcs + - http + - https + consumer: + nullable: true + $ref: '#/components/schemas/consumers' + default: ~ + route: + nullable: true + $ref: '#/components/schemas/routes' + default: ~ + name: + type: string + required: + - name + - protocols + - enabled + certificates: + type: object + properties: + tags: + type: array id: type: string - format: uuid - required: [] - plugins: + format: uuid + cert_alt: + type: string + created_at: + type: integer + format: int32 + key_alt: + type: string + cert: + type: string + key: + type: string + required: + - cert + - key + ca_certificates: + type: object + properties: + cert_digest: + type: string + id: + type: string + format: uuid + created_at: + type: integer + format: int32 + cert: + type: string + tags: + type: array + required: + - cert + snis: + type: object + properties: + tags: + type: array + id: + type: string + format: uuid + created_at: + type: integer + format: int32 + certificate: + $ref: '#/components/schemas/certificates' + name: + type: string + required: + - name + - certificate + upstreams: + type: object + properties: + hash_on_uri_capture: + type: string + id: + type: string + format: uuid + hash_fallback_uri_capture: + type: string + created_at: + type: integer + format: int32 + healthchecks: + type: array + default: + passive: + type: http + healthy: + successes: 0 + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + tcp_failures: 0 + timeouts: 0 + http_failures: 0 + active: + type: http + http_path: / + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + interval: 0 + successes: 0 + unhealthy: + tcp_failures: 0 + timeouts: 0 + http_failures: 0 + interval: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeout: 1 + concurrency: 10 + slots: + type: integer + default: 10000 + algorithm: + type: string + default: round-robin + name: + type: string + hash_on: + type: string + default: none + hash_fallback: + type: string + default: none + hash_on_header: + type: string + hash_fallback_header: + type: string + hash_on_cookie: + type: string + client_certificate: + $ref: '#/components/schemas/certificates' + hash_on_cookie_path: + type: string + default: / + hash_on_query_arg: + type: string + host_header: + type: string + hash_fallback_query_arg: + type: string + tags: + type: array + required: + - name + targets: + type: object + properties: + tags: + type: array + id: + type: string + format: uuid + created_at: + type: number + format: float + upstream: + $ref: '#/components/schemas/upstreams' + target: + type: string + weight: + type: integer + default: 100 + required: + - upstream + - target + vaults: type: object properties: - service: - default: ~ - nullable: true - $ref: '#/components/schemas/services' tags: type: array - name: - type: string id: type: string format: uuid - consumer: - default: ~ - nullable: true - $ref: '#/components/schemas/consumers' - enabled: - type: boolean - default: true config: type: array - route: - default: ~ - nullable: true - $ref: '#/components/schemas/routes' created_at: type: integer format: int32 - protocols: - type: array - enum: - - http - - https - - tcp - - tls - - udp - - grpc - - grpcs - default: - - grpc - - grpcs - - http - - https + prefix: + type: string + updated_at: + type: integer + format: int32 + description: + type: string + name: + type: string required: + - prefix - name - - protocols - - enabled - certificates: + parameters: type: object properties: - key_alt: - type: string - cert_alt: - type: string - tags: - type: array - key: - type: string - cert: - type: string created_at: type: integer format: int32 - id: + value: + type: string + key: type: string - format: uuid required: - - cert - key - ca_certificates: + - value + clustering_data_planes: type: object properties: - tags: - type: array id: type: string - format: uuid - cert: - type: string - created_at: + last_seen: type: integer format: int32 - cert_digest: + config_hash: type: string - required: - - cert - snis: - type: object - properties: - tags: - type: array - certificate: - $ref: '#/components/schemas/certificates' - name: + hostname: type: string - created_at: - type: integer - format: int32 - id: + ip: + type: string + sync_status: + type: string + default: unknown + version: type: string - format: uuid required: - - name - - certificate -info: - description: " {{site.base_gateway}} comes with an **internal** RESTful Admin - API for administration purposes.\n Requests to the Admin API can be sent - to any node in the cluster, and Kong will\n keep the configuration consistent - across all nodes.\n\n - `8001` is the default port on which the Admin API - listens.\n - `8444` is the default port for HTTPS traffic to the Admin - API.\n\n This API is designed for internal use and provides full control - over Kong, so\n care should be taken when setting up Kong environments - to avoid undue public\n exposure of this API. See [this document][secure-admin-api] - for a discussion\n of methods to secure the Admin API.\n " - contact: - url: https://github.com/Kong/kong - name: Kong - version: 3.0.0 - title: Kong Admin API - license: - url: https://github.com/Kong/kong/blob/master/LICENSE - name: Apache 2.0 - summary: Kong RESTful Admin API for administration purposes. + - id + - ip + - hostname + - sync_status paths: + /timers: + get: + summary: Retrieve runtime debugging info of Kong's timers /cache/{key}: - get: [] delete: description: This method is not available when using DB-less mode. + get: [] /upstreams/{upstreams}/targets/all: get: summary: List all Targets - /: + /config: + post: + description: This method is only available when using DB-less mode. get: - summary: Retrieve node information - /upstreams/{upstreams}/targets/{targets}/{address}/unhealthy: - put: - description: This method is not available when using DB-less mode. - /upstreams/{upstreams}/targets: + description: This method is only available when using DB-less mode. + /consumers: get: [] - post: - description: This method is not available when using DB-less mode. - /routes/{routes}/plugins/{plugins}: - patch: - description: This method is not available when using DB-less mode. - /certificates/{certificates}/snis/{snis}: [] /upstreams/{upstreams}/targets/{targets}: - delete: - summary: Delete Target + put: description: This method is not available when using DB-less mode. patch: + description: This method is not available when using DB-less mode. summary: Update Target + delete: description: This method is not available when using DB-less mode. + summary: Delete Target get: [] + /upstreams/{upstreams}/targets/{targets}/healthy: put: description: This method is not available when using DB-less mode. - /upstreams/{upstreams}/targets/{targets}/unhealthy: - put: + summary: Set target as healthy + /plugins/{plugins}: + patch: description: This method is not available when using DB-less mode. - /consumers: - get: [] - /services/{services}/plugins: + /plugins: post: description: This method is not available when using DB-less mode. - /services/{services}/plugins/{plugins}: - patch: - description: This method is not available when using DB-less mode. /upstreams/{upstreams}/targets/{targets}/{address}/healthy: put: description: This method is not available when using DB-less mode. - /targets/{targets}: [] - /consumers/{consumers}/plugins: - post: - description: This method is not available when using DB-less mode. - /consumers/{consumers}/plugins/{plugins}: - patch: - description: This method is not available when using DB-less mode. - /schemas/{db_entity_name}/validate: + summary: Set target address as healthy + /services/{services}/plugins: post: - summary: Validate a configuration against a schema description: This method is not available when using DB-less mode. - /targets/{targets}/upstream: [] - /schemas/{name}: - get: - summary: Retrieve Entity Schema + /upstreams/:upstreams/targets/:targets/:address/unhealthy: + put: [] /tags/{tags}: get: summary: ' List entity IDs by tag ' - /schemas/plugins/validate: - post: - summary: Validate a plugin configuration against the schema - description: This method is not available when using DB-less mode. - /snis/{snis}/certificate: [] - /plugins/{plugins}: - patch: - description: This method is not available when using DB-less mode. - /schemas/plugins/{name}: - get: - summary: Retrieve Plugin Schema /plugins/enabled: get: summary: Retrieve Enabled Plugins - /plugins/schema/{name}: + /upstreams/{upstreams}/targets/{targets}/unhealthy: + put: + description: This method is not available when using DB-less mode. + summary: Set target as unhealthy + /routes/{routes}/plugins: + post: + description: This method is not available when using DB-less mode. + /consumers/{consumers}/plugins: [] + /consumers/:consumers/plugins/:plugins: + patch: [] + /upstreams/:upstreams/targets: + post: [] get: [] + /endpoints: + get: + summary: List available endpoints + /schemas/plugins/validate: + post: [] + /snis/{snis}/certificate: [] /upstreams/{upstreams}/health: get: summary: Show Upstream health for node - /plugins: - post: - description: This method is not available when using DB-less mode. - /upstreams/{upstreams}/targets/{targets}/healthy: - put: - description: This method is not available when using DB-less mode. - /status: + /consumers/{consumers}: [] + /: get: - summary: Retrieve node status - /cache: - delete: - description: This method is not available when using DB-less mode. + summary: Retrieve node information /certificates/{certificates}: patch: description: This method is not available when using DB-less mode. @@ -588,25 +579,48 @@ paths: description: This method is not available when using DB-less mode. get: [] /certificates/{certificates}/snis: [] - /targets: [] - /routes/{routes}/plugins: + /auth: + delete: + description: This method is not available when using DB-less mode. + get: [] + /certificates: post: description: This method is not available when using DB-less mode. + /plugins/schema/{name}: + get: [] /clustering/data-planes: [] - /clustering/status: [] - /timers: - get: - summary: Retrieve runtime debugging info of Kong's timers - /config: + /userinfo: + get: [] + /status: get: - description: This method is only available when using DB-less mode. + summary: Retrieve node status + /schemas/{db_entity_name}/validate: post: - description: This method is only available when using DB-less mode. - /endpoints: + description: This method is not available when using DB-less mode. + summary: Validate a configuration against a schema + /certificates/{certificates}/snis/{snis}: [] + /targets/{targets}: [] + /targets/{targets}/upstream: [] + /schemas/{name}: get: - summary: List available endpoints + summary: Retrieve Entity Schema + /services/{services}/plugins/{plugins}: + patch: + description: This method is not available when using DB-less mode. + /routes/{routes}/plugins/{plugins}: + patch: + description: This method is not available when using DB-less mode. + /clustering/status: [] + /targets: [] + /schemas/plugins/{name}: + get: + summary: Retrieve Plugin Schema + /cache: + delete: + description: This method is not available when using DB-less mode. servers: -- url: http://localhost:8001 - description: 8001 is the default port on which the Admin API listens. -- url: https://localhost:8444 - description: 8444 is the default port for HTTPS traffic to the Admin API. +- description: 8001 is the default port on which the Admin API listens. + url: http://localhost:8001 +- description: 8444 is the default port for HTTPS traffic to the Admin API. + url: https://localhost:8444 +openapi: 3.1.0 From 5039ca65acc465261c47be18dfbd7ec6df1b3fd9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hans=20H=C3=BCbner?= Date: Mon, 12 Sep 2022 12:25:57 +0000 Subject: [PATCH 4/4] release: 3.0.0