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-synced.slack: my-channel