把"部署应用"写成一份 YAML：KubeVela 深度实战指南

【免费下载链接】kubevelaThe Modern Application Platform.项目地址: https://gitcode.com/gh_mirrors/ku/kubevela

KubeVela 是一个把"应用交付"做成声明式工作流的现代化应用平台，它基于 Open Application Model（OAM，一种描述应用如何组成、如何部署的开放标准），让你能用一份 YAML 描述清楚"应用由哪些组件构成、按什么顺序发布、发到哪些集群"，其余交给控制器去执行。这篇文章会从一次真实的部署经历讲起，带你理解 KubeVela 的核心设计，并亲手跑通安装、部署、版本回滚与生产调优的全过程。

从一个"部署翻车"的夜晚说起

想象一下这个场景：你维护着一个前后端分离的微服务应用，上线前要手动执行十几条命令——先改数据库、再起后端、等健康检查通过、最后切流量到前端。操作多、依赖强、顺序错一步就翻车。你试着把这些步骤写进 CI 脚本，结果脚本越写越长，环境一换就要大改。

这正是 KubeVela 要解决的问题。它把"部署流程"本身变成了一种可编程、可版本化的资源：你描述"最终要长成什么样"和"按什么顺序长"，KubeVela 负责让集群变成那样。

第一步：用 5 分钟把平台跑起来

准备一个 Kubernetes 集群

KubeVela 的控制器本质上是运行在 Kubernetes 里的一个 Operator（即一种"盯住自定义资源并自动调谐"的程序），所以你需要一个可用的集群，任意主流发行版都可以：

kubectl cluster-info # 确认集群可达 kubectl get nodes # 确认节点就绪 helm version # 确认 Helm 3 已安装

用 Helm 安装控制平面

控制平面组件统一部署在kubevela-system命名空间：

helm repo add kubevela https://charts.kubevela.io/stable helm repo update helm install kubevela kubevela/kubevela \ --namespace kubevela-system \ --create-namespace \ --wait

装完后看一眼 Pod 是否全部 Running：

kubectl get pods -n kubevela-system

安装 CLI：vela

CLI 不是必需品，但它能让你用几条命令完成查看状态、对比版本、跟踪工作流等操作，强烈建议装上：

curl -fsSl https://kubevela.io/script/install.sh | bash vela version

想从源码构建的同学，可以 clone 仓库后自行编译，仓库地址：https://gitcode.com/gh_mirrors/ku/kubevela，CLI 入口在 references/cli/，控制器入口在 cmd/core/main.go。

平台就绪后，我们来写第一份应用描述。

能力一：一份 YAML，说清"应用长什么样"

KubeVela 用Application资源（核心类型定义在 apis/core.oam.dev/v1beta1/application_types.go）把组件、运维能力和发布策略打包在一起。来看仓库自带的最小示例（docs/examples/application/application-sample.yaml）：

apiVersion: core.oam.dev/v1beta1 kind: Application metadata: name: application-sample spec: components: - name: myweb type: worker # 用系统内置的 worker 组件类型 properties: image: "busybox" cmd: ["sleep", "1000"] traits: # 运维能力：副本、边车、服务暴露 - type: scaler properties: replicas: 10 - type: sidecar properties: name: "sidecar-test" image: "nginx" - type: kservice properties: http: server: 80

提交即部署：

vela up -f docs/examples/application/application-sample.yaml

这条命令背后发生了什么？可以结合这张图理解 KubeVela 在 CI/CD 链路里的位置——左侧 CI 产出代码和配置，中间是 KubeVela 的**渲染（Render）→ 编排（Orchestrate）→ 部署（Deploy）**三段式流水线，右侧是各类目标环境：

这里有个新手容易困惑的点：type: webservice、type: scaler这些"类型"是谁定义的？答案是定义类资源——ComponentDefinition（组件定义）和TraitDefinition（运维能力定义）。它们把"如何把参数渲染成 Deployment / Service / Ingress"的逻辑封装起来，这也是 KubeVela 可扩展性的根基。安装时系统已经预置了一批内置定义，可以用vela component list和vela trait list查看。

能力二：部署顺序，交给"工作流"而不是祈祷

多组件应用往往有严格的上线顺序：先数据库、再后端、最后前端。手写脚本维护这种顺序很痛苦，而 KubeVela 把它变成了spec.workflow里的一段声明。仓库里的依赖示例（docs/examples/workflow/depends-on-app/app.yaml）演示了步骤之间的依赖写法：

apiVersion: core.oam.dev/v1beta1 kind: Application metadata: name: kruise spec: components: - name: kruise type: helm properties: chart: ./charts/kruise/v0.9.0 repoType: git workflow: steps: - name: check-flux type: depends-on-app # 先确认另一个应用已就绪 properties: name: fluxcd namespace: vela-system - name: apply-kruise type: apply-component # 再执行真正的部署 properties: component: kruise

工作流步骤由WorkflowStepDefinition定义（见 apis/core.oam.dev/v1beta1/workflow_step_definition.go），内置了apply-component、deploy2env、health-check、notification、read-object等常用步骤，还可以用 CUE 或 shell 脚本自定义步骤。执行内部是"控制器—工作流管理器—任务管理器"三层的闭环：

落到日常操作上，工作流给开发体验带来的变化是：

• 步骤失败会自动重试，重试次数可在 Helm values 里配置；
• 卡住时可以暂停，从容排查而不是直接回滚；
• 每一步的进度和日志可查：vela workflow status <app>、vela workflow logs <app> --step <step>；
• 支持条件分支、超时、步骤分组，对应示例见 docs/examples/workflow/app-with-if/ 和 docs/examples/workflow/step-group/。

如果你做金丝雀发布，工作流配合rollout与canary-traffic两个 trait，可以在不写任何脚本的情况下完成分批放量与灰度流量切换，完整示例就在 docs/examples/workflow/canary-rollout/。

能力三：每次发布都有"快照"，回滚不再靠翻 Git 记录

KubeVela 每次应用变更都会生成一个ApplicationRevision（应用修订版本），它把当时的组件定义、运维能力定义、工作流定义连同参数一起做成快照。所以"回滚到某个历史版本"意味着把当时整套定义原样重放，而不是只换镜像——这比 GitOps 工具通常做的"内容回滚"更彻底。

日常操作：

vela revision list microservices-demo # 查看版本历史 vela revision get microservices-demo # 查看某个版本的详细信息

仓库里对应的版本管理设计文档在 docs/examples/application/versioning.md。版本保留数量由 Helm 参数applicationRevisionLimit控制，默认只留 2 个，生产环境建议调大以留足回滚余量（后面会讲）。

能力四：一套配置，铺到多集群多云

多集群部署在 KubeVela 里不是"高级功能"，而是平台的一等公民。通过topology策略声明目标集群，通过override策略按集群差异化调整参数，KubeVela 会自动完成分发：

apiVersion: core.oam.dev/v1beta1 kind: Application metadata: name: example-app spec: components: - name: express-server type: webservice properties: image: crccheck/hello-world port: 8000 policies: - type: topology name: topology properties: clusters: ["cluster-1", "cluster-2"]

常见的"测试环境验证 → 预发灰度 → 生产放量"渐进式发布，本质上就是多套topology+override策略的组合，配合工作流按阶段执行。多集群的参考架构图在 docs/examples/multicluster/ref-arch.jpg，相关策略实现位于 pkg/policy/。

能力五：0.5C1G 的轻量底座 + 无限扩展

KubeVela 的整个控制平面可以只跑一个 Pod、占用约 0.5 核 1G 内存，却足以管理上千个应用——这得益于它把大多数逻辑放在了"定义"层，控制器本体保持精简。

扩展有两条路：

1. 定义扩展：用 CUE 语言（一种配置即代码的描述语言）编写自定义组件/运维能力/工作流步骤，写入ComponentDefinition等定义资源。仓库的 CUE 模板目录在 vela-templates/definitions/，里面能看到内置定义的写法。
2. 插件扩展：通过vela addon生态安装现成能力：

vela addon list # 查看可用插件 vela addon enable observability # 一键启用监控面板

再叠加一层"角色分离"视角，就更清楚这套设计的价值了：平台工程师定义"怎么部署"，应用开发者只声明"我要什么"，两者各司其职，互不阻塞。

生产落地：照抄这 5 个调优项就够了

前面聊的是能力，这一段聊"上线前必须改的东西"。KubeVela 的 Helm values 集中在 charts/vela-core/values.yaml，下面几个参数请务必按生产环境调整：

1. 版本保留数：别让回滚"无票可买"

applicationRevisionLimit: 10 # 默认只有 2，上线前调大到 10 左右 definitionRevisionLimit: 5

2. 并发与同步：跟着集群规模走

concurrentReconciles: 8 # 控制器并发调谐数，默认 4 controllerArgs: reSyncPeriod: 5m # 定期重新同步周期，需要更快的状态收敛可调小

3. 失败处理：暂停而不是默默重试到天荒地老

workflow: enableSuspendOnFailure: true # 失败即暂停，方便现场排查 step: errorRetryTimes: 5 # 默认 10 次，可按需调小

4. 资源配额：从"够用"到"稳"

resources: requests: cpu: 250m memory: 256Mi limits: cpu: 500m memory: 1Gi

5. 大规模场景：分片架构

当应用规模大到单控制器吃紧时，KubeVela 支持主从分片：master 实例负责各类定义和调度，多个 slave 实例各自分管一组应用（通过shard-id划分），实现水平扩展：

分片设计文档在 design/vela-core/vela-core-sharding-arch.jpg 同目录，配合featureGates（如applyOnce、enableInMemoryWorkflowContext）还能进一步压性能。这些开关在 pkg/features/controller_features.go 里都有定义，按需开启即可。

踩坑备忘：三个高频问题的一线排查思路

• Pod 一直 Pending 或反复重启：先kubectl describe pod <name> -n <ns>看事件，再查资源配额kubectl describe resourcequota，最后看容器日志定位应用层问题。大多数时候不是 KubeVela 的问题，而是资源或镜像的问题。
• 工作流步骤卡在 Running：用vela workflow status <app>确认卡在哪一步，再vela workflow logs <app> --step <step>看该步日志；如果开启了失败暂停，先检查是不是上一步的条件依赖没满足。
• 多集群里某个集群没部署上：先vela cluster list确认集群注册与心跳正常，再针对该集群查看应用状态与资源配额。注意topology策略里集群名必须与注册名完全一致。

要点清单

• 核心心智：KubeVela 把"部署"从命令/脚本抽象成了声明式资源，你描述"最终状态与顺序"，平台负责"变成现实"。
• 一份 YAML 交付：Application聚合组件、trait、工作流、策略，vela up一条命令完成渲染-编排-部署。
• 工作流是灵魂：步骤依赖、失败重试、暂停恢复、金丝雀发布都在这层实现，别再写胶水脚本了。
• 版本快照兜底：每次变更生成ApplicationRevision，回滚是"整套定义重放"，比只改镜像更可靠。
• 多集群是标配：topology+override策略解决跨集群分发与差异化配置。
• 轻量但可扩展：0.5C1G 起步，CUE 定义与 addon 插件两条扩展路径。
• 上线前必调：applicationRevisionLimit、concurrentReconciles、enableSuspendOnFailure、资源配额，四个参数先改到位。

下一步建议：先在测试集群把 docs/examples/ 下的示例逐个跑一遍，尤其是 canary-rollout 和 multicluster；然后尝试用 CUE 写一个自己的组件定义，体会"定义一次、处处复用"；最后按本文的调优清单走一遍生产化检查。等你对"渲染-编排-部署"的闭环有手感之后，再去看 design/ 目录下的设计文档，会发现每一篇都能读懂了。

【免费下载链接】kubevelaThe Modern Application Platform.项目地址: https://gitcode.com/gh_mirrors/ku/kubevela