Argo 的通知功能

作者：Alexander Matyushentsev

通知是完整的最终用户体验的重要组成部分，但却很难正确处理。不同的组织使用不同类型的通知服务，如 Slack、OpsGenie 或传统的电子邮件。可能需要通知的事件有几十种不同类型，因此很难预测所有可能的场景并对它们进行优化。最后，每个组织都有不同的标准，可能希望以不同的方式定制通知。

在过去的一年里，Argoproj 团队尝试了几种不同的通知方法。我们收到了很多反馈，也学到了很多东西，经过多次试验，我们很高兴正式宣布支持通知功能！我们已经设计[1]并实现了一个可重用的 Golang 库，它可以满足各种 Argo 项目的通知功能需求。设计文档和库定义了配置语法、基本概念，并确保了所有 Argo 项目的一致用户体验。

Argo CD Notifications

Argo CD 是第一个提供通知的项目。Argo Rollouts 是下一个目标，之后 Argo Workflows 应该很快就能实现。在本文中，我们将学习一些基本概念，亲自动手，并使用 Argo CD 通知解决一些现实生活中的问题。

等等，Argo Rollouts 和 Workflows 呢？好消息是，所有 Argo 项目的通知设计和配置将非常相似，所以你今天学到的一切都将与所有 Argo 项目相关。

准备

首先，我们需要一个带有 Argo CD 的 Kubernetes 集群。如果你已经安装了带有 Argo CD 的集群，请放心进入下一步。如果没有，我们创建一个测试集群并安装 Argo CD。我们将使用以下指南：

• Minikube：https://kubernetes.io/docs/setup/[2]
• Argo CD：https://argoproj.github.io/argo-cd/getting_started/[3]

如果你是一个 Mac 用户，那么指南可以归结为以下步骤。

• 安装 minikube 和 Argo CD CLI：

brew install minikube argocd

• 为这个演示创建一个新的 minikube 集群：

minikube start -p argocd-notifications-demo

• 创建 argocd 命名空间并安装 argocd：

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

完成了！现在我们有了一个带有 Argo CD 的 Kubernetes 集群，是时候安装和配置通知了！

基本通知

Argo CD Notifications 是一个可选的独立项目[4]，应该安装在 argocd 命名空间中。让我们跟随这里提供的 Argo CD Notifications入门指南[5]。安装过程包括：

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/manifests/install.yaml
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/catalog/install.yaml

第一个 YAML 文件安装负责通知处理的控制器，第二个配置的通知触发器和模板。我们将很快讨论触发器和模板，但首先，让我们配置与通知服务的集成。

通知服务集成

Argo CD 通知已经支持 Slack、电子邮件、Telegram、Netgenie、Grafana、定制 Webhooks，并且列表还在不断增长。你可以在Argo CD Notifications 文档[6]中找到关于每个服务的详细说明。

为了简单起见，让我们配置普通的电子邮件集成，因为我们大多数人都使用电子邮件：

• 存储你的电子邮件帐户用户名和密码到 argocd-notifications-secret 秘密：

export EMAIL_USER=<your-username>
export PASSWORD=<your-password>
kubectl apply -n argocd -f - << EOF
apiVersion: v1
kind: Secret
metadata:
  name: argocd-notifications-secret
stringData:
  email-username: $EMAIL_USER
  email-password: $PASSWORD
type: Opaque
EOF

注意：如果你正在使用 Gmail，那么你可以通过到https://myaccount.google.com/apppasswords[7]创建一个应用程序密码，如下所述：https://support.google.com/accounts/answer/185833?hl=en[8]

• 电子邮件服务必须在 argocd-notifications-cm ConfigMap 中注册：

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
data:
  service.email.gmail: |
    username: $email-username
    password: $email-password
    host: smtp.gmail.com
    port: 465
    from: $email-username

要配置你的 Argo CD 实例，使用以下命令修补 ConfigMap：

kubectl patch cm argocd-notifications-cm -n argocd --type merge -p '{"data": {"service.email.gmail": "{ username: $email-username, password: $email-password, host: smtp.gmail.com, port: 465, from: $email-username }" }}'

完成了！现在，Argo CD 通知可以使用了。下一步是创建一个 Argo CD 应用程序并订阅通知。

订阅通知

Argo CD 通知订阅使用 notifications.argoproj.io/subscription 注释进行管理。继续，使用以下命令创建应用程序：

kubectl apply -n argocd -f - << EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  annotations:
    notifications.argoproj.io/subscribe.on-sync-succeeded.gmail: $EMAIL_USER
spec:
  destination:
    namespace: default
    server: https://kubernetes.default.svc
  project: default
  source:
    path: kustomize-guestbook
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
  syncPolicy:
    automated: {}
EOF

当创建了应用程序，Argo CD 就会对应用程序清单进行协调和同步。是时候查看你的收件箱了!你应该会收到关于同步成功的电子邮件通知。

订阅、触发器和模板

现在是时候回过头来了解我们已经配置的详细内容了。让我们看看应用到 guestbook 应用程序的注释：

notifications.argoproj.io/subscribe.on-sync-succeeded.gmail: <email>

注释由以下部分组成：

• notifications.argoproj.io/subscribe 是一个表示订阅的注释前缀
• on-sync-succeeded 是捕获成功同步事件的触发器名称
• gmail 是我们配置的基于电子邮件的服务的名称
• 是需要通知的收件人电子邮件地址

除了 on-sync-succeeded 之外，其他一切都应该清楚。什么是触发器，为什么 on-sync-succeeded？

触发器定义了应该发送通知的条件。当需要发送通知时，它会连续地监视 Argo CD 应用程序的状态和需求。与通知服务一样，触发器在 argocd-notifications-cm 中配置。下面的 YAML 包含了 on-sync-succeeded 触发器配置：

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
data:
  trigger.on-sync-succeeded: |
    - when: app.status.operationState.phase in ['Succeeded']
      send: [app-sync-succeeded]

when 属性包含一个表达式，该表达式对应用程序进行计算并返回 true 或 false。

第二个有趣的属性是 send。它包含一个通知模板列表。该模板负责生成通知文本，并在 argocd-notifications-cm ConfigMap 中配置：

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
data:
  template.app-sync-succeeded: |
    message: |
      {{if eq .serviceType "slack"}}:white_check_mark:{{end}} Application {{.app.metadata.name}} has been successfully synced at {{.app.status.operationState.finishedAt}}.
Sync operation details are available at: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}?operation=true .

如果你想利用更复杂的通知服务（如 Slack）的高级特性，那么模板可能会更复杂。

模板和触发器一起解决了两个重要的需求：为运营者提供强大的定制功能，同时为用户提供更好、更直观的用户体验。一方面，操作人员需要完全的灵活性和配置额外触发器和完全定制通知消息的能力，而最终用户只需要应用注释来订阅触发器和指定接收者。你可以在Argo CD 通知文档[9]中了解更多关于触发器和模板的附加特性。

如果你一直认真地遵循这个练习，你可能已经注意到我们没有真正地配置 on-sync-succeeded 触发器和 app-sync-succeeded 模板。那么它们从何而来？我们从触发器和模板目录中获取了它们，这些目录包含了一系列有用的触发器和 Argo CD 模板。当我们使用以下命令配置 Argo CD Notifications 控制器时，目录已经安装好了：

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/catalog/install.yaml

目录描述可以在 Argo CD Notifications 文档中找到，并在argoproj-labs/argocd-notifications[10]仓库的 catalog 目录中定义。

接下来是？

通过 Argo Notifications，你可以做更多的事情。webhook 的集成是最令人兴奋的特性之一。webhook 支持有趣的用例，比如更好地与 Github 集成、触发 Jenkins jobs 等等。如果设置有任何问题，有一个 CLI 工具可以简化故障排除[11]。

如你所见，通知提供了一种与用户和其他服务交互的很好的方式！目前，通知功能只支持 Argo CD，但很快其他 Argo 项目也会支持。请敬请期待！

感谢 Ed Lee 和 Henrik Blixt。

参考资料

[1]

设计: https://docs.google.com/document/d/1nw0i7EAehNnjEkbpx-I3BVjfZvRgetUFUZby4iMUSWU/edit#heading=h.efmu907hcczu

[2]

https://kubernetes.io/docs/setup/: https://kubernetes.io/docs/setup/

[3]

https://argoproj.github.io/argo-cd/getting_started/: https://argoproj.github.io/argo-cd/getting_started/

[4]

项目: https://github.com/argoproj-labs/argocd-notifications

[5]

入门指南: https://argocd-notifications.readthedocs.io/en/latest/

[6]

Argo CD Notifications 文档: https://argocd-notifications.readthedocs.io/en/latest/services/overview/

[7]

https://myaccount.google.com/apppasswords: https://myaccount.google.com/apppasswords

[8]

https://support.google.com/accounts/answer/185833?hl=en: https://support.google.com/accounts/answer/185833?hl=en

[9]

Argo CD 通知文档: https://argocd-notifications.readthedocs.io/en/latest/triggers/

[10]

argoproj-labs/argocd-notifications: https://github.com/argoproj-labs/argocd-notifications

[11]

故障排除: https://argocd-notifications.readthedocs.io/en/latest/troubleshooting/