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_cache shm被分割成两个shm: kong_core_cache和kong_cache。如果使用自定义Nginx模板，请确保定义了核心缓存共享字典，包括无数据库模式阴影定义。这两个缓存值都依赖于已经存在的mem_cache_size配置选项来设置它们的大小，因此当从以前的Kong版本升级时，如果不调整该值，缓存内存消耗可能会翻倍。

Nginx 配置改变如下：

  1. diff --git a/kong/templates/nginx_kong.lua b/kong/templates/nginx_kong.lua
  2. index 5c6c1db03..6b4b4a818 100644
  3. --- a/kong/templates/nginx_kong.lua
  4. +++ b/kong/templates/nginx_kong.lua
  5. @@ -5,52 +5,46 @@ server_tokens off;
  6.  > if anonymous_reports then
  7.  $
  8.  > end
  9. -
  10.  error_log $ $;
  12. -> if nginx_optimizations then
  13. ->-- send_timeout 60s;          # default value
  14. ->-- keepalive_timeout 75s;     # default value
  15. ->-- client_body_timeout 60s;   # default value
  16. ->-- client_header_timeout 60s; # default value
  17. ->-- tcp_nopush on;             # disabled until benchmarked
  18. ->-- proxy_buffer_size 128k;    # disabled until benchmarked
  19. ->-- proxy_buffers 4 256k;      # disabled until benchmarked
  20. ->-- proxy_busy_buffers_size 256k; # disabled until benchmarked
  21. ->-- reset_timedout_connection on; # disabled until benchmarked
  22. -> end
  23. -
  24. -client_max_body_size $;
  25. -proxy_ssl_server_name on;
  26. -underscores_in_headers on;
  27. -
  28.  lua_package_path       '$;;';
  29.  lua_package_cpath      '$;;';
  30.  lua_socket_pool_size   $;
  31. +lua_socket_log_errors  off;
  32.  lua_max_running_timers 4096;
  33.  lua_max_pending_timers 16384;
  34. +lua_ssl_verify_depth   $;
  35. +> if lua_ssl_trusted_certificate then
  36. +lua_ssl_trusted_certificate '$';
  37. +> end
  38. +
  39.  lua_shared_dict kong                        5m;
  40. +lua_shared_dict kong_locks                  8m;
  41. +lua_shared_dict kong_healthchecks           5m;
  42. +lua_shared_dict kong_process_events         5m;
  43. +lua_shared_dict kong_cluster_events         5m;
  44. +lua_shared_dict kong_rate_limiting_counters 12m;
  45. +lua_shared_dict kong_core_db_cache          $;
  46. +lua_shared_dict kong_core_db_cache_miss     12m;
  47.  lua_shared_dict kong_db_cache               $;
  48. -> if database == "off" then
  49. -lua_shared_dict kong_db_cache_2     $;
  50. -> end
  51.  lua_shared_dict kong_db_cache_miss          12m;
  52.  > if database == "off" then
  53. +lua_shared_dict kong_core_db_cache_2        $;
  54. +lua_shared_dict kong_core_db_cache_miss_2   12m;
  55. +lua_shared_dict kong_db_cache_2             $;
  56.  lua_shared_dict kong_db_cache_miss_2        12m;
  57.  > end
  58. -lua_shared_dict kong_locks          8m;
  59. -lua_shared_dict kong_process_events 5m;
  60. -lua_shared_dict kong_cluster_events 5m;
  61. -lua_shared_dict kong_healthchecks   5m;
  62. -lua_shared_dict kong_rate_limiting_counters 12m;
  63.  > if database == "cassandra" then
  64.  lua_shared_dict kong_cassandra              5m;
  65.  > end
  66. -lua_socket_log_errors off;
  67. -> if lua_ssl_trusted_certificate then
  68. -lua_ssl_trusted_certificate '$';
  69. +> if role == "control_plane" then
  70. +lua_shared_dict kong_clustering             5m;
  71. +> end
  72. +
  73. +underscores_in_headers on;
  74. +> if ssl_ciphers then
  75. +ssl_ciphers $;
  76.  > end
  77. -lua_ssl_verify_depth $;
  79.  # injected nginx_http_* directives
  80.  > for _, el in ipairs(nginx_http_directives) do
  81. @@ -66,61 +60,47 @@ init_worker_by_lua_block {
  82.      Kong.init_worker()
  83.  }
  85. -
  86. -> if #proxy_listeners > 0 then
  87. +> if (role == "traditional" or role == "data_plane") and #proxy_listeners > 0 then
  88.  upstream kong_upstream {
  89.      server 0.0.0.1;
  90.      balancer_by_lua_block {
  91.          Kong.balancer()
  92.      }
  94. -# injected nginx_http_upstream_* directives
  95. -> for _, el in ipairs(nginx_http_upstream_directives) do
  96. +    # injected nginx_upstream_* directives
  97. +> for _, el in ipairs(nginx_upstream_directives) do
  98.      $(el.name) $(el.value);
  99.  > end
  100.  }
  102.  server {
  103.      server_name kong;
  104. -> for i = 1, #proxy_listeners do
  105. -    listen $(proxy_listeners[i].listener);
  106. +> for _, entry in ipairs(proxy_listeners) do
  107. +    listen $(entry.listener);
  108.  > end
  109. +
  110.      error_page 400 404 408 411 412 413 414 417 494 /kong_error_handler;
  111.      error_page 500 502 503 504                     /kong_error_handler;
  113.      access_log $;
  114.      error_log  $ $;
  116. -    client_body_buffer_size $;
  117. -
  118.  > if proxy_ssl_enabled then
  119.      ssl_certificate     $;
  120.      ssl_certificate_key $;
  121. +    ssl_session_cache   shared:SSL:10m;
  122.      ssl_certificate_by_lua_block {
  123.          Kong.ssl_certificate()
  124.      }
  125. -
  126. -    ssl_session_cache shared:SSL:10m;
  127. -    ssl_session_timeout 10m;
  128. -    ssl_prefer_server_ciphers on;
  129. -    ssl_ciphers $;
  130. -> end
  131. -
  132. -> if client_ssl then
  133. -    proxy_ssl_certificate $;
  134. -    proxy_ssl_certificate_key $;
  135. -> end
  136. -
  137. -    real_ip_header     $;
  138. -    real_ip_recursive  $;
  139. -> for i = 1, #trusted_ips do
  140. -    set_real_ip_from   $(trusted_ips[i]);
  141.  > end
  143.      # injected nginx_proxy_* directives
  144.  > for _, el in ipairs(nginx_proxy_directives) do
  145.      $(el.name) $(el.value);
  146.  > end
  147. +> for i = 1, #trusted_ips do
  148. +    set_real_ip_from  $(trusted_ips[i]);
  149. +> end
  151.      rewrite_by_lua_block {
  152.          Kong.rewrite()
  153. @@ -171,43 +151,93 @@ server {
  154.          proxy_pass_header     Server;
  155.          proxy_pass_header     Date;
  156.          proxy_ssl_name        $upstream_host;
  157. +        proxy_ssl_server_name on;
  158. +> if client_ssl then
  159. +        proxy_ssl_certificate $;
  160. +        proxy_ssl_certificate_key $;
  161. +> end
  162.          proxy_pass            $upstream_scheme://kong_upstream$upstream_uri;
  163.      }
  165.      location @grpc {
  166.          internal;
  167. +        default_type         '';
  168.          set $kong_proxy_mode 'grpc';
  170. +        grpc_set_header      TE                $upstream_te;
  171.          grpc_set_header      Host              $upstream_host;
  172.          grpc_set_header      X-Forwarded-For   $upstream_x_forwarded_for;
  173.          grpc_set_header      X-Forwarded-Proto $upstream_x_forwarded_proto;
  174.          grpc_set_header      X-Forwarded-Host  $upstream_x_forwarded_host;
  175.          grpc_set_header      X-Forwarded-Port  $upstream_x_forwarded_port;
  176.          grpc_set_header      X-Real-IP         $remote_addr;
  177. -
  178. +        grpc_pass_header     Server;
  179. +        grpc_pass_header     Date;
  180.          grpc_pass            grpc://kong_upstream;
  181.      }
  183.      location @grpcs {
  184.          internal;
  185. +        default_type         '';
  186.          set $kong_proxy_mode 'grpc';
  188. +        grpc_set_header      TE                $upstream_te;
  189.          grpc_set_header      Host              $upstream_host;
  190.          grpc_set_header      X-Forwarded-For   $upstream_x_forwarded_for;
  191.          grpc_set_header      X-Forwarded-Proto $upstream_x_forwarded_proto;
  192.          grpc_set_header      X-Forwarded-Host  $upstream_x_forwarded_host;
  193.          grpc_set_header      X-Forwarded-Port  $upstream_x_forwarded_port;
  194.          grpc_set_header      X-Real-IP         $remote_addr;
  195. -
  196. +        grpc_pass_header     Server;
  197. +        grpc_pass_header     Date;
  198. +        grpc_ssl_name        $upstream_host;
  199. +        grpc_ssl_server_name on;
  200. +> if client_ssl then
  201. +        grpc_ssl_certificate $;
  202. +        grpc_ssl_certificate_key $;
  203. +> end
  204.          grpc_pass            grpcs://kong_upstream;
  205.      }
  207. +    location = /kong_buffered_http {
  208. +        internal;
  209. +        default_type         '';
  210. +        set $kong_proxy_mode 'http';
  211. +
  212. +        rewrite_by_lua_block       {;}
  213. +        access_by_lua_block        {;}
  214. +        header_filter_by_lua_block {;}
  215. +        body_filter_by_lua_block   {;}
  216. +        log_by_lua_block           {;}
  217. +
  218. +        proxy_http_version 1.1;
  219. +        proxy_set_header      TE                $upstream_te;
  220. +        proxy_set_header      Host              $upstream_host;
  221. +        proxy_set_header      Upgrade           $upstream_upgrade;
  222. +        proxy_set_header      Connection        $upstream_connection;
  223. +        proxy_set_header      X-Forwarded-For   $upstream_x_forwarded_for;
  224. +        proxy_set_header      X-Forwarded-Proto $upstream_x_forwarded_proto;
  225. +        proxy_set_header      X-Forwarded-Host  $upstream_x_forwarded_host;
  226. +        proxy_set_header      X-Forwarded-Port  $upstream_x_forwarded_port;
  227. +        proxy_set_header      X-Real-IP         $remote_addr;
  228. +        proxy_pass_header     Server;
  229. +        proxy_pass_header     Date;
  230. +        proxy_ssl_name        $upstream_host;
  231. +        proxy_ssl_server_name on;
  232. +> if client_ssl then
  233. +        proxy_ssl_certificate $;
  234. +        proxy_ssl_certificate_key $;
  235. +> end
  236. +        proxy_pass            $upstream_scheme://kong_upstream$upstream_uri;
  237. +    }
  238. +
  239.      location = /kong_error_handler {
  240.          internal;
  241. +        default_type                 '';
  242. +
  243.          uninitialized_variable_warn  off;
  245.          rewrite_by_lua_block {;}
  246. -
  247.          access_by_lua_block  {;}
  249.          content_by_lua_block {
  250. @@ -215,13 +245,13 @@ server {
  251.          }
  252.      }
  253.  }
  254. -> end
  255. +> end -- (role == "traditional" or role == "data_plane") and #proxy_listeners > 0
  257. -> if #admin_listeners > 0 then
  258. +> if (role == "control_plane" or role == "traditional") and #admin_listeners > 0 then
  259.  server {
  260.      server_name kong_admin;
  261. -> for i = 1, #admin_listeners do
  262. -    listen $(admin_listeners[i].listener);
  263. +> for _, entry in ipairs(admin_listeners) do
  264. +    listen $(entry.listener);
  265.  > end
  267.      access_log $;
  268. @@ -233,11 +263,7 @@ server {
  269.  > if admin_ssl_enabled then
  270.      ssl_certificate     $;
  271.      ssl_certificate_key $;
  272. -
  273. -    ssl_session_cache shared:SSL:10m;
  274. -    ssl_session_timeout 10m;
  275. -    ssl_prefer_server_ciphers on;
  276. -    ssl_ciphers $;
  277. +    ssl_session_cache   shared:AdminSSL:10m;
  278.  > end
  280.      # injected nginx_admin_* directives
  281. @@ -265,20 +291,20 @@ server {
  282.          return 200 'User-agent: *\nDisallow: /';
  283.      }
  284.  }
  285. -> end
  286. +> end -- (role == "control_plane" or role == "traditional") and #admin_listeners > 0
  288.  > if #status_listeners > 0 then
  289.  server {
  290.      server_name kong_status;
  291. -> for i = 1, #status_listeners do
  292. -    listen $(status_listeners[i].listener);
  293. +> for _, entry in ipairs(status_listeners) do
  294. +    listen $(entry.listener);
  295.  > end
  297.      access_log $;
  298.      error_log  $ $;
  300. -    # injected nginx_http_status_* directives
  301. -> for _, el in ipairs(nginx_http_status_directives) do
  302. +    # injected nginx_status_* directives
  303. +> for _, el in ipairs(nginx_status_directives) do
  304.      $(el.name) $(el.value);
  305.  > end
  307. @@ -303,4 +329,26 @@ server {
  308.      }
  309.  }
  310.  > end
  311. +
  312. +> if role == "control_plane" then
  313. +server {
  314. +    server_name kong_cluster_listener;
  315. +> for _, entry in ipairs(cluster_listeners) do
  316. +    listen $(entry.listener) ssl;
  317. +> end
  318. +
  319. +    access_log off;
  320. +
  321. +    ssl_verify_client   optional_no_ca;
  322. +    ssl_certificate     $;
  323. +    ssl_certificate_key $;
  324. +    ssl_session_cache   shared:ClusterSSL:10m;
  325. +
  326. +    location = /v1/outlet {
  327. +        content_by_lua_block {
  328. +            Kong.serve_cluster_listener()
  329. +        }
  330. +    }
  331. +}
  332. +> end -- role == "control_plane"
  333.  ]]

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的最终预期状态)执行。

  1. 下载2.0.0，并将其配置为指向与旧集群(1.0到1.5)相同的数据存储。运行kong migration up。
  2. 一旦它完成运行，旧集群和新集群(2.0.0)现在可以在同一个数据存储上同时运行。开始供应2.0.0节点，但还不使用它们的管理API。如果需要执行管理API请求，应该对旧集群的节点执行这些请求。其原因是为了防止新集群生成旧集群无法识别的数据。
  3. 逐渐将流量从旧节点转移到2.0.0集群中。监控你的流程以确保一切顺利。
  4. 当您的流量完全迁移到2.0.0集群时，下线您的旧节点。
  5. 在2.0.0集群中运行:kong migration finish。从现在起，将不能在旧集群中启动指向相同数据存储的节点。只有在确信迁移成功时才运行此命令。从现在开始，您可以安全地向2.0.0节点发出管理API请求。

在新的数据存储上安装2.0.0

下面的命令应该用于从新的数据存储准备新的2.0.0集群:

  1. $ kong migrations bootstrap [-c config]
  2. $ kong start [-c config]