cd/docs/operator-manual/notifications/index.md

Notifications Overview

Hanzo CD Notifications continuously monitors Hanzo CD applications and provides a flexible way to notify users about important changes in the application state. Using a flexible mechanism of triggers and templates you can configure when the notification should be sent as well as notification content. Hanzo CD Notifications includes the catalog of useful triggers and templates. So you can just use them instead of reinventing new ones.

Getting Started

• Install Triggers and Templates from the catalog

  kubectl apply -n cd --server-side --force-conflicts -f https://raw.githubusercontent.com/hanzoai/cd/main/notifications_catalog/install.yaml
  

• Add email username and password token to the cd-notifications-secret secret

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

• Register email notification service

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

• Subscribe to notifications by adding the notifications.apps.hanzo.ai/subscribe.on-sync-succeeded.slack annotation to the Hanzo CD application or project:

  kubectl patch app <my-app> -n cd -p '{"metadata": {"annotations": {"notifications.apps.hanzo.ai/subscribe.on-sync-succeeded.slack":"<my-channel>"}}}' --type merge
  

Try syncing an application to get notified when the sync is completed.

Namespace based configuration

A common installation method for Hanzo CD Notifications is to install it in a dedicated namespace to manage a whole cluster. In this case, the administrator is the only person who can configure notifications in that namespace generally. However, in some cases, it is required to allow end-users to configure notifications for their Hanzo CD applications. For example, the end-user can configure notifications for their Hanzo CD application in the namespace where they have access to and their Hanzo CD application is running in.

This feature is based on applications in any namespace. See applications in any namespace page for more information.

In order to enable this feature, the Hanzo CD administrator must reconfigure the cd-notification-controller workloads to add --application-namespaces and --self-service-notification-enabled parameters to the container's startup command. --application-namespaces controls the list of namespaces that Hanzo CD applications are in. --self-service-notification-enabled turns on this feature.

The startup parameters for both can also be conveniently set up and kept in sync by specifying the application.namespaces and notificationscontroller.selfservice.enabled in the cd-cmd-params-cm ConfigMap instead of changing the manifests for the respective workloads. For example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cd-cmd-params-cm
data:
  application.namespaces: app-team-one, app-team-two
  notificationscontroller.selfservice.enabled: "true"

Other notifications controller startup settings can be managed the same way. For notifications-heavy installations, notificationscontroller.processors.count configures the worker concurrency and maps to the --processors-count startup flag. For example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cd-cmd-params-cm
data:
  notificationscontroller.processors.count: "4"

To use this feature, you can deploy configmap named cd-notifications-cm and possibly a secret cd-notifications-secret in the namespace where the Hanzo CD application lives.

When it is configured this way the controller will send notifications using both the controller level configuration (the configmap located in the same namespaces as the controller) as well as the configuration located in the same namespace where the Hanzo CD application is at.

Example: Application team wants to receive notifications using PagerDutyV2, when the controller level configuration is only supporting Slack.

The following two resources are deployed in the namespace where the Hanzo CD application lives.

apiVersion: v1
kind: ConfigMap
metadata:
  name: cd-notifications-cm
data:
  service.pagerdutyv2: |
    serviceKeys:
      my-service: $pagerduty-key-my-service
...

apiVersion: v1
kind: Secret
metadata:
  name: cd-notifications-secret
type: Opaque
data:
  pagerduty-key-my-service: <pd-integration-key>

When a Hanzo CD application has the following subscriptions, user receives application sync failure message from pager duty.

apiVersion: apps.hanzo.ai/v1alpha1
kind: Application
metadata:
  annotations:
    notifications.apps.hanzo.ai/subscribe.on-sync-failed.pagerdutyv2: "<serviceID for Pagerduty>"

Note

When the same notification service and trigger are defined in controller level configuration and application level configuration, both notifications will be sent according to its own configuration.

Defining and using secrets within notification templates function is not available when flag --self-service-notification-enable is on.