Kong 2.0 升级指南
Kong 2.0 升级指南
原文地址：https://docs.konghq.com/2.0.x/upgrading/ （不能保证所有的翻译都是准确无误的，所有如有翻译的不准确或错误之处，请一定记得查看原文，并欢迎留言指出）
注意: 下面是2.0.x的升级指南。如果您试图升级到早期版本的Kong，请阅读upgrade.md文件。
本指南将告诉您在升级时应该注意的重大更改，并指导您完成正确的步骤顺序，以便在不同的升级场景中实现无停机迁移。
升级到 2.0.0
Kong坚持语义化版本，区分“主要”、“次要”和“补丁”版本。升级路径与您要迁移的前一个版本不同。升级到2.0。是一个主要的版本升级，所以要注意在CHANGELOG.md文档中列出的任何重大更改。
1. 依赖项
如果您正在使用已提供的二进制包，那么所有必要的依赖项都已绑定，可以跳过此部分。
如果您是手动构建您的依赖项，那么自上一个版本以来有一些更改，因此您将需要使用最新的补丁重新构建它们。
所需的OpenResty版本是1.15.8.2，其中包含的OpenResty补丁集已经改变，包括最新版本的lua-kong-nginx-module。我们的kong-build-tools库允许您轻松地使用必要的补丁和模块构建OpenResty。
对于GO的支持，你还需要Kong go-pluginserver。这是与Kong二进制包绑定的，如果在Kong的配置中启用Go插件支持，它会自动启动。注意，用于编译任何Go插件的Go版本需要匹配go-pluginserver的Go版本。可以检查用于构建运行go-pluginserver版本的gopluginserver二进制文件的Go版本。
2. 重大修改项
Kong 2.0.0包含了对Kong 1.x的一些重大更改，且都和移除Service Mesh相关：
- 删除了Service Mesh支持：在Kong 1.4中已经被弃用了，并且默认设置了，现在代码已经在2.0中直接去掉。对于Service Mesh，我们现在有了Kuma，这是从一开始就为Mesh模式设计的，所以我们对移除Kong的本地Service Mesh功能感到放心，并专注于其作为网关的核心功能。
- 作为服务网格移除的一部分，无服务代理被移除。在创建用于无服务器插件(如
aws-lambda或request-termination)的路由时，您仍然可以设置service = null。 - 移除
origins属性。 - 移除
transparent属性。 - 移除了用于服务网格的 Sidecar Injector plugin 插件。
- NGINX 配置文件改变：这意味着如果您使用自定义模板，则需要对其进行更新。改进了流模式支持，使Nginx注入系统更加强大，这样定制模板就不那么必要了。下面的差异中详细介绍了这些变化。
- 警告：注意
kong_cacheshm被分割成两个shm:kong_core_cache和kong_cache。如果使用自定义Nginx模板，请确保定义了核心缓存共享字典，包括无数据库模式阴影定义。这两个缓存值都依赖于已经存在的mem_cache_size配置选项来设置它们的大小，因此当从以前的Kong版本升级时，如果不调整该值，缓存内存消耗可能会翻倍。
Nginx 配置改变如下：
diff --git a/kong/templates/nginx_kong.lua b/kong/templates/nginx_kong.lua
index 5c6c1db03..6b4b4a818 100644
--- a/kong/templates/nginx_kong.lua
+++ b/kong/templates/nginx_kong.lua
@@ -5,52 +5,46 @@ server_tokens off;
> if anonymous_reports then
$
> end
-
error_log $ $;
-> if nginx_optimizations then
->-- send_timeout 60s; # default value
->-- keepalive_timeout 75s; # default value
->-- client_body_timeout 60s; # default value
->-- client_header_timeout 60s; # default value
->-- tcp_nopush on; # disabled until benchmarked
->-- proxy_buffer_size 128k; # disabled until benchmarked
->-- proxy_buffers 4 256k; # disabled until benchmarked
->-- proxy_busy_buffers_size 256k; # disabled until benchmarked
->-- reset_timedout_connection on; # disabled until benchmarked
-> end
-
-client_max_body_size $;
-proxy_ssl_server_name on;
-underscores_in_headers on;
-
lua_package_path '$;;';
lua_package_cpath '$;;';
lua_socket_pool_size $;
+lua_socket_log_errors off;
lua_max_running_timers 4096;
lua_max_pending_timers 16384;
+lua_ssl_verify_depth $;
+> if lua_ssl_trusted_certificate then
+lua_ssl_trusted_certificate '$';
+> end
+
lua_shared_dict kong 5m;
+lua_shared_dict kong_locks 8m;
+lua_shared_dict kong_healthchecks 5m;
+lua_shared_dict kong_process_events 5m;
+lua_shared_dict kong_cluster_events 5m;
+lua_shared_dict kong_rate_limiting_counters 12m;
+lua_shared_dict kong_core_db_cache $;
+lua_shared_dict kong_core_db_cache_miss 12m;
lua_shared_dict kong_db_cache $;
-> if database == "off" then
-lua_shared_dict kong_db_cache_2 $;
-> end
lua_shared_dict kong_db_cache_miss 12m;
> if database == "off" then
+lua_shared_dict kong_core_db_cache_2 $;
+lua_shared_dict kong_core_db_cache_miss_2 12m;
+lua_shared_dict kong_db_cache_2 $;
lua_shared_dict kong_db_cache_miss_2 12m;
> end
-lua_shared_dict kong_locks 8m;
-lua_shared_dict kong_process_events 5m;
-lua_shared_dict kong_cluster_events 5m;
-lua_shared_dict kong_healthchecks 5m;
-lua_shared_dict kong_rate_limiting_counters 12m;
> if database == "cassandra" then
lua_shared_dict kong_cassandra 5m;
> end
-lua_socket_log_errors off;
-> if lua_ssl_trusted_certificate then
-lua_ssl_trusted_certificate '$';
+> if role == "control_plane" then
+lua_shared_dict kong_clustering 5m;
+> end
+
+underscores_in_headers on;
+> if ssl_ciphers then
+ssl_ciphers $;
> end
-lua_ssl_verify_depth $;
# injected nginx_http_* directives
> for _, el in ipairs(nginx_http_directives) do
@@ -66,61 +60,47 @@ init_worker_by_lua_block {
Kong.init_worker()
}
-
-> if #proxy_listeners > 0 then
+> if (role == "traditional" or role == "data_plane") and #proxy_listeners > 0 then
upstream kong_upstream {
server 0.0.0.1;
balancer_by_lua_block {
Kong.balancer()
}
-# injected nginx_http_upstream_* directives
-> for _, el in ipairs(nginx_http_upstream_directives) do
+ # injected nginx_upstream_* directives
+> for _, el in ipairs(nginx_upstream_directives) do
$(el.name) $(el.value);
> end
}
server {
server_name kong;
-> for i = 1, #proxy_listeners do
- listen $(proxy_listeners[i].listener);
+> for _, entry in ipairs(proxy_listeners) do
+ listen $(entry.listener);
> end
+
error_page 400 404 408 411 412 413 414 417 494 /kong_error_handler;
error_page 500 502 503 504 /kong_error_handler;
access_log $;
error_log $ $;
- client_body_buffer_size $;
-
> if proxy_ssl_enabled then
ssl_certificate $;
ssl_certificate_key $;
+ ssl_session_cache shared:SSL:10m;
ssl_certificate_by_lua_block {
Kong.ssl_certificate()
}
-
- ssl_session_cache shared:SSL:10m;
- ssl_session_timeout 10m;
- ssl_prefer_server_ciphers on;
- ssl_ciphers $;
-> end
-
-> if client_ssl then
- proxy_ssl_certificate $;
- proxy_ssl_certificate_key $;
-> end
-
- real_ip_header $;
- real_ip_recursive $;
-> for i = 1, #trusted_ips do
- set_real_ip_from $(trusted_ips[i]);
> end
# injected nginx_proxy_* directives
> for _, el in ipairs(nginx_proxy_directives) do
$(el.name) $(el.value);
> end
+> for i = 1, #trusted_ips do
+ set_real_ip_from $(trusted_ips[i]);
+> end
rewrite_by_lua_block {
Kong.rewrite()
@@ -171,43 +151,93 @@ server {
proxy_pass_header Server;
proxy_pass_header Date;
proxy_ssl_name $upstream_host;
+ proxy_ssl_server_name on;
+> if client_ssl then
+ proxy_ssl_certificate $;
+ proxy_ssl_certificate_key $;
+> end
proxy_pass $upstream_scheme://kong_upstream$upstream_uri;
}
location @grpc {
internal;
+ default_type '';
set $kong_proxy_mode 'grpc';
+ grpc_set_header TE $upstream_te;
grpc_set_header Host $upstream_host;
grpc_set_header X-Forwarded-For $upstream_x_forwarded_for;
grpc_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
grpc_set_header X-Forwarded-Host $upstream_x_forwarded_host;
grpc_set_header X-Forwarded-Port $upstream_x_forwarded_port;
grpc_set_header X-Real-IP $remote_addr;
-
+ grpc_pass_header Server;
+ grpc_pass_header Date;
grpc_pass grpc://kong_upstream;
}
location @grpcs {
internal;
+ default_type '';
set $kong_proxy_mode 'grpc';
+ grpc_set_header TE $upstream_te;
grpc_set_header Host $upstream_host;
grpc_set_header X-Forwarded-For $upstream_x_forwarded_for;
grpc_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
grpc_set_header X-Forwarded-Host $upstream_x_forwarded_host;
grpc_set_header X-Forwarded-Port $upstream_x_forwarded_port;
grpc_set_header X-Real-IP $remote_addr;
-
+ grpc_pass_header Server;
+ grpc_pass_header Date;
+ grpc_ssl_name $upstream_host;
+ grpc_ssl_server_name on;
+> if client_ssl then
+ grpc_ssl_certificate $;
+ grpc_ssl_certificate_key $;
+> end
grpc_pass grpcs://kong_upstream;
}
+ location = /kong_buffered_http {
+ internal;
+ default_type '';
+ set $kong_proxy_mode 'http';
+
+ rewrite_by_lua_block {;}
+ access_by_lua_block {;}
+ header_filter_by_lua_block {;}
+ body_filter_by_lua_block {;}
+ log_by_lua_block {;}
+
+ proxy_http_version 1.1;
+ proxy_set_header TE $upstream_te;
+ proxy_set_header Host $upstream_host;
+ proxy_set_header Upgrade $upstream_upgrade;
+ proxy_set_header Connection $upstream_connection;
+ proxy_set_header X-Forwarded-For $upstream_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
+ proxy_set_header X-Forwarded-Host $upstream_x_forwarded_host;
+ proxy_set_header X-Forwarded-Port $upstream_x_forwarded_port;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_pass_header Server;
+ proxy_pass_header Date;
+ proxy_ssl_name $upstream_host;
+ proxy_ssl_server_name on;
+> if client_ssl then
+ proxy_ssl_certificate $;
+ proxy_ssl_certificate_key $;
+> end
+ proxy_pass $upstream_scheme://kong_upstream$upstream_uri;
+ }
+
location = /kong_error_handler {
internal;
+ default_type '';
+
uninitialized_variable_warn off;
rewrite_by_lua_block {;}
-
access_by_lua_block {;}
content_by_lua_block {
@@ -215,13 +245,13 @@ server {
}
}
}
-> end
+> end -- (role == "traditional" or role == "data_plane") and #proxy_listeners > 0
-> if #admin_listeners > 0 then
+> if (role == "control_plane" or role == "traditional") and #admin_listeners > 0 then
server {
server_name kong_admin;
-> for i = 1, #admin_listeners do
- listen $(admin_listeners[i].listener);
+> for _, entry in ipairs(admin_listeners) do
+ listen $(entry.listener);
> end
access_log $;
@@ -233,11 +263,7 @@ server {
> if admin_ssl_enabled then
ssl_certificate $;
ssl_certificate_key $;
-
- ssl_session_cache shared:SSL:10m;
- ssl_session_timeout 10m;
- ssl_prefer_server_ciphers on;
- ssl_ciphers $;
+ ssl_session_cache shared:AdminSSL:10m;
> end
# injected nginx_admin_* directives
@@ -265,20 +291,20 @@ server {
return 200 'User-agent: *\nDisallow: /';
}
}
-> end
+> end -- (role == "control_plane" or role == "traditional") and #admin_listeners > 0
> if #status_listeners > 0 then
server {
server_name kong_status;
-> for i = 1, #status_listeners do
- listen $(status_listeners[i].listener);
+> for _, entry in ipairs(status_listeners) do
+ listen $(entry.listener);
> end
access_log $;
error_log $ $;
- # injected nginx_http_status_* directives
-> for _, el in ipairs(nginx_http_status_directives) do
+ # injected nginx_status_* directives
+> for _, el in ipairs(nginx_status_directives) do
$(el.name) $(el.value);
> end
@@ -303,4 +329,26 @@ server {
}
}
> end
+
+> if role == "control_plane" then
+server {
+ server_name kong_cluster_listener;
+> for _, entry in ipairs(cluster_listeners) do
+ listen $(entry.listener) ssl;
+> end
+
+ access_log off;
+
+ ssl_verify_client optional_no_ca;
+ ssl_certificate $;
+ ssl_certificate_key $;
+ ssl_session_cache shared:ClusterSSL:10m;
+
+ location = /v1/outlet {
+ content_by_lua_block {
+ Kong.serve_cluster_listener()
+ }
+ }
+}
+> end -- role == "control_plane"
]]3. 建议升级路径
从0.x升级到2.0.0
Kong 2.0.0支持迁移的最低版本是1.0.0。如果您是从低于0.14.1的版本迁移，那么首先需要迁移到0.14.1。然后，如果是从0.14.1开始迁移，请先升级到到1.5.0。
从0.14.1升级到1.5.0的步骤与从0.14.1升级到Kong 1.0的步骤相同。请遵循Kong 1.0建议升级路径中的“从0.14迁移步骤”中描述的步骤，并添加kong migrations migrate-apis命令，您可以使用该命令迁移保留apis配置。
当迁移到1.5.0之后，可以按照下面一节中的说明迁移到2.0.0。
从1.0.0 - 1.5.0 升级到 2.0.0
Kong 2.0.0支持无停机迁移模型。这意味着在迁移过程中，您将运行两个Kong集群，共享相同的数据库。(这有时被称为蓝/绿迁移模型。)
迁移的设计使得不需要完全复制数据。但这也意味着它们的设计方式使得新版Kong能够在迁移过程中使用数据，并且要以一种方式来完成它，使旧的Kong集群能够一直工作，直到它最终下线。由于这个原因，整个迁移现在分成两个步骤，通过命令kong migrations up(只执行非破性操作)和kong migrations finish(将数据库置于kong 2.0.0的最终预期状态)执行。
- 下载2.0.0，并将其配置为指向与旧集群(1.0到1.5)相同的数据存储。运行
kong migration up。 - 一旦它完成运行，旧集群和新集群(2.0.0)现在可以在同一个数据存储上同时运行。开始供应2.0.0节点，但还不使用它们的管理API。如果需要执行管理API请求，应该对旧集群的节点执行这些请求。其原因是为了防止新集群生成旧集群无法识别的数据。
- 逐渐将流量从旧节点转移到2.0.0集群中。监控你的流程以确保一切顺利。
- 当您的流量完全迁移到2.0.0集群时，下线您的旧节点。
- 在2.0.0集群中运行:
kong migration finish。从现在起，将不能在旧集群中启动指向相同数据存储的节点。只有在确信迁移成功时才运行此命令。从现在开始，您可以安全地向2.0.0节点发出管理API请求。
在新的数据存储上安装2.0.0
下面的命令应该用于从新的数据存储准备新的2.0.0集群:
$ kong migrations bootstrap [-c config]
$ kong start [-c config]编辑于 2021-03-31 10:19
