docs(webhook): add documentation for webhook feature

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")

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: <Value between 0 - 65535>
+```
+
+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: <Value between 0 - 65535>
+```
+
+## 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=<YOUR_REGISTRY_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: <YOUR_SECRET>
+  webhook.ghcr-secret: <YOUR_SECRET>
+  webhook.harbor-secret: <YOUR SECRET>
+  webhook.quay-secret: <YOUR_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<YOUR_REGISTRY_TYPE>&secret?=<YOUR_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.

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 "[email protected]")
@@ -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
+**--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

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 "[email protected]")
+
+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