From d84137dbe9e4485bfc27b62fb9d8763643c56116 Mon Sep 17 00:00:00 2001 From: Christopher Coco Date: Mon, 4 Aug 2025 16:27:01 -0400 Subject: [PATCH 1/6] docs(webhook): add documentation for webhook command and add webhook related flags to run command docs Signed-off-by: Christopher Coco --- cmd/webhook.go | 3 - docs/configuration/webhook.md | 0 docs/install/cmd/run.md | 26 ++++- docs/install/cmd/webhook.md | 189 ++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 + 5 files changed, 216 insertions(+), 4 deletions(-) create mode 100644 docs/configuration/webhook.md create mode 100644 docs/install/cmd/webhook.md diff --git a/cmd/webhook.go b/cmd/webhook.go index 35c09865..0dfe744e 100644 --- a/cmd/webhook.go +++ b/cmd/webhook.go @@ -10,7 +10,6 @@ import ( "strings" "syscall" "text/template" - "time" "github.com/argoproj-labs/argocd-image-updater/pkg/argocd" "github.com/argoproj-labs/argocd-image-updater/pkg/common" @@ -169,8 +168,6 @@ Supported registries: webhookCmd.Flags().BoolVar(&cfg.ClientOpts.Insecure, "argocd-insecure", env.GetBoolVal("ARGOCD_INSECURE", false), "(INSECURE) ignore invalid TLS certs for ArgoCD server") webhookCmd.Flags().BoolVar(&cfg.ClientOpts.Plaintext, "argocd-plaintext", env.GetBoolVal("ARGOCD_PLAINTEXT", false), "(INSECURE) connect without TLS to ArgoCD server") webhookCmd.Flags().StringVar(&cfg.ClientOpts.AuthToken, "argocd-auth-token", "", "use token for authenticating to ArgoCD (unsafe - consider setting ARGOCD_TOKEN env var instead)") - webhookCmd.Flags().BoolVar(&cfg.DryRun, "dry-run", false, "run in dry-run mode. If set to true, do not perform any changes") - webhookCmd.Flags().DurationVar(&cfg.CheckInterval, "interval", env.GetDurationVal("IMAGE_UPDATER_INTERVAL", 2*time.Minute), "interval for how often to check for updates") webhookCmd.Flags().StringVar(&cfg.LogLevel, "loglevel", env.GetStringVal("IMAGE_UPDATER_LOGLEVEL", "info"), "set the loglevel to one of trace|debug|info|warn|error") webhookCmd.Flags().StringVar(&kubeConfig, "kubeconfig", "", "full path to kubernetes client configuration, i.e. ~/.kube/config") webhookCmd.Flags().StringVar(&cfg.RegistriesConf, "registries-conf-path", defaultRegistriesConfPath, "path to registries configuration file") diff --git a/docs/configuration/webhook.md b/docs/configuration/webhook.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/install/cmd/run.md b/docs/install/cmd/run.md index 738f9231..efe62fb8 100644 --- a/docs/install/cmd/run.md +++ b/docs/install/cmd/run.md @@ -83,6 +83,18 @@ for images can only be specified from an environment variable. If this flag is set, Argo CD Image Updater won't actually perform any changes to workloads it found in need for upgrade. +**--docker-webhook-secret *secret*** + +Secret for validating Docker Hub webhooks. + +**--enable-webhook *enabled*** + +Enable webhook server for receiving registry events. + +**--ghcr-webhook-secret *secret*** + +Secret for validating GitHub container registryw webhooks. + **--git-commit-email *email*** E-Mail address to use for Git commits (default "noreply@argoproj.io") @@ -115,6 +127,10 @@ Username to use for Git commits (default "argocd-image-updater") Can also be set using the *GIT_COMMIT_USER* environment variable. +**--harbor-webhook-secret *secret*** + +Secret for validating Harbor webhooks + **--health-port *port*** Specifies the local port to bind the health server to. The health server is @@ -190,6 +206,10 @@ port to start the metrics server on, 0 to disable (default 8081) A shortcut for specifying `--interval 0 --health-port 0`. If given, Argo CD Image Updater will exit after the first update cycle. +**--quay-webhook-secret *secret*** + +Secret for validating Quay webhooks. + **--registries-conf-path *path*** Load the registry configuration from file at *path*. Defaults to the path @@ -201,4 +221,8 @@ default configuration should be used instead, specify the empty string, i.e. whether to perform a cache warm-up on startup (default true) -[label selector syntax]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors \ No newline at end of file +**--webhook-port *port*** + +Port to listen on for webhook events (default 8082) + +[label selector syntax]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors diff --git a/docs/install/cmd/webhook.md b/docs/install/cmd/webhook.md new file mode 100644 index 00000000..559d6601 --- /dev/null +++ b/docs/install/cmd/webhook.md @@ -0,0 +1,189 @@ +## Command "webhook" + +### Synopsis + +`argocd-image-updater webhook [flags]` + +### Description + +Starts a server that listens for webhook events from container registries. When an event is received, it can trigger an image update check for the affected images. + +Supported Registries: + +- Docker Hub +- GitHub Container Registry (GHCR) +- Quay +- Harbor + +### Flags + +**--application-namespace *namespace*** + +Specifies the Kubernetes namespace in which Argo CD Image Updater will manage Argo CD Applications when using the Kubernetes-based Application API. By default, applications in all namespaces are considered. This flag can be used to limit scope to a single namespace for performance, security, or organizational reasons. + +**--applications-api *api kind*** + +API kind that is used to manage Argo CD applications ('kubernetes' or 'argocd') (default "kubernetes") + +Can also be set using the *APPLICATIONS_API* environment variable. + +**--argocd-auth-token *token*** + +Use *token* for authenticating to the Argo CD API. This token must be a base64 +encoded JWT, as generated by Argo CD. + +The token can also be set using the *ARGOCD_TOKEN* environment variable. + +**--argocd-grpc-web** + +If this flag is given, use the gRPC-web protocol to connect to the Argo CD API. +This can be useful if your Argo CD API is behind a proxy that does not support +HTTP/2, or only accept HTTP/2 on the front end. + +Can also be set using the *ARGOCD_GRPC_WEB* environment variable. + +**--argocd-insecure** + +If specified, the certificate of the Argo CD API server is not verified. Useful +if you are using a self-signed TLS certificate for the Argo CD API server. As +the name implies, this is an *insecure* setting and should not be used for +production systems. + +Can also be set using the *ARGOCD_INSECURE* environment variable. + +**-argocd-namespace *namespace*** + +namespace where ArgoCD runs in (current namespace by default) + +**--argocd-plaintext** + +If specified, use an unencrypted HTTP connection to the ArgoCD API instead of +TLS. + +Can also be set using the *ARGOCD_PLAINTEXT* environment variable. + +**--argocd-server-addr *server address*** + +Connect to the Argo CD API server at *server address*. *server address* must +be a valid IP address or DNS host name, optionally with a port specification +delimited using a colon, i.e. *10.23.42.5* or *argocd-server.argocd:8080*. +If no port given, the protocol default will be used: Port 80 for plaintext +connections, and port 443 for TLS connections. + +Can also be set using the *ARGOCD_SERVER* environment variable. + +**--disable-kube-events** + +Disable kubernetes events + +Can also be set with the *IMAGE_UPDATER_KUBE_EVENTS* environment variable. + +**--disable-kubernetes** + +If running locally, and you do not have a working connection to any Kubernetes +cluster, this flag will prevent Argo CD Image Updater from creating a client +to interact with Kubernetes. When Kubernetes access is disabled, pull secrets +for images can only be specified from an environment variable. + +**--docker-webhook-secret *secret*** + +Secret for validating Docker Hub webhooks. + +**--ghcr-webhook-secret *secret*** + +Secret for validating GitHub container registry secrets. + +**--git-commit-email *email*** + +E-Mail address to use for Git commits (default "noreply@argoproj.io") + +Can also be set using the *GIT_COMMIT_EMAIL* environment variable. + +**--git-commit-message-path *path*** + +Path to a template to use for Git commit messages (default "/app/config/commit.template") + +**--git-commit-sign-off** + +Whether to sign-off git commits + +**--git-commit-signing-key *key*** + +GnuPG key ID or path to Private SSH Key used to sign the commits + +Can also be set using the *GIT_COMMIT_SIGNING_KEY* environment variable. + +**--git-commit-signing-method *method*** + +Method used to sign Git commits ('openpgp' or 'ssh') (default "openpgp") + +Can also be set using the *GIT_COMMIT_SIGNING_METHOD* environment variable. + +**--git-commit-user *user*** + +Username to use for Git commits (default "argocd-image-updater") + +Can also be set using the *GIT_COMMIT_USER* environment variable. + +**--harbor-webhook-secret *secret*** + +Secret for validating Harbor webhooks + +**-h, --help** + +help for run + +**--kubeconfig *path*** + +Specify the Kubernetes client config file to use when running outside a +Kubernetes cluster, i.e. `~/.kube/config`. When specified, Argo CD Image +Updater will use the currently active context in the configuration to connect +to the Kubernetes cluster. + +**--loglevel *level*** + +Set the log level to *level*, where *level* can be one of `trace`, `debug`, +`info`, `warn` or `error`. + +Can also be set using the *IMAGE_UPDATER_LOGLEVEL* environment variable. + +**--match-application-label *selector*** + +Only process applications that have a valid annotation and match the given +*label* selector. The *selector* is a string that matches the standard kubernetes +[label selector syntax][]. For e.g., `custom.label/name=xyz` would be a valid label +that can be supplied through this parameter. Any applications carrying this +exact label will be considered as candidates for image updates. This parameter +currently does not support pattern matching on label values (e.g `customer.label/name=*-staging`). +You can specify equality, inequality, or set based requirements or a combination. +For e.g., `app,app!=foo,custom.label/name=xyz,customer in (a,b,c)` + +**--match-application-name *pattern*** + +Only process applications that have a valid annotation and matches the given +*pattern*. The *pattern* is a simple glob pattern and supports file system +style wildcards, i.e. `*-staging` would match any application name with a +suffix of `-staging`. Can be specified multiple times to define more than +one pattern, from which at least one has to match. + +**--max-concurrency *number*** + +Process a maximum of *number* applications concurrently. To disable concurrent +application processing, specify a number of `1`. + +**--quay-webhook-secret *secret*** + +Secret for validating Quay webhooks + +**--registries-conf-path *path*** + +Load the registry configuration from file at *path*. Defaults to the path +`/app/config/registries.conf`. If no configuration should be loaded, and the +default configuration should be used instead, specify the empty string, i.e. +`--registries-conf-path=""`. + +**--webhook-port *int*** + +Port to listen on for webhook events (default 8080) + +[label selector syntax]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors diff --git a/mkdocs.yml b/mkdocs.yml index e5781421..2a49cd34 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,6 +35,7 @@ nav: - Command "template": install/cmd/template.md - Command "test": install/cmd/test.md - Command "version": install/cmd/version.md + - Command "webhook": install/cmd/webhook.md - Basics: - Updating images: basics/update.md - Update methods: basics/update-methods.md @@ -44,6 +45,7 @@ nav: - Applications: configuration/applications.md - Images: configuration/images.md - Container Registries: configuration/registries.md + - Webhook: configuration/webhook.md - Contributing: - Overview: contributing/start.md - Developing: contributing/development.md From 7baff671f65b4c963a615c64e5131fc59c9870cc Mon Sep 17 00:00:00 2001 From: Christopher Coco Date: Tue, 5 Aug 2025 14:46:53 -0400 Subject: [PATCH 2/6] docs(webhook): add configuration page for webhook Signed-off-by: Christopher Coco --- docs/configuration/webhook.md | 134 ++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/docs/configuration/webhook.md b/docs/configuration/webhook.md index e69de29b..7d8d6f50 100644 --- a/docs/configuration/webhook.md +++ b/docs/configuration/webhook.md @@ -0,0 +1,134 @@ +# Webhook Configuration + +Image Updater can be configured to respond to webhook notifications from various container registries. + +Currently Supported Registries: + +- Docker Hub +- GitHub Container Registry +- Harbor +- Quay + +Using webhooks can help reduce some of the stress that is put on the container registries and where you are running Image Updater by reducing the need to poll. + +## Enabling the Webhook Server + +There are two ways to enable the webhook server. You can either use it with polling still enabled through the `run` command or just have the webhook +server running through the webhook command. + +### Enabling with `run` Command +Below is the command for running the webhook server with polling through the `run` command. The `--enable-webhook` flag is all that is required. The default port of the webhook server in this method is `8082`. +``` +argocd-image-updater run --enable-webhook --webhook-port [PORT] +``` + +### Enabling with `webhook` Command +You can also run the webhook server without polling. See below for the command for this. The default port for this method is `8080`. +``` +argocd-image-updater webhook --webhook-port [PORT] +``` + +### Altering Manifests to Use Webhook +If you are running Image Updater within your cluster, to enable the webhook you will need to alter the manifests of the application. +What you need to edit depends on what command you plan to use. + +If you want to use the webhook with polling through the `run` command you need to edit the `argocd-image-updater-config` ConfigMap with the following data: +``` +data: + # enable the webhook server + webhook.enable: true + # (OPTIONAL) set the port for the webhook server + webhook.port: +``` + +If you plan to use the webhook command for the server then the `argocd-image-updater` Deployment must be updated. Adjustments to the `argocd-image-updater-config` ConfigMap are optional. +``` +# argocd-image-updater Deployment, container args need to be changed to webhook +spec: + template: + spec: + containers: + - args: + - webhook +--- +# (OPTIONAL) argocd-image-updater-config ConfigMap, edit to change the webhook server port +data: + webhook.port: +``` + +## Endpoints +The webhook server contains two endpoints, `webhook` and `healthz`. + +The `webhook` endpoint is used to receive and process webhook notifications. + +The `healthz` endpoint acts has a health endpoint to check to see if the server is alive. + +## Setting Up a Webhook Notification + +To set up a webhook notification, refer to your container registries documentation on how to do that. Documentation for the supported registries can be found here: + +- [Docker Hub](https://docs.docker.com/docker-hub/repos/manage/webhooks/) +- [GitHub Container Registry](https://docs.github.com/en/webhooks/webhook-events-and-payloads) +- [Harbor](https://goharbor.io/docs/1.10/working-with-projects/project-configuration/configure-webhooks/) +- [Quay](https://docs.quay.io/guides/notifications.html) + +For the URL that you set for the webhook, your link should go as the following: +``` +https://imageupdater.yourdomain.com/webhook?type= +# Value of `type` for each supported container registry +# Docker = docker.io +# GitHub Container Registry = ghcr.io +# Harbor = harbor +# Quay = quay.io +``` + +## Secrets + +To help secure the webhook server you can apply a secret that is used to validate the incoming notification. The secrets can be set by editing the `argocd-image-updater-secret` secret. + +``` +stringData: + webhook.docker-secret: + webhook.ghcr-secret: + webhook.harbor-secret: + webhook.quay-secret: +``` + +You also need to configure the webhook notification to use the secret based on the methods below. See below for the two ways and which of the supported registries use that. + +### Registries With Preexisting Support For Secrets + +There are container registries that have built in secrets support. How you apply the secret will vary depending on the registry so follow the instructions linked in the documentation for that registry. + +Supported Registries That Use This: + +- GitHub Container Registry +- Harbor + +### Parameter Secrets + +Because some container registries do not support secrets, there is a method included to have secrets for registries. This is through the query parameters in the URL of the webhook. This is not the most secure method and is there for a small extra layer. + +!!!warning + This is not the most secure method, it is just here for a small extra layer. + **Do not use a secret that is shared with other critical services for this method!** + +It can be applied to the URL as below: +``` +https://imageupdater.yourdomain.com/webhook?type&secret?= +``` + +Supported Registries That Use This: + +- Docker Hub +- Quay + +## Exposing the Server + +To expose the webhook server we have provided a service and ingress to get started. These manifests are not applied with `install.yaml` so you will need to apply them yourself. + +They are located in the `manifets/base/networking` directory. + +## Adding Support For Other Registries + +If the container registry that you use is not supported yet, feel free to implement a handler for it. You can find examples on how the other handlers are implemented in the `pkg/webhook` directory. If you intend to open a PR for your handler to be added please update this documentation page to include the information about yours with the others. From 67f555c32de36459f5a72a868336c1ac248b3fe2 Mon Sep 17 00:00:00 2001 From: Christopher Coco Date: Tue, 5 Aug 2025 15:28:25 -0400 Subject: [PATCH 3/6] docs(webhook): fix typo Signed-off-by: Christopher Coco --- docs/configuration/webhook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/webhook.md b/docs/configuration/webhook.md index 7d8d6f50..52e19935 100644 --- a/docs/configuration/webhook.md +++ b/docs/configuration/webhook.md @@ -115,7 +115,7 @@ Because some container registries do not support secrets, there is a method incl It can be applied to the URL as below: ``` -https://imageupdater.yourdomain.com/webhook?type&secret?= +https://imageupdater.yourdomain.com/webhook?type=&secret= ``` Supported Registries That Use This: From eb9cdd08cf76b2932953b2ae770b69f9fa1a7b6e Mon Sep 17 00:00:00 2001 From: Christopher Coco Date: Wed, 6 Aug 2025 09:09:14 -0400 Subject: [PATCH 4/6] docs(webhook): alter url for examples Signed-off-by: Christopher Coco --- docs/configuration/webhook.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration/webhook.md b/docs/configuration/webhook.md index 52e19935..12292584 100644 --- a/docs/configuration/webhook.md +++ b/docs/configuration/webhook.md @@ -74,7 +74,7 @@ To set up a webhook notification, refer to your container registries documentati For the URL that you set for the webhook, your link should go as the following: ``` -https://imageupdater.yourdomain.com/webhook?type= +https://app1.example.com/webhook?type= # Value of `type` for each supported container registry # Docker = docker.io # GitHub Container Registry = ghcr.io @@ -115,7 +115,7 @@ Because some container registries do not support secrets, there is a method incl It can be applied to the URL as below: ``` -https://imageupdater.yourdomain.com/webhook?type=&secret= +https://app1.example.com/webhook?type=&secret= ``` Supported Registries That Use This: From 34907678628a4739195d02d38252735ec94a7341 Mon Sep 17 00:00:00 2001 From: Christopher Coco Date: Wed, 6 Aug 2025 12:09:49 -0400 Subject: [PATCH 5/6] docs(webhook): fix various typos and add section for environment variables Signed-off-by: Christopher Coco --- docs/configuration/webhook.md | 21 +++++++++++++++++---- docs/install/cmd/run.md | 2 +- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/configuration/webhook.md b/docs/configuration/webhook.md index 12292584..9217ad48 100644 --- a/docs/configuration/webhook.md +++ b/docs/configuration/webhook.md @@ -33,7 +33,7 @@ If you are running Image Updater within your cluster, to enable the webhook you What you need to edit depends on what command you plan to use. If you want to use the webhook with polling through the `run` command you need to edit the `argocd-image-updater-config` ConfigMap with the following data: -``` +```yaml data: # enable the webhook server webhook.enable: true @@ -42,7 +42,7 @@ data: ``` If you plan to use the webhook command for the server then the `argocd-image-updater` Deployment must be updated. Adjustments to the `argocd-image-updater-config` ConfigMap are optional. -``` +```yaml # argocd-image-updater Deployment, container args need to be changed to webhook spec: template: @@ -86,11 +86,11 @@ https://app1.example.com/webhook?type= To help secure the webhook server you can apply a secret that is used to validate the incoming notification. The secrets can be set by editing the `argocd-image-updater-secret` secret. -``` +```yaml stringData: webhook.docker-secret: webhook.ghcr-secret: - webhook.harbor-secret: + webhook.harbor-secret: webhook.quay-secret: ``` @@ -129,6 +129,19 @@ To expose the webhook server we have provided a service and ingress to get start They are located in the `manifets/base/networking` directory. +## Environment Variables + +The flags for both the `run` and `webhook` CLI commands can also be set via environment variables. Below is the list of which variables correspond to which flag. + +|Environment Variable|Corresponding Flag| +|--------|--------| +|`ENABLE_WEBHOOK`|`--enable-webhook`| +|`WEBHOOK_PORT`|`--webhook-port`| +|`DOCKER_WEBHOOK_SECRET` |`--docker-webhook-secret`| +|`GHCR_WEBHOOK_SECRET` |`--gchr-webhook-secret`| +|`HARBOR_WEBHOOK_SECRET` |`--harbor-webhook-secret`| +|`QUAY_WEBHOOK_SECRET` |`--quay-webhook-secret`| + ## Adding Support For Other Registries If the container registry that you use is not supported yet, feel free to implement a handler for it. You can find examples on how the other handlers are implemented in the `pkg/webhook` directory. If you intend to open a PR for your handler to be added please update this documentation page to include the information about yours with the others. diff --git a/docs/install/cmd/run.md b/docs/install/cmd/run.md index efe62fb8..06126c28 100644 --- a/docs/install/cmd/run.md +++ b/docs/install/cmd/run.md @@ -93,7 +93,7 @@ Enable webhook server for receiving registry events. **--ghcr-webhook-secret *secret*** -Secret for validating GitHub container registryw webhooks. +Secret for validating GitHub container registry webhooks. **--git-commit-email *email*** From 30a5f08739b2a0b67df76859d71cf596161986e8 Mon Sep 17 00:00:00 2001 From: Christopher Coco Date: Wed, 6 Aug 2025 13:51:12 -0400 Subject: [PATCH 6/6] docs(webhook): add sections for troubleshooting and links to example payloads Signed-off-by: Christopher Coco --- docs/configuration/webhook.md | 99 +++++++++++++++++++++++++++++------ 1 file changed, 82 insertions(+), 17 deletions(-) diff --git a/docs/configuration/webhook.md b/docs/configuration/webhook.md index 9217ad48..3bff84b9 100644 --- a/docs/configuration/webhook.md +++ b/docs/configuration/webhook.md @@ -1,6 +1,7 @@ # Webhook Configuration -Image Updater can be configured to respond to webhook notifications from various container registries. +Image Updater can be configured to respond to webhook notifications from +various container registries. Currently Supported Registries: @@ -9,30 +10,38 @@ Currently Supported Registries: - Harbor - Quay -Using webhooks can help reduce some of the stress that is put on the container registries and where you are running Image Updater by reducing the need to poll. +Using webhooks can help reduce some of the stress that is put on the +container registries and where you are running Image Updater by reducing the +need to poll. ## Enabling the Webhook Server -There are two ways to enable the webhook server. You can either use it with polling still enabled through the `run` command or just have the webhook +There are two ways to enable the webhook server. You can either use it with +polling still enabled through the `run` command or just have the webhook server running through the webhook command. ### Enabling with `run` Command -Below is the command for running the webhook server with polling through the `run` command. The `--enable-webhook` flag is all that is required. The default port of the webhook server in this method is `8082`. +Below is the command for running the webhook server with polling through the ` +run` command. The `--enable-webhook` flag is all that is required. The +default port of the webhook server in this method is `8082`. ``` argocd-image-updater run --enable-webhook --webhook-port [PORT] ``` ### Enabling with `webhook` Command -You can also run the webhook server without polling. See below for the command for this. The default port for this method is `8080`. +You can also run the webhook server without polling. See below for the +command for this. The default port for this method is `8080`. ``` argocd-image-updater webhook --webhook-port [PORT] ``` ### Altering Manifests to Use Webhook -If you are running Image Updater within your cluster, to enable the webhook you will need to alter the manifests of the application. -What you need to edit depends on what command you plan to use. +If you are running Image Updater within your cluster, to enable the webhook +you will need to alter the manifests of the application. What you need to +edit depends on what command you plan to use. -If you want to use the webhook with polling through the `run` command you need to edit the `argocd-image-updater-config` ConfigMap with the following data: +If you want to use the webhook with polling through the `run` command you +need to edit the `argocd-image-updater-config` ConfigMap with the following data: ```yaml data: # enable the webhook server @@ -41,7 +50,9 @@ data: webhook.port: ``` -If you plan to use the webhook command for the server then the `argocd-image-updater` Deployment must be updated. Adjustments to the `argocd-image-updater-config` ConfigMap are optional. +If you plan to use the webhook command for the server then the `argocd-image- +updater` Deployment must be updated. Adjustments to the `argocd-image-updater-config` +ConfigMap are optional. ```yaml # argocd-image-updater Deployment, container args need to be changed to webhook spec: @@ -65,7 +76,9 @@ The `healthz` endpoint acts has a health endpoint to check to see if the server ## Setting Up a Webhook Notification -To set up a webhook notification, refer to your container registries documentation on how to do that. Documentation for the supported registries can be found here: +To set up a webhook notification, refer to your container registries +documentation on how to do that. Documentation for the supported registries +can be found here: - [Docker Hub](https://docs.docker.com/docker-hub/repos/manage/webhooks/) - [GitHub Container Registry](https://docs.github.com/en/webhooks/webhook-events-and-payloads) @@ -84,7 +97,9 @@ https://app1.example.com/webhook?type= ## Secrets -To help secure the webhook server you can apply a secret that is used to validate the incoming notification. The secrets can be set by editing the `argocd-image-updater-secret` secret. +To help secure the webhook server you can apply a secret that is used to +validate the incoming notification. The secrets can be set by editing the +`argocd-image-updater-secret` secret. ```yaml stringData: @@ -94,11 +109,14 @@ stringData: webhook.quay-secret: ``` -You also need to configure the webhook notification to use the secret based on the methods below. See below for the two ways and which of the supported registries use that. +You also need to configure the webhook notification to use the secret based +on the methods below. See below for the two ways and which of the supported registries use that. ### Registries With Preexisting Support For Secrets -There are container registries that have built in secrets support. How you apply the secret will vary depending on the registry so follow the instructions linked in the documentation for that registry. +There are container registries that have built in secrets support. How you +apply the secret will vary depending on the registry so follow the +instructions linked in the documentation for that registry. Supported Registries That Use This: @@ -107,7 +125,10 @@ Supported Registries That Use This: ### Parameter Secrets -Because some container registries do not support secrets, there is a method included to have secrets for registries. This is through the query parameters in the URL of the webhook. This is not the most secure method and is there for a small extra layer. +Because some container registries do not support secrets, there is a method +included to have secrets for registries. This is through the query parameters +in the URL of the webhook. This is not the most secure method and is there +for a small extra layer. !!!warning This is not the most secure method, it is just here for a small extra layer. @@ -123,15 +144,21 @@ Supported Registries That Use This: - Docker Hub - Quay +Also be aware that if the container registry has a built-in secrets method you will +not be able to use this method. + ## Exposing the Server -To expose the webhook server we have provided a service and ingress to get started. These manifests are not applied with `install.yaml` so you will need to apply them yourself. +To expose the webhook server we have provided a service and ingress to get +started. These manifests are not applied with `install.yaml` so you will need +to apply them yourself. They are located in the `manifets/base/networking` directory. ## Environment Variables -The flags for both the `run` and `webhook` CLI commands can also be set via environment variables. Below is the list of which variables correspond to which flag. +The flags for both the `run` and `webhook` CLI commands can also be set via +environment variables. Below is the list of which variables correspond to which flag. |Environment Variable|Corresponding Flag| |--------|--------| @@ -144,4 +171,42 @@ The flags for both the `run` and `webhook` CLI commands can also be set via envi ## Adding Support For Other Registries -If the container registry that you use is not supported yet, feel free to implement a handler for it. You can find examples on how the other handlers are implemented in the `pkg/webhook` directory. If you intend to open a PR for your handler to be added please update this documentation page to include the information about yours with the others. +If the container registry that you use is not supported yet, feel free to +implement a handler for it. You can find examples on how the other handlers +are implemented in the `pkg/webhook` directory. If you intend to open a PR for +your handler to be added please update this documentation page to include the +information about yours with the others. + +## Example Payloads + +Below is a list of links for finding example payloads for each of the container +registries supported. + +- [Docker Hub](https://docs.docker.com/docker-hub/repos/manage/webhooks/#example-webhook-payload) +- [GitHub Container Registry](https://docs.github.com/en/webhooks/webhook-events-and-payloads#example-webhook-delivery) +- [Harbor](https://goharbor.io/docs/1.10/working-with-projects/project-configuration/configure-webhooks/) +(View JSON Payload Format Section) +- [Quay](https://docs.quay.io/guides/notifications.html) +(View Repository Push Section) + +## Troubleshooting + +This section will cover some potential errors that may arise when sending +notifications to the webhook server. Errors are propagated through the response body. + +**Failed to process webhook/webhook event: ** + +If you are consistently seeing this error then there may be something wrong +with the handler for that registry or there could be a problem with something +else. If this continuously occurs please open an issue with the error information. + +**no handler available for this webhook** + +Make sure you included the `type` query parameter for the type of webhook +handler and ensure that it is correct. + +**Missing/incorrect webhook secret** + +If you are seeing this message make sure that you have secrets configured +properly in your container registry whether it is through their service +or the query parameters.