From 8149751393386901305263eceb0afee7c98cd8e5 Mon Sep 17 00:00:00 2001 From: Michael Crenshaw <350466+crenshaw-dev@users.noreply.github.com> Date: Thu, 5 Oct 2023 14:41:53 -0400 Subject: [PATCH] more fixes Signed-off-by: Michael Crenshaw <350466+crenshaw-dev@users.noreply.github.com> --- docs/operator-manual/notifications/index.md | 48 ++-- .../notifications/monitoring.md | 10 +- .../notifications/subscriptions.md | 8 +- .../notifications/templates.md | 46 ++-- .../operator-manual/notifications/triggers.md | 8 +- .../notifications/troubleshooting-commands.md | 225 +----------------- .../notifications/troubleshooting-errors.md | 2 +- .../notifications/troubleshooting.md | 45 ++-- mkdocs.yml | 2 +- 9 files changed, 91 insertions(+), 303 deletions(-) diff --git a/docs/operator-manual/notifications/index.md b/docs/operator-manual/notifications/index.md index 165dfd4df3726..c719d10e7611c 100644 --- a/docs/operator-manual/notifications/index.md +++ b/docs/operator-manual/notifications/index.md @@ -10,38 +10,38 @@ So you can just use them instead of reinventing new ones. * Install Triggers and Templates from the catalog -``` -kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/notifications_catalog/install.yaml -``` + ```bash + kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/notifications_catalog/install.yaml + ``` * Add Email username and password token to `argocd-notifications-secret` secret -```bash -EMAIL_USER= - 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 -``` + ```bash + EMAIL_USER= + 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 }" }}' -``` + ```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 -``` + ```bash + kubectl patch app -n argocd -p '{"metadata": {"annotations": {"notifications.argoproj.io/subscribe.on-sync-succeeded.slack":""}}}' --type merge + ``` Try syncing an application to get notified when the sync is completed. diff --git a/docs/operator-manual/notifications/monitoring.md b/docs/operator-manual/notifications/monitoring.md index 31b6f45cf4392..a0aabbaae1f09 100644 --- a/docs/operator-manual/notifications/monitoring.md +++ b/docs/operator-manual/notifications/monitoring.md @@ -3,7 +3,7 @@ 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. + The metrics port can be changed using the `--metrics-port` flag in `argocd-notifications-controller` deployment. ## Metrics The following metrics are available: @@ -15,7 +15,7 @@ The following metrics are available: * `template` - notification template name * `notifier` - notification service name -* `succeeded` - flag that indicates if notification was successfully sent or failed. +* `succeeded` - flag that indicates if notification was successfully sent or failed ### `argocd_notifications_trigger_eval_total` @@ -23,8 +23,8 @@ The following metrics are available: Labels: * `name` - trigger name -* `triggered` - flag that indicates if trigger condition returned true of false. +* `triggered` - flag that indicates if trigger condition returned true of false -# Examples: +## Examples -* Grafana Dashboard: [grafana-dashboard.json](grafana-dashboard.json) \ No newline at end of file +* Grafana Dashboard: [grafana-dashboard.json](grafana-dashboard.json) diff --git a/docs/operator-manual/notifications/subscriptions.md b/docs/operator-manual/notifications/subscriptions.md index 44c500ac16f4a..e9f985280f8ad 100644 --- a/docs/operator-manual/notifications/subscriptions.md +++ b/docs/operator-manual/notifications/subscriptions.md @@ -9,13 +9,13 @@ metadata: notifications.argoproj.io/subscribe.on-sync-succeeded.slack: my-channel1;my-channel2 ``` -Annotation key consists of following parts: +The 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: +You can create subscriptions for all applications of an Argo CD project by adding the same annotation to the AppProject resource: ```yaml apiVersion: argoproj.io/v1alpha1 @@ -27,7 +27,7 @@ metadata: ## Default Subscriptions -The subscriptions might be configured globally in the `argocd-notifications-cm` ConfigMap using `subscriptions` field. The default subscriptions +The subscriptions might be configured globally in the `argocd-notifications-cm` ConfigMap using the `subscriptions` field. The default subscriptions are applied to all applications. The trigger and applications might be configured using the `triggers` and `selector` fields: @@ -53,7 +53,7 @@ data: - on-sync-status-unknown ``` -If you want to use webhook in subscriptions, you need to store the custom name to recipients. +If you want to use webhook in subscriptions, you need to store the custom webhook name in the subscription's `recipients` field. ```yaml apiVersion: v1 diff --git a/docs/operator-manual/notifications/templates.md b/docs/operator-manual/notifications/templates.md index 972c62734f739..f865229e12835 100644 --- a/docs/operator-manual/notifications/templates.md +++ b/docs/operator-manual/notifications/templates.md @@ -1,5 +1,5 @@ -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. +The notification template is used to generate the notification content and is configured in the `argocd-notifications-cm` ConfigMap. The template is leveraging +the [html/template](https://golang.org/pkg/html/template/) golang package and allows customization of the 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. @@ -19,9 +19,9 @@ data: 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. +- `context` is a user-defined string map and might include any string keys and values. +- `serviceType` holds the notification service type name (such as "slack" or "email). The field can be used to conditionally +render service-specific fields. - `recipient` holds the recipient name. ## Defining user-defined `context` @@ -51,30 +51,30 @@ See corresponding service [documentation](services/overview.md) for more informa ## Change the timezone -You can change the timezone to show it as follows. +You can change the timezone to show in notifications as follows. 1. Call time functions. -``` -{{ (call .time.Parse .app.status.operationState.startedAt).Local.Format "2006-01-02T15:04:05Z07:00" }} -``` + ``` + {{ (call .time.Parse .app.status.operationState.startedAt).Local.Format "2006-01-02T15:04:05Z07:00" }} + ``` -2. Set environment to container. +2. Set the `TZ` environment variable on the argocd-notifications-controller container. -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: argocd-notifications-controller -spec: -(snip) + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: argocd-notifications-controller spec: - containers: - - name: argocd-notifications-controller - env: - - name: TZ - value: Asia/Tokyo -``` + template: + spec: + containers: + - name: argocd-notifications-controller + env: + - name: TZ + value: Asia/Tokyo + ``` ## Functions diff --git a/docs/operator-manual/notifications/triggers.md b/docs/operator-manual/notifications/triggers.md index c5fe7aa68967f..c3e2dc601296b 100644 --- a/docs/operator-manual/notifications/triggers.md +++ b/docs/operator-manual/notifications/triggers.md @@ -3,7 +3,7 @@ and notification templates reference. The condition is a predicate expression th 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 +The trigger is configured in the `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 @@ -17,9 +17,9 @@ data: 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. +Each condition might use several templates. Typically, each template is responsible for generating a service-specific notification part. +In the example above, the `app-sync-status` template "knows" how to create email and Slack notification, and `github-commit-status` knows how to +generate the payload for GitHub webhook. ## Conditions Bundles diff --git a/docs/operator-manual/notifications/troubleshooting-commands.md b/docs/operator-manual/notifications/troubleshooting-commands.md index 633eb47d71690..7374efbce2859 100644 --- a/docs/operator-manual/notifications/troubleshooting-commands.md +++ b/docs/operator-manual/notifications/troubleshooting-commands.md @@ -1,221 +1,6 @@ -## argocd admin notifications template get - -Prints information about configured templates - -``` -argocd admin notifications template get [flags] -``` - -### Examples - -``` - -# prints all templates -argocd admin notifications template get -# print YAML formatted app-sync-succeeded template definition -argocd admin 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. - --as-uid string UID to impersonate for the operation - --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 - --proxy-url string If provided, this URL will be used to connect via proxy - --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 admin notifications template notify - -Generates notification using the specified template and send it to specified recipients - -``` -argocd admin notifications template notify NAME RESOURCE_NAME [flags] -``` - -### Examples - -``` - -# Trigger notification using in-cluster config map and secret -argocd admin notifications template notify app-sync-succeeded guestbook --recipient slack:my-slack-channel - -# Render notification render generated notification in console -argocd admin 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. - --as-uid string UID to impersonate for the operation - --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 - --proxy-url string If provided, this URL will be used to connect via proxy - --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 admin notifications trigger get - -Prints information about configured triggers - -``` -argocd admin notifications trigger get [flags] -``` - -### Examples - -``` - -# prints all triggers -argocd admin notifications trigger get -# print YAML formatted on-sync-failed trigger definition -argocd admin 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. - --as-uid string UID to impersonate for the operation - --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 - --proxy-url string If provided, this URL will be used to connect via proxy - --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 admin notifications trigger run - -Evaluates specified trigger condition and prints the result - -``` -argocd admin notifications trigger run NAME RESOURCE_NAME [flags] -``` - -### Examples - -``` - -# Execute trigger configured in 'argocd-notification-cm' ConfigMap -argocd admin notifications trigger run on-sync-status-unknown ./sample-app.yaml - -# Execute trigger using my-config-map.yaml instead of 'argocd-notifications-cm' ConfigMap -argocd admin 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. - --as-uid string UID to impersonate for the operation - --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 - --proxy-url string If provided, this URL will be used to connect via proxy - --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 -``` +The following commands may help debug issues with notifications: +* [`argocd admin notifications template get`](../../user-guide/commands/argocd_admin_notifications_template_get.md) +* [`argocd admin notifications template notify`](../../user-guide/commands/argocd_admin_notifications_template_notify.md) +* [`argocd admin notifications trigger get`](../../user-guide/commands/argocd_admin_notifications_trigger_get.md) +* [`argocd admin notifications trigger run`](../../user-guide/commands/argocd_admin_notifications_trigger_run.md) diff --git a/docs/operator-manual/notifications/troubleshooting-errors.md b/docs/operator-manual/notifications/troubleshooting-errors.md index c46d4c47468e0..f76bb7a2b0d3f 100644 --- a/docs/operator-manual/notifications/troubleshooting-errors.md +++ b/docs/operator-manual/notifications/troubleshooting-errors.md @@ -36,6 +36,6 @@ You need to check your argocd-notifications controller version. For instance, th ## Failed to notify recipient -### notification service 'xxxx' is not supported" +### 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/operator-manual/notifications/troubleshooting.md b/docs/operator-manual/notifications/troubleshooting.md index 68ea134e0c52a..6e144bb0c9985 100644 --- a/docs/operator-manual/notifications/troubleshooting.md +++ b/docs/operator-manual/notifications/troubleshooting.md @@ -1,32 +1,30 @@ -## Troubleshooting - -The `argocd admin notifications` is a CLI command group that helps to configure the controller -settings and troubleshoot issues. +`argocd admin notifications` is a CLI command group that helps to configure the controller +settings and troubleshoot issues. Full command details are available in the [command reference](../../user-guide/commands/argocd_admin_notifications.md). ## Global flags -Following global flags are available for all sub-commands: +The following global flags are available for all sub-commands: -* `config-map` - path to the file containing `argocd-notifications-cm` ConfigMap. If not specified +* `--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 +* `--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. +Additionally, you can specify `:empty` to use empty secret with no notification service settings. **Examples:** -* Get list of triggers configured in the local config map: +* Get a list of triggers configured in the local config map: -```bash -argocd admin notifications trigger get \ - --config-map ./argocd admin notifications-cm.yaml --secret :empty -``` + ```bash + argocd admin notifications trigger get \ + --config-map ./argocd admin notifications-cm.yaml --secret :empty + ``` * Trigger notification using in-cluster config map and secret: -```bash -argocd admin notifications template notify \ - app-sync-succeeded guestbook --recipient slack:argocd admin notifications -``` + ```bash + argocd admin notifications template notify \ + app-sync-succeeded guestbook --recipient slack:argocd admin notifications + ``` ## Kustomize @@ -44,17 +42,17 @@ kustomize build ./argocd-notifications | \ ### On your laptop -You can download the `argocd` CLI from the github [release](https://github.com/argoproj/argo-cd/releases) +You can download the `argocd` CLI from the GitHub [release](https://github.com/argoproj/argo-cd/releases) attachments. -The binary is available in `argoproj/argo-cd` image. Use the `docker run` and volume mount +The binary is available in the `quay.io/argoproj/argocd` 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 \ - argoproj/argo-cd: \ + quay.io/argoproj/argocd: \ /app/argocd admin notifications trigger get \ --config-map ./argocd-notifications-cm.yaml --secret :empty ``` @@ -72,7 +70,12 @@ kubectl exec -it argocd-notifications-controller- \ ## Commands -{!docs/operator-manual/notifications/troubleshooting-commands.md!} +The following commands may help debug issues with notifications: + +* [`argocd admin notifications template get`](../../user-guide/commands/argocd_admin_notifications_template_get.md) +* [`argocd admin notifications template notify`](../../user-guide/commands/argocd_admin_notifications_template_notify.md) +* [`argocd admin notifications trigger get`](../../user-guide/commands/argocd_admin_notifications_trigger_get.md) +* [`argocd admin notifications trigger run`](../../user-guide/commands/argocd_admin_notifications_trigger_run.md) ## Errors diff --git a/mkdocs.yml b/mkdocs.yml index f20e3105e2b4f..35b0b30c10345 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,7 +60,7 @@ nav: - operator-manual/web_based_terminal.md - operator-manual/config-management-plugins.md - operator-manual/deep_links.md - - Notification: + - Notifications: - Overview: operator-manual/notifications/index.md - operator-manual/notifications/triggers.md - operator-manual/notifications/templates.md