概述
cdk8s（Cloud Development Kit for Kubernetes）是一个 CNCF Sandbox 项目，提供类型安全、可编程的 Kubernetes 基础设施定义方式。它允许使用 Python、TypeScript、JavaScript、Java 或 Go 定义 Kubernetes 资源，并合成（synth）为标准 Kubernetes YAML 清单，可配合任意 Kubernetes 集群使用（云无关）。其设计概念与 AWS CDK 相同，自 2021 年 10 月起为 GA，属于 CNCF Sandbox 项目。
主要能力
- 类型安全：在开发阶段即可发现配置错误。
- IDE 支持：自动补全、内联文档、重构。
- 可复用性：为常见模式创建自定义构造（construct）。
- 可测试性：对基础设施代码进行单元测试。
- 减少样板代码：意图驱动的 API，相对冗长的 YAML 更简洁。
适用场景
- 包含多个微服务的复杂应用
- 多环境部署（dev/staging/prod）
- 可复用组件库
- 偏好用代码而非 YAML 的团队
- 与 AWS CDK 集成进行 EKS 部署
快速开始
安装（需 Node.js 18+）：
npm install -g cdk8s-cli
cdk8s init python-app
cd my-cdk8s-app
pip install -r requirements.txt
首个应用示例：
#!/usr/bin/env python3
from constructs import Construct
from cdk8s import App, Chart
from cdk8s_plus_27 import Deployment, ContainerProps
class WebApp(Chart):
def __init__(self, scope: Construct, id: str):
super().__init__(scope, id)
deployment = Deployment(
self, "web",
replicas=3,
containers=[
ContainerProps(
image="nginx:1.21",
port=80
)
]
)
deployment.expose_via_service(port=80)
app = App()
WebApp(app, "my-app")
app.synth()
合成与部署：
cdk8s synth
cat dist/my-app.k8s.yaml
kubectl apply -f dist/
核心概念
构造层级
cdk8s 使用三层构造：
- L1 构造（低层）：由 Kubernetes API 自动生成，直接映射 K8s 资源，完全控制但语法冗长。
from imports import k8s
k8s.KubeDeployment(
self, "deployment",
spec=k8s.DeploymentSpec(
replicas=3,
selector=k8s.LabelSelector(match_labels={"app": "web"}),
template=k8s.PodTemplateSpec(...)
)
)
- L2 构造（高层，cdk8s-plus）：手工打造的意图驱动 API，自动管理关系，减少样板代码。
from cdk8s_plus_27 import Deployment, ContainerProps
Deployment(
self, "deployment",
replicas=3,
containers=[ContainerProps(image="nginx", port=80)]
)
- L3 构造（自定义抽象）：自建可复用组件，封装组织模式。
class WebService(Construct):
def __init__(self, scope, id, image, replicas=3):
super().__init__(scope, id)
App 与 Chart
- App：所有 chart 的根容器。
- Chart：代表单个 Kubernetes 清单文件。
app = App()
dev_chart = MyChart(app, "dev", namespace="development")
prod_chart = MyChart(app, "prod", namespace="production")
app.synth()
导入自定义资源
支持导入 CRD、Helm chart 和外部定义：
cdk8s import k8s
cdk8s import https://raw.githubusercontent.com/aws-controllers-k8s/s3-controller/main/helm/crds/s3.services.k8s.aws_buckets.yaml
cdk8s import helm:https://charts.bitnami.com/bitnami/redis@18.2.0
cdk8s import github:crossplane/crossplane@0.14.0
常见工作流
工作流一：简单 Web 应用
结合 ConfigMap、Deployment 与 Service，通过 EnvValue.from_config_map 注入配置，并暴露为服务。
工作流二：多环境部署
为 dev、staging、prod 分别实例化 Chart，设置不同的命名空间、副本数与镜像标签。
工作流三：自定义可复用构造
封装 MicroserviceApp 构造，统一创建 ConfigMap、Secret、Deployment 与 Service，一次调用即可部署多个微服务。
测试
使用 pytest 与 cdk8s.Testing 对合成后的清单进行断言，例如校验副本数、Service 端口；还可编写策略校验，如禁止 :latest 镜像标签、要求所有容器设置资源限制。
CI/CD 集成
GitHub Actions 示例中，依次安装 Node.js 与 Python 依赖、执行 cdk8s synth、再用 kubectl apply 部署到 EKS。
与 AWS CDK（EKS）集成
可通过 cluster.add_cdk8s_chart("my-app", k8s_chart) 将 cdk8s chart 部署到由 AWS CDK 创建的 EKS 集群。
最佳实践
- 锁定版本：在 requirements.txt 中固定 cdk8s 与 cdk8s-plus 版本，并匹配 K8s 版本。
- 使用显式名称：重命名 ID 会导致资源重建，建议通过 metadata 使用稳定名称。
- 隔离环境：为生产 Chart 指定命名空间与标签。
- 部署前测试：使用
kubectl apply --dry-run=client -f dist/、运行 pytest、审查 git diff。
常用命令
cdk8s init python-app
cdk8s import k8s
cdk8s import https://example.com/crd.yaml
cdk8s import helm:https://charts.example.com/chart@1.0.0
cdk8s synth
cdk8s synth --watch
kubectl apply -f dist/
kubectl apply --dry-run=client -f dist/
版本兼容性
| cdk8s-plus | Kubernetes | Python | Node.js |
|---|---|---|---|
| cdk8s-plus-27 | 1.27+ | 3.7+ | 18+ |
| cdk8s-plus-28 | 1.28+ | 3.7+ | 18+ |
| cdk8s-plus-29 | 1.29+ | 3.7+ | 18+ |
与其他方案的选择
- 使用 cdk8s：复杂多组件应用、团队偏好代码而非 YAML、需要可复用组件库、重要基础设施代码测试、与 AWS CDK 集成 EKS。
- 使用 Helm：需要现有社区 chart、简单模板足够、需要包分发。
- 使用 Kustomize：需要简单覆盖、透明的 YAML 修改、学习曲线低。
- 使用原生 YAML：非常简单的应用、一次性部署、无需复用。
快速参考：可用构造（cdk8s-plus）
- 工作负载：Deployment、StatefulSet、DaemonSet、Job、CronJob、Pod
- 服务：Service、Ingress
- 配置：ConfigMap、Secret、EnvValue
- 存储：Volume、PersistentVolume、PersistentVolumeClaim
- RBAC：ServiceAccount、Role、ClusterRole、RoleBinding、ClusterRoleBinding
- 扩缩：HorizontalPodAutoscaler
- 网络：NetworkPolicy
资源
- 官方文档：cdk8s.io
- 源码：GitHub
- API 参考与示例详见官方文档
- AWS 资源：Introducing CDK for Kubernetes、cdk8s+ Intent-driven APIs
- 社区：CNCF Project Page、Slack Channel