Werf项目部署注解详解：控制资源部署顺序与跟踪行为

Werf作为一个强大的Kubernetes部署工具，提供了丰富的注解(annotations)来精确控制资源在部署过程中的行为和跟踪方式。本文将深入解析这些注解的功能和使用场景，帮助您更好地掌控部署流程。

资源权重控制：werf.io/weight

werf.io/weight注解允许您为资源设置权重值，从而影响部署顺序：

werf.io/weight: "10"  # 正数表示高优先级
werf.io/weight: "-5"  # 负数表示低优先级

关键特性：

• 权重值可以是任意整数（正数、负数或零）
• 值必须以字符串形式传递（用引号包裹）
• 仅适用于非Hook资源（Hook资源应使用helm.sh/hook-weight）

部署时，Werf会按权重分组资源，从最低权重组开始依次部署，确保前一组完全就绪后才继续下一组。

资源依赖管理

内部资源依赖

werf.io/deploy-dependency-*系列注解用于定义资源间的依赖关系：

werf.io/deploy-dependency-db: "state=ready,kind=StatefulSet,name=postgres"

参数说明：

• state（必需）：ready表示等待依赖资源就绪，present表示仅需存在
• 至少指定以下一项：name、namespace、kind、group或version

外部资源依赖

对于跨命名空间或集群外部的依赖，可以使用：

external-dependency.werf.io/resource: "deployments.v1.apps/app"
external-dependency.werf.io/namespace: "production"

副本数精细控制

当使用HPA（Horizontal Pod Autoscaler）时，静态设置spec.replicas会导致问题。解决方案：

1. 完全移除模板中的spec.replicas（推荐）
2. 使用werf.io/replicas-on-creation仅在创建时设置初始副本数：

werf.io/replicas-on-creation: "3"  # 字符串格式

部署跟踪模式

werf.io/track-termination-mode控制资源跟踪行为：

• WaitUntilResourceReady（默认）：等待资源完全就绪
• NonBlocking：非阻塞模式，仅当其他资源未就绪时跟踪

适用场景：

• StatefulSet使用OnDelete更新策略时
• 后台Job任务不影响主部署流程时

故障处理策略

失败模式

werf.io/fail-mode定义资源失败时的处理方式：

werf.io/fail-mode: "HopeUntilEndOfDeployProcess"

可选值：

• FailWholeDeployProcessImmediately（默认）：立即失败
• HopeUntilEndOfDeployProcess：延迟检查
• IgnoreAndContinueDeployProcess：完全忽略

失败阈值

werf.io/failures-allowed-per-replica设置每个副本允许的失败次数：

werf.io/failures-allowed-per-replica: "2"

就绪探针控制

werf.io/ignore-readiness-probe-fails-for-*覆盖默认的就绪探针失败忽略期：

werf.io/ignore-readiness-probe-fails-for-backend: "30s"

注意：如果探针配置了failureThreshold: 1，此设置将被忽略。

日志管理

日志过滤

使用正则表达式过滤日志输出：

werf.io/log-regex: "error|warn"  # 全局过滤
werf.io/log-regex-for-nginx: "404|500"  # 容器级过滤

日志显示控制

werf.io/skip-logs: "true"  # 完全禁用日志
werf.io/skip-logs-for-containers: "sidecar,init"  # 跳过特定容器
werf.io/show-logs-only-for-containers: "app"  # 仅显示指定容器

调试与安全

服务消息显示

werf.io/show-service-messages: "true"  # 显示Kubernetes事件

敏感资源标记

werf.io/sensitive: "true"  # 在`werf plan`中隐藏diff

最佳实践建议

1. 部署顺序规划：合理使用权重和依赖注解，确保关键服务优先部署
2. HPA集成：使用replicas-on-creation避免与自动扩缩容冲突
3. 后台任务处理：对非关键Job使用NonBlocking和Ignore模式
4. 日志管理：生产环境建议过滤无关日志，提高可观察性
5. 敏感数据保护：标记包含敏感信息的资源，防止意外暴露

通过灵活组合这些注解，您可以构建出高度可控、可靠的Kubernetes部署流程，满足各种复杂场景的需求。