Konga网关管理后台升级操作手册

现状

序号资源名称版本获取方式
1 Kong 1.0.2 kong version
2 PostgreSQL 10.6 psql --version
目标

此次升级Kong，同时将数据迁移至自建数据库。

序号资源名称版本
1 Kong 2.4.1
2 PostgreSQL 10.6
升级步骤

官方指导文档
1. 升级步骤:
  - 因Kong在每个大版本发布时数据库结构发生变更，因此不支持直接升级至最新版。
  - 升级期间不允许在中间版本进行Admin API更新请求
  - 升级版本过程
```
kong:1.0.2 > kong:1.5.0 > kong:2.0 > kong:2.4
```
2. 在各中间版本运行：kong migrations up，kong migrations finish
3. 启动新版本服务前，确认流量切换完成后再执行：kong migrations finish
4. 执行完finish指令后将多实例连接同一数据库，请停用旧集群服务、启动新集群服务。
实施步骤

如kong安装有第三方(非konga列表展示)的组件请额外备份及升级
1. 准备镜像
  
  分别准备目标版本及各中间版本Docker镜像文件，上传至私有仓库。
  - kong:1.5.0
  - kong:2.0
  - kong:2.4
2. 备份
  1. 备份配置
    - 需备份配置文件
  2. 备份数据库
    
    升级Kong网关数据库，进入终端执行以下指令：
```
# 备份
pg_dump  -h old_kong_dbhost -U kong -W -d kong > /tmp/kong.bak
# 备份完成后将文件传输至服务器本地
```
    如在升级过程出现问题，根据恢复时间决定是否回滚数据
```
# 回滚
psql -h new_kong_dbhost -U kong -W -d kong < /tmp/kong.bak
```
3. 基础环境
  
  请注意版本顺序及替换变量，本文示例Docker与K8S版本，请根据实际需要进行选择。
  1. 部署数据库
    1. 创建存储
      - 创建持久化存储卷
    2. 创建数据库
      1. 创建Postgres有状态工作负载
        
        容器配置
        
        镜像名称：postgres
        镜像Tag：10.6
        环境变量：
        POSTGRES_DB：kong
        POSTGRES_USER：kong
        POSTGRES_PASSWORD：保密字典/kong-postgresql/postgresql-password
        PGDATA：/var/lib/postgresql/data/pgdata // 此处必须多一层目录，否则数据卷挂载后初始化文件将不可见
        
        数据卷：
        增加存储声明：
        挂载源：选择对应存储声明名称
        容器路径：/var/lib/postgresql/data
        
        访问设置：
        服务：
        端口映射：postgresql/5432/5432/TCP
      2. 导入备份数据
        
        在新数据库容器中执行备份动作或上传备份文件至/tmp
        
        # 导入 psql -h new_kong_dbhost -U kong -W -d kong < /tmp/kong.bak
  2. 部署网关服务
    1. 创建Kong无状态工作负载
      1. 容器配置
        
        镜像名称：kong
        镜像Tag：1.5
        环境变量：
        KONG_DATABASE：postgres
        KONG_PG_HOST：kong-postgresql-svc
        KONG_PG_USER：kong
        KONG_PG_PASSWORD：kong
        
        生命周期：
        启动执行：
        命令：sleep 3600 # 防止kong启动失败后退出
      2. 高级配置
        
        中间状态应用不进行特殊配置
      以上确认无误后点击创建。
4. 数据库升级
  1. 执行非破坏性升级
    
    进入Kong网关容器终端，执行升级指令：
    1. 应用数据库版本升级
```
kong migrations up
```
    2. 确认无误后结束升级，关闭更新状态
```
kong migrations finish
```
    - 如在升级过程出现问题，根据恢复时间决定是否回滚数据
```
# 删除数据文件
rm -rf /var/lib/postgresql/data/*
# 重启容器
# 回滚
psql -h new_kong_dbhost -U kong -W < /tmp/kong.bak
```
    以上执行指令均不应有错误输出，如有错误输出请回滚数据，检查配置后重新升级。
  2. 更新至下一版本
    1. 修改工作负载镜像Tag至下一版本，在操作栏点击【重新部署】；
    2. 启动成功后执行上述“执行非破坏性升级”操作；
    3. 循环执行上述动作，直至将数据库更新至最新稳定版。
5. 配置Kong网关
  
  可修改基础环境中Kong网关工作负载配置，也可删除该工作负载后后重新创建，具体配置请根据实际情况进行修改，示例配置如下：
  1. 容器配置
    - 镜像名称：kong
    - 镜像Tag：2.4.1-centos
    - 端口：
      - admin：8001/TCP
      - proxy：8000/TCP
      - proxy-tls：8443/TCP
    - 环境变量：
      - KONG_DATABASE：postgres
      - KONG_PG_HOST：kong-postgresql-svc
      - KONG_PG_USER：kong
      - KONG_PG_PASSWORD：kong
      - KONG_ADMIN_LISTEN：0.0.0.0:8001
      - KONG_PROXY_LISTEN：0.0.0.0:8000,0.0.0.0:8443 ssl
      - KONG_NGINX_DAEMON：off
      - KONG_ADMIN_ACCESS_LOG：/dev/stdout
      - KONG_ADMIN_ERROR_LOG：/dev/stderr
      - KONG_ADMIN_GUI_ACCESS_LOG：/dev/stdout
      - KONG_ADMIN_GUI_ERROR_LOG：/dev/stderr
      - KONG_PORTAL_API_ACCESS_LOG：/dev/stdout
      - KONG_PORTAL_API_ERROR_LOG：/dev/stderr
      - KONG_PROXY_ACCESS_LOG：/dev/stdout
      - KONG_PROXY_ERROR_LOG：/dev/stderr
      - KONG_PG_PORT：5432
      - KONG_PG_DATABASE：kong
      - KONG_NGINX_HTTP_GZIP：on
      - KONG_NGINX_HTTP_GZIP_MIN_LENGTH：1k
      - KONG_NGINX_HTTP_GZIP_TYPES：text/html application/json text/plain
连接新实例

通过Konga管理平台connections页面创建新连接
```
Name: 新命名
Kong Admin URL: 新服务地址(http://admin-svc:8001)
```
切换至新版本查看服务及路由等数据是否正常
迁移流量
- 根据实际情况切换网关外部负载均衡标签

序号	资源名称	版本	获取方式
1	Kong	1.0.2	kong version
2	PostgreSQL	10.6	psql --version

序号	资源名称	版本
1	Kong	2.4.1
2	PostgreSQL	10.6

其他

本次数据库版本升级输出如下：

1.0-1.5

/ # kong migrations up
migrating core on database 'kong'...
core migrated up to: 005_120_to_130 (pending)
core migrated up to: 006_130_to_140 (executed)
core migrated up to: 007_140_to_150 (executed)
migrating hmac-auth on database 'kong'...
hmac-auth migrated up to: 002_130_to_140 (executed)
migrating oauth2 on database 'kong'...
oauth2 migrated up to: 003_130_to_140 (executed)
migrating jwt on database 'kong'...
jwt migrated up to: 002_130_to_140 (executed)
migrating basic-auth on database 'kong'...
basic-auth migrated up to: 002_130_to_140 (executed)
migrating key-auth on database 'kong'...
key-auth migrated up to: 002_130_to_140 (executed)
migrating acl on database 'kong'...
acl migrated up to: 002_130_to_140 (executed)
migrating session on database 'kong'...
session migrated up to: 000_base_session (executed)
10 migrations processed
9 executed
1 pending

Database has pending migrations; run 'kong migrations finish' when ready
/ # kong migrations finish
migrating core on database 'kong'...
core migrated up to: 005_120_to_130 (executed)
1 migration processed
1 executed
No pending migrations to finish
/ #

1.5-2.0

bash-5.0$ kong migrations up
migrating core on database 'kong'...
core migrated up to: 008_150_to_200 (pending)
migrating acme on database 'kong'...
acme migrated up to: 000_base_acme (executed)
2 migrations processed
1 executed
1 pending

Database has pending migrations; run 'kong migrations finish' when ready
bash-5.0$ kong migrations finish
migrating core on database 'kong'...
core migrated up to: 008_150_to_200 (executed)
1 migration processed
1 executed
No pending migrations to finish
bash-5.0$

2.0-2.4

bash-5.0$ kong migrations up
migrating core on database 'kong'...
core migrated up to: 009_200_to_210 (pending)
core migrated up to: 010_210_to_211 (executed)
core migrated up to: 011_212_to_213 (executed)
core migrated up to: 012_213_to_220 (pending)
core migrated up to: 013_220_to_230 (executed)
migrating acl on database 'kong'...
acl migrated up to: 003_200_to_210 (pending)
acl migrated up to: 004_212_to_213 (pending)
migrating basic-auth on database 'kong'...
basic-auth migrated up to: 003_200_to_210 (pending)
migrating bot-detection on database 'kong'...
bot-detection migrated up to: 001_200_to_210 (pending)
migrating hmac-auth on database 'kong'...
hmac-auth migrated up to: 003_200_to_210 (pending)
migrating ip-restriction on database 'kong'...
ip-restriction migrated up to: 001_200_to_210 (pending)
migrating jwt on database 'kong'...
jwt migrated up to: 003_200_to_210 (pending)
migrating key-auth on database 'kong'...
key-auth migrated up to: 003_200_to_210 (pending)
migrating oauth2 on database 'kong'...
oauth2 migrated up to: 004_200_to_210 (pending)
oauth2 migrated up to: 005_210_to_211 (executed)
migrating rate-limiting on database 'kong'...
rate-limiting migrated up to: 004_200_to_210 (executed)
migrating session on database 'kong'...
session migrated up to: 001_add_ttl_index (executed)
17 migrations processed
6 executed
11 pending

Database has pending migrations; run 'kong migrations finish' when ready
bash-5.0$ kong migrations finish
migrating core on database 'kong'...
core migrated up to: 009_200_to_210 (executed)
core migrated up to: 012_213_to_220 (executed)
migrating acl on database 'kong'...
acl migrated up to: 003_200_to_210 (executed)
acl migrated up to: 004_212_to_213 (executed)
migrating basic-auth on database 'kong'...
basic-auth migrated up to: 003_200_to_210 (executed)
migrating bot-detection on database 'kong'...
bot-detection migrated up to: 001_200_to_210 (executed)
migrating hmac-auth on database 'kong'...
hmac-auth migrated up to: 003_200_to_210 (executed)
migrating ip-restriction on database 'kong'...
ip-restriction migrated up to: 001_200_to_210 (executed)
migrating jwt on database 'kong'...
jwt migrated up to: 003_200_to_210 (executed)
migrating key-auth on database 'kong'...
key-auth migrated up to: 003_200_to_210 (executed)
migrating oauth2 on database 'kong'...
oauth2 migrated up to: 004_200_to_210 (executed)
11 migrations processed
11 executed
No pending migrations to finish
bash-5.0$