diff --git a/.readthedocs.yml b/.readthedocs.yml index 7b50ab94..994ee84e 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,4 +1,9 @@ version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.12" formats: all mkdocs: fail_on_warning: false diff --git a/docs/argocd-notifications-cm.yaml b/docs/argocd-notifications-cm.yaml deleted file mode 100644 index 5c6b95a4..00000000 --- a/docs/argocd-notifications-cm.yaml +++ /dev/null @@ -1,95 +0,0 @@ -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] - - # Optional 'oncePer' property ensure that notification is sent only once per specified field value - # E.g. following is triggered once per sync revision - trigger.on-deployed: | - - when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy' - oncePer: app.status.sync.revision - send: [app-sync-succeeded] - - # Templates are used to generate the notification template message - template.my-custom-template: | - message: | - Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}. - - # Templates might have notification service specific fields. E.g. slack message might include annotations - template.my-custom-template-slack-template: | - 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}} - slack: - attachments: | - [{ - "title": "{{.app.metadata.name}}", - "title_link": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#18be52" - }] - - # Holds list of triggers that are used by default if trigger is not specified explicitly in the subscription - defaultTriggers: | - - on-sync-status-unknown - - # Notification services are used to deliver message. - # Service definition might reference values from argocd-notifications-secret Secret using $my-key format - # Service format key is: service.. - # Slack - service.slack: | - token: $slack-token - username: # optional username - icon: # optional icon for the message (supports both emoij and url notation) - - # Slack based notifier with name mattermost - service.slack.mattermost: | - apiURL: https://my-mattermost-url.com/api - token: $slack-token - username: # optional username - icon: # optional icon for the message (supports both emoij and url notation) - - # Email - service.email: | - host: smtp.gmail.com - port: 587 - from: @gmail.com - username: $email-username - password: $email-password - - # Opsgenie - service.opsgenie: | - apiUrl: api.opsgenie.com - apiKeys: - $opsgenie-team-id: $opsgenie-team-api-key - ... - - # Telegram - service.telegram: | - token: $telegram-token - - # Context holds list of variables that can be referenced in templates - context: | - argocdUrl: https://cd.apps.argoproj.io/ - - # Contains centrally managed global application subscriptions - subscriptions: | - # subscription for on-sync-status-unknown trigger notifications - - recipients: - - slack:test2 - - email:test@gmail.com - triggers: - - on-sync-status-unknown - # subscription restricted to applications with matching labels only - - recipients: - - slack:test3 - selector: test=true - triggers: - - on-sync-status-unknown \ No newline at end of file diff --git a/docs/argocd-notifications-secret.yaml b/docs/argocd-notifications-secret.yaml deleted file mode 100644 index 72ed67c5..00000000 --- a/docs/argocd-notifications-secret.yaml +++ /dev/null @@ -1,10 +0,0 @@ -apiVersion: v1 -kind: Secret -metadata: - name: argocd-notifications-secret -stringData: - slack-token: - email-username: @gmail.com - email-password: - -type: Opaque diff --git a/docs/assets/argo.png b/docs/assets/argo.png deleted file mode 100644 index ff6c3a1e..00000000 Binary files a/docs/assets/argo.png and /dev/null differ diff --git a/docs/assets/logo.png b/docs/assets/logo.png deleted file mode 100644 index b9cb18e6..00000000 Binary files a/docs/assets/logo.png and /dev/null differ diff --git a/docs/assets/versions.css b/docs/assets/versions.css deleted file mode 100644 index 03ae8a0c..00000000 --- a/docs/assets/versions.css +++ /dev/null @@ -1,172 +0,0 @@ -.md-header__title { - display: flex; -} - -.dropdown-caret { - display: inline-block !important; - position: absolute; - right: 4px; -} - -.fa .fa-caret-down { - display: none !important; -} - -.rst-other-versions { - text-align: right; -} - -.rst-other-versions > dl, .rst-other-versions dt, .rst-other-versions small { - display: none; -} - -.rst-other-versions > dl:first-child { - display: flex !important; - flex-direction: column; - line-height: 0px !important; -} - -.rst-versions.shift-up .rst-other-versions { - display: flex !important; -} - -.rst-versions .rst-other-versions { - display: none; -} - -/* Version Warning */ -div[data-md-component=announce] { - background-color: rgba(255,145,0,.1); -} -div[data-md-component=announce]>div#announce-msg{ - color: var(--md-admonition-fg-color); - font-size: .8rem; - text-align: center; - margin: 15px; -} -div[data-md-component=announce]>div#announce-msg>a{ - color: var(--md-typeset-a-color); - text-decoration: underline; -} - -/* from https://assets.readthedocs.org/static/css/badge_only.css, -most styles have to be overriden here */ -.rst-versions{ - position: relative !important; - bottom: 0; - left: 0; - width: 100px !important; - background: hsla(173, 100%, 24%, 1) !important; - font-family: inherit !important; - z-index: 0 !important; -} -.rst-versions a{ - color:#2980B9; - text-decoration:none -} -.rst-versions .rst-badge-small{ - display:none -} -.rst-versions .rst-current-version{ - padding:12px; - background: hsla(173, 100%, 24%, 1) !important; - display:block; - text-align:right; - font-size:90%; - cursor:pointer; - color: white !important; - *zoom:1 -} -.rst-versions .rst-current-version:before,.rst-versions .rst-current-version:after{ - display:table;content:"" -} -.rst-versions .rst-current-version:after{ - clear:both -} -.rst-versions .rst-current-version .fa{ - color:#fcfcfc -} -.rst-versions .rst-current-version .fa-caret-down{ - display: none; -} -.rst-versions.shift-up .rst-other-versions{ - display:block -} -.rst-versions .rst-other-versions{ - font-size:90%; - padding:12px; - color:gray; - display:none -} -.rst-versions .rst-other-versions hr{ - display: none !important; - height: 0px !important; - border: 0px; - margin: 0px !important; - padding: 0px; - border-top: none !important; -} -.rst-versions .rst-other-versions dd{ - display:inline-block; - margin:0 -} -.rst-versions .rst-other-versions dd a{ - display:inline-block; - padding: 1em 0em !important; - color:#fcfcfc; - font-size: .6rem !important; - white-space: nowrap; - text-overflow: ellipsis; - overflow: hidden; - width: 80px; -} -.rst-versions .rst-other-versions dd a:hover{ - font-size: .7rem !important; - font-weight: bold; -} -.rst-versions.rst-badge{ - display: block !important; - width: 100px !important; - bottom: 0px !important; - right: 0px !important; - left:auto; - border:none; - text-align: center !important; - line-height: 0; -} -.rst-versions.rst-badge .icon-book{ - display: none; -} -.rst-versions.rst-badge .fa-book{ - display: none !important; -} -.rst-versions.rst-badge.shift-up .rst-current-version{ - text-align: left !important; -} -.rst-versions.rst-badge.shift-up .rst-current-version .fa-book{ - display: none !important; -} -.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{ - display: none !important; -} -.rst-versions.rst-badge .rst-current-version{ - width: 70px !important; - height: 2.4rem !important; - line-height:2.4rem !important; - padding: 0px 5px !important; - display: inline-block !important; - font-size: .6rem !important; - overflow: hidden !important; - text-overflow: ellipsis !important; - white-space: nowrap !important; - text-align: left !important; -} -@media screen and (max-width: 768px){ - .rst-versions{ - width:85%; - display:none - } - .rst-versions.shift{ - display:block - } -} diff --git a/docs/assets/versions.js b/docs/assets/versions.js deleted file mode 100644 index 255307bd..00000000 --- a/docs/assets/versions.js +++ /dev/null @@ -1,43 +0,0 @@ -setTimeout(function() { - const callbackName = 'callback_' + new Date().getTime(); - window[callbackName] = function (response) { - const div = document.createElement('div'); - div.innerHTML = response.html; - document.querySelector(".md-header__inner > .md-header__title").appendChild(div); - const container = div.querySelector('.rst-versions'); - var caret = document.createElement('div'); - caret.innerHTML = "" - caret.classList.add('dropdown-caret') - div.querySelector('.rst-current-version').appendChild(caret); - div.querySelector('.rst-current-version').addEventListener('click', function() { - const classes = container.className.split(' '); - const index = classes.indexOf('shift-up'); - if (index === -1) { - classes.push('shift-up'); - } else { - classes.splice(index, 1); - } - container.className = classes.join(' '); - }); - } - - var CSSLink = document.createElement('link'); - CSSLink.rel='stylesheet'; - CSSLink.href = '/assets/versions.css'; - document.getElementsByTagName('head')[0].appendChild(CSSLink); - - var script = document.createElement('script'); - script.src = 'https://argocd-notifications.readthedocs.io/_/api/v2/footer_html/?'+ - 'callback=' + callbackName + '&project=argocd-notifications&page=&theme=mkdocs&format=jsonp&docroot=docs&source_suffix=.md&version=' + (window['READTHEDOCS_DATA'] || { version: 'latest' }).version; - document.getElementsByTagName('head')[0].appendChild(script); - }, 0); - - // VERSION WARNINGS -window.addEventListener("DOMContentLoaded", function() { - if ((window['READTHEDOCS_DATA']).version === "latest") { - document.querySelector("div[data-md-component=announce]").innerHTML = "
You are viewing the docs for an unreleased version of Argo CD, click here to go to the latest stable version.
" - } - else if ((window['READTHEDOCS_DATA']).version !== "stable") { - document.querySelector("div[data-md-component=announce]").innerHTML = "
You are viewing the docs for a previous version of Argo CD, click here to go to the latest stable version.
" - } - }); diff --git a/docs/bots/opsgenie-bot.md b/docs/bots/opsgenie-bot.md deleted file mode 100644 index 6ae36c84..00000000 --- a/docs/bots/opsgenie-bot.md +++ /dev/null @@ -1,12 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/). Redirecting to the new page. - -# Opsgenie bot - -!!! note "Do you need Opsgenie bot? Please consider contributing or create [feature request](https://github.com/argoproj-labs/argocd-notifications/issues/new)!" - - -
- \ No newline at end of file diff --git a/docs/bots/overview.md b/docs/bots/overview.md deleted file mode 100644 index 45eb4898..00000000 --- a/docs/bots/overview.md +++ /dev/null @@ -1,20 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/). Redirecting to the new page. - -The optional bot component simplifies managing subscriptions. The end users can use bot commands to manage subscriptions -even if they don't have access to the Kubernetes API and cannot modify annotations. - -The bot is not installed by default. Use the `install-bot.yaml` to intall it: - -``` -kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/stable/manifests/install-bot.yaml -``` - -!!! note - You can edit deployment and change some arguments such as `--port`, `--namespace` or `slack-path`flag in `argocd-notifications-controller` deployment. - -* [Slack bot](./slack-bot.md) -* [Opsgenie bot](./opsgenie-bot.md) -* [Telegram bot](./telegram-bot.md) \ No newline at end of file diff --git a/docs/bots/slack-bot.md b/docs/bots/slack-bot.md deleted file mode 100644 index c0ad127d..00000000 --- a/docs/bots/slack-bot.md +++ /dev/null @@ -1,38 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/). Redirecting to the new page. - -# Slack bot - -The Slack bot leverages [slash commands](https://api.slack.com/interactivity/slash-commands). The bot allows slack users -to view existing channel subscriptions and subscribe or unsubscribe channels. - -1. Make sure bot component is [installed](./overview.md). -1. Configure slack [integration](../services/slack.md). -1. In the slack application settings page navigate to the 'Slash Commands' section and click 'Create New Command' button. -1. Fill in new slack command details -![image](https://user-images.githubusercontent.com/426437/75645798-2e022480-5bfc-11ea-8682-5ce362bdcc9a.png) -1. In the slack application settings page navigate to the 'Basic Information' section and copy 'Signing Secret' from the 'App Credentials' section. -1. Add `signingSecret` to the slack configuration. - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - service.slack: - token: $slack-token - signingSecret: $slack-signing-secret -``` - -## Commands - -The bot supports following commands: - -* `list-subscriptions` - list channel subscriptions -* `subscribe ` - subscribes channel to the app notifications -* `subscribe proj: ` - subscribes channel to the app project notifications -* `unsubscribe ` - unsubscribes channel from the app notifications -* `unsubscribe proj: ` - unsubscribes channel from the app project notifications \ No newline at end of file diff --git a/docs/bots/telegram-bot.md b/docs/bots/telegram-bot.md deleted file mode 100644 index 832aa1cc..00000000 --- a/docs/bots/telegram-bot.md +++ /dev/null @@ -1,12 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/). Redirecting to the new page. - -# Telegram bot - -!!! note "Do you need Telegram bot? Please consider contributing or create [feature request](https://github.com/argoproj-labs/argocd-notifications/issues/new)!" - - -
- \ No newline at end of file diff --git a/docs/catalog.md b/docs/catalog.md deleted file mode 100644 index 2a663224..00000000 --- a/docs/catalog.md +++ /dev/null @@ -1,525 +0,0 @@ -# Triggers and Templates Catalog -## Triggers -| NAME | DESCRIPTION | TEMPLATE | -|------------------------|---------------------------------------------------------------|-----------------------------------------------------| -| on-created | Application is created. | [app-created](#app-created) | -| on-deleted | Application is deleted. | [app-deleted](#app-deleted) | -| on-deployed | Application is synced and healthy. Triggered once per commit. | [app-deployed](#app-deployed) | -| on-health-degraded | Application has degraded | [app-health-degraded](#app-health-degraded) | -| on-sync-failed | Application syncing has failed | [app-sync-failed](#app-sync-failed) | -| on-sync-running | Application is being synced | [app-sync-running](#app-sync-running) | -| on-sync-status-unknown | Application status is 'Unknown' | [app-sync-status-unknown](#app-sync-status-unknown) | -| on-sync-succeeded | Application syncing has succeeded | [app-sync-succeeded](#app-sync-succeeded) | - -## Templates -### app-created -**definition**: -```yaml -email: - subject: Application {{.app.metadata.name}} has been created. -message: Application {{.app.metadata.name}} has been created. -teams: - title: Application {{.app.metadata.name}} has been created. - -``` -### app-deleted -**definition**: -```yaml -email: - subject: Application {{.app.metadata.name}} has been deleted. -message: Application {{.app.metadata.name}} has been deleted. -teams: - title: Application {{.app.metadata.name}} has been deleted. - -``` -### app-deployed -**definition**: -```yaml -email: - subject: New version of an application {{.app.metadata.name}} is up and running. -message: | - {{if eq .serviceType "slack"}}:white_check_mark:{{end}} Application {{.app.metadata.name}} is now running new version of deployments manifests. -slack: - attachments: | - [{ - "title": "{{ .app.metadata.name}}", - "title_link":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#18be52", - "fields": [ - { - "title": "Sync Status", - "value": "{{.app.status.sync.status}}", - "short": true - }, - { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - }, - { - "title": "Revision", - "value": "{{.app.status.sync.revision}}", - "short": true - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "title": "{{$c.type}}", - "value": "{{$c.message}}", - "short": true - } - {{end}} - ] - }] - groupingKey: "" - notifyBroadcast: false -teams: - facts: | - [{ - "name": "Sync Status", - "value": "{{.app.status.sync.status}}" - }, - { - "name": "Repository", - "value": "{{.app.spec.source.repoURL}}" - }, - { - "name": "Revision", - "value": "{{.app.status.sync.revision}}" - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "name": "{{$c.type}}", - "value": "{{$c.message}}" - } - {{end}} - ] - potentialAction: |- - [{ - "@type":"OpenUri", - "name":"Operation Application", - "targets":[{ - "os":"default", - "uri":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}" - }] - }, - { - "@type":"OpenUri", - "name":"Open Repository", - "targets":[{ - "os":"default", - "uri":"{{.app.spec.source.repoURL | call .repo.RepoURLToHTTPS}}" - }] - }] - themeColor: '#000080' - title: New version of an application {{.app.metadata.name}} is up and running. - -``` -### app-health-degraded -**definition**: -```yaml -email: - subject: Application {{.app.metadata.name}} has degraded. -message: | - {{if eq .serviceType "slack"}}:exclamation:{{end}} Application {{.app.metadata.name}} has degraded. - Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}. -slack: - attachments: | - [{ - "title": "{{ .app.metadata.name}}", - "title_link": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#f4c030", - "fields": [ - { - "title": "Health Status", - "value": "{{.app.status.health.status}}", - "short": true - }, - { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "title": "{{$c.type}}", - "value": "{{$c.message}}", - "short": true - } - {{end}} - ] - }] - groupingKey: "" - notifyBroadcast: false -teams: - facts: | - [{ - "name": "Health Status", - "value": "{{.app.status.health.status}}" - }, - { - "name": "Repository", - "value": "{{.app.spec.source.repoURL}}" - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "name": "{{$c.type}}", - "value": "{{$c.message}}" - } - {{end}} - ] - potentialAction: | - [{ - "@type":"OpenUri", - "name":"Open Application", - "targets":[{ - "os":"default", - "uri":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}" - }] - }, - { - "@type":"OpenUri", - "name":"Open Repository", - "targets":[{ - "os":"default", - "uri":"{{.app.spec.source.repoURL | call .repo.RepoURLToHTTPS}}" - }] - }] - themeColor: '#FF0000' - title: Application {{.app.metadata.name}} has degraded. - -``` -### app-sync-failed -**definition**: -```yaml -email: - subject: Failed to sync application {{.app.metadata.name}}. -message: | - {{if eq .serviceType "slack"}}:exclamation:{{end}} The sync operation of application {{.app.metadata.name}} has failed at {{.app.status.operationState.finishedAt}} with the following error: {{.app.status.operationState.message}} - Sync operation details are available at: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}?operation=true . -slack: - attachments: | - [{ - "title": "{{ .app.metadata.name}}", - "title_link":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#E96D76", - "fields": [ - { - "title": "Sync Status", - "value": "{{.app.status.sync.status}}", - "short": true - }, - { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "title": "{{$c.type}}", - "value": "{{$c.message}}", - "short": true - } - {{end}} - ] - }] - groupingKey: "" - notifyBroadcast: false -teams: - facts: | - [{ - "name": "Sync Status", - "value": "{{.app.status.sync.status}}" - }, - { - "name": "Failed at", - "value": "{{.app.status.operationState.finishedAt}}" - }, - { - "name": "Repository", - "value": "{{.app.spec.source.repoURL}}" - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "name": "{{$c.type}}", - "value": "{{$c.message}}" - } - {{end}} - ] - potentialAction: |- - [{ - "@type":"OpenUri", - "name":"Open Operation", - "targets":[{ - "os":"default", - "uri":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}?operation=true" - }] - }, - { - "@type":"OpenUri", - "name":"Open Repository", - "targets":[{ - "os":"default", - "uri":"{{.app.spec.source.repoURL | call .repo.RepoURLToHTTPS}}" - }] - }] - themeColor: '#FF0000' - title: Failed to sync application {{.app.metadata.name}}. - -``` -### app-sync-running -**definition**: -```yaml -email: - subject: Start syncing application {{.app.metadata.name}}. -message: | - The sync operation of application {{.app.metadata.name}} has started at {{.app.status.operationState.startedAt}}. - Sync operation details are available at: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}?operation=true . -slack: - attachments: | - [{ - "title": "{{ .app.metadata.name}}", - "title_link":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#0DADEA", - "fields": [ - { - "title": "Sync Status", - "value": "{{.app.status.sync.status}}", - "short": true - }, - { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "title": "{{$c.type}}", - "value": "{{$c.message}}", - "short": true - } - {{end}} - ] - }] - groupingKey: "" - notifyBroadcast: false -teams: - facts: | - [{ - "name": "Sync Status", - "value": "{{.app.status.sync.status}}" - }, - { - "name": "Started at", - "value": "{{.app.status.operationState.startedAt}}" - }, - { - "name": "Repository", - "value": "{{.app.spec.source.repoURL}}" - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "name": "{{$c.type}}", - "value": "{{$c.message}}" - } - {{end}} - ] - potentialAction: |- - [{ - "@type":"OpenUri", - "name":"Open Operation", - "targets":[{ - "os":"default", - "uri":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}?operation=true" - }] - }, - { - "@type":"OpenUri", - "name":"Open Repository", - "targets":[{ - "os":"default", - "uri":"{{.app.spec.source.repoURL | call .repo.RepoURLToHTTPS}}" - }] - }] - title: Start syncing application {{.app.metadata.name}}. - -``` -### app-sync-status-unknown -**definition**: -```yaml -email: - subject: Application {{.app.metadata.name}} sync status is 'Unknown' -message: | - {{if eq .serviceType "slack"}}:exclamation:{{end}} Application {{.app.metadata.name}} sync is 'Unknown'. - Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}. - {{if ne .serviceType "slack"}} - {{range $c := .app.status.conditions}} - * {{$c.message}} - {{end}} - {{end}} -slack: - attachments: | - [{ - "title": "{{ .app.metadata.name}}", - "title_link":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#E96D76", - "fields": [ - { - "title": "Sync Status", - "value": "{{.app.status.sync.status}}", - "short": true - }, - { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "title": "{{$c.type}}", - "value": "{{$c.message}}", - "short": true - } - {{end}} - ] - }] - groupingKey: "" - notifyBroadcast: false -teams: - facts: | - [{ - "name": "Sync Status", - "value": "{{.app.status.sync.status}}" - }, - { - "name": "Repository", - "value": "{{.app.spec.source.repoURL}}" - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "name": "{{$c.type}}", - "value": "{{$c.message}}" - } - {{end}} - ] - potentialAction: |- - [{ - "@type":"OpenUri", - "name":"Open Application", - "targets":[{ - "os":"default", - "uri":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}" - }] - }, - { - "@type":"OpenUri", - "name":"Open Repository", - "targets":[{ - "os":"default", - "uri":"{{.app.spec.source.repoURL | call .repo.RepoURLToHTTPS}}" - }] - }] - title: Application {{.app.metadata.name}} sync status is 'Unknown' - -``` -### app-sync-succeeded -**definition**: -```yaml -email: - subject: Application {{.app.metadata.name}} has been successfully synced. -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: - attachments: | - [{ - "title": "{{ .app.metadata.name}}", - "title_link":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#18be52", - "fields": [ - { - "title": "Sync Status", - "value": "{{.app.status.sync.status}}", - "short": true - }, - { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "title": "{{$c.type}}", - "value": "{{$c.message}}", - "short": true - } - {{end}} - ] - }] - groupingKey: "" - notifyBroadcast: false -teams: - facts: | - [{ - "name": "Sync Status", - "value": "{{.app.status.sync.status}}" - }, - { - "name": "Synced at", - "value": "{{.app.status.operationState.finishedAt}}" - }, - { - "name": "Repository", - "value": "{{.app.spec.source.repoURL}}" - } - {{range $index, $c := .app.status.conditions}} - {{if not $index}},{{end}} - {{if $index}},{{end}} - { - "name": "{{$c.type}}", - "value": "{{$c.message}}" - } - {{end}} - ] - potentialAction: |- - [{ - "@type":"OpenUri", - "name":"Operation Details", - "targets":[{ - "os":"default", - "uri":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}?operation=true" - }] - }, - { - "@type":"OpenUri", - "name":"Open Repository", - "targets":[{ - "os":"default", - "uri":"{{.app.spec.source.repoURL | call .repo.RepoURLToHTTPS}}" - }] - }] - themeColor: '#000080' - title: Application {{.app.metadata.name}} has been successfully synced - -``` diff --git a/docs/demo.gif b/docs/demo.gif deleted file mode 100644 index 345b8eb4..00000000 Binary files a/docs/demo.gif and /dev/null differ diff --git a/docs/functions.md b/docs/functions.md deleted file mode 100644 index 468a33d8..00000000 --- a/docs/functions.md +++ /dev/null @@ -1,88 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/functions//](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/functions//). Redirecting to the new page. - -### **time** - -Time related functions. - -
-**`time.Now() Time`** - -Executes function built-in Golang [time.Now](https://golang.org/pkg/time/#Now) function. Returns an instance of -Golang [Time](https://golang.org/pkg/time/#Time). - -
-**`time.Parse(val string) Time`** - -Parses specified string using RFC3339 layout. Returns an instance of Golang [Time](https://golang.org/pkg/time/#Time). - -### **strings** - -String related functions. - -
-**`strings.ReplaceAll() string`** - -Executes function built-in Golang [strings.ReplaceAll](https://pkg.go.dev/strings#ReplaceAll) function. - -
-**`strings.ToUpper() string`** - -Executes function built-in Golang [strings.ToUpper](https://pkg.go.dev/strings#ToUpper) function. - -
-**`strings.ToLower() string`** - -Executes function built-in Golang [strings.ToLower](https://pkg.go.dev/strings#ToLower) function. - -### **sync** - -
-**`sync.GetInfoItem(app map, name string) string`** - -Returns the `info` item value by given name stored in the Argo CD App sync operation. - -### **repo** - -Functions that provide additional information about Application source repository. -
-**`repo.RepoURLToHTTPS(url string) string`** - -Transforms given GIT URL into HTTPs format. - -
-**`repo.FullNameByRepoURL(url string) string`** - -Returns repository URL full name `(/)`. Currently supports only Github, Gitlab and Bitbucket. - -
-**`repo.GetCommitMetadata(sha string) CommitMetadata`** - -Returns commit metadata. The commit must belong to the application source repository. `CommitMetadata` fields: - -* `Message string` commit message -* `Author string` - commit author -* `Date time.Time` - commit creation date -* `Tags []string` - Associated tags - -
-**`repo.GetAppDetails() AppDetail`** - -Returns application details. `AppDetail` fields: - -* `Type string` - AppDetail type -* `Helm HelmAppSpec` - Helm details - * Fields : - * `Name string` - * `ValueFiles []string` - * `Parameters []*v1alpha1.HelmParameter` - * `Values string` - * `FileParameters []*v1alpha1.HelmFileParameter` - * Methods : - * `GetParameterValueByName(Name string)` Retrieve value by name in Parameters field - * `GetFileParameterPathByName(Name string)` Retrieve path by name in FileParameters field -* `Ksonnet *apiclient.KsonnetAppSpec` - Ksonnet details -* `Kustomize *apiclient.KustomizeAppSpec` - Kustomize details -* `Directory *apiclient.DirectoryAppSpec` - Directory details diff --git a/docs/grafana-dashboard.json b/docs/grafana-dashboard.json deleted file mode 100644 index 5d04f911..00000000 --- a/docs/grafana-dashboard.json +++ /dev/null @@ -1,305 +0,0 @@ -{ - "annotations": { - "list": [ - { - "builtIn": 1, - "datasource": "-- Grafana --", - "enable": true, - "hide": true, - "iconColor": "rgba(0, 211, 255, 1)", - "name": "Annotations & Alerts", - "type": "dashboard" - } - ] - }, - "editable": true, - "gnetId": null, - "graphTooltip": 0, - "id": 4, - "iteration": 1589141097815, - "links": [], - "panels": [ - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": "$datasource", - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 12, - "x": 0, - "y": 0 - }, - "hiddenSeries": false, - "id": 4, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(argocd_notifications_trigger_eval_total[$interval])) by (notifier)", - "refId": "A" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Trigger Evaluations", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": "$datasource", - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 12, - "x": 12, - "y": 0 - }, - "hiddenSeries": false, - "id": 2, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(argocd_notifications_deliveries_total[$interval])) by (notifier)", - "refId": "A" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Notification deliveries", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - } - ], - "schemaVersion": 21, - "style": "dark", - "tags": [], - "templating": { - "list": [ - { - "current": { - "text": "Prometheus", - "value": "Prometheus" - }, - "hide": 0, - "includeAll": false, - "label": null, - "multi": false, - "name": "datasource", - "options": [], - "query": "prometheus", - "refresh": 1, - "regex": "", - "skipUrlSync": false, - "type": "datasource" - }, - { - "auto": true, - "auto_count": 30, - "auto_min": "10s", - "current": { - "selected": false, - "text": "1m", - "value": "1m" - }, - "hide": 0, - "label": null, - "name": "interval", - "options": [ - { - "selected": false, - "text": "auto", - "value": "$__auto_interval_interval" - }, - { - "selected": true, - "text": "1m", - "value": "1m" - }, - { - "selected": false, - "text": "5m", - "value": "5m" - }, - { - "selected": false, - "text": "10m", - "value": "10m" - }, - { - "selected": false, - "text": "30m", - "value": "30m" - }, - { - "selected": false, - "text": "1h", - "value": "1h" - }, - { - "selected": false, - "text": "2h", - "value": "2h" - }, - { - "selected": false, - "text": "4h", - "value": "4h" - }, - { - "selected": false, - "text": "8h", - "value": "8h" - } - ], - "query": "1m,5m,10m,30m,1h,2h,4h,8h", - "refresh": 2, - "skipUrlSync": false, - "type": "interval" - } - ] - }, - "time": { - "from": "now-15m", - "to": "now" - }, - "timepicker": { - "refresh_intervals": [ - "5s", - "10s", - "30s", - "1m", - "5m", - "15m", - "30m", - "1h", - "2h", - "1d" - ] - }, - "timezone": "", - "title": "Argo CD Notifications", - "uid": "3qXvXigMz", - "version": 1 -} \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 7e9ca233..10e15d33 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,118 +1 @@ - -!!! important "This page has moved" - Warning. Argo notifications has been merged with the Argo CD project. You do not need to install it separately anymore. It is now part of the main Argo CD installation See https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/ for latest docs. - - -# Overview - -Argo CD Notifications continuously monitors Argo CD applications and provides a flexible way to notify -users about important changes in the application state. Using a flexible mechanism of -[triggers](./triggers.md) and [templates](./templates.md) you can configure when the notification should be sent as -well as notification content. Argo CD Notifications includes the [catalog](./catalog.md) of useful triggers and templates. -So you can just use them instead of reinventing new ones. - -## Getting Started - -* Install Argo CD Notifications - -``` -kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/v1.1.0/manifests/install.yaml -``` - -* Install Triggers and Templates from the catalog - -``` -kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/v1.1.0/catalog/install.yaml -``` - -* Add Email username and password token to `argocd-notifications-secret` secret - -```bash -export EMAIL_USER= -export 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 -``` - -* Register Email notification service - -```bash -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 }" }}' -``` - -* Subscribe to notifications by adding the `notifications.argoproj.io/subscribe.on-sync-succeeded.slack` annotation to the Argo CD application or project: - -```bash -kubectl patch app -n argocd -p '{"metadata": {"annotations": {"notifications.argoproj.io/subscribe.on-sync-succeeded.slack":""}}}' --type merge -``` - -Try syncing and application and get the notification once sync is completed. - -## Kustomize Getting Started - -The argocd-notification manifests can also be installed using [Kustomize](https://kustomize.io/). To install -argocd-notifications, we recommend using the remote kustomize resource: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -namespace: argocd -resources: -- https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/stable/manifests/install.yaml - -patchesStrategicMerge: -- https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/stable/catalog/install.yaml -``` - -## Helm v3 Getting Started - -argocd-notifications is now on [Helm Hub](https://hub.helm.sh/charts/argo/argocd-notifications) as a Helm v3 chart, making it even easier to get started as -installing and configuring happen together: - -```shell -helm repo add argo https://argoproj.github.io/argo-helm -helm install argo/argocd-notifications --generate-name -n argocd -f values.yaml -``` - -```yaml -argocdUrl: https://argocd.example.com - -notifiers: - service.email.gmail: | - username: $email-username - password: $email-password - host: smtp.gmail.com - port: 465 - from: $email-username - -secret: - items: - email-username: - email-password: - -templates: - template.app-deployed: | - email: - subject: New version of an application {{.app.metadata.name}} is up and running. - message: | - {{if eq .serviceType "slack"}}:white_check_mark:{{end}} Application {{.app.metadata.name}} is now running new version of deployments manifests. -triggers: - trigger.on-deployed: | - - description: Application is synced and healthy. Triggered once per commit. - oncePer: app.status.operationState.syncResult.revision - send: - - app-deployed - when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy' -``` - -For more information or to contribute, check out the [argoproj/argo-helm repository](https://github.com/argoproj/argo-helm/tree/master/charts/argocd-notifications). diff --git a/docs/monitoring.md b/docs/monitoring.md deleted file mode 100644 index e6172132..00000000 --- a/docs/monitoring.md +++ /dev/null @@ -1,35 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/monitoring//](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/monitoring//). Redirecting to the new page. - -# Monitoring - -The Argo CD Notification controller serves Prometheus metrics on port 9001. - -!!! note - Metrics port might be changed using the `--metrics-port` flag in `argocd-notifications-controller` deployment. - -## Metrics -The following metrics are available: - -### `argocd_notifications_deliveries_total` - - Number of delivered notifications. - Labels: - -* `template` - notification template name -* `notifier` - notification service name -* `succeeded` - flag that indicates if notification was successfully sent or failed. - -### `argocd_notifications_trigger_eval_total` - - Number of trigger evaluations. - Labels: - -* `name` - trigger name -* `triggered` - flag that indicates if trigger condition returned true of false. - -# Examples: - -* Grafana Dashboard: [grafana-dashboard.json](grafana-dashboard.json) \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 0c06bf58..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,4 +0,0 @@ -mkdocs==1.1.2 -mkdocs-material==7.1.7 -markdown_include==0.6.0 -pygments==2.7.4 diff --git a/docs/services/alertmanager.md b/docs/services/alertmanager.md deleted file mode 100644 index e0f9d7e4..00000000 --- a/docs/services/alertmanager.md +++ /dev/null @@ -1,164 +0,0 @@ -# Alertmanager - -## Parameters - -The notification service is used to push events to [Alertmanager](https://github.com/prometheus/alertmanager), and the following settings need to be specified: - -* `targets` - the alertmanager service address, array type -* `scheme` - optional, default is "http", e.g. http or https -* `apiPath` - optional, default is "/api/v2/alerts" -* `insecureSkipVerify` - optional, default is "false", when scheme is https whether to skip the verification of ca -* `basicAuth` - optional, server auth -* `bearerToken` - optional, server auth -* `timeout` - optional, the timeout in seconds used when sending alerts, default is "3 seconds" - -`basicAuth` or `bearerToken` is used for authentication, you can choose one. If the two are set at the same time, `basicAuth` takes precedence over `bearerToken`. - -## Example - -### Prometheus Alertmanager config - -```yaml -global: - resolve_timeout: 5m - -route: - group_by: ['alertname'] - group_wait: 10s - group_interval: 10s - repeat_interval: 1h - receiver: 'default' -receivers: -- name: 'default' - webhook_configs: - - send_resolved: false - url: 'http://10.5.39.39:10080/api/alerts/webhook' -``` - -You should turn off "send_resolved" or you will receive unnecessary recovery notifications after "resolve_timeout". - -### Send one alertmanager without auth - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.alertmanager: | - targets: - - 10.5.39.39:9093 -``` - -### Send alertmanager cluster with custom api path - -If your alertmanager has changed the default api, you can customize "apiPath". - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.alertmanager: | - targets: - - 10.5.39.39:443 - scheme: https - apiPath: /api/events - insecureSkipVerify: true -``` - -### Send high availability alertmanager with auth - -Store auth token in `argocd-notifications-secret` Secret and use configure in `argocd-notifications-cm` ConfigMap. - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: -stringData: - alertmanager-username: - alertmanager-password: - alertmanager-bearer-token: -``` - -- with basicAuth - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.alertmanager: | - targets: - - 10.5.39.39:19093 - - 10.5.39.39:29093 - - 10.5.39.39:39093 - scheme: https - apiPath: /api/v2/alerts - insecureSkipVerify: true - basicAuth: - username: $alertmanager-username - password: $alertmanager-password -``` - -- with bearerToken - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.alertmanager: | - targets: - - 10.5.39.39:19093 - - 10.5.39.39:29093 - - 10.5.39.39:39093 - scheme: https - apiPath: /api/v2/alerts - insecureSkipVerify: true - bearerToken: $alertmanager-bearer-token -``` - -## Templates - -* `labels` - at least one label pair required, implement different notification strategies according to alertmanager routing -* `annotations` - optional, specifies a set of information labels, which can be used to store longer additional information, but only for display -* `generatorURL` - optional, default is '{{.app.spec.source.repoURL}}', backlink used to identify the entity that caused this alert in the client - -the `label` or `annotations` or `generatorURL` values can be templated. - -```yaml -context: | - argocdUrl: https://example.com/argocd - -template.app-deployed: | - message: Application {{.app.metadata.name}} has been healthy. - alertmanager: - labels: - fault_priority: "P5" - event_bucket: "deploy" - event_status: "succeed" - recipient: "{{.recipient}}" - annotations: - application: '{{.app.metadata.name}}' - author: "{{(call .repo.GetCommitMetadata .app.status.sync.revision).Author}}" - message: "{{(call .repo.GetCommitMetadata .app.status.sync.revision).Message}}" -``` - -You can do targeted push on [Alertmanager](https://github.com/prometheus/alertmanager) according to labels. - -```yaml -template.app-deployed: | - message: Application {{.app.metadata.name}} has been healthy. - alertmanager: - labels: - alertname: app-deployed - fault_priority: "P5" - event_bucket: "deploy" -``` - -There is a special label `alertname`. If you don’t set its value, it will be equal to the template name by default. \ No newline at end of file diff --git a/docs/services/email.md b/docs/services/email.md deleted file mode 100644 index e3c4b7d9..00000000 --- a/docs/services/email.md +++ /dev/null @@ -1,63 +0,0 @@ -# Email - -## Parameters - -The Email notification service sends email notifications using SMTP protocol and requires specifying the following settings: - -* `host` - the SMTP server host name -* `port` - the SMTP server port -* `username` - username -* `password` - password -* `from` - from email address -* `html` - optional bool, true or false -* `insecure_skip_verify` - optional bool, true or false - -## Example - -The following snippet contains sample Gmail service configuration: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.email.gmail: | - username: $email-username - password: $email-password - host: smtp.gmail.com - port: 465 - from: $email-username -``` - -Without authentication: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.email.example: | - host: smtp.example.com - port: 587 - from: $email-username -``` - -## Template - -Notification templates support specifying subject for email notifications: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - template.app-sync-succeeded: | - email: - subject: Application {{.app.metadata.name}} has been successfully synced. - 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 . -``` diff --git a/docs/services/github.md b/docs/services/github.md deleted file mode 100644 index 953e55bd..00000000 --- a/docs/services/github.md +++ /dev/null @@ -1,72 +0,0 @@ -# GitHub - -## Parameters - -The GitHub notification service changes commit status using [GitHub Apps](https://docs.github.com/en/developers/apps) and requires specifying the following settings: - -* `appID` - the app id -* `installationID` - the app installation id -* `privateKey` - the app private key -* `enterpriseBaseURL` - optional URL, e.g. https://git.example.com/ - -## Configuration - -1. Create a GitHub Apps using https://github.com/settings/apps/new -2. Change repository permissions to enable write commit statuses -![2](https://user-images.githubusercontent.com/18019529/108397381-3ca57980-725b-11eb-8d17-5b8992dc009e.png) -3. Generate a private key, and download it automatically -![3](https://user-images.githubusercontent.com/18019529/108397926-d4a36300-725b-11eb-83fe-74795c8c3e03.png) -4. Install app to account -5. Store privateKey in `argocd-notifications-secret` Secret and configure GitHub integration -in `argocd-notifications-cm` ConfigMap - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.github: | - appID: - installationID: - privateKey: $github-privateKey -``` - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: -stringData: - github-privateKey: | - -----BEGIN RSA PRIVATE KEY----- - (snip) - -----END RSA PRIVATE KEY----- -``` - -6. Create subscription for your GitHub integration - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe..github: "" -``` - -## Templates - -![](https://user-images.githubusercontent.com/18019529/108520497-168ce180-730e-11eb-93cb-b0b91f99bdc5.png) - -If the message is set to 140 characters or more, it will be truncate. - -```yaml -template.app-deployed: | - message: | - Application {{.app.metadata.name}} is now running new version of deployments manifests. - github: - status: - state: success - label: "continuous-delivery/{{.app.metadata.name}}" - targetURL: "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}?operation=true" -``` diff --git a/docs/services/googlechat.md b/docs/services/googlechat.md deleted file mode 100644 index 04484691..00000000 --- a/docs/services/googlechat.md +++ /dev/null @@ -1,81 +0,0 @@ -# Google Chat - -## Parameters - -The Google Chat notification service send message notifications to a google chat webhook. This service uses the following settings: - -* `webhooks` - a map of the form `webhookName: webhookUrl` - -## Configuration - -1. Open `Google chat` and go to the space to which you want to send messages -2. From the menu at the top of the page, select **Configure Webhooks** -3. Under **Incoming Webhooks**, click **Add Webhook** -4. Give a name to the webhook, optionally add an image and click **Save** -5. Copy the URL next to your webhook -6. Store the URL in `argocd-notification-secret` and declare it in `argocd-notifications-cm` - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.googlechat: | - webhooks: - spaceName: $space-webhook-url -``` - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: -stringData: - space-webhook-url: https://chat.googleapis.com/v1/spaces//messages?key=&token= -``` - -6. Create a subscription for your space - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe.on-sync-succeeded.googlechat: spaceName -``` - -## Templates - -You can send [simple text](https://developers.google.com/chat/reference/message-formats/basic) or [card messages](https://developers.google.com/chat/reference/message-formats/cards) to a Google Chat space. A simple text message template can be defined as follows: - -```yaml -template.app-sync-succeeded: | - message: The app {{ .app.metadata.name }} has succesfully synced! -``` - -A card message can be defined as follows: - -```yaml -template.app-sync-succeeded: | - googlechat: - cards: | - - header: - title: ArgoCD Bot Notification - sections: - - widgets: - - textParagraph: - text: The app {{ .app.metadata.name }} has succesfully synced! - - widgets: - - keyValue: - topLabel: Repository - content: {{ call .repo.RepoURLToHTTPS .app.spec.source.repoURL }} - - keyValue: - topLabel: Revision - content: {{ .app.spec.source.targetRevision }} - - keyValue: - topLabel: Author - content: {{ (call .repo.GetCommitMetadata .app.status.sync.revision).Author }} -``` - -The card message can be written in JSON too. diff --git a/docs/services/grafana.md b/docs/services/grafana.md deleted file mode 100644 index ff567b71..00000000 --- a/docs/services/grafana.md +++ /dev/null @@ -1,45 +0,0 @@ -# Grafana - -To be able to create Grafana annotation with argocd-notifications you have to create an [API Key](https://grafana.com/docs/grafana/latest/http_api/auth/#create-api-key) inside your [Grafana](https://grafana.com). - -![sample](https://user-images.githubusercontent.com/18019529/112024976-0f106080-8b78-11eb-9658-7663305899be.png) - -1. Login to your Grafana instance as `admin` -2. On the left menu, go to Configuration / API Keys -3. Click "Add API Key" -4. Fill the Key with name `ArgoCD Notification`, role `Editor` and Time to Live `10y` (for example) -5. Click on Add button -6. Store apiKey in `argocd-notifications-secret` Secret and Copy your API Key and define it in `argocd-notifications-cm` ConfigMap - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.grafana: | - apiUrl: https://grafana.example.com/api - apiKey: $grafana-api-key -``` - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: -stringData: - grafana-api-key: api-key -``` - -7. Create subscription for your Grafana integration - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe..grafana: tag1|tag2 # list of tags separated with | -``` - -8. Change the annotations settings -![8](https://user-images.githubusercontent.com/18019529/112022083-47fb0600-8b75-11eb-849b-d25d41925909.png) diff --git a/docs/services/mattermost.md b/docs/services/mattermost.md deleted file mode 100644 index 98e0d0fd..00000000 --- a/docs/services/mattermost.md +++ /dev/null @@ -1,78 +0,0 @@ -# Mattermost - -## Parameters - -* `apiURL` - the server url, e.g. https://mattermost.example.com -* `token` - the bot token -* `insecureSkipVerify` - optional bool, true or false - -## Configuration - -1. Create a bot account and copy token after creating it -![1](https://user-images.githubusercontent.com/18019529/111499520-62ed0500-8786-11eb-88b0-d0aade61fed4.png) -2. Invite team -![2](https://user-images.githubusercontent.com/18019529/111500197-1229dc00-8787-11eb-98e5-587ee36c94a9.png) -3. Store token in `argocd-notifications-secret` Secret and configure Mattermost integration -in `argocd-notifications-cm` ConfigMap - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.mattermost: | - apiURL: - token: $mattermost-token -``` - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: -stringData: - mattermost-token: token -``` - -4. Copy channel id -![4](https://user-images.githubusercontent.com/18019529/111501289-333efc80-8788-11eb-9731-8353170cd73a.png) - -5. Create subscription for your Mattermost integration - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe..mattermost: -``` - -## Templates - -![](https://user-images.githubusercontent.com/18019529/111502636-5fa74880-8789-11eb-97c5-5eac22c00a37.png) - -You can reuse the template of slack. -Mattermost is compatible with attachments of Slack. See [Mattermost Integration Guide](https://docs.mattermost.com/developer/message-attachments.html). - -```yaml -template.app-deployed: | - message: | - Application {{.app.metadata.name}} is now running new version of deployments manifests. - mattermost: - attachments: | - [{ - "title": "{{.app.metadata.name}}", - "title_link": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#18be52", - "fields": [{ - "title": "Sync Status", - "value": "{{.app.status.sync.status}}", - "short": true - }, { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - }] - }] -``` diff --git a/docs/services/opsgenie.md b/docs/services/opsgenie.md deleted file mode 100644 index 665d0081..00000000 --- a/docs/services/opsgenie.md +++ /dev/null @@ -1,28 +0,0 @@ -# Opsgenie - -To be able to send notifications with argocd-notifications you have to create an [API Integration](https://docs.opsgenie.com/docs/integrations-overview) inside your [Opsgenie Team](https://docs.opsgenie.com/docs/teams). - -1. Login to Opsgenie at https://app.opsgenie.com or https://app.eu.opsgenie.com (if you have an account in the european union) -2. Make sure you already have a team, if not follow this guide https://docs.opsgenie.com/docs/teams -3. Click "Teams" in the Menu on the left -4. Select the team that you want to notify -5. In the teams configuration menu select "Integrations" -6. click "Add Integration" in the top right corner -7. Select "API" integration -8. Give your integration a name, copy the "API key" and safe it somewhere for later -9. Make sure the checkboxes for "Create and Update Access" and "enable" are selected, disable the other checkboxes to remove unnecessary permissions -10. Click "Safe Integration" at the bottom -11. Check your browser for the correct server apiURL. If it is "app.opsgenie.com" then use the us/international api url `api.opsgenie.com` in the next step, otherwise use `api.eu.opsgenie.com` (european api). -12. You are finished with configuring opsgenie. Now you need to configure argocd-notifications. Use the apiUrl, the team name and the apiKey to configure the opsgenie integration in the `argocd-notifications-secret` secret. - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.opsgenie: | - apiUrl: - apiKeys: - : -``` \ No newline at end of file diff --git a/docs/services/overview.md b/docs/services/overview.md deleted file mode 100644 index 15e674f6..00000000 --- a/docs/services/overview.md +++ /dev/null @@ -1,53 +0,0 @@ -The notification services represent integration with services such as slack, email or custom webhook. Services are configured in `argocd-notifications-cm` ConfigMap -using `service..()` keys and might reference sensitive data from `argocd-notifications-secret` Secret. Following example demonstrates slack -service configuration: - -```yaml - service.slack: | - token: $slack-token -``` - - -The `slack` indicates that service sends slack notification; name is missing and defaults to `slack`. - -## Sensitive Data - -Sensitive data like authentication tokens should be stored in `` Secret and can be referenced in -service configuration using `$` format. For example `$slack-token` referencing value of key `slack-token` in -`` Secret. - -## Custom Names - -Service custom names allow configuring two instances of the same service type. - -```yaml - service.slack.workspace1: | - token: $slack-token-workspace1 - service.slack.workspace2: | - token: $slack-token-workspace2 -``` - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe.on-sync-succeeded.workspace1: my-channel - notifications.argoproj.io/subscribe.on-sync-succeeded.workspace2: my-channel -``` - -## Service Types - -* [Email](./email.md) -* [GitHub](./github.md) -* [Slack](./slack.md) -* [Mattermost](./mattermost.md) -* [Opsgenie](./opsgenie.md) -* [Grafana](./grafana.md) -* [Webhook](./webhook.md) -* [Telegram](./telegram.md) -* [Teams](./teams.md) -* [Google Chat](./googlechat.md) -* [Rocket.Chat](./rocketchat.md) -* [Pushover](./pushover.md) -* [Alertmanager](./alertmanager.md) \ No newline at end of file diff --git a/docs/services/pushover.md b/docs/services/pushover.md deleted file mode 100644 index 37cb20b2..00000000 --- a/docs/services/pushover.md +++ /dev/null @@ -1,33 +0,0 @@ -# Pushover - -1. Create an app at [pushover.net](https://pushover.net/apps/build). -2. Store the API key in `` Secret and define the secret name in `` ConfigMap: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.pushover: | - token: $pushover-token -``` - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: -stringData: - pushover-token: avtc41pn13asmra6zaiyf7dh6cgx97 -``` - -3. Add your user key to your Application resource: - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe.on-sync-succeeded.pushover: uumy8u4owy7bgkapp6mc5mvhfsvpcd -``` \ No newline at end of file diff --git a/docs/services/rocketchat.md b/docs/services/rocketchat.md deleted file mode 100644 index 554f42a8..00000000 --- a/docs/services/rocketchat.md +++ /dev/null @@ -1,96 +0,0 @@ -# Rocket.Chat - -## Parameters - -The Rocket.Chat notification service configuration includes following settings: - -* `email` - the Rocker.Chat user's email -* `password` - the Rocker.Chat user's password -* `alias` - optional alias that should be used to post message -* `icon` - optional message icon -* `avatar` - optional message avatar -* `serverUrl` - optional Rocket.Chat server url - -## Configuration - -1. Login to your RocketChat instance -2. Go to user management - -![2](https://user-images.githubusercontent.com/15252187/115824993-7ccad900-a411-11eb-89de-6a0c4438ffdf.png) - -3. Add new user with `bot` role. Also note that `Require password change` checkbox mus be not checked - -![3](https://user-images.githubusercontent.com/15252187/115825174-b4d21c00-a411-11eb-8f20-cda48cea9fad.png) - -4. Copy username and password that you was created for bot user -5. Create a public or private channel, or a team, for this example `my_channel` -6. Add your bot to this channel **otherwise it won't work** -7. Store email and password in argocd_notifications-secret Secret - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: -stringData: - rocketchat-email: - rocketchat-password: -``` - -8. Finally, use these credentials to configure the RocketChat integration in the `argocd-configmap` config map: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.rocketchat: | - email: $rocketchat-email - password: $rocketchat-password -``` - -9. Create a subscription for your Rocket.Chat integration: - -*Note: channel, team or user must be prefixed with # or @ elsewhere we will be interpretative destination as a room ID* - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe.on-sync-succeeded.rocketchat: #my_channel -``` - -## Templates - -Notification templates can be customized with RocketChat [attachments](https://developer.rocket.chat/api/rest-api/methods/chat/postmessage#attachments-detail). - -*Note: Attachments structure in Rocketchat is same with Slack attachments [feature](https://api.slack.com/messaging/composing/layouts).* - - - -The message attachments can be specified in `attachments` string fields under `rocketchat` field: - -```yaml -template.app-sync-status: | - message: | - Application {{.app.metadata.name}} sync is {{.app.status.sync.status}}. - Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}. - rocketchat: - attachments: | - [{ - "title": "{{.app.metadata.name}}", - "title_link": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#18be52", - "fields": [{ - "title": "Sync Status", - "value": "{{.app.status.sync.status}}", - "short": true - }, { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - }] - }] -``` diff --git a/docs/services/slack.md b/docs/services/slack.md deleted file mode 100644 index 6119a32a..00000000 --- a/docs/services/slack.md +++ /dev/null @@ -1,147 +0,0 @@ -# Slack - -If you want to send message using incoming webhook, you can use [webhook](./webhook.md#send-slack). - -## Parameters - -The Slack notification service configuration includes following settings: - -* `token` - the app token -* `apiURL` - optional, the server url, e.g. https://example.com/api -* `username` - optional, the app username -* `icon` - optional, the app icon, e.g. :robot_face: or https://example.com/image.png -* `insecureSkipVerify` - optional bool, true or false - -## Configuration - -1. Create Slack Application using https://api.slack.com/apps?new_app=1 -![1](https://user-images.githubusercontent.com/426437/73604308-4cb0c500-4543-11ea-9092-6ca6bae21cbb.png) -1. Once application is created navigate to `Enter OAuth & Permissions` -![2](https://user-images.githubusercontent.com/426437/73604309-4d495b80-4543-11ea-9908-4dea403d3399.png) -1. Click `Permissions` under `Add features and functionality` section and add `chat:write` scope. To use the optional username and icon overrides in the Slack notification service also add the `chat:write.customize` scope. -![3](https://user-images.githubusercontent.com/426437/73604310-4d495b80-4543-11ea-8576-09cd91aea0e5.png) -1. Scroll back to the top, click 'Install App to Workspace' button and confirm the installation. -![4](https://user-images.githubusercontent.com/426437/73604311-4d495b80-4543-11ea-9155-9d216b20ec86.png) -1. Once installation is completed copy the OAuth token. -![5](https://user-images.githubusercontent.com/426437/73604312-4d495b80-4543-11ea-832b-a9d9d5e4bc29.png) - -1. Create a public or private channel, for this example `my_channel` -1. Invite your slack bot to this channel **otherwise slack bot won't be able to deliver notifications to this channel** -1. Store Oauth access token in `argocd-notifications-secret` secret - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: - stringData: - slack-token: - ``` - -1. Define service type slack in data section of `argocd-notifications-cm` configmap: -service - ```yaml - apiVersion: v1 - kind: ConfigMap - metadata: - name: - data: - service.slack: | - token: $slack-token - ``` - -1. Add annotation in application yaml file to enable notifications for specific argocd app - - ```yaml - apiVersion: argoproj.io/v1alpha1 - kind: Application - metadata: - annotations: - notifications.argoproj.io/subscribe.on-sync-succeeded.slack: my_channel - ``` - -## Templates - -Notification templates can be customized to leverage slack message blocks and attachments -[feature](https://api.slack.com/messaging/composing/layouts). - -![](https://user-images.githubusercontent.com/426437/72776856-6dcef880-3bc8-11ea-8e3b-c72df16ee8e6.png) - -The message blocks and attachments can be specified in `blocks` and `attachments` string fields under `slack` field: - -```yaml -template.app-sync-status: | - message: | - Application {{.app.metadata.name}} sync is {{.app.status.sync.status}}. - Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}. - slack: - attachments: | - [{ - "title": "{{.app.metadata.name}}", - "title_link": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#18be52", - "fields": [{ - "title": "Sync Status", - "value": "{{.app.status.sync.status}}", - "short": true - }, { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - }] - }] -``` - -The messages can be aggregated to the slack threads by grouping key which can be specified in a `groupingKey` string field under `slack` field. -`groupingKey` is used across each template and works independently on each slack channel. -When multiple applications will be updated at the same time or frequently, the messages in slack channel can be easily read by aggregating with git commit hash, application name, etc. -Furthermore, the messages can be broadcast to the channel at the specific template by `notifyBroadcast` field. - -```yaml -template.app-sync-status: | - message: | - Application {{.app.metadata.name}} sync is {{.app.status.sync.status}}. - Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}. - slack: - attachments: | - [{ - "title": "{{.app.metadata.name}}", - "title_link": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#18be52", - "fields": [{ - "title": "Sync Status", - "value": "{{.app.status.sync.status}}", - "short": true - }, { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - }] - }] - # Aggregate the messages to the thread by git commit hash - groupingKey: "{{.app.status.sync.revision}}" - notifyBroadcast: false -template.app-sync-failed: | - message: | - Application {{.app.metadata.name}} sync is {{.app.status.sync.status}}. - Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}. - slack: - attachments: | - [{ - "title": "{{.app.metadata.name}}", - "title_link": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#ff0000", - "fields": [{ - "title": "Sync Status", - "value": "{{.app.status.sync.status}}", - "short": true - }, { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - }] - }] - # Aggregate the messages to the thread by git commit hash - groupingKey: "{{.app.status.sync.revision}}" - notifyBroadcast: true -``` diff --git a/docs/services/teams.md b/docs/services/teams.md deleted file mode 100644 index eb50f553..00000000 --- a/docs/services/teams.md +++ /dev/null @@ -1,126 +0,0 @@ -# Teams - -## Parameters - -The Teams notification service send message notifications using Teams bot and requires specifying the following settings: - -* `recipientUrls` - the webhook url map, e.g. `channelName: https://example.com` - -## Configuration - -1. Open `Teams` and goto `Apps` -2. Find `Incoming Webhook` microsoft app and click on it -3. Press `Add to a team` -> select team and channel -> press `Set up a connector` -4. Enter webhook name and upload image (optional) -5. Press `Create` then copy webhook url and store it in `argocd-notifications-secret` and define it in `argocd-notifications-cm` - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.teams: | - recipientUrls: - channelName: $channel-teams-url -``` - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: -stringData: - channel-teams-url: https://example.com -``` - -6. Create subscription for your Teams integration: - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe.on-sync-succeeded.teams: channelName -``` - -## Templates - -![](https://user-images.githubusercontent.com/18019529/114271500-9d2b8880-9a4c-11eb-85c1-f6935f0431d5.png) - -Notification templates can be customized to leverage teams message sections, facts, themeColor, summary and potentialAction [feature](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using). - -```yaml -template.app-sync-succeeded: | - teams: - themeColor: "#000080" - sections: | - [{ - "facts": [ - { - "name": "Sync Status", - "value": "{{.app.status.sync.status}}" - }, - { - "name": "Repository", - "value": "{{.app.spec.source.repoURL}}" - } - ] - }] - potentialAction: |- - [{ - "@type":"OpenUri", - "name":"Operation Details", - "targets":[{ - "os":"default", - "uri":"{{.context.argocdUrl}}/applications/{{.app.metadata.name}}?operation=true" - }] - }] - title: Application {{.app.metadata.name}} has been successfully synced - text: Application {{.app.metadata.name}} has been successfully synced at {{.app.status.operationState.finishedAt}}. - summary: "{{.app.metadata.name}} sync succeeded" -``` - -### facts field - -You can use `facts` field instead of `sections` field. - -```yaml -template.app-sync-succeeded: | - teams: - facts: | - [{ - "name": "Sync Status", - "value": "{{.app.status.sync.status}}" - }, - { - "name": "Repository", - "value": "{{.app.spec.source.repoURL}}" - }] -``` - -### theme color field - -You can set theme color as hex string for the message. - -![](https://user-images.githubusercontent.com/1164159/114864810-0718a900-9e24-11eb-8127-8d95da9544c1.png) - -```yaml -template.app-sync-succeeded: | - teams: - themeColor: "#000080" -``` - -### summary field - -You can set a summary of the message that will be shown on Notifcation & Activity Feed - -![](https://user-images.githubusercontent.com/6957724/116587921-84c4d480-a94d-11eb-9da4-f365151a12e7.jpg) - -![](https://user-images.githubusercontent.com/6957724/116588002-99a16800-a94d-11eb-807f-8626eb53b980.jpg) - -```yaml -template.app-sync-succeeded: | - teams: - summary: "Sync Succeeded" -``` \ No newline at end of file diff --git a/docs/services/telegram.md b/docs/services/telegram.md deleted file mode 100644 index 953c2a9f..00000000 --- a/docs/services/telegram.md +++ /dev/null @@ -1,35 +0,0 @@ -# Telegram - -1. Get an API token using [@Botfather](https://t.me/Botfather). -2. Store token in `` Secret and configure telegram integration -in `` ConfigMap: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.telegram: | - token: $telegram-token -``` - -3. Create new Telegram [channel](https://telegram.org/blog/channels). -4. Add your bot as an administrator. -5. Use this channel `username` (public channel) or `chatID` (private channel) in the subscription for your Telegram integration: - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe.on-sync-succeeded.telegram: username -``` - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe.on-sync-succeeded.telegram: -1000000000000 -``` diff --git a/docs/services/webhook.md b/docs/services/webhook.md deleted file mode 100644 index b6aee1ea..00000000 --- a/docs/services/webhook.md +++ /dev/null @@ -1,177 +0,0 @@ -## Configuration - -The webhook notification service allows sending a generic HTTP request using the templatized request body and URL. -Using Webhook you might trigger a Jenkins job, update Github commit status. - -Use the following steps to configure webhook: - -1 Register webhook in `argocd-notifications-cm` ConfigMap: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.webhook.: | - url: https:/// - headers: #optional headers - - name: - value: - basicAuth: #optional username password - username: - password: -``` - -2 Define template that customizes webhook request method, path and body: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - template.github-commit-status: | - webhook: - : - method: POST # one of: GET, POST, PUT, PATCH. Default value: GET - path: - body: | - - trigger.: | - - when: app.status.operationState.phase in ['Succeeded'] - send: [github-commit-status] -``` - -3 Create subscription for webhook integration: - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe..: "" -``` - -## Examples - -### Set Github commit status - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.webhook.github: | - url: https://api.github.com - headers: #optional headers - - name: Authorization - value: token $github-token -``` - -2 Define template that customizes webhook request method, path and body: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.webhook.github: | - url: https://api.github.com - headers: #optional headers - - name: Authorization - value: token $github-token - - template.github-commit-status: | - webhook: - github: - method: POST - path: /repos/{{call .repo.FullNameByRepoURL .app.spec.source.repoURL}}/statuses/{{.app.status.operationState.operation.sync.revision}} - body: | - { - {{if eq .app.status.operationState.phase "Running"}} "state": "pending"{{end}} - {{if eq .app.status.operationState.phase "Succeeded"}} "state": "success"{{end}} - {{if eq .app.status.operationState.phase "Error"}} "state": "error"{{end}} - {{if eq .app.status.operationState.phase "Failed"}} "state": "error"{{end}}, - "description": "ArgoCD", - "target_url": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "context": "continuous-delivery/{{.app.metadata.name}}" - } -``` - -### Start Jenkins Job - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.webhook.jenkins: | - url: http:///job//build?token= - basicAuth: - username: - password: - -type: Opaque -``` - -### Send form-data - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.webhook.form: | - url: https://form.example.com - headers: - - name: Content-Type - value: application/x-www-form-urlencoded - - template.form-data: | - webhook: - form: - method: POST - body: key1=value1&key2=value2 -``` - -### Send Slack - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: -data: - service.webhook.slack_webhook: | - url: https://hooks.slack.com/services/xxxxx - headers: - - name: Content-Type - value: application/json - - template.send-slack: | - webhook: - slack_webhook: - method: POST - body: | - { - "attachments": [{ - "title": "{{.app.metadata.name}}", - "title_link": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}", - "color": "#18be52", - "fields": [{ - "title": "Sync Status", - "value": "{{.app.status.sync.status}}", - "short": true - }, { - "title": "Repository", - "value": "{{.app.spec.source.repoURL}}", - "short": true - }] - }] - } -``` diff --git a/docs/subscriptions.md b/docs/subscriptions.md deleted file mode 100644 index 5da0ccf2..00000000 --- a/docs/subscriptions.md +++ /dev/null @@ -1,76 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/subscriptions//](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/subscriptions//). Redirecting to the new page. - -The subscription to Argo CD application events can be defined using `notifications.argoproj.io/subscribe..: ` annotation. -For example, the following annotation subscribes two Slack channels to notifications about every successful synchronization of the Argo CD application: - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe.on-sync-succeeded.slack: my-channel1;my-channel2 -``` - -Annotation key consists of following parts: - -* `on-sync-succeeded` - trigger name -* `slack` - notification service name -* `my-channel1;my-channel2` - a semicolon separated list of recipients - -You can create subscriptions for all applications of the Argo CD project by adding the same annotation to AppProject CRD: - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: AppProject -metadata: - annotations: - notifications.argoproj.io/subscribe.on-sync-succeeded.slack: my-channel1;my-channel2 -``` - -## Default Subscriptions - -The subscriptions might be configured globally in the `argocd-notifications-cm` ConfigMap using `subscriptions` field. The default subscriptions -are applied to all applications. The trigger and applications might be configured using the -`triggers` and `selector` fields: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - # Contains centrally managed global application subscriptions - subscriptions: | - # subscription for on-sync-status-unknown trigger notifications - - recipients: - - slack:test2 - - email:test@gmail.com - triggers: - - on-sync-status-unknown - # subscription restricted to applications with matching labels only - - recipients: - - slack:test3 - selector: test=true - triggers: - - on-sync-status-unknown -``` - -If you want to use webhook in subscriptions, you need to store the custom name to recipients. - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - service.webhook.: | - (snip) - subscriptions: | - - recipients: - - - triggers: - - on-sync-status-unknown -``` diff --git a/docs/templates.md b/docs/templates.md deleted file mode 100644 index 2981b7bc..00000000 --- a/docs/templates.md +++ /dev/null @@ -1,98 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/templates//](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/templates//). Redirecting to the new page. - -The notification template is used to generate the notification content and configured in `argocd-notifications-cm` ConfigMap. The template is leveraging -[html/template](https://golang.org/pkg/html/template/) golang package and allow to customize notification message. -Templates are meant to be reusable and can be referenced by multiple triggers. - -The following template is used to notify the user about application sync status. - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - template.my-custom-template-slack-template: | - message: | - Application {{.app.metadata.name}} sync is {{.app.status.sync.status}}. - Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}. -``` - -Each template has access to the following fields: - -- `app` holds the application object. -- `context` is user defined string map and might include any string keys and values. -- `serviceType` holds the notification service type name. The field can be used to conditionally -render service specific fields. -- `recipient` holds the recipient name. - -## Defining user-defined `context` - -It is possible to define some shared context between all notification templates by setting a top-level -YAML document of key-value pairs, which can then be used within templates, like so: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - context: | - region: east - environmentName: staging - - template.a-slack-template-with-context: | - message: "Something happened in {{ .context.environmentName }} in the {{ .context.region }} data center!" -``` - -## Notification Service Specific Fields - -The `message` field of the template definition allows creating a basic notification for any notification service. You can leverage notification service-specific -fields to create complex notifications. For example using service-specific you can add blocks and attachments for Slack, subject for Email or URL path, and body for Webhook. -See corresponding service [documentation](./services/overview.md) for more information. - -## Change the timezone - -You can change the timezone to show it as follows. - -1. Call time functions. - -``` -{{ (call .time.Parse .app.status.operationState.startedAt).Local.Format "2006-01-02T15:04:05Z07:00" }} -``` - -2. Set environment to container. - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: argocd-notifications-controller -spec: -(snip) - spec: - containers: - - name: argocd-notifications-controller - env: - - name: TZ - value: Asia/Tokyo -``` - -## Functions - -Templates have access to the set of built-in functions: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - template.my-custom-template-slack-template: | - message: "Author: {{(call .repo.GetCommitMetadata .app.status.sync.revision).Author}}" -``` - -{!functions.md!} diff --git a/docs/triggers.md b/docs/triggers.md deleted file mode 100644 index e687b9ba..00000000 --- a/docs/triggers.md +++ /dev/null @@ -1,130 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/triggers//](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/triggers//). Redirecting to the new page. - -The trigger defines the condition when the notification should be sent. The definition includes name, condition -and notification templates reference. The condition is a predicate expression that returns true if the notification -should be sent. The trigger condition evaluation is powered by [antonmedv/expr](https://github.com/antonmedv/expr). -The condition language syntax is described at [Language-Definition.md](https://github.com/antonmedv/expr/blob/master/docs/Language-Definition.md). - -The trigger is configured in `argocd-notifications-cm` ConfigMap. For example the following trigger sends a notification -when application sync status changes to `Unknown` using the `app-sync-status` template: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - trigger.on-sync-status-unknown: | - - when: app.status.sync.status == 'Unknown' # trigger condition - send: [app-sync-status, github-commit-status] # template names -``` - -Each condition might use several templates. Typically each template is responsible for generating a service-specific notification part. -In the example above `app-sync-status` template "knows" how to create email and slack notification and `github-commit-status` knows how to -generate payload for Github webhook. - -## Conditions Bundles - -Triggers are typically managed by administrators and encapsulate information about when and which notification should be sent. -The end users just need to subscribe to the trigger and specify the notification destination. In order to improve user experience -triggers might include multiple conditions with a different set of templates for each condition. For example, the following trigger -covers all stages of sync status operation and use a different template for different cases: - - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - trigger.sync-operation-change: | - - when: app.status.operationState.phase in ['Succeeded'] - send: [github-commit-status] - - when: app.status.operationState.phase in ['Running'] - send: [github-commit-status] - - when: app.status.operationState.phase in ['Error', 'Failed'] - send: [app-sync-failed, github-commit-status] -``` - -## Avoid Sending Same Notification Too Often - -In some cases, the trigger condition might be "flapping". The example below illustrates the problem. -The trigger is supposed to generate a notification once when Argo CD application is successfully synchronized and healthy. -However, the application health status might intermittently switch to `Progressing` and then back to `Healthy` so the trigger might unnecessarily generate -multiple notifications. The `oncePer` field configures triggers to generate the notification only when the corresponding application field changes. -The `on-deployed` trigger from the example below sends the notification only once per observed Git revision of the deployment repository. - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - # Optional 'oncePer' property ensure that notification is sent only once per specified field value - # E.g. following is triggered once per sync revision - trigger.on-deployed: | - when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy' - oncePer: app.status.sync.revision - send: [app-sync-succeeded] -``` - -### oncePer - -The `oncePer` filed is supported like as follows. - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - example.com/version: v0.1 -``` - -```yaml -oncePer: app.metadata.annotations["example.com/version"] -``` - -## Default Triggers - -You can use `defaultTriggers` field instead of specifying individual triggers to the annotations. - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - # Holds list of triggers that are used by default if trigger is not specified explicitly in the subscription - defaultTriggers: | - - on-sync-status-unknown - - defaultTriggers.mattermost: | - - on-sync-running - - on-sync-succeeded -``` - -Specify the annotations as follows to use `defaultTriggers`. In this example, `slack` sends when `on-sync-status-unknown`, and `mattermost` sends when `on-sync-running` and `on-sync-succeeded`. - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - annotations: - notifications.argoproj.io/subscribe.slack: my-channel - notifications.argoproj.io/subscribe.mattermost: my-mattermost-channel -``` - -## Functions - -Triggers have access to the set of built-in functions. - -Example: - -```yaml -when: time.Now().Sub(time.Parse(app.status.operationState.startedAt)).Minutes() >= 5 -``` - -{!functions.md!} diff --git a/docs/troubleshooting-commands.md b/docs/troubleshooting-commands.md deleted file mode 100644 index 42b89c7e..00000000 --- a/docs/troubleshooting-commands.md +++ /dev/null @@ -1,213 +0,0 @@ -## argocd-notifications template get - -Prints information about configured templates - -``` -argocd-notifications template get [flags] -``` - -### Examples - -``` - -# prints all templates -argocd-notifications template get -# print YAML formatted app-sync-succeeded template definition -argocd-notifications template get app-sync-succeeded -o=yaml - -``` - -### Options - -``` - -h, --help help for get - -o, --output string Output format. One of:json|yaml|wide|name (default "wide") -``` - -### Options inherited from parent commands - -``` - --argocd-repo-server string Argo CD repo server address (default "argocd-repo-server:8081") - --argocd-repo-server-plaintext Use a plaintext client (non-TLS) to connect to repository server - --argocd-repo-server-strict-tls Perform strict validation of TLS certificates when connecting to repo server - --as string Username to impersonate for the operation - --as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups. - --certificate-authority string Path to a cert file for the certificate authority - --client-certificate string Path to a client certificate file for TLS - --client-key string Path to a client key file for TLS - --cluster string The name of the kubeconfig cluster to use - --config-map string argocd-notifications-cm.yaml file path - --context string The name of the kubeconfig context to use - --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure - --kubeconfig string Path to a kube config. Only required if out-of-cluster - -n, --namespace string If present, the namespace scope for this CLI request - --password string Password for basic authentication to the API server - --request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0") - --secret string argocd-notifications-secret.yaml file path. Use empty secret if provided value is ':empty' - --server string The address and port of the Kubernetes API server - --tls-server-name string If provided, this name will be used to validate server certificate. If this is not provided, hostname used to contact the server is used. - --token string Bearer token for authentication to the API server - --user string The name of the kubeconfig user to use - --username string Username for basic authentication to the API server -``` - -## argocd-notifications template notify - -Generates notification using the specified template and send it to specified recipients - -``` -argocd-notifications template notify NAME RESOURCE_NAME [flags] -``` - -### Examples - -``` - -# Trigger notification using in-cluster config map and secret -argocd-notifications template notify app-sync-succeeded guestbook --recipient slack:my-slack-channel - -# Render notification render generated notification in console -argocd-notifications template notify app-sync-succeeded guestbook - -``` - -### Options - -``` - -h, --help help for notify - --recipient stringArray List of recipients (default [console:stdout]) -``` - -### Options inherited from parent commands - -``` - --argocd-repo-server string Argo CD repo server address (default "argocd-repo-server:8081") - --argocd-repo-server-plaintext Use a plaintext client (non-TLS) to connect to repository server - --argocd-repo-server-strict-tls Perform strict validation of TLS certificates when connecting to repo server - --as string Username to impersonate for the operation - --as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups. - --certificate-authority string Path to a cert file for the certificate authority - --client-certificate string Path to a client certificate file for TLS - --client-key string Path to a client key file for TLS - --cluster string The name of the kubeconfig cluster to use - --config-map string argocd-notifications-cm.yaml file path - --context string The name of the kubeconfig context to use - --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure - --kubeconfig string Path to a kube config. Only required if out-of-cluster - -n, --namespace string If present, the namespace scope for this CLI request - --password string Password for basic authentication to the API server - --request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0") - --secret string argocd-notifications-secret.yaml file path. Use empty secret if provided value is ':empty' - --server string The address and port of the Kubernetes API server - --tls-server-name string If provided, this name will be used to validate server certificate. If this is not provided, hostname used to contact the server is used. - --token string Bearer token for authentication to the API server - --user string The name of the kubeconfig user to use - --username string Username for basic authentication to the API server -``` - -## argocd-notifications trigger get - -Prints information about configured triggers - -``` -argocd-notifications trigger get [flags] -``` - -### Examples - -``` - -# prints all triggers -argocd-notifications trigger get -# print YAML formatted on-sync-failed trigger definition -argocd-notifications trigger get on-sync-failed -o=yaml - -``` - -### Options - -``` - -h, --help help for get - -o, --output string Output format. One of:json|yaml|wide|name (default "wide") -``` - -### Options inherited from parent commands - -``` - --argocd-repo-server string Argo CD repo server address (default "argocd-repo-server:8081") - --argocd-repo-server-plaintext Use a plaintext client (non-TLS) to connect to repository server - --argocd-repo-server-strict-tls Perform strict validation of TLS certificates when connecting to repo server - --as string Username to impersonate for the operation - --as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups. - --certificate-authority string Path to a cert file for the certificate authority - --client-certificate string Path to a client certificate file for TLS - --client-key string Path to a client key file for TLS - --cluster string The name of the kubeconfig cluster to use - --config-map string argocd-notifications-cm.yaml file path - --context string The name of the kubeconfig context to use - --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure - --kubeconfig string Path to a kube config. Only required if out-of-cluster - -n, --namespace string If present, the namespace scope for this CLI request - --password string Password for basic authentication to the API server - --request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0") - --secret string argocd-notifications-secret.yaml file path. Use empty secret if provided value is ':empty' - --server string The address and port of the Kubernetes API server - --tls-server-name string If provided, this name will be used to validate server certificate. If this is not provided, hostname used to contact the server is used. - --token string Bearer token for authentication to the API server - --user string The name of the kubeconfig user to use - --username string Username for basic authentication to the API server -``` - -## argocd-notifications trigger run - -Evaluates specified trigger condition and prints the result - -``` -argocd-notifications trigger run NAME RESOURCE_NAME [flags] -``` - -### Examples - -``` - -# Execute trigger configured in 'argocd-notification-cm' ConfigMap -argocd-notifications trigger run on-sync-status-unknown ./sample-app.yaml - -# Execute trigger using my-config-map.yaml instead of 'argocd-notifications-cm' ConfigMap -argocd-notifications trigger run on-sync-status-unknown ./sample-app.yaml \ - --config-map ./my-config-map.yaml -``` - -### Options - -``` - -h, --help help for run -``` - -### Options inherited from parent commands - -``` - --argocd-repo-server string Argo CD repo server address (default "argocd-repo-server:8081") - --argocd-repo-server-plaintext Use a plaintext client (non-TLS) to connect to repository server - --argocd-repo-server-strict-tls Perform strict validation of TLS certificates when connecting to repo server - --as string Username to impersonate for the operation - --as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups. - --certificate-authority string Path to a cert file for the certificate authority - --client-certificate string Path to a client certificate file for TLS - --client-key string Path to a client key file for TLS - --cluster string The name of the kubeconfig cluster to use - --config-map string argocd-notifications-cm.yaml file path - --context string The name of the kubeconfig context to use - --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure - --kubeconfig string Path to a kube config. Only required if out-of-cluster - -n, --namespace string If present, the namespace scope for this CLI request - --password string Password for basic authentication to the API server - --request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0") - --secret string argocd-notifications-secret.yaml file path. Use empty secret if provided value is ':empty' - --server string The address and port of the Kubernetes API server - --tls-server-name string If provided, this name will be used to validate server certificate. If this is not provided, hostname used to contact the server is used. - --token string Bearer token for authentication to the API server - --user string The name of the kubeconfig user to use - --username string Username for basic authentication to the API server -``` - diff --git a/docs/troubleshooting-errors.md b/docs/troubleshooting-errors.md deleted file mode 100644 index 4861694b..00000000 --- a/docs/troubleshooting-errors.md +++ /dev/null @@ -1,46 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/troubleshooting-errors//](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/troubleshooting-errors//). Redirecting to the new page. - -## Failed to parse new settings - -### error converting YAML to JSON - -YAML syntax is incorrect. - -**incorrect:** - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - service.slack: | - token: $slack-token - icon: :rocket: -``` - -**correct:** - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - service.slack: | - token: $slack-token - icon: ":rocket:" -``` - -### service type 'xxxx' is not supported - -You need to check your argocd-notifications controller version. For instance, the teams integration is to support `v1.1.0` and more. - -## Failed to notify recipient - -### notification service 'xxxx' is not supported" - -You have not defined `xxxx` in `argocd-notifications-cm` or to fail to parse settings. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md deleted file mode 100644 index cd6d7f0f..00000000 --- a/docs/troubleshooting.md +++ /dev/null @@ -1,84 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/troubleshooting//](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/troubleshooting//). Redirecting to the new page. - -## Troubleshooting - -The `argocd-notifications` binary includes a set of CLI commands that helps to configure the controller -settings and troubleshoot issues. - -## Global flags -Following global flags are available for all sub-commands: - -* `config-map` - path to the file containing `argocd-notifications-cm` ConfigMap. If not specified -then the command loads `argocd-notification-cm` ConfigMap using the local Kubernetes config file. -* `secret` - path to the file containing `argocd-notifications-secret` ConfigMap. If not -specified then the command loads `argocd-notification-secret` Secret using the local Kubernetes config file. -Additionally, you can specify `:empty` value to use empty secret with no notification service settings. - -**Examples:** - -* Get list of triggers configured in the local config map: - -```bash -argocd-notifications trigger get \ - --config-map ./argocd-notifications-cm.yaml --secret :empty -``` - -* Trigger notification using in-cluster config map and secret: - -```bash -argocd-notifications template notify \ - app-sync-succeeded guestbook --recipient slack:argocd-notifications -``` - -## Kustomize - -If you are managing `argocd-notifications` config using Kustomize you can pipe whole `kustomize build` output -into stdin using `--config-map -` flag: - -```bash -kustomize build ./argocd-notifications | \ - argocd-notifications \ - template notify app-sync-succeeded guestbook --recipient grafana:argocd \ - --config-map - -``` - -## How to get it - -### On your laptop - -You can download `argocd-notifications` from the github [release](https://github.com/argoproj-labs/argocd-notifications/releases) -attachments. - -The binary is available in `argoprojlabs/argocd-notifications` image. Use the `docker run` and volume mount -to execute binary on any platform. - -**Example:** - -```bash -docker run --rm -it -w /src -v $(pwd):/src \ - argoprojlabs/argocd-notifications: \ - /app/argocd-notifications trigger get \ - --config-map ./argocd-notifications-cm.yaml --secret :empty -``` - -### In your cluster - -SSH into the running `argocd-notifications-controller` pod and use `kubectl exec` command to validate in-cluster -configuration. - -**Example** -```bash -kubectl exec -it argocd-notifications-controller- \ - /app/argocd-notifications trigger get -``` - -## Commands - -{!troubleshooting-commands.md!} - -## Errors - -{!troubleshooting-errors.md!} diff --git a/docs/upgrading/0.x-1.0.md b/docs/upgrading/0.x-1.0.md deleted file mode 100644 index 81aadb6b..00000000 --- a/docs/upgrading/0.x-1.0.md +++ /dev/null @@ -1,225 +0,0 @@ - - -!!! important "This page has moved" - This page has moved to [https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/). Redirecting to the new page. - -# 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](../catalog.md). - -**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](https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/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: - -```yaml -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:` (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:` 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.(.)` 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** - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: argocd-notifications-secret -stringData: - notifiers.yaml: | - email: - host: smtp.gmail.com - port: 587 - from: @gmail.com - username: @gmail.com - password: -``` - -**After** - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-notifications-cm -data: - service.email: | - host: smtp.gmail.com - port: 587 - from: @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 `$`. - -### 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.` and `template.` -keys. - -**Before** - -```yaml -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** - -```yaml -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](../triggers.md#conditions-bundles) that improves user experience. - -**Before** - -```yaml -name: on-sync-status-unknown -condition: app.status.sync.status == 'Unknown' -template: app-sync-status -enabled: true -``` - -**After** - -```yaml -- when: app.status.sync.status == 'Unknown' - send: [my-custom-template] -``` - -### Template Definition - -Template `title` and `body` fields have been replaced with `message` field. - - -**Before** - -```yaml -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** - -```yaml -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 `.recipients.argocd-notifications.argoproj.io: :` annotation has been replaced -with `notifications.argoproj.io/subscribe..: ` 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` diff --git a/mkdocs.yml b/mkdocs.yml index 5f202f7c..99c5b535 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,53 +1,5 @@ site_name: Argo CD Notifications repo_url: https://github.com/argoproj-labs/argocd-notifications strict: true -google_analytics: -- 'UA-105170809-5' -- 'auto' -theme: - name: material - palette: - primary: teal - font: - text: 'Work Sans' - logo: 'assets/logo.png' -extra_javascript: -- assets/versions.js -extra_css: -- assets/versions.css -markdown_extensions: -- codehilite -- admonition -- pymdownx.highlight -- pymdownx.superfences -- markdown_include.include: - base_path: docs -- toc: - permalink: true nav: - - Overview: index.md - - triggers.md - - templates.md - - subscriptions.md - - Notification Services: - - services/overview.md - - services/email.md - - services/github.md - - services/slack.md - - services/mattermost.md - - services/opsgenie.md - - services/grafana.md - - services/teams.md - - services/telegram.md - - services/webhook.md - - services/rocketchat.md - - catalog.md - - troubleshooting.md - - Bots: - - bots/overview.md - - bots/slack-bot.md - - bots/opsgenie-bot.md - - bots/telegram-bot.md - - monitoring.md - - Upgrading: - - upgrading/0.x-1.0.md + - Overview: index.md \ No newline at end of file