Skip to content

v0.x to v1.0

The v1.0 release introduces a lot of new features and changes the format of configuration settings to improve usability. However, most of the pre-v1.0 settings and annotations are still supported. So you can upgrade with a minimal set of manual changes and migrate to new settings gradually.

Breaking Changes

This section lists breaking changes that could not be done in a backward compatible way and corresponding upgrade steps:

Built-in triggers and templates are removed

Built-in (hard-coded) triggers and template were replaced with catalog.

Why was it changed?

The built-in triggers and templates were meant to simplify onboarding. Instead of configuring everything from scratch user could just use triggers and templates developed by the community. However one set of triggers and templates don't work for everyone. So instead of baking it into binary triggers and templates now can be distributed as a simple YAML file. All built-in triggers and templates were moved into catalog/install.yaml

After upgrading make sure to either kubectl apply it:

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

or include as a patch into your kustomization.yaml file:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
- https://github.com/argoproj-labs/argocd-notifications/manifests/bot?ref=release-1.0

patchesStrategicMerge:
- https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/catalog/install.yaml

Webhook Subscriptions

The webhook recipient annotation value had special format: webhook:<webhook-name> (e.g. on-app-synced.recipients.argocd-notifications.argoproj.io: webhook:github). In v1.0 the annotation value has to change to just github and webhook: prefix should be removed.

Why was it changed?

Previous way to configure notification services did not allow to give a custom service name, so you could configure only one Slack or email integation. The webhook was an exception and relied on webhook:<name> format to support multiple webhook types. The v1.0 allows giving a custom name to any service and exception for webhook no longer required.

Upgrading To New Settings and Annotations

Notification Services

The notifiers.yaml key of argocd-notifications-secret is replaced with service.<service-type>(.<service-name>) keys in argocd-notifications-cm ConfigMap.

Why was it changed?

The change allows to provide custom name to any service and enables support for more than one Slack/Email etc integation.

Before

apiVersion: v1
kind: Secret
metadata:
  name: argocd-notifications-secret
stringData:
  notifiers.yaml: |
    email:
      host: smtp.gmail.com
      port: 587
      from: <myemail>@gmail.com
      username: <myemail>@gmail.com
      password: <mypassword>

After

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

Sensitive values like tokens and password are still stored in argocd-notifications-secret Secret and can be referenced as $<key-name>.

Custom Triggers and Templates

Why was it changed?

The change allows to distribute templates and triggers as ConfigMap merge patch and enables templates/triggers catalogs.

The custom triggers and templates are no longer stored in config.yaml format. Instead you can use trigger.<trigger-name> and template.<template-name> keys.

Before

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
data:
  config.yaml: |
    triggers:
      - name: on-sync-status-unknown
        condition: app.status.sync.status == 'Unknown'
        template: app-sync-status
        enabled: true
    templates:
      - name: app-sync-status
        title: Application {{.app.metadata.name}} sync status is {{.app.status.sync.status}}
        body: |
          Application {{.app.metadata.name}} sync is {{.app.status.sync.status}}.
          Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}.

After

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
data:
  # Triggers define the condition when the notification should be sent and list of templates required to generate the message
  # Recipients can subscribe to the trigger and specify the required message template and destination notification service.
  trigger.on-sync-status-unknown: |
    - when: app.status.sync.status == 'Unknown'
      send: [my-custom-template]
  # Templates are used to generate the notification template message
  template.app-sync-status: |
    message: |
      Application {{.app.metadata.name}} sync is {{.app.status.sync.status}}.
      Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}.
    email:
      subject: Application {{.app.metadata.name}} sync status is {{.app.status.sync.status}}

Trigger Definition

Trigger fields has changed. The v1.0 trigger might include multiple conditions and multiple templates in each condition.

Why was it changed?

Multiple conditions allows to create condition bundles that improves user experience.

Before

name: on-sync-status-unknown
condition: app.status.sync.status == 'Unknown'
template: app-sync-status
enabled: true

After

- when: app.status.sync.status == 'Unknown'
  send: [my-custom-template]

Template Definition

Template title and body fields have been replaced with message field.

Before

title: Application {{.app.metadata.name}} sync status is {{.app.status.sync.status}}
body: |
  Application {{.app.metadata.name}} sync is {{.app.status.sync.status}}.
  Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}.

After

message: |
  Application {{.app.metadata.name}} sync is {{.app.status.sync.status}}.
  Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}.
email:
  subject: Application {{.app.metadata.name}} sync status is {{.app.status.sync.status}}

Why was it changed?

The only service that uses title is Email/SMTP notification service. So that field was causing confusion. To remove the confusion body field was renamed to message and title became Email specific field email.subject.

Recipient/Subscription Annotation

The <trigger-name>.recipients.argocd-notifications.argoproj.io: <service>:<recipient> annotation has been replaced with notifications.argoproj.io/subscribe.<trigger>.<service>: <recipient> annotation.

Why was it changed?

The goal is to generalize Argo CD Notifications settings and reuse the same format in other Argo projects. So we've reworked the annotation and removed argocd-notifications part.

Before

on-app-synced.recipients.argocd-notifications.argoproj.io: slack:my-channel

After

notifications.argoproj.io/subscribe.on-app-synched.slack: my-channel