DecK工具介绍（Declarative Configuration for Kong网关的声明式配置工具，可同步配置，热更新运行中的网关）类似Terraform、导出Kong配置、导出配置

DecK 完全指南：Kong 网关的声明式配置工具

在使用 API 网关时，一个常见问题是：

如何优雅地管理大量网关配置？

如果你正在使用 Kong API Gateway，那么你一定会接触到一个非常重要的工具：

decK（Declarative Configuration for Kong）

它能够帮助你：

• 用代码管理 Kong 配置
• 实现 GitOps
• 配置版本化
• 自动同步环境
• CI/CD 自动部署
• 团队协作审计

很多团队会把 decK 理解为：

“Kong 世界里的 Terraform + kubectl”

本文将全面介绍 decK 的核心概念、工作原理、常见命令、最佳实践与企业级使用方式。

一、什么是 decK？

decK 是 Kong 官方 提供的一个：

Kong 配置管理与同步工具

官方名称：

Declarative Configuration for Kong

它可以：

• 从 Kong 导出配置
• 将 YAML 配置同步到 Kong
• 比较差异
• 批量管理对象
• 实现 Infrastructure as Code（IaC）

二、为什么需要 decK？

在没有 decK 之前：

很多团队直接：

• 在 Kong Manager UI 点点点
• 或手动调用 Admin API

例如：

# 这个命令是向本地运行的API网关（如Kong）注册一个名为"user-service"的服务，其后端地址为"http://user-service:8080"。# `--data`是curl命令中用于指定POST请求体数据的参数，用于向服务器发送表单格式的数据。curl-XPOST http://localhost:8001/services\--dataname=user-service\--dataurl=http://user-service:8080

问题会越来越严重：

于是：

decK 出现了。

三、decK 的核心思想

decK 的理念非常类似：

• Kubernetes YAML
• Terraform
• GitOps

核心思想：

“声明你想要的最终状态”

例如：

services:-name:user-serviceurl:http://user-service:8080routes:-name:user-routeservice:user-servicepaths:-/users

然后：

decksync

decK 会自动：

• 创建缺失配置
• 更新已有配置
• 删除多余配置

最终：

Kong 状态 = YAML 文件状态

这叫：

Desired State（期望状态）

四、decK 的工作原理

decK 实际上是：

YAML 配置 ↓ 读取配置 ↓ 调用 Kong Admin API ↓ 对比当前状态 ↓ 计算 diff ↓ 同步变更

它不是直接修改数据库。

它本质上：

是 Kong Admin API 的高级封装。

五、decK 支持管理哪些对象？

decK 几乎支持所有 Kong 配置对象：

例如：

plugins:-name:rate-limitingservice:user-serviceconfig:minute:100policy:local

六、安装 decK

官方 GitHub：

decK GitHub 仓库

Linux/macOS

brewinstalldeck

或者：

curl-sLhttps://github.com/Kong/deck/releases/latest/download/deck_linux_amd64.tar.gz|tar-xz

Windows

choco install deck

Choco 是 Chocolatey 的命令行简称，Chocolatey 是 Windows 系统下的一个 命令行包管理器（类似于 Linux 中的 apt 或 yum）。 它的核心功能是通过命令行自动化安装、更新和卸载 Windows 软件，无需手动下载安装包或点击图形界面。choco install deck 表示使用 Chocolatey 安装名为 deck 的软件包。

验证安装

deck version

输出：

decK v1.x.x

七、连接 Kong

默认：

deck gatewayping

如果 Kong Admin API 不在默认地址：

deck gatewayping\--kong-addr http://localhost:8001

八、导出 Kong 配置

这是最常见操作之一：

deck gateway dump

输出：

_format_version:"3.0"services:-name:user-serviceurl:http://user-service:8080

通常会保存：

deck gateway dump>kong.yaml

这样就能：

• 纳入 Git
• 代码评审
• 配置备份

九、同步配置

这是 decK 最核心的命令：

deck gatewaysynckong.yaml

它会：

• 创建对象
• 更新对象
• 删除未声明对象

类似：

Terraform Apply

十、查看差异（Diff）

非常推荐在同步前先看 diff：

deck gatewaydiffkong.yaml

输出示例：

+ service user-service created - plugin old-plugin removed ~ route api-route updated

这在 CI/CD 中非常重要。

十一、验证配置

同步前可先校验：

deckfilevalidate kong.yaml

避免 YAML 错误。

十二、decK 配置结构

一个完整例子：

_format_version:"3.0"services:-name:user-serviceurl:http://user-service:8080routes:-name:user-routepaths:-/usersplugins:-name:rate-limitingconfig:minute:100

你会发现：

配置结构非常接近 Kong 实体关系。

十三、环境管理

很多团队会这样组织：

kong-config/ ├── base/ ├── dev/ ├── staging/ └── prod/

例如：

base/ services.yaml prod/ rate-limit.yaml

然后：

deck gatewaysyncprod/kong.yaml

十四、GitOps 场景

这是 decK 最大价值之一。

典型流程：

开发修改 YAML ↓ 提交 Git ↓ PR Review ↓ CI 执行 deck diff ↓ CD 执行 deck sync ↓ Kong 自动更新

这样：

• 所有配置可审计
• 所有变更可回滚
• 所有环境可复现

十五、与 DB-less 模式的关系

很多人容易混淆：

它们：

不是同一个东西。

但经常一起使用。

DB-less

直接加载 declarative config：

# Kong 网关的"开机启动方式"，决定网关如何获取初始配置kong start--confkong.conf

decK

通过 Admin API 管理配置：

# 动态管理已运行的 Kong 配置（通过 Admin API）deck gatewaysync

十六、decK 与 Terraform 的区别

很多人会问：

已经有 Terraform，为啥还需要 decK？

区别：

很多企业：

• Terraform 管 infra
• decK 管 Kong

十七、CI/CD 集成示例

GitHub Actions：

name:Sync Kongon:push:branches:-mainjobs:sync:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:Install decKrun:|curl -sL https://github.com/Kong/deck/releases/latest/download/deck_linux_amd64.tar.gz | tar -xz-name:Sync Kongrun:|./deck gateway sync kong.yaml

十八、企业最佳实践

1. 永远使用 Git 管理

不要只存在 Kong 里。

必须：

Git 才是真实来源

2. Sync 前先 Diff

推荐：

deck gatewaydiffdeck gatewaysync

避免误删。

3. 分环境管理

不要：

一个 YAML 管所有环境

容易混乱。

4. 配置拆分模块化

大型项目：

services/ plugins/ consumers/ routes/

更清晰。

5. 与 CI/CD 集成

避免人工操作。

十九、常见问题

Q1：decK 会删除未声明配置吗？

会。

默认：

声明式同步

所以：

YAML 中不存在的对象可能被删除。

因此：

deckdiff

非常重要。

Q2：能部分同步吗？

可以。

支持：

--select-tag

例如：

deck gatewaysync\--select-tag team-a

Q3：适合大型团队吗？

非常适合。

因为它天然支持：

• GitOps
• Review
• 审计
• 自动化

二十、decK 的核心价值总结

decK 真正解决的是：

API Gateway 配置治理问题。

它把：

手工点 UI

升级成：

声明式配置 + GitOps + 自动化

这是现代平台工程的重要组成部分。

二十一、总结

decK 是 Kong 生态里极其重要的工具。

它让 Kong 配置：

• 可版本化
• 可审计
• 可回滚
• 可自动化
• 可 GitOps 化

如果说：

Kong = API Gateway

那么：

decK = Kong 的配置操作系统

对于中大型团队来说：

decK 几乎是生产环境的标准配置管理方案。