From 5424e1602e56200cdf9d5c1d45c2f007ddd9915f Mon Sep 17 00:00:00 2001 From: jannfis Date: Sun, 13 Mar 2022 21:12:43 +0100 Subject: docs: Refactor docs (#398) * docs: Refactor docs Signed-off-by: jannfis * Fix spelling Signed-off-by: jannfis * Fix spelling Signed-off-by: jannfis * Sort expect Signed-off-by: jannfis --- docs/assets/extra.css | 15 ++ docs/basics/authentication.md | 245 ++++++++++++++++++++++++ docs/basics/update-methods.md | 282 +++++++++++++++++++++++++++ docs/basics/update-strategies.md | 236 +++++++++++++++++++++++ docs/basics/update.md | 85 ++++++++ docs/configuration/applications.md | 293 +++------------------------- docs/configuration/images.md | 74 ++++++- docs/configuration/registries.md | 383 +++++++++++++++++++++++++------------ docs/examples/index.md | 7 + docs/index.md | 31 +-- docs/install/installation.md | 266 ++++++++++++++++++++++++++ docs/install/reference.md | 144 ++++++++++++++ docs/install/running.md | 144 -------------- docs/install/start.md | 312 ------------------------------ docs/install/strategies.md | 205 -------------------- docs/install/testing.md | 132 +++++++++++++ 16 files changed, 1786 insertions(+), 1068 deletions(-) create mode 100644 docs/basics/authentication.md create mode 100644 docs/basics/update-methods.md create mode 100644 docs/basics/update-strategies.md create mode 100644 docs/basics/update.md create mode 100644 docs/examples/index.md create mode 100644 docs/install/installation.md create mode 100644 docs/install/reference.md delete mode 100644 docs/install/running.md delete mode 100644 docs/install/start.md delete mode 100644 docs/install/strategies.md create mode 100644 docs/install/testing.md (limited to 'docs') diff --git a/docs/assets/extra.css b/docs/assets/extra.css index 055aff2..bc120d7 100644 --- a/docs/assets/extra.css +++ b/docs/assets/extra.css @@ -8,3 +8,18 @@ background-color: transparent; padding: .525rem .6rem; } + +@media only screen and (min-width: 76.25em) { + .md-main__inner { + max-width: none; + } + .md-sidebar--primary { + left: 0; + } + .md-sidebar--secondary { + right: 0; + margin-left: 0; + -webkit-transform: none; + transform: none; + } + } \ No newline at end of file diff --git a/docs/basics/authentication.md b/docs/basics/authentication.md new file mode 100644 index 0000000..ffcc343 --- /dev/null +++ b/docs/basics/authentication.md @@ -0,0 +1,245 @@ +# Authentication in Argo CD Image Updater + +There are several scenarios where Argo CD Image Updater needs to authenticate +to external systems in order to fulfil its duties. + +## Authentication to Kubernetes + +If you are running Argo CD Image Updater as a Kubernetes workload in the +`kubernetes` API access mode (which is the default), it uses the token of a +ServiceAccount mounted to its pod to authenticate at the Kubernetes API. + +The name of this ServiceAccount is `argocd-image-updater`, and it gets +created through the installation manifests in the installation namespace. +The ServiceAccount is accompanied with an appropriate Kubernetes RBAC +Role that holds the required permissions, and a RoleBinding to bind the +Role to the ServiceAccount. + +In the default installation scenario, i.e. Argo CD Image Updater installed +to the `argocd` namespace, no further configuration has to done in order +for Argo CD Image Updater to access the Kubernetes API. If your Argo CD +installation is in a different namespace than `argocd`, you would have +to adapt the RoleBinding to bind to the ServiceAccount in the correct +namespace. + +## Authentication to Argo CD + +If you are using Argo CD Image Updater to connect to Argo CD via its API, +you will need to create credentials in Argo CD and provide them to the +Image Updater. + +This usually involves the following steps: + +1. Create a local user with `apiKey` capabilities in Argo CD +1. Generate an authentication token for that user +1. Create appropriate RBAC permissions for that user in Argo CD +1. Configure Argo CD Image Updater to connect to the Argo CD API endpoint + instead of the Kubernetes API +1. Configure Argo CD Image Updater to use the credentials created in steps 1 + and 2 for authenticating at the Argo CD API + +A complete walk-through can be found in the installation guide. + +## Authentication to container registries + +If you are using private registries, or private repositories on public +registries, chances are that you will need to have Argo CD Image Updater use +credentials to access the registry. + +Credentials can be configured either on a per registry basis or on a per image +basis. You can also use a mixed setup where credentials are configured in both +ways. + +If credentials are configured on a per registry basis, all requests to that +registry will use these credentials, without requiring any further +configuration. Also, credentials configured for a registry will be cached +for a configurable time and don't have to be re-read for every authentication +requests. This can be useful especially for situations where you use tokens +with a limited life time that are generated externally, and don't want to +regenerate the token for each request. + +However, you can override the credentials used for authentication to the same +registry on a per image basis, e.g. if you use repositories on the registry +that require a different set of credentials. + +You can read more about +[configuration credentials at the registry level]() +and +[configuration credentials at the image level]() +for more details on how to configure either mechanisms. + +### Types of supported credential sources + +Argo CD Image Updater can source credentials for accessing registries using the +following mechanisms: + +* Secrets stored in Kubernetes. Argo CD Image Updater can either use a typical + Docker pull secret, or a custom secret with credentials in a certain format. + +* An environment variable available to Argo CD Image Updater (for example, + an environment variable mounted to the pod from a secret) + +* A script that, when executed, outputs the credentials to stdout. + +The following sections describe the configuration format to be used for the +different types of credential sources. + +### Using a pull secret + +A pull secret is a secret with a well-defined format, that can also be used +by Kubernetes' container engine to pull container images from registries. + +These secrets typically have a field `.dockerconfigjson` in the `.data` +section, which holds a JSON string with the appropriate credentials. + +In its default configuration, Argo CD Image Updater can only read secrets +from the same namespace where it is installed to. + +Pull secrets can be referenced as follows in credentials configuration: + +``` +pullsecret:/ +``` + +Where `` is the namespace the secret resides in, and `` +is the name of the Secret resource. + +You can create a pull secret by using `kubectl`. The following command would +create a pull secret for Docker Hub named `dockerhub-secret` in the namespace +`argocd`: + +```shell +kubectl create -n argocd secret docker-registry dockerhub-secret \ + --docker-username someuser \ + --docker-password s0m3p4ssw0rd \ + --docker-registry "https://registry-1.docker.io" +``` + +This secret could then be referred to as + +``` +pullsecret:argocd/dockerhub-secret +``` + +### Using a generic secret + +Argo CD Image Updater can also retrieve credentials from a field in a generic +Secret. This may be useful if you have similar credentials for a different set +of registries, and don't want to maintain a unique pull-secret for each +registry. + +The credentials can be stored in any field of the Secret's `.data` section, +but credentials must be stored in the format `:`. + +To retrieve the credentials from a generic secret, you must specify the field +name along with the namespace and name of the secret like follows: + +``` +secret:/# +``` + +E.g. if you have stored your credentials in the field `creds` in the secret +`some-secret` in the namespace `argocd`, you would refer to it as + +``` +secret:argocd/some-secret#creds +``` + +### Using an environment variable + +Argo CD Image Updater can read credentials from an environment variable. This +can be useful for testing purposes (e.g. when using the command +`argocd-image-updater test` to test access to a registry), or if you have the +environment variable to use mounted from a secret to the `argocd-image-updater` +pod. + +To retrieve credentials from an environment variable, you must specify the name +of the environment variable as follows: + +``` +env: +``` + +The credentials passed via environment variables must be specified in the format +`:`, e.g. to store credentials in an environment variable +named `DOCKER_HUB_CREDS`: + +``` +DOCKER_HUB_CREDS=someuser:s0m3p4ssw0rd +``` + +And then, to use this environment variable, reference it as + +``` +env:DOCKER_HUB_CREDS +``` + +### Using a script to generate credentials + +Argo CD Image Updater supports using credentials that are generated by an +external script. In order to retrieve the credentials, Argo CD Image Updater +will execute a user configured script or executable, and parse its output. + +Having a script generate the credentials can be useful if your registry does +require a short-lived token for authentication which is issued by a third +party system, possibly with this third party system requiring a different set +of credentials. A prominent example would be ECR on aws. + +Referencing a script used to output the credentials is done as follows: + +``` +ext: +``` + +When executing the script, Argo CD Image Updater does not pass any arguments +to it. + +The executed script is expected to output exactly one line to stdout, which +holds the credentials used for accessing the registry in the format +`:`. Please note that the output should contain a newline +character. For example, the most simple form of such a script would be: + +```bash +#!/bin/sh + +echo "someuser:s0mep4ssw0rd" +``` + +When executing on Kubernetes, the script to be executed must exist in the +Image Updater container's file system. You can either mount the script from +a config map, or use an init container to copy it. Make sure that the script +is executable. + +For example, if above script would exist at `/usr/local/bin/creds.sh`, it +would be referenced as + +``` +ext:/usr/local/bin/creds.sh +``` + +Please keep in mind that executing scripts to retrieve credentials can become +expensive. If possible, use this method only on a per-registry level with +proper caching. Read more about this in the +[Registry configuration]() +section of the docs. + +* A typical pull secret, i.e. a secret containing a `.dockerconfigjson` field + which holds a Docker client configuration with auth information in JSON + format. This kind of secret is specified using the notation + `pullsecret:/` + +* A custom secret, which has the credentials stored in a configurable field in + the format `:`. This kind of secret is specified using + the notation `secret:/#` + +* An environment variable which holds the credentials in the format + `:`. This kind of secret is specified using the notation + `env:`. + +* A script that outputs credentials on a single line to stdout, in the format + ``. This can be used to support external authentication + mechanisms. You can specify this kind of secret in the notation + `ext:/path/to/script`. Please note that the script must be referenced as + absolute path, and must be executable (i.e. have the `+x` bit set). You + can add scripts to `argocd-image-updater` by using an init container. + diff --git a/docs/basics/update-methods.md b/docs/basics/update-methods.md new file mode 100644 index 0000000..2a368ea --- /dev/null +++ b/docs/basics/update-methods.md @@ -0,0 +1,282 @@ +# Update methods + +## Overview + +Argo CD Image Updater supports several methods to propagate new versions of the +images to Argo CD. These methods are also refered to as *write back methods*. + +Currently, the following methods are supported: + +* [argocd](../configuration/applications.md#method-argocd) + directly modifies the Argo CD *Application* resource, either using Kubernetes + or via Argo CD API, depending on Argo CD Image Updater's configuration. + +* [git](../configuration/applications.md#method-git) + will create a Git commit in your Application's Git repository that holds the + information about the image to update to. + +Depending on the write back method, further configuration may be possible. + +The write back method and its configuration is specified per Application. + +## `argocd` write-back method + +When using the Argo CD API to write back changes, Argo CD Image Updater will +perform a similar action as `argocd app set --parameter ...` to instruct +Argo CD to re-render the manifests using those parameters. + +This method is pseudo-persistent. If you delete the `Application` resource +from the cluster and re-create it, changes made by Image Updater will be gone. +The same is true if you manage your `Application` resources using Git, and +the version stored in Git is synced over the resource in the cluster. This +method is most suitable for Applications also created imperatively, i.e. +using the Web UI or CLI. + +This method is the default and requires no further configuration. + +## `git` write-back method + +!!!warning "Compatibility with Argo CD" + The Git write-back method requires a feature in Argo CD that has been + introduced with Argo CD v2.0. Git write-back will not work with earlier + versions of Argo CD. + +The `git` write-back method uses Git to permanently store its parameter +overrides along with the Application's resource manifests. This will enable +persistent storage of the parameters in Git. + +By default, Argo CD Image Updater will store the parameter in a file named +`.argocd-source-.yaml` in the path used by the Application to source +its manifests from. This will allow Argo CD to pick up parameters in this +file, when rendering manifests for the Application named ``. Using +this approach will also minimize the possibility of merge conflicts, as long +as no other party in your CI will modify this file. + +!!!note "A note on the application's target revision" + Due to the nature of how Git write-back works, your application really + should track a *branch* instead of a revision. If you track `HEAD`, a tag + or a certain revision with your application, you **must** override the + branch in an annotation (see below). But in order for Argo CD to pick up + the change after Image Updater has committed & pushed the change, you + really want to set it up so it tracks a branch. + +To use the Git write-back method, annotate your `Application` with the right +write-back method: + +```yaml +argocd-image-updater.argoproj.io/write-back-method: git +``` + +In order to better decide whether this method is suitable for your use-case, +this is the workflow how Argo CD Image Updater performs change to Git: + +* Fetch the remote repository from location specified by `.spec.source.repoURL` + in the Argo CD Application manifest, using credentials specified as annotation + (see below) +* Check-out the target branch on the local copy. The target branch is either + taken from an annotation (see below), or if no annotation is set, taken from + `.spec.source.targetRevision` in the Application manifest +* Create or update `.argocd-source-.yaml` in the local repository +* Commit the changed file to the local repository +* Push the commit to the remote repository, using credentials specified as + annotation (see below) + +The important pieces to this workflow are: + +* Credentials configured in Argo CD will be re-used, unless you override with a + dedicated set of credentials + +* Write-back is a commit to the tracking branch of the Application. + +* If `.spec.source.targetRevision` does not reference a *branch*, you will have + to specify the branch to use manually (see below) + +### General configuration + +Configuration for the Git write-back method comes from two sources: + +* The Argo CD `Application` manifest is used to define the repository and the + path where the `.argocd-source-.yaml` should be written to. These + are defined in `.spec.source.repoURL` and `.spec.source.path` fields, + respectively. Additionally, `.spec.source.targetRevision` is used to define + the branch to commit and push the changes to. The branch to use can be + overridden by an annotation, see below. + +* A set of annotations on the `Application` manifest, see below + +### Specifying Git credentials + +By default Argo CD Image Updater re-uses the credentials you have configured +in Argo CD for accessing the repository. + +If you don't want to use credentials configured for Argo CD you can use other credentials stored in a Kubernetes secret, +which needs to be accessible by the Argo CD Image Updater's Service Account. The secret should be specified in +`argocd-image-updater.argoproj.io/write-back-method` annotation using `git:` format. Where `` might +take one of following values: + +* `repocreds` (default) - Git repository credentials configured in Argo CD settings +* `secret:/` - namespace and secret name. + +Example: + +```yaml +argocd-image-updater.argoproj.io/write-back-method: git:secret:argocd-image-updater/git-creds +``` + +If the repository is accessed using HTTPS, the secret must contain two fields: +`username` which holds the Git username, and `password` which holds the user's +password or a private access token (PAT) with write access to the repository. +You can generate such a secret using `kubectl`, e.g.: + +```bash +kubectl -n argocd-image-updater create secret generic git-creds \ + --from-literal=username=someuser \ + --from-literal=password=somepassword +``` + +If the repository is accessed using SSH, the secret must contain the field +`sshPrivateKey`, which holds a SSH private key in OpenSSH-compatible PEM +format. To create such a secret from an existing private key, you can use +`kubectl`, for example: + +```bash +kubectl -n argocd-image-updater create secret generic git-creds \ + --from-file=sshPrivateKey=~/.ssh/id_rsa +``` + +### Specifying a branch to commit to + +By default, Argo CD Image Updater will use the value found in the Application +spec at `.spec.source.targetRevision` as Git branch to checkout, commit to +and push back the changes it made. In some scenarios, this might not be what +is desired, and you can (and maybe have to) override the branch to use by +specifying the annotation `argocd-image-updater.argoproj.io/git-branch` on the +Application manifest. + +The value of this annotation will define the Git branch to use, for example the +following would use GitHub's default `main` branch: + +```yaml +argocd-image-updater.argoproj.io/git-branch: main +``` + +### Specifying a separate base and commit branch + +By default, Argo CD Imager Updater will checkout, commit, and push back to the +same branch specified above. There are many scenarios where this is not +desired or possible, such as when the default branch is protected. You can +add a separate write-branch by modifying `argocd-image-updater.argoproj.io/git-branch` +with additional data, which will create a new branch from the base branch, and +push to this new branch instead: + +```yaml +argocd-image-updater.argoproj.io/git-branch: base:target +``` + +If you want to specify a write-branch but continue to use the target revision from the application +specification, just omit the base branch name: + +```yaml +argocd-image-updater.argoproj.io/git-branch: :target +``` + +A static branch name may not be desired for this value, so a simple template +can be created (evaluating using the `text/template` Golang package) within +the annotation. For example, the following would create a branch named +`image-updater-foo/bar-1.1` based on `main` in the event an image with +the name `foo/bar` was updated to the new tag `1.1`. + +```yaml +argocd-image-updater.argoproj.io/git-branch: main:image-updater{{range .Images}}-{{.Name}}-{{.NewTag}}{{end}} +``` + +Alternatively, to assure unique branch names you could use the SHA1 representation of the changes: + +```yaml +argocd-image-updater.argoproj.io/git-branch: main:image-updater-{{.SHA256}} +``` + +The following variables are provided for this template: + +* `.Images` is a list of changes that were performed by the update. Each + entry in this list is a struct providing the following information for + each change: + * `.Name` holds the full name of the image that was updated + * `.Alias` holds the alias of the image that was updated + * `.OldTag` holds the tag name or SHA digest previous to the update + * `.NewTag` holds the tag name or SHA digest that was updated to +* `.SHA256` is a unique SHA256 has representing these changes + +Please note that if the output of the template exceeds 255 characters (git branch name limit) it will be truncated. + +### Specifying the user and email address for commits + +Each Git commit is associated with an author's name and email address. If not +configured, commits performed by Argo CD Image Updater will use +`argocd-image-updater ` +as the author. You can override the author using the +`--git-commit-user` and `--git-commit-email` command line switches or set +`git.user` and `git.email` +in the `argocd-image-updater-config` ConfigMap. + +### Changing the Git commit message + +You can change the default commit message used by Argo CD Image Updater to some +message that best suites your processes and regulations. For this, a simple +template can be created (evaluating using the `text/template` Golang package) +and made available through setting the key `git.commit-message-template` in the +`argocd-image-updater-config` ConfigMap to the template's contents, e.g. + +```yaml +data: + git.commit-message-template: | + build: automatic update of {{ .AppName }} + + {{ range .AppChanges -}} + updates image {{ .Image }} tag '{{ .OldTag }}' to '{{ .NewTag }}' + {{ end -}} +``` + +Two top-level variables are provided to the template: + +* `.AppName` is the name of the application that is being updated +* `.AppChanges` is a list of changes that were performed by the update. Each + entry in this list is a struct providing the following information for + each change: + * `.Image` holds the full name of the image that was updated + * `.OldTag` holds the tag name or SHA digest previous to the update + * `.NewTag` holds the tag name or SHA digest that was updated to + +In order to test a template before configuring it for use in Image Updater, +you can store the template you want to use in a temporary file, and then use +the `argocd-image-updater template /path/to/file` command to render the +template using pre-defined data and see its outcome on the terminal. + +### Git Write-Back Target + +By default, git write-back will create or update `.argocd-source-.yaml`. + +If you are using Kustomize and want the image updates available for normal use with `kustomize`, +you may set the `write-back-target` to `kustomization`. This method commits changes to the Kustomization +file back to git as though you ran `kustomize edit set image`. + +```yaml +argocd-image-updater.argoproj.io/write-back-method: git # all git options are supported +argocd-image-updater.argoproj.io/write-back-target: kustomization +``` + +You may also specify which kustomization to update with either a path relative to the project source path... + +```yaml +argocd-image-updater.argoproj.io/write-back-target: "kustomization:../../base" +# if the Application spec.source.path = config/overlays/foo, this would update the kustomization in config/base +``` + +...or absolute with respect to the repository: + +```yaml +# absolute paths start with / +argocd-image-updater.argoproj.io/write-back-target: "kustomization:/config/overlays/bar" +``` + +Note that the Kustomization directory needs to be specified, not a file, like when using Kustomize. diff --git a/docs/basics/update-strategies.md b/docs/basics/update-strategies.md new file mode 100644 index 0000000..453cbf1 --- /dev/null +++ b/docs/basics/update-strategies.md @@ -0,0 +1,236 @@ +# Update strategies + +## Supported update strategies + +An update strategy defines how Argo CD Image Updater will find new versions of +an image that is to be updated. + +Argo CD Image Updater supports different update strategies for the images that +are configured to be tracked and updated. + +You can configure the update strategy to be used for each image individually, +with the default being the `semver` strategy. + +The following update strategies are currently supported: + +* [semver](#strategy-semver) - Update to the latest version of an image + considering semantic versioning constraints +* [latest](#strategy-latest) - Update to the most recently built image found in a registry +* [digest](#strategy-digest) - Update to the latest version of a given version (tag), using the tag's SHA digest +* [name](#strategy-name) - Sorts tags alphabetically and update to the one with the highest cardinality + +Some of the strategies will require additional configuration, or can be tweaked +with additional parameters. Please have a look at the +[image configuration](../../configuration/images) +documentation for more details. + +## Mutable vs immutable tags + +Please note that all update strategies except `digest` assume tags to be +*immutable* and that new images will be pushed with a new, unique tag. If +you want to update to *mutable* tags (e.g. the commonly used `latest` tag), +you should use the `digest` strategy. + +## Update strategies in detail +### semver - Update to semantic versions + +This is the default strategy. + +Strategy name: `semver` + +Basic configuration: + +```yaml +argocd-image-updater.argoproj.io/image-list: some/image[:] +# Specifying update-strategy is optional, because semver is the default +argocd-image-updater.argoproj.io/.update-strategy: semver +``` + +The `semver` strategy allows you to track & update images which use tags that +follow the +[semantic versioning scheme](https://semver.org). Tag names must contain semver +compatible identifiers in the format `X.Y.Z`, where `X`, `Y` and `Z` must be +whole numbers. An optional prefix of `v`, e.g. `vX.Y.Z` is allowed, and both +variants are treated equal (so, a constraint of `v1.x` would match a tag `1.0` +and a constraint of `1.x` also matches a tag `v1.0`). + +Updating to pre-release versions (e.g. `-rc1`) is supported, but must be +explicitly allowed (see below). + +This will allow you to update to the latest version of an image within a given +patch branch or minor release, or just to the latest version that has is tagged +with a valid semantic version identifier. + +To tell Argo CD Image Updater which versions are allowed, simply give a semver +version as a constraint in the `image-list` annotation. For example, to allow +updates to the latest patch release within the `1.2` minor release branch, use + +``` +argocd-image-updater.argoproj.io/image-list: some/image:1.2.x +``` + +The above example would update to any new tag pushed to the registry matching +this constraint, e.g. `1.2.5`, `1.2.12` etc, but not to a new minor version +(e.g. `1.3`). + +Likewise, to allow updates to any minor release within the major version `1`, +use + +```yaml +argocd-image-updater.argoproj.io/image-list: some/image:1.x +``` + +The above example would update to any new tag pushed to the registry matching +this constraint, e.g. `1.2.12`, `1.3.0`, `1.15.2` etc, but not to a new major +version (e.g. `2.0`). + +If you also want to allow updates to pre-release versions (e.g. `v2.0-rc1`), +you need to append the suffix `-0` to the constraint, for example + +``` +argocd-image-updater.argoproj.io/image-list: some/image:2.x-0 +``` + +If no version constraint is specified in the list of allowed images, Argo CD +Image Updater will pick the highest version number found in the registry. + +Argo CD Image Updater will omit any tags from your registry that do not match +a semantic version when using the `semver` update strategy. + +### latest - Update to the most recently built image + +!!!warning + As of November 2020, Docker Hub has introduced pull limits for accounts on + the free plan and unauthenticated requests. The `latest` update strategy + will perform manifest pulls for determining the most recently pushed tags, + and these will count into your pull limits. So unless you are not affected + by these pull limits, it is **not recommended** to use the `latest` update + strategy with images hosted on Docker Hub. + +!!!note + If you are using *reproducible builds* for your container images (e.g. if + your build pipeline always sets the creation date of the image to the same + value), the `latest` strategy will not be able to determine which tag to + update to. + +Strategy name: `latest` + +Basic configuration: + +```yaml +argocd-image-updater.argoproj.io/image-list: =some/image +argocd-image-updater.argoproj.io/.update-strategy: latest +``` + +Argo CD Image Updater can update to the image that has the most recent build +date, and is tagged with an arbitrary name (e.g. a Git commit SHA, or even a +random string). + +It is important to understand, that this strategy will consider the build date +of the image, and not the date of when the image was tagged or pushed to the +registry. If you are tagging the same image with multiple tags, these tags +will have the same build date. In this case, Argo CD Image Updater will sort +the tag names lexically descending and pick the last tag name of that list. +For example, consider an image that was tagged with the `f33bacd`, `dev` +and `latest` tags. You might want to have the `f33bacd` tag set for your +application, but Image Updater will pick the `latest` tag name. In order to +prevent such a situation, you need to further restrict the tags that Image +Updater will inspect, see below. + +By default, this update strategy will inspect all of the tags it found in the +image's repository. If you wish to allow only certain tags to be considered +for update, you will need additional configuration. For example, + +```yaml +argocd-image-updater.argoproj.io/image-list: myimage=some/image +argocd-image-updater.argoproj.io/myimage.update-strategy: latest +argocd-image-updater.argoproj.io/myimage.allow-tags: regexp:^[0-9a-f]{7}$ +``` + +would only consider tags that match a given regular expression for update. In +this case, the regular expression matches a 7-digit hexadecimal string that +could represent the short version of a Git commit SHA, so it would match tags +like `a5fb3d3` or `f7bb2e3`, but not `latest` or `master`. + +Likewise, you can ignore a certain list of tags from your repository: + +```yaml +argocd-image-updater.argoproj.io/image-list: myimage=some/image +argocd-image-updater.argoproj.io/myimage.update-strategy: latest +argocd-image-updater.argoproj.io/myimage.ignore-tags: latest, master +``` + +This would allow for considering all tags found but `latest` and `master`. You +can read more about filtering tags +[here](../../configuration/images/#filtering-tags). + +### digest - Update to the most recent pushed version of a given tag + +Strategy name: `digest` + +Basic configuration: + +```yaml +argocd-image-updater.argoproj.io/image-list: =some/image: +argocd-image-updater.argoproj.io/.update-strategy: digest +``` + +This update strategy inspects a single tag in the registry for changes, and +updates the image on any change to the previous state. The tag name to be +inspected must be specified as a version constraint in the image list. + +Use this update strategy if you want to follow a *mutable* tag, such as the +commonly used `latest` tag, or when your CI system produces a tag named as +the environment it is intended for, e.g. `dev` or `stage` or `prod`. + +Argo CD Image Updater will then update the image when either + +* The currently running image has a non-digest specification (e.g. uses a tag), + or +* the currently used digest differs from what is found in the registry + +!!!note "Tags and digests" + Note that the `digest` update strategy will use image digests for updating + the image tags in your applications, so the image running in your + application will appear as `some/image@sha256:` instead + of `some/image:latest`. So in your running system, the tag information will + be effectively lost. + +For example, the following specification would always update the image for an +application on each new push of the image `some/image` with the tag `latest`: + +```yaml +argocd-image-updater.argoproj.io/image-list: myimage=some/image:latest +argocd-image-updater.argoproj.io/myimage.update-strategy: digest +``` + +### Update according to lexical sort + +Strategy name: `name` + +Basic configuration: + +```yaml +argocd-image-updater.argoproj.io/image-list: =some/image +argocd-image-updater.argoproj.io/.update-strategy: name +``` + +This update strategy sorts the tags returned by the registry in a lexical way +(by name, in descending order) and picks the last tag in the list for update. +This can be useful if the image you want to track uses `calver` versioning, +with tags in the format of e.g. `YYYY-MM-DD` or similar lexical sortable +strings. + +By default, this update strategy will inspect all of the tags it found in the +image's repository. If you wish to allow only certain tags to be considered +for update, you will need additional configuration. For example, + +```yaml +argocd-image-updater.argoproj.io/image-list: myimage=some/image +argocd-image-updater.argoproj.io/myimage.update-strategy: name +argocd-image-updater.argoproj.io/myimage.allow-tags: regexp:^[0-9]{4}-[0-9]{2}[0-9]{2}$ +``` + +would only consider tags that match a given regular expression for update. In +this case, only tags matching a date specification of `YYYY-MM-DD` would be +considered for update. diff --git a/docs/basics/update.md b/docs/basics/update.md new file mode 100644 index 0000000..30da0f7 --- /dev/null +++ b/docs/basics/update.md @@ -0,0 +1,85 @@ +# Updating container images + +## General process overview + +Argo CD Image Updater can update container images managed by one or more of +your Argo CD applications, according to how it is configured. + +The workflow of Argo CD Image Updater can be described as follows: + +* It scans for currently configured Argo CD `Application` resources either + using the Kubernetes or the Argo CD API (depending on how you installed + the Argo CD Image Updater). The `Applications` to consider can be further + limited by having Argo CD Image Updater selecting only those applications + whose name match a given pattern, or match a given label. + +* It then goes through the list of `Applications` found and inspects each + for the the annotation `argocd-image-updater.argoproj.io/image-list`. This + annotation holds a list of image names that should be updated, and is a + mandatory annotation for Argo CD Image Updater to indicate it should + process this `Application`. Read more about the syntax expected in this + annotations's value in the [marking images for update](#TODO) + section in this doc. + +* For each image found in the list, Argo CD Image Updater will first check + if this image is actually deployed with the application. It does a strict + check for the complete image name, including the registry the image is + pulled from. For example, `docker.io/some/image` and `quay.io/some/image`, + while both referring to `some/image`, are not considered equal. This strict + behavior can be relaxed, however. See [forcing image updates](#TODO) for + further explanation. + +* If Argo CD Image Updater considers an image from the list eligible for an + update check, it will connect the corresponding container registry to see + if there is a newer version of the image according to the + [update strategy](../strategies/) + and other constraints that may have been configured for the image (e.g. + a list of tags that are allowed to consider). + +* If a newer version of an image was found, Argo CD Image Updater will try + to update the image according to the configured + [update method](../methods/). Please note that Argo CD Image Updater will + never update your manifests, instead it re-configures your Application + sources to use the new image tag, and control is handed over to Argo CD. + +## Multi-arch images and clusters + +As of version 0.12, Argo CD Image Updater has full support for multi-arch +images (and multi-arch clusters) by being able to inspect images with multiple +manifests (i.e. a manifest list). + +Multi-arch currently only is supported for +[update strategies](../basics/update-strategies.md) +which fetch image meta-data: `latest` and `digest`. Multi-arch will be ignored +for the update strategies that do not fetch meta-data, `semver` and `name`. + +By default, Argo CD Image Updater will only consider updating to images that +have a manifest for the same platform where itself runs on. If you are on a +cluster that has nodes of multiple architectures, and are pinning certain +workloads to certain nodes, you will have to tell Argo CD Image Updater which +platforms are allowed for a certain application or an image. This can be done +by setting an appropriate +[annotation per image](../configuration/images.md#platforms) +or for all images of a given +[application as a default setting](../configuration/images.md#appendix-defaults). + +Multi-arch is also implemented by the +[test command](../install/testing.md#multi-arch). + +## Sync policies and image updates + +As explained above, the Argo CD Image Updater will assume that Argo CD will +update the manifests in your cluster to use any new image that has been set +by the Argo CD Image Updater. + +Argo CD Image Updater will work best with automatic syncing enabled for the +Argo CD applications that are being updated. + +## Rollback and image updates + +Currently, Argo CD Image Updater does not honor the rollback status of an +Argo CD application, and keeps updating to new images also for Applications +that are being rolled back. However, Argo CD will disable auto-sync for +such applications. + +Honoring rollbacked applications correctly is on our roadmap. diff --git a/docs/configuration/applications.md b/docs/configuration/applications.md index 6a05d8f..c334c4b 100644 --- a/docs/configuration/applications.md +++ b/docs/configuration/applications.md @@ -1,6 +1,19 @@ # Application configuration -## Marking an application for being updateable +Most of the runtime configuration for Argo CD Image Updater is performed by +setting various annotations on resources of type `Application`, which are +managed by Argo CD. + +For its annotations, Argo CD Image Updater uses the following prefix: + +```yaml +argocd-image-updater.argoproj.io +``` + +This section of the documentation tells you about which things you can +configure, and what annotations are available. + +## Marking an application for being updateable In order for Argo CD Image Updater to know which applications it should inspect for updating the workloads' container images, the corresponding Kubernetes @@ -9,12 +22,6 @@ only resources of kind `application.argoproj.io`, that is, your Argo CD `Application` resources. Annotations on other kinds of resources will have no effect and will not be considered. -For its annotations, Argo CD Image Updater uses the following prefix: - -```yaml -argocd-image-updater.argoproj.io -``` - As explained earlier, your Argo CD applications must be of either `Kustomize` or `Helm` type. Other types of applications will be ignored. @@ -48,7 +55,10 @@ spec: targetRevision: HEAD ``` -## Configuring the write-back method +There is a whole chapter dedicated on how to +[configure images for update](../images). + +## Configuring the write-back method The Argo CD Image Updater supports two distinct methods on how to update images of an application: @@ -72,264 +82,15 @@ Where `` must be one of `argocd` (imperative) or `git` (declarative). The default used by Argo CD Image Updater is `argocd`. -### Using the Argo CD API write-back method - -When using the Argo CD API to write back changes, Argo CD Image Updater will -perform a similar action as `argocd app set --parameter ...` to instruct -Argo CD to re-render the manifests using those parameters. - -This method is pseudo-persistent. If you delete the `Application` resource -from the cluster and re-create it, changes made by Image Updater will be gone. -The same is true if you manage your `Application` resources using Git, and -the version stored in Git is synced over the resource in the cluster. This -method is most suitable for Applications also created imperatively, i.e. -using the Web UI or CLI. - -This method is the default and requires no further configuration. - -### Using the Git write-back method - -!!!warning "Compatibility with Argo CD" - The Git write-back method requires a feature in Argo CD that has been - introduced with Argo CD v2.0. Git write-back will not work with earlier - versions of Argo CD. - -The `git` write-back method uses Git to permanently store its parameter -overrides along with the Application's resource manifests. This will enable -persistent storage of the parameters in Git. - -By default, Argo CD Image Updater will store the parameter in a file named -`.argocd-source-.yaml` in the path used by the Application to source -its manifests from. This will allow Argo CD to pick up parameters in this -file, when rendering manifests for the Application named ``. Using -this approach will also minimize the possibility of merge conflicts, as long -as no other party in your CI will modify this file. - -!!!note "A note on the application's target revision" - Due to the nature of how Git write-back works, your application really - should track a *branch* instead of a revision. If you track `HEAD`, a tag - or a certain revision with your application, you **must** override the - branch in an annotation (see below). But in order for Argo CD to pick up - the change after Image Updater has committed & pushed the change, you - really want to set it up so it tracks a branch. - -To use the Git write-back method, annotate your `Application` with the right -write-back method: - -```yaml -argocd-image-updater.argoproj.io/write-back-method: git -``` - -In order to better decide whether this method is suitable for your use-case, -this is the workflow how Argo CD Image Updater performs change to Git: - -* Fetch the remote repository from location specified by `.spec.source.repoURL` - in the Argo CD Application manifest, using credentials specified as annotation - (see below) -* Check-out the target branch on the local copy. The target branch is either - taken from an annotation (see below), or if no annotation is set, taken from - `.spec.source.targetRevision` in the Application manifest -* Create or update `.argocd-source-.yaml` in the local repository -* Commit the changed file to the local repository -* Push the commit to the remote repository, using credentials specified as - annotation (see below) - -The important pieces to this workflow are: - -* Credentials configured in Argo CD will be re-used, unless you override with a - dedicated set of credentials - -* Write-back is a commit to the tracking branch of the Application. - -* If `.spec.source.targetRevision` does not reference a *branch*, you will have - to specify the branch to use manually (see below) - -#### General configuration - -Configuration for the Git write-back method comes from two sources: - -* The Argo CD `Application` manifest is used to define the repository and the - path where the `.argocd-source-.yaml` should be written to. These - are defined in `.spec.source.repoURL` and `.spec.source.path` fields, - respectively. Additionally, `.spec.source.targetRevision` is used to define - the branch to commit and push the changes to. The branch to use can be - overridden by an annotation, see below. - -* A set of annotations on the `Application` manifest, see below - -#### Specifying Git credentials - -By default Argo CD Image Updater re-uses the credentials you have configured -in Argo CD for accessing the repository. - -If you don't want to use credentials configured for Argo CD you can use other credentials stored in a Kubernetes secret, -which needs to be accessible by the Argo CD Image Updater's Service Account. The secret should be specified in -`argocd-image-updater.argoproj.io/write-back-method` annotation using `git:` format. Where `` might -take one of following values: - -* `repocreds` (default) - Git repository credentials configured in Argo CD settings -* `secret:/` - namespace and secret name. - -Example: - -```yaml -argocd-image-updater.argoproj.io/write-back-method: git:secret:argocd-image-updater/git-creds -``` - -If the repository is accessed using HTTPS, the secret must contain two fields: -`username` which holds the Git username, and `password` which holds the user's -password or a private access token (PAT) with write access to the repository. -You can generate such a secret using `kubectl`, e.g.: - -```bash -kubectl -n argocd-image-updater create secret generic git-creds \ - --from-literal=username=someuser \ - --from-literal=password=somepassword -``` - -If the repository is accessed using SSH, the secret must contain the field -`sshPrivateKey`, which holds a SSH private key in OpenSSH-compatible PEM -format. To create such a secret from an existing private key, you can use -`kubectl`, for example: - -```bash -kubectl -n argocd-image-updater create secret generic git-creds \ - --from-file=sshPrivateKey=~/.ssh/id_rsa -``` - -#### Specifying a branch to commit to - -By default, Argo CD Image Updater will use the value found in the Application -spec at `.spec.source.targetRevision` as Git branch to checkout, commit to -and push back the changes it made. In some scenarios, this might not be what -is desired, and you can (and maybe have to) override the branch to use by -specifying the annotation `argocd-image-updater.argoproj.io/git-branch` on the -Application manifest. - -The value of this annotation will define the Git branch to use, for example the -following would use GitHub's default `main` branch: - -```yaml -argocd-image-updater.argoproj.io/git-branch: main -``` - -#### Specifying a separate base and commit branch - -By default, Argo CD Imager Updater will checkout, commit, and push back to the -same branch specified above. There are many scenarios where this is not -desired or possible, such as when the default branch is protected. You can -add a separate write-branch by modifying `argocd-image-updater.argoproj.io/git-branch` -with additional data, which will create a new branch from the base branch, and -push to this new branch instead: - -```yaml -argocd-image-updater.argoproj.io/git-branch: base:target -``` - -If you want to specify a write-branch but continue to use the target revision from the application -specification, just omit the base branch name: - -```yaml -argocd-image-updater.argoproj.io/git-branch: :target -``` - -A static branch name may not be desired for this value, so a simple template -can be created (evaluating using the `text/template` Golang package) within -the annotation. For example, the following would create a branch named -`image-updater-foo/bar-1.1` based on `main` in the event an image with -the name `foo/bar` was updated to the new tag `1.1`. - -```yaml -argocd-image-updater.argoproj.io/git-branch: main:image-updater{{range .Images}}-{{.Name}}-{{.NewTag}}{{end}} -``` - -Alternatively, to assure unique branch names you could use the SHA1 representation of the changes: - -```yaml -argocd-image-updater.argoproj.io/git-branch: main:image-updater-{{.SHA256}} -``` - -The following variables are provided for this template: +You can read more about the update methods and how to configure them in the +[chapter about update methods](../basics/update-methods.md) -* `.Images` is a list of changes that were performed by the update. Each - entry in this list is a struct providing the following information for - each change: - * `.Name` holds the full name of the image that was updated - * `.Alias` holds the alias of the image that was updated - * `.OldTag` holds the tag name or SHA digest previous to the update - * `.NewTag` holds the tag name or SHA digest that was updated to -* `.SHA256` is a unique SHA256 has representing these changes +## Application defaults -Please note that if the output of the template exceeds 255 characters (git branch name limit) it will be truncated. - -#### Specifying the user and email address for commits - -Each Git commit is associated with an author's name and email address. If not -configured, commits performed by Argo CD Image Updater will use -`argocd-image-updater ` -as the author. You can override the author using the -`--git-commit-user` and `--git-commit-email` command line switches or set -`git.user` and `git.email` -in the `argocd-image-updater-config` ConfigMap. - -#### Changing the Git commit message - -You can change the default commit message used by Argo CD Image Updater to some -message that best suites your processes and regulations. For this, a simple -template can be created (evaluating using the `text/template` Golang package) -and made available through setting the key `git.commit-message-template` in the -`argocd-image-updater-config` ConfigMap to the template's contents, e.g. - -```yaml -data: - git.commit-message-template: | - build: automatic update of {{ .AppName }} - - {{ range .AppChanges -}} - updates image {{ .Image }} tag '{{ .OldTag }}' to '{{ .NewTag }}' - {{ end -}} -``` - -Two top-level variables are provided to the template: - -* `.AppName` is the name of the application that is being updated -* `.AppChanges` is a list of changes that were performed by the update. Each - entry in this list is a struct providing the following information for - each change: - * `.Image` holds the full name of the image that was updated - * `.OldTag` holds the tag name or SHA digest previous to the update - * `.NewTag` holds the tag name or SHA digest that was updated to - -In order to test a template before configuring it for use in Image Updater, -you can store the template you want to use in a temporary file, and then use -the `argocd-image-updater template /path/to/file` command to render the -template using pre-defined data and see its outcome on the terminal. - -#### Git Write-Back Target - -By default, git write-back will create or update `.argocd-source-.yaml`. - -If you are using Kustomize and want the image updates available for normal use with `kustomize`, -you may set the `write-back-target` to `kustomization`. This method commits changes to the Kustomization -file back to git as though you ran `kustomize edit set image`. - -```yaml -argocd-image-updater.argoproj.io/write-back-method: git # all git options are supported -argocd-image-updater.argoproj.io/write-back-target: kustomization -``` - -You may also specify which kustomization to update with either a path relative to the project source path... - -```yaml -argocd-image-updater.argoproj.io/write-back-target: "kustomization:../../base" -# if the Application spec.source.path = config/overlays/foo, this would update the kustomization in config/base -``` - -...or absolute with respect to the repository: - -```yaml -# absolute paths start with / -argocd-image-updater.argoproj.io/write-back-target: "kustomization:/config/overlays/bar" -``` +Additional to per-image configuration, you can also set some defaults for the +application. -Note that the Kustomization directory needs to be specified, not a file, like when using Kustomize. +For example, if you have multiple images tracked in your application, and all +of them should use the `latest` update strategy, you can define this strategy +as the application's default and may omit any specific configuration for the +images' update strategy. diff --git a/docs/configuration/images.md b/docs/configuration/images.md index f5e67f9..7edf9bb 100644 --- a/docs/configuration/images.md +++ b/docs/configuration/images.md @@ -61,13 +61,12 @@ of the [Semver library](https://github.com/Masterminds/semver) we're using. [filtering tags](#filtering-tags) below. - ### Forcing Image Updates By default, Image Updater will only update an image that is actually used in your Application (i.e., is it exported in the Status of your ArgoCD Application.) -To support custom resources and things like PodTemplates that don't actually create a container, +To support custom resources and things like PodTemplates that don't actually create a container, you may force an update: ```yaml @@ -75,7 +74,6 @@ argocd-image-updater.argoproj.io/image-list: myalias=some/image argocd-image-updater.argoproj.io/myalias.force-update: "true" ``` - ## Assigning aliases to images It's possible (and sometimes necessary) to assign an alias name to any given @@ -108,6 +106,11 @@ as `_` (underscore) in the annotation. This is a limit of Kubernetes. So for example, if you assign the alias `argoproj/argocd` to your image, the appropriate key in the annotation would be referenced as `argoproj_argocd`. +!!!note + It is generally recommended to set aliases for each of your images. Many of + the features depend on an alias being set, and aliases might become a strict + requirement in the future. + ## Update strategies Argo CD Image Updater can update images according to the following strategies: @@ -137,7 +140,6 @@ strategy `semver` will be used. by these pull limits, it is **not recommended** to use the `latest` update strategy with images hosted on Docker Hub. - ## Filtering tags You can specify an expression that is matched against each tag returned from @@ -190,7 +192,38 @@ argocd-image-updater.argoproj.io/.ignore-tags: "*" Please note that regular expressions are not supported to be used for patterns. -## Specifying pull secrets +## Image platforms + +By default, Argo CD Image Updater will only consider images from the registry +that are built for the same platform as the one Argo CD Image Updater is +running on. In multi-arch clusters, your workloads may be targeted to a +different platform, and you can configure the allowed platforms for a given +image. + +For example, when Argo CD Image Updater is running on a `linux/amd64` node but +your application will be executed on a node with `linux/arm64` platform, you +need to let Argo CD Image Updater know: + +```yaml +argocd-image-updater.argoproj.io/.platforms: linux/arm64 +``` + +You can specify multiple allowed platforms as a comma separated list of allowed +platforms: + +```yaml +argocd-image-updater.argoproj.io/.platforms: linux/arm64,linux/amd64 +``` + +The correct image to execute will be chosen by Kubernetes. + +!!!note + The `platforms` annotation only has effect for images that use an update + strategy which fetches meta-data. Currently, these are the `latest` and + `digest` strategies. For `semver` and `name` strategies, the `platforms` + setting has no effect. + +## Specifying pull secrets There are generally two ways on how to specify pull secrets for Argo CD Image Updater to use. Either you configure a secret reference globally for the @@ -384,27 +417,52 @@ argocd-image-updater.argoproj.io/baralias.helm.image-name: bar.image argocd-image-updater.argoproj.io/baralias.helm.image-tag: bar.tag ``` +### Tracking an image's `latest` tag + +*Scenario:* You want to track the latest build of a given tag, e.g. the `latest` +tag that many images use without having to restart your pods manually. + +*Solution:* + +1. Define an alias for your image, i.e. `fooalias` + +2. Set the constraint of your image to the tag you want to track, e.g. `latest` + +3. Set the update strategy for this image to `digest` + +```yaml +argocd-image-updater.argoproj.io/image-list: fooalias=yourorg/yourimage:latest +argocd-image-updater.argoproj.io/fooalias.update-strategy: digest +``` + +When there's a new build for `yourorg/yourimage:latest` found in the registry, +Argo CD Image Updater will update your configuration to use the SHA256 sum of +the image, and Kubernetes will restart your pods automatically to have them +use the new image. + ## Appendix -### Available annotations +### Available annotations The following is a complete list of available annotations to control the update strategy and set options for images. Please note, all annotations -must be prefixed with `argocd-image-updater.argoproj.io`. +must be prefixed with `argocd-image-updater.argoproj.io/`. |Annotation name|Default value|Description| |---------------|-------|-----------| |`image-list`|*none*|Comma separated list of images to consider for update| |`.update-strategy`|`semver`|The update strategy to be used for the image| +|`.force-update`|`"false"`|If set to "true" (with quotes), even images that are not currently deployed will be updated| |`.allow-tags`|*any*|A function to match tag names from registry against to be considered for update| |`.ignore-tags`|*none*|A comma-separated list of glob patterns that when match ignore a certain tag from the registry| |`.pull-secret`|*none*|A reference to a secret to be used as registry credentials for this image| +|`.platform`|*none*|Only update to images for given platform(s). Comma separated list, e.g. `linux/amd64,linux/arm64`| |`.helm.image-spec`|*none*|Name of the Helm parameter to specify the canonical name of the image, i.e. holds `image/name:1.0`. If this is set, other Helm parameter related options will be ignored.| |`.helm.image-name`|`image.name`|Name of the Helm parameter used for specifying the image name, i.e. holds `image/name`| |`.helm.image-tag`|`image.tag`|Name of the Helm parameter used for specifying the image tag, i.e. holds `1.0`| |`.kustomize.image-name`|*original name of image*|Name of Kustomize image parameter to set during updates| -### Application-wide defaults +### Application-wide defaults If you want to update multiple images in an Application, that all share common settings (such as, update strategy, allowed tags, etc), you can define common diff --git a/docs/configuration/registries.md b/docs/configuration/registries.md index fd9f346..8a20582 100644 --- a/docs/configuration/registries.md +++ b/docs/configuration/registries.md @@ -1,128 +1,201 @@ -# Configuring Container Registries +# Configuration of Container Registries -Argo CD Image Updater comes with support for the following registries out of the -box: +## Supported registries -* Docker Hub Registry -* Google Container Registry (*gcr.io*) -* RedHat Quay Registry (*quay.io*) -* GitHub Docker Packages (*docker.pkg.github.com*) -* GitHub Container Registry (*ghcr.io*) +Argo CD Image Updater comes with out of the box support for most container +registries that implement the Docker registry v2 API. -Adding additional (and custom) container registries is supported by means of a -configuration file. If you run Argo CD Image Updater within Kubernetes, you can -edit the registries in a ConfigMap resource, which will get mounted to the pod -running Argo CD Image Updater. +It has been successfully tested against the following popular registries: -## Configuring a custom container registry +* Docker Hub (`docker.io`) +* Docker Registry v2 reference implementation (on-premise) +* Red Hat Quay (`quay.io` and on-premise) +* JFrog Artifactory (`jfrog.io` and on-premise) +* GitHub Container Registry (`ghcr.io`) +* GitHub Packages Registry (`docker.pkg.github.com`) +* GitLab Container Registry (`registry.gitlab.com`) +* Google Container Registry (`gcr.io`) -A sample configuration configuring a couple of registries might look like the -following: +Chances are, that it will work out of the box for other registries as well. -```yaml -registries: -- name: Docker Hub - api_url: https://registry-1.docker.io - ping: yes - credentials: secret:foo/bar#creds - defaultns: library -- name: Google Container Registry - api_url: https://gcr.io - prefix: gcr.io - ping: no - credentials: pullsecret:foo/bar -- name: RedHat Quay - api_url: https://quay.io - ping: no - prefix: quay.io - insecure: yes - credentials: env:REGISTRY_SECRET -- name: GitHub Docker Packages - prefix: docker.pkg.github.com - api_url: https://docker.pkg.github.com - ping: no - tagsortmode: latest-first -- name: GitHub Container Registry - prefix: ghcr.io - api_url: https://docker.pkg.github.com - ping: no - tagsortmode: latest-last +If you have a registry that doesn't work with Argo CD Image Updater, please +let us know. + +## When to configure a custom registry? + +Generally, there is no need to configure custom registries. Image Updater will +infer the registry from the image slug, e.g. if you are using an image that is +defined as `ghcr.io/somerepo/someimage`, Image Updater will infer the registry +from the `ghcr.io` prefix and use the Docker registry at `https://ghcr.io/v2`. + +However, there may be reasons when you need to configure a custom registry, or +adapt the default settings to your requirements: + +* Your registry uses a self-signed (or not publicly known) TLS certificate, + and you want to either turn off TLS certificate verification or provide a + custom CA certificate to be used for verification + +* Your registry has its API endpoint at a different location. One notable + example is Docker Hub, which uses `docker.io` as image prefix but the + registry is at `registry-1.docker.io`. However, this quirk related to + Docker Hub has been accounted for in Argo CD Image Updater, so you won't + have to configure Docker Hub as a custom registry. + +* You want to use a certain registry with deviations from the default settings, + such as setting a custom rate limit, or configuring global credentials for + accessing that registry. + +* Your cluster's container engine is set up to use a different registry than + `docker.io` as the default so that it does not pull images from Docker Hub + when no prefix is specified, but e.g. from an on-premise registry. + +## Can I use my registry without further configuration? + +There is an easy way to find out by running the argocd-image-updater CLI in +[test mode](../install/testing.md). You can run the CLI either from your +workstation (if the registry is reachable from there) or from the pod deployed +to your cluster. + +Assuming you have an image at `myregistry.com/somerepo/someimage`, and you +want to find out if Argo CD Image Updater could possibly connect to that +specific registry at `myregistry.com` and gather information about the image, +run the following command: + +``` +argocd-image-updater test myregistry.com/somerepo/someimage ``` -The above example defines access to three registries. The properties have the -following semantics: +You may also want to pass some options to that command to set the appropriate +[update strategy](../basics/update-strategies.md) +or +[credentials](../basics/authentication.md) +to access the registry. -* `name` is just a symbolic name for the registry. Must be unique. +The `argocd-image-updater test` command won't perform any modifications to +your cluster or your workloads. -* `api_url` is the base URL (without `/v2` suffix) to the API of the registry +## Configuring custom registries +### Configuration format -* `ping` specifies whether to send a ping request to `/v2` endpoint first. - Some registries don't support this. +Registries are configured in a configuration file in YAML syntax. That YAML +must have a top level key of `registries`, which holds a list of registries +to be configured. Each item in the list represents a single registry. You +can add as many registries as you like. -* `prefix` is the prefix used in the image specification. This prefix will - be consulted when determining the configuration for given image(s). If no - prefix is specified, will be used as the default registry. The prefix is - mandatory, except for one of the registries in the configuration. +The following properties can be set to configure a registry. Most of these +properties are optional, unless otherwise stated: -* `credentials` (optional) is a reference to the credentials to use for - accessing the registry API (see below). Credentials can also be specified - [per image](../images/#specifying-pull-secrets) + * `name` (mandatory) - The symbolic name for your registry. Can be any string, + used only for informational purposes. -* `credsexpire` (optional) can be used to set an expiry time for the - credentials. The value must be in a `time.Duration` compatible format, - having a unit suffix, i.e. `5s` for 5 seconds or `2h` for 2 hours. The - value should be positive, and `0` can be used to disable it (the default). + Default value: _none_ - From the golang documentation: + Example value: `My Custom Registry` - > A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". + * `prefix` - (mandatory) The lookup prefix for this registry. Must match a DNS + name, and must be unique in the configuration. -* `insecure` (optional) if set to true, does not validate the TLS certificate - for the connection to the registry. Use with care. + Default value: _none_ -* `defaultns` (optional) defines a default namespace for images that do not - specify one. For example, Docker Hub uses the default namespace `library` - which turns an image specification of `nginx:latest` into the canonical name - `library/nginx:latest`. + Example value: `docker.io` + + * `api_url` - The URL to the API of the Docker registry. Must be a HTTP or + HTTPS URL. + + Default value: _none_ + + Example value: `https://registry-1.docker.io` + + * `defaultns`- Some registries (notably Docker Hub) have a default namespace, + which can be specified here. + + Default value: _none_ + + Example value: `library` + + * `default` - If set to true, use this registry as the default registry. + + Default value: `false` + + Example value: `true` + + * `credentials` - A string describing the credential source to use when + accessing this registry and no other credentials are configured on the + image level. For more information, refer to + [Authenticating to container registries](../../basics/authentication/#auth-registries). + + Default value: _none_ + + Example value: `pullsecret:argocd/dockerhub-secret` + + * `credsexpire` - Whether and when credentials should expire and be + re-fetched. Must be specified as _Duration_ value, with an integer value + and a unit suffix, i.e. `s` for seconds, `m` for minutes, or `h` for hours. + + Default value: _none (no expiry)_ + + Example value: `5h` + + * `insecure` - Whether to turn off verification of the registry's TLS + certificate. As the name implies, it's insecure and should not be used in + production environments + + Default value: `false` + + Example value: `true` + + * `limit` - The rate limit (max. number of requests per second) to use for + this registry, specified as integer. + + Default value: `20` + + Example value: `100` + +The following is an example that configures two registries. + +```yaml +registries: +- name: Docker Hub + prefix: docker.io + api_url: https://registry-1.docker.io + credentials: secret:foo/bar#creds + defaultns: library + default: true +- name: RedHat Quay + api_url: https://quay.io + prefix: quay.io + insecure: yes + credentials: env:REGISTRY_SECRET +``` -* `tagsortmode` (optional) defines whether and how the list of tags is sorted - chronologically by the registry. Valid values are `latest-first` (the last - pushed image will appear first in list), `latest-last` (the last pushed image - will appear last in list) or `none` (the default, list is not chronological - sorted). If `tagsortmode` is set to one of `latest-first` or `latest-last`, - Argo CD Image Updater will not request additional meta data from the registry - if the `.sort-mode` is `latest` but will instead use the sorting - from the tag list. +When running Argo CD Image Updater from the command line (e.g. using the `test` +command), the path to this YAML file can be specified with the command line +parameter `--registries-conf-path `. -If you want to take above example to the `argocd-image-updater-config` ConfigMap, -you need to define the key `registries.conf` in the data of the ConfigMap as -below: +If you are running Argo CD Image Updater as a Kubernetes workload, you will +need to tie that up in the `argocd-image-updater-config` ConfigMap, as a multi +line string under the `registries.conf` key, e.g.: ```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: argocd-image-updater-config data: registries.conf: | registries: - name: Docker Hub + prefix: docker.io api_url: https://registry-1.docker.io - ping: yes credentials: secret:foo/bar#creds defaultns: library - - name: Google Container Registry - api_url: https://gcr.io - prefix: gcr.io - ping: no - credentials: pullsecret:foo/bar + default: true - name: RedHat Quay api_url: https://quay.io - ping: no prefix: quay.io + insecure: yes credentials: env:REGISTRY_SECRET - - name: GitHub Container Registry - api_url: https://ghcr.io - ping: no - prefix: ghcr.io - credentials: ext:/custom/ghcr-creds.sh.io - credsexpire: 5h + ``` !!!note @@ -130,45 +203,117 @@ data: configuration to take effect. There are plans to change this behaviour so that changes will be reload automatically in a future release. -## Specifying credentials for accessing container registries +### Configuring a default registry + +!!!warning + When you change the default registry for Argo CD Image Updater, make sure + it matches the default registry set up in your cluster. If the default + registries mismatch between the Argo CD Image Updater and your cluster, + it is going to break your workloads. + +Most container engines will follow Docker's approach and use Docker Hub as the +default registry when no registry is specified in the image's reference. For +example, in most environments, the two image references `argoproj/argocd` and +`docker.io/argoproj/argocd` are semantically the same, and would refer to the +same image stored in Docker Hub's registry. You can configure the default +registry if your cluster's container engine is configured to use a different +default registry than `docker.io`, which is the default for Argo CD Image +Updater in the standard configuration. + +In order to set another registry to be used as default, you will have to set +the registry's `default` property to `true`, e.g. the following: + +```yaml +registries: +- name: RedHat Quay + api_url: https://quay.io + prefix: quay.io + default: true +``` + +would make `quay.io` the default registry, so `argoproj/argocd` would become +synonymous to `quay.io/argoproj/argocd`. + +Please note that you can only configure one registry as the default registry. +If you set `default` to `true` for more than one registry's configuration, +Argo CD Image Updater will not load that configuration. -You can optionally specify a reference to a secret or an environment variable -which contain credentials for accessing the container registry. If credentials -are configured for a registry, they will be used as a default when accessing -the registry and no dedicated credential is specified for the image that is -being processed. +Also note, as stated previously, Docker Hub (i.e. `docker.io`) is the default +used by Image Updater without any additional configuration. + +### Configuring a registry's default namespace + +Some registries provide a default namespace, that is, a namespace that doesn't +have to be specified in the image's slug. A good example for that is the +implicit `library` namespace on Docker Hub, that allows you to pull an image +from that library by just specifying the name of the image. Consider e.g. the +command `docker pull nginx`, which will pull from `docker.io/library/nginx`. + +If your registry supports a default namespace and you would like this to be +used with Image Updater, you can configure this by setting the `defaultns` +property of the registry to the name of the namespace to use as the default. + +The canonical example for Docker Hub would be: + +```yaml +registries: +- name: Docker Hub + api_url: https://registry-1.docker.io + prefix: docker.io + defaultns: library +``` + +### Configuring a request rate limit for your registry + +Some registries might be picky about how many requests per time they let you +perform from a client's connection. In order to play nicely, and to prevent +Image Updater from triggering rate limit failures on your registry, you can +set a rate limit for each of the registries you are using. + +The rate limit can currently be configured as _requests per second_ allowed +and is specified via the `limit` configuration property. It takes an integer +as argument. + +For example, the following connection would cap requests to `quay.io` to 10 +per second: + +```yaml +registries: +- name: RedHat Quay + api_url: https://quay.io + prefix: quay.io + limit: 10 +``` -Credentials can be referenced as follows: +Please note that the limit considers all HTTP requests sent to the registry. +For inspecting a single tag of any given image, Image Updater may require +performing multiple requests to the registry. -* A typical pull secret, i.e. a secret containing a `.dockerconfigjson` field - which holds a Docker client configuration with auth information in JSON - format. This kind of secret is specified using the notation - `pullsecret:/` +The default for all registries is 20 requests per second. If your registry +doesn't impose limits upon you, raising this limit may significantly speed +up Argo CD Image Updater. But please be considerate and careful before you +increase the limit. -* A custom secret, which has the credentials stored in a configurable field in - the format `:`. This kind of secret is specified using - the notation `secret:/#` +### Configuring default credentials for container registries -* An environment variable which holds the credentials in the format - `:`. This kind of secret is specified using the notation - `env:`. +If you require authentication for accessing your registry, you can configure +a set of default credentials to use. If you have configured the credentials +on the registry level, it will be reused for any image processed from that +registry, unless an image configuration overrides it. A benefit of having +the credentials configured at the registry level is -* A script that outputs credentials on a single line to stdout, in the format - ``. This can be used to support external authentication - mechanisms. You can specify this kind of secret in the notation - `ext:/path/to/script`. Please note that the script must be referenced as - absolute path, and must be executable (i.e. have the `+x` bit set). You - can add scripts to `argocd-image-updater` by using an init container. +Registry credentials are configured using the `credentials` property of a +registry's configuration. -## Credentials caching +### Credentials caching By default, credentials specified in registry configuration are read once on startup and then cached until `argocd-image-updater` is restarted. There are two strategies to overcome this: -* Use per-image credentials in annotations - credentials will be read every - time an image update cycle is performed, and your credentials will always - be up-to-date (i.e. if you update a secret). +* Use per-image credentials in annotations - credentials will be read from + their source every time an image update cycle is performed, and your + credentials will always be up-to-date (i.e. if you update a secret). * Specify credential expiry time in the registry configuration - if set, the registry credentials will have a defined lifetime, and will be re-read from diff --git a/docs/examples/index.md b/docs/examples/index.md new file mode 100644 index 0000000..2eddaf9 --- /dev/null +++ b/docs/examples/index.md @@ -0,0 +1,7 @@ +# Examples + +This chapter contains community contributed examples on how to configure Argo +CD Image Updater for a certain registry or environment. + +Feel free to submit your own examples or guides to the documentation, as we do +not have access to all the registries and cloud platforms out there. diff --git a/docs/index.md b/docs/index.md index e48da53..511c77f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,9 +7,9 @@ that are managed by !!!warning "A note on the current status" Argo CD Image Updater is under active development. - You are welcome to test it out on non-critical environments, and to - contribute by sending bug reports, enhancement requests and - most - appreciated - pull requests. + You are welcome to test it out on non-critical environments, and of + course to + [contribute](./contributing/start.md) by many means. There will be (probably a lot of) breaking changes from release to release as development progresses until version 1.0. We will do our @@ -44,23 +44,26 @@ RBAC authorization on Application resources etc. are fully supported. * Updates images of apps that are managed by Argo CD and are either generated from *Helm* or *Kustomize* tooling -* Update app images according to different update strategies +* Update app images according to different + [update strategies](./basics/update-strategies.md) * `semver`: update to highest allowed version according to given image constraint, * `latest`: update to the most recently created image tag, * `name`: update to the last tag in an alphabetically sorted list * `digest`: update to the most recent pushed version of a mutable tag -* Default support for public images on widely used container registries: - * Docker Hub (docker.io) - * Google Container Registry (gcr.io) - * Red Hat Quay (quay.io) - * GitHub Container Registry (docker.pkg.github.com) -* Support for private container registries via configuration +* Support for + [widely used container registries](./configuration/registries.md#supported-registries) +* Support for private container registries via + [configuration](./configuration/registries.md#custom-registries) +* Can write changes + [back to Git](./basics/update-methods.md#method-git) * Ability to filter list of tags returned by a registry using matcher functions -* Support for custom, per-image pull secrets (using generic K8s secrets, K8s - pull secrets or environment variables) -* Runs in a Kubernetes cluster or can be used stand-alone from the command - line +* Support for custom, per-image + [pull secrets](./basics/authentication.md#auth-registries) (using generic K8s + secrets, K8s pull secrets, environment variables or external scripts) +* Runs in a + [Kubernetes cluster](./install/installation.md#install-kubernetes) or can be + used stand-alone from the command line * Ability to perform parallel update of applications ## Limitations diff --git a/docs/install/installation.md b/docs/install/installation.md new file mode 100644 index 0000000..b7b4241 --- /dev/null +++ b/docs/install/installation.md @@ -0,0 +1,266 @@ +# Getting Started + +## Installation methods + +It is recommended to run Argo CD Image Updater in the same Kubernetes namespace +cluster that Argo CD is running in, however, this is not a requirement. In fact, +it is not even a requirement to run Argo CD Image Updater within a Kubernetes +cluster or with access to any Kubernetes cluster at all. + +However, some features might not work without accessing Kubernetes, and it is +strongly advised to use the first installation method. + +## Method 1: Installing as Kubernetes workload in Argo CD namespace + +The most straightforward way to run the image updater is to install it as a Kubernetes workload into the namespace where +Argo CD is running. Don't worry, without any configuration, it will not start messing with your workloads yet. + +!!!note + We also provide a Kustomize base in addition to the plain Kubernetes YAML + manifests. You can use it as remote base and create overlays with your + configuration on top of it. The remote base's URL is + `https://github.com/argoproj-labs/argocd-image-updater/manifests/base` + +### Apply the installation manifests + +```shell +kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/manifests/install.yaml +``` + +!!!note "A word on high availability" + It is not advised to run multiple replicas of the same Argo CD Image Updater + instance. Just leave the number of replicas at 1, otherwise weird side + effects could occur. + +### Configure the desired log level + +While this step is optional, we recommend to set the log level explicitly. +During your first steps with the Argo CD Image Updater, a more verbose logging +can help greatly in troubleshooting things. + +Edit the `argocd-image-updater-config` ConfigMap and add the following keys +(the values are dependent upon your environment) + +```yaml +data: + # log.level can be one of trace, debug, info, warn or error + log.level: debug +``` + +If you omit the `log.level` setting, the default `info` level will be used. + +## Method 2: Connect using Argo CD API Server + +If you are unable to install Argo CD Image Updater into the same Kubernetes +cluster you can configure it to use the API of your Argo CD installation. + +If you chose to install the Argo CD Image Updater outside of the cluster where +Argo CD is running in, the API must be exposed externally (i.e. using Ingress). +If you have network policies in place, make sure that Argo CD Image Updater will +be allowed to communicate with the Argo CD API, which is usually the service +`argocd-server` in namespace `argocd` on port 443 and port 80. + +### Apply the manifests + +First, create a namespace and apply the manifests to your cluster + +```shell +kubectl create namespace argocd-image-updater +kubectl apply -n argocd-image-updater -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/manifests/install.yaml +``` + +!!!note "A word on high availability" + It is not advised to run multiple replicas of the same Argo CD Image Updater + instance. Just leave the number of replicas at 1, otherwise weird side + effects could occur. + +### Create a local user within Argo CD + +Argo CD Image Updater needs credential for accessing the Argo CD API. Using a +[local user](https://argoproj.github.io/argo-cd/operator-manual/user-management/) +is recommended, but a *project token* will work as well (although, this will +limit updating to the applications of the given project obviously). + +Let's use an account named `image-updater` with appropriate API permissions. + +Add the following user definition to `argocd-cm`: + +```yaml +data: + # ... + accounts.image-updater: apiKey +``` + +Now, you will need to create an access token for this user, which can be either +done using the CLI or the Web UI. The following CLI command will create a named +token for the user and print it to the console: + +```shell +argocd account generate-token --account image-updater --id image-updater +``` + +Copy the token's value somewhere, you will need it later on. + +### Granting RBAC permissions in Argo CD + +The technical user `image-updater` we have configured in the previous step now +needs appropriate RBAC permissions within Argo CD. Argo CD Image Updater needs +the `update` and `get` permissions on the applications you want to manage. + +A most basic version that grants `get` and `update` permissions on all of the +applications managed by Argo CD might look as follows: + +```text +p, role:image-updater, applications, get, */*, allow +p, role:image-updater, applications, update, */*, allow +g, image-updater, role:image-updater +``` + +You might want to strip that down to apps in a specific project, or to specific +apps, however. + +Put the RBAC permissions to Argo CD's `argocd-rbac-cm` ConfigMap and Argo CD will +pick them up automatically. + +### Configure Argo CD endpoint + +If you run Argo CD Image Updater in another cluster than Argo CD, or if your +Argo CD installation is not in namespace `argocd` or if you use a default or +otherwise self-signed TLS certificate for Argo CD API endpoint, you probably +need to divert from the default connection values. + +Edit the `argocd-image-updater-config` ConfigMap and add the following keys +(the values are dependent upon your environment) + +```yaml +data: + applications_api: argocd + # The address of Argo CD API endpoint - defaults to argocd-server.argocd + argocd.server_addr: + # Whether to use GRPC-web protocol instead of GRPC over HTTP/2 + argocd.grpc_web: "true" + # Whether to ignore invalid TLS cert from Argo CD API endpoint + argocd.insecure: "false" + # Whether to use plain text connection (http) instead of TLS (https) + argocd.plaintext: "false" +``` + +After changing values in the ConfigMap, Argo CD Image Updater needs to be +restarted for the changes to take effect, i.e. + +```shell +kubectl -n argocd-image-updater rollout restart deployment argocd-image-updater +``` + +### Configure API access token secret + +When installed from the manifests into a Kubernetes cluster, the Argo CD Image +Updater reads the token required for accessing Argo CD API from an environment +variable named `ARGOCD_TOKEN`, which is set from a a field named +`argocd.token` in a secret named `argocd-image-updater-secret`. + +The value for `argocd.token` should be set to the *base64 encoded* value of the +access token you have generated above. As a short-cut, you can use generate the +secret with `kubectl` and apply it over the existing resource: + +```shell +kubectl create secret generic argocd-image-updater-secret \ + --from-literal argocd.token=$YOUR_TOKEN --dry-run -o yaml | + kubectl -n argocd-image-updater apply -f - +``` + +You must restart the `argocd-image-updater` pod after such a change, i.e run + +```shell +kubectl -n argocd-image-updater rollout restart deployment argocd-image-updater +``` + +Or alternatively, simply delete the running pod to have it recreated by +Kubernetes automatically. + +## Running locally + +As long as you have access to the Argo CD API and your Kubernetes cluster from +your workstation, running Argo CD Image Updater is simple. Make sure that you +have your API token noted and that your Kubernetes client configuration points +to the correct K8s cluster. + +Grab the binary (it does not have any external dependencies) and run: + +```bash +export ARGOCD_TOKEN= +./argocd-image-updater run \ + --kubeconfig ~/.kube/config + --once +``` + +or use `--applications-api` flag if you prefer to connect using Argo CD API + +```bash +export ARGOCD_TOKEN= +./argocd-image-updater run \ + --kubeconfig ~/.kube/config + --applications-api argocd + --argocd-server-addr argo-cd.example.com + --once +``` + +Note: The `--once` flag disables the health server and the check interval, so +the tool will not regularly check for updates but exit after the first run. + +Check `argocd-image-updater --help` for a list of valid command line flags, or +consult the appropriate section of the documentation. + +## Running multiple instances + +Generally, multiple instances of Argo CD Image Updater can be run within the same +Kubernetes cluster, however they should not operate on the same set of +applications. This allows for multiple application teams to manage their own set +of applications. + +If opting for such an approach, you should make sure that: + +* Each instance of Argo CD Image Updater runs in its own namespace +* Each instance has a dedicated user in Argo CD, with dedicated RBAC permissions +* RBAC permissions are set-up so that instances cannot interfere with each + others managed resources + +## Metrics + +Starting with v0.8.0, Argo CD Image Updater exports Prometheus-compatible +metrics on a dedicated endpoint, which by default listens on TCP port 8081 +and serves data from `/metrics` path. This endpoint is exposed by a service +named `argocd-image-updater` on a port named `metrics`. + +The following metrics are being made available: + +* Number of applications processed (i.e. those with an annotation) + + * `argocd_image_updater_applications_watched_total` + +* Number of images watched for new tags + + * `argocd_image_updater_images_watched_total` + +* Number of images updated (successful and failed) + + * `argocd_image_updater_images_updated_total` + * `argocd_image_updater_images_errors_total` + +* Number of requests to Argo CD API (successful and failed) + + * `argocd_image_updater_argocd_api_requests_total` + * `argocd_image_updater_argocd_api_errors_total` + +* Number of requests to K8s API (successful and failed) + + * `argocd_image_updater_k8s_api_requests_total` + * `argocd_image_updater_k8s_api_errors_total` + +* Number of requests to the container registries (successful and failed) + + * `argocd_image_updater_registry_requests_total` + * `argocd_image_updater_registry_requests_failed_total` + +A (very) rudimentary example dashboard definition for Grafana is provided +[here](https://github.com/argoproj-labs/argocd-image-updater/tree/master/config) diff --git a/docs/install/reference.md b/docs/install/reference.md new file mode 100644 index 0000000..bfd0b42 --- /dev/null +++ b/docs/install/reference.md @@ -0,0 +1,144 @@ +# Configuration and command line reference + +The `argocd-image-updater` provides some command line parameters to control the +behaviour of its operations. The following is a list of available parameters +and their description. + +## Command "version" + +### Synopsis + +`argocd-image-updater version` + +### Description + +Prints out the version of the binary and exits. + +## Command "run" + +### Synopsis + +`argocd-image-updater run [flags]` + +### Description + +Runs the Argo CD Image Updater, possibly in an endless loop. + +### Flags + +**--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-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-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. + +**--dry-run** + +If this flag is set, Argo CD Image Updater won't actually perform any changes +to workloads it found in need for upgrade. + +**--health-port *port* ** + +Specifies the local port to bind the health server to. The health server is +used to provide health and readiness probes when running as K8s workload. +Use value *0* for *port* to disable launching the health server. + +**--interval *duration* ** + +Sets the interval for checking whether there are new images available to +*duration*. *duration* must be given as a valid duration identifier with +a unit suffix, i.e. `2m` for 2 minutes or `30s` for 30 seconds. If no unit +is given, milliseconds will be assumed. If set to `0`, ArgoCD Image Updater +will exit after the first run, effectively disabling the interval. Default +value is `2m0s`. + +**--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-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. + +**--match-application-label *label* ** + +Only process applications that have a valid annotation and match the given +*label*. The *label* is a string that matches the standard kubernetes label +syntax of `key=value`. 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 patten matching on label values (e.g `customer.label/name=*-staging`) +and only accepts a single label to match applications against. + +**--max-concurrency *number* ** + +Process a maximum of *number* applications concurrently. To disable concurrent +application processing, specify a number of `1`. + +**--once** + +A shortcut for specifying `--check-interval 0 --health-port 0`. If given, +Argo CD Image Updater will exit after the first update cycle. + +**--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=""`. diff --git a/docs/install/running.md b/docs/install/running.md deleted file mode 100644 index e5556c1..0000000 --- a/docs/install/running.md +++ /dev/null @@ -1,144 +0,0 @@ -# Running Argo CD Image Updater - -The `argocd-image-updater` provides some command line parameters to control the -behaviour of its operations. The following is a list of available parameters -and their description. - -## Command "version" - -### Synopsis - -`argocd-image-updater version` - -### Description - -Prints out the version of the binary and exits. - -## Command "run" - -### Synopsis - -`argocd-image-updater run [flags]` - -### Description - -Runs the Argo CD Image Updater, possibly in an endless loop. - -### Flags - -**--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-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-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. - -**--dry-run** - -If this flag is set, Argo CD Image Updater won't actually perform any changes -to workloads it found in need for upgrade. - -**--health-port *port* ** - -Specifies the local port to bind the health server to. The health server is -used to provide health and readiness probes when running as K8s workload. -Use value *0* for *port* to disable launching the health server. - -**--interval *duration* ** - -Sets the interval for checking whether there are new images available to -*duration*. *duration* must be given as a valid duration identifier with -a unit suffix, i.e. `2m` for 2 minutes or `30s` for 30 seconds. If no unit -is given, milliseconds will be assumed. If set to `0`, ArgoCD Image Updater -will exit after the first run, effectively disabling the interval. Default -value is `2m0s`. - -**--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-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. - -**--match-application-label *label* ** - -Only process applications that have a valid annotation and match the given -*label*. The *label* is a string that matches the standard kubernetes label -syntax of `key=value`. 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 patten matching on label values (e.g `customer.label/name=*-staging`) -and only accepts a single label to match applications against. - -**--max-concurrency *number* ** - -Process a maximum of *number* applications concurrently. To disable concurrent -application processing, specify a number of `1`. - -**--once** - -A shortcut for specifying `--check-interval 0 --health-port 0`. If given, -Argo CD Image Updater will exit after the first update cycle. - -**--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=""`. diff --git a/docs/install/start.md b/docs/install/start.md deleted file mode 100644 index bf425b4..0000000 --- a/docs/install/start.md +++ /dev/null @@ -1,312 +0,0 @@ -# Getting Started - -## Runtime environment - -It is recommended to run Argo CD Image Updater in the same Kubernetes namespace cluster that -Argo CD is running in, however, this is not a requirement. In fact, it is not -even a requirement to run Argo CD Image Updater within a Kubernetes cluster or -with access to any Kubernetes cluster at all. - -However, some features might not work without accessing Kubernetes. - -## Testing beforehand - -With v0.8.0, a new method to test your desired configuration before configuring -your applications was introduced with the `argocd-image-updater test` command. - -You can use this command from your workstation without any modifications to your -Argo CD installation or applications, and without having to install the image -updater in your Kubernetes cluster. The `test` command does not need to talk to -Argo CD, and only needs access to your Kubernetes cluster if you need to use -image pull secret stored in Kubernetes. - -The new `test` command's main purpose is to verify the behaviour of Argo CD -Image Updater on arbitrary images. For example, the most simple form of running -a test is the following: - -```shell -argocd-image-updater test -``` - -For example, to see what Argo CD Image Updater would consider the latest nginx -version according to semantic versioning, you can run: - -```shell -$ argocd-image-updater test nginx -INFO[0000] getting image image_name=nginx registry= -INFO[0002] Fetching available tags and metadata from registry image_name=nginx -INFO[0004] Found 321 tags in registry image_name=nginx -INFO[0004] latest image according to constraint is nginx:1.19.5 -``` - -To see what it would consider the latest patch version within the 1.17 release, -run: - -```shell -$ argocd-image-updater test nginx --semver-constraint 1.17.X -INFO[0000] getting image image_name=nginx registry= -INFO[0002] Fetching available tags and metadata from registry image_name=nginx -INFO[0004] Found 321 tags in registry image_name=nginx -INFO[0004] latest image according to constraint is nginx:1.17.10 -``` - -You can also specify parameters that you would set for any given application, -i.e. to use [update strategy](../../configuration/images/#update-strategies) -`latest` and the registry requires [authentication](../../configuration/images/#specifying-pull-secrets), -you can use additional command line options: - -```shell -$ export GITHUB_PULLSECRET=":" -$ argocd-image-updater test docker.pkg.github.com/argoproj/argo-cd/argocd --update-strategy latest --credentials env:GITHUB_PULLSECRET -INFO[0000] getting image image_name=argoproj/argo-cd/argocd registry=docker.pkg.github.com -INFO[0000] Fetching available tags and metadata from registry image_name=argoproj/argo-cd/argocd -INFO[0040] Found 100 tags in registry image_name=argoproj/argo-cd/argocd -INFO[0040] latest image according to constraint is docker.pkg.github.com/argoproj/argo-cd/argocd:1.8.0-9fb51f7a -``` - -For a complete list of available command line parameters, run -`argocd-image-updater test --help`. - -It is recommended that you read about core updating and image concepts in the -[documentation](../../configuration/images/) -before using this command. - -## Installing as Kubernetes workload in Argo CD namespace - -The most straightforward way to run the image updater is to install it as a Kubernetes workload into the namespace where -Argo CD is running. Don't worry, without any configuration, it will not start messing with your workloads yet. - -!!!note - We also provide a Kustomize base in addition to the plain Kubernetes YAML - manifests. You can use it as remote base and create overlays with your - configuration on top of it. The remote base's URL is - `https://github.com/argoproj-labs/argocd-image-updater/manifests/base` - -### Apply the installation manifests - -```shell -kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/manifests/install.yaml -``` - -!!!note "A word on high availability" - It is not advised to run multiple replicas of the same Argo CD Image Updater - instance. Just leave the number of replicas at 1, otherwise weird side - effects could occur. - -### Configure the desired log level - -While this step is optional, we recommend to set the log level explicitly. -During your first steps with the Argo CD Image Updater, a more verbose logging -can help greatly in troubleshooting things. - -Edit the `argocd-image-updater-config` ConfigMap and add the following keys -(the values are dependent upon your environment) - -```yaml -data: - # log.level can be one of trace, debug, info, warn or error - log.level: debug -``` - -If you omit the `log.level` setting, the default `info` level will be used. - -## Connect using Argo CD API Server - -If you unable to install Argo CD Image Updater into the same Kubernetes cluster you might -configure it to use API of your Argo CD installation. -If you chose to install the Argo CD Image Updater outside of the cluster where -Argo CD is running in, the API must be exposed externally (i.e. using Ingress). -If you have network policies in place, make sure that Argo CD Image Updater will -be allowed to communicate with the Argo CD API, which is usually the service -`argocd-server` in namespace `argocd` on port 443 and port 80. - -### Create a local user within Argo CD - -Argo CD Image Updater needs credential for accessing the Argo CD API. Using a -[local user](https://argoproj.github.io/argo-cd/operator-manual/user-management/) -is recommended, but a *project token* will work as well (although, this will -limit updating to the applications of the given project obviously). - -Let's use an account named `image-updater` with appropriate API permissions. - -Add the following user definition to `argocd-cm`: - -```yaml -data: - # ... - accounts.image-updater: apiKey -``` - -Now, you will need to create an access token for this user, which can be either -done using the CLI or the Web UI. The following CLI command will create a named -token for the user and print it to the console: - -```shell -argocd account generate-token --account image-updater --id image-updater -``` - -Copy the token's value somewhere, you will need it later on. - -### Granting RBAC permissions in Argo CD - -The technical user `image-updater` we have configured in the previous step now -needs appropriate RBAC permissions within Argo CD. Argo CD Image Updater needs -the `update` and `get` permissions on the applications you want to manage. - -A most basic version that grants `get` and `update` permissions on all of the -applications managed by Argo CD might look as follows: - -```text -p, role:image-updater, applications, get, */*, allow -p, role:image-updater, applications, update, */*, allow -g, image-updater, role:image-updater -``` - -You might want to strip that down to apps in a specific project, or to specific -apps, however. - -Put the RBAC permissions to Argo CD's `argocd-rbac-cm` ConfigMap and Argo CD will -pick them up automatically. - -### Configure Argo CD endpoint - -If you run Argo CD Image Updater in another cluster than Argo CD, or if your -Argo CD installation is not in namespace `argocd` or if you use a default or -otherwise self-signed TLS certificate for Argo CD API endpoint, you probably -need to divert from the default connection values. - -Edit the `argocd-image-updater-config` ConfigMap and add the following keys -(the values are dependent upon your environment) - -```yaml -data: - applications_api: argocd - # The address of Argo CD API endpoint - defaults to argocd-server.argocd - argocd.server_addr: - # Whether to use GRPC-web protocol instead of GRPC over HTTP/2 - argocd.grpc_web: "true" - # Whether to ignore invalid TLS cert from Argo CD API endpoint - argocd.insecure: "false" - # Whether to use plain text connection (http) instead of TLS (https) - argocd.plaintext: "false" -``` - -After changing values in the ConfigMap, Argo CD Image Updater needs to be -restarted for the changes to take effect, i.e. - -```shell -kubectl -n argocd-image-updater rollout restart deployment argocd-image-updater -``` - -### Configure API access token secret - -When installed from the manifests into a Kubernetes cluster, the Argo CD Image -Updater reads the token required for accessing Argo CD API from an environment -variable named `ARGOCD_TOKEN`, which is set from a a field named -`argocd.token` in a secret named `argocd-image-updater-secret`. - -The value for `argocd.token` should be set to the *base64 encoded* value of the -access token you have generated above. As a short-cut, you can use generate the -secret with `kubectl` and apply it over the existing resource: - -```shell -kubectl create secret generic argocd-image-updater-secret \ - --from-literal argocd.token=$YOUR_TOKEN --dry-run -o yaml | - kubectl -n argocd-image-updater apply -f - -``` - -You must restart the `argocd-image-updater` pod after such a change, i.e run - -```shell -kubectl -n argocd-image-updater rollout restart deployment argocd-image-updater -``` - -Or alternatively, simply delete the running pod to have it recreated by -Kubernetes automatically. - -## Running locally - -As long as you have access to the Argo CD API and your Kubernetes cluster from -your workstation, running Argo CD Image Updater is simple. Make sure that you -have your API token noted and that your Kubernetes client configuration points -to the correct K8s cluster. - -Grab the binary (it does not have any external dependencies) and run: - -```bash -export ARGOCD_TOKEN= -./argocd-image-updater run \ - --kubeconfig ~/.kube/config - --once -``` - -or use `--applications-api` flag if you prefer to connect using Argo CD API - -```bash -export ARGOCD_TOKEN= -./argocd-image-updater run \ - --kubeconfig ~/.kube/config - --applications-api argocd - --argocd-server-addr argo-cd.example.com - --once -``` - -Note: The `--once` flag disables the health server and the check interval, so -the tool will not regularly check for updates but exit after the first run. - -Check `argocd-image-updater --help` for a list of valid command line flags, or -consult the appropriate section of the documentation. - -## Running multiple instances - -Generally, multiple instances of Argo CD Image Updater can be run within the same -Kubernetes cluster, however they should not operate on the same set of -applications. This allows for multiple application teams to manage their own set -of applications. - -If opting for such an approach, you should make sure that: - -* Each instance of Argo CD Image Updater runs in its own namespace -* Each instance has a dedicated user in Argo CD, with dedicated RBAC permissions -* RBAC permissions are set-up so that instances cannot interfere with each - others managed resources - -## Metrics - -Starting with v0.8.0, Argo CD Image Updater exports Prometheus-compatible -metrics on a dedicated endpoint, which by default listens on TCP port 8081 -and serves data from `/metrics` path. This endpoint is exposed by a service -named `argocd-image-updater` on a port named `metrics`. - -The following metrics are being made available: - -* Number of applications processed (i.e. those with an annotation) - - * `argocd_image_updater_applications_watched_total` - -* Number of images watched for new tags - - * `argocd_image_updater_images_watched_total` - -* Number of images updated (successful and failed) - - * `argocd_image_updater_images_updated_total` - * `argocd_image_updater_images_errors_total` - -* Number of requests to Argo CD API (successful and failed) - - * `argocd_image_updater_argocd_api_requests_total` - * `argocd_image_updater_argocd_api_errors_total` - -* Number of requests to K8s API (successful and failed) - - * `argocd_image_updater_k8s_api_requests_total` - * `argocd_image_updater_k8s_api_errors_total` - -* Number of requests to the container registries (successful and failed) - - * `argocd_image_updater_registry_requests_total` - * `argocd_image_updater_registry_requests_failed_total` - -A (very) rudimentary example dashboard definition for Grafana is provided -[here](https://github.com/argoproj-labs/argocd-image-updater/tree/master/config) diff --git a/docs/install/strategies.md b/docs/install/strategies.md deleted file mode 100644 index e9d8b67..0000000 --- a/docs/install/strategies.md +++ /dev/null @@ -1,205 +0,0 @@ -# Update strategies - -Argo CD Image Updater supports different update strategies for the images that -are configured to be tracked and updated. - -You can configure the strategy to be used for each image individually, with the -default strategy being `semver` (see below). - -Some of the strategies will require additional configuration, or can be tweaked -with additional parameters. Please have a look at the -[image configuration](../../configuration/images) -documentation for more details. - -Please note that all update strategies except `digest` assume tags to be -*immutable* and that new images will be pushed with a new, unique tag. If -you want to update to *mutable* tags (e.g. the commonly used `latest` tag), -you should use the `digest` strategy. - -## Update to semantic versions - -This is the default strategy. - -Strategy name: `semver` - -```yaml -argocd-image-updater.argoproj.io/image-list: some/image[:] -# Specifying update-strategy is optional, because semver is the default -argocd-image-updater.argoproj.io/.update-strategy: semver -``` - -The `semver` strategy allows you to track & update images which use tags that -follow the -[semantic versioning scheme](https://semver.org). Tag names must contain semver -compatible identifiers in the format `X.Y.Z`, where `X`, `Y` and `Z` must be -whole numbers. An optional prefix of `v`, e.g. `vX.Y.Z` is allowed, and both -variants are treated equal (so, a constraint of `v1.x` would match a tag `1.0` -and a constraint of `1.x` also matches a tag `v1.0`). - -Updating to pre-release versions (e.g. `-rc1`) is supported, but must be -explicitly allowed (see below). - -This will allow you to update to the latest version of an image within a given -patch branch or minor release, or just to the latest version that has is tagged -with a valid semantic version identifier. - -To tell Argo CD Image Updater which versions are allowed, simply give a semver -version as a constraint in the `image-list` annotation. For example, to allow -updates to the latest patch release within the `1.2` minor release branch, use - -``` -argocd-image-updater.argoproj.io/image-list: some/image:1.2.x -``` - -The above example would update to any new tag pushed to the registry matching -this constraint, e.g. `1.2.5`, `1.2.12` etc, but not to a new minor version -(e.g. `1.3`). - -Likewise, to allow updates to any minor release within the major version `1`, -use - -```yaml -argocd-image-updater.argoproj.io/image-list: some/image:1.x -``` - -The above example would update to any new tag pushed to the registry matching -this constraint, e.g. `1.2.12`, `1.3.0`, `1.15.2` etc, but not to a new major -version (e.g. `2.0`). - -If you also want to allow updates to pre-release versions (e.g. `v2.0-rc1`), -you need to append the suffix `-0` to the constraint, for example - -``` -argocd-image-updater.argoproj.io/image-list: some/image:2.x-0 -``` - -If no version constraint is specified in the list of allowed images, Argo CD -Image Updater will pick the highest version number found in the registry. - -Argo CD Image Updater will omit any tags from your registry that do not match -a semantic version when using the `semver` update strategy. - -## Update to the most recently built image - -!!!warning - As of November 2020, Docker Hub has introduced pull limits for accounts on - the free plan and unauthenticated requests. The `latest` update strategy - will perform manifest pulls for determining the most recently pushed tags, - and these will count into your pull limits. So unless you are not affected - by these pull limits, it is **not recommended** to use the `latest` update - strategy with images hosted on Docker Hub. - -Strategy name: `latest` - -```yaml -argocd-image-updater.argoproj.io/image-list: =some/image -argocd-image-updater.argoproj.io/.update-strategy: latest -``` - -Argo CD Image Updater can update to the image that has the most recent build -date, and is tagged with an arbitrary name (e.g. a Git commit SHA, or even a -random string). - -It is important to understand, that this strategy will consider the build date -of the image, and not the date of when the image was tagged or pushed to the -registry. If you are tagging the same image with multiple tags, these tags -will have the same build date. In this case, Argo CD Image Updater will sort -the tag names lexically descending and pick the last tag name of that list. -For example, consider an image that was tagged with the `f33bacd`, `dev` -and `latest` tags. You might want to have the `f33bacd` tag set for your -application, but Image Updater will pick the `latest` tag name. In order to -prevent such a situation, you need to further restrict the tags that Image -Updater will inspect, see below. - -By default, this update strategy will inspect all of the tags it found in the -image's repository. If you wish to allow only certain tags to be considered -for update, you will need additional configuration. For example, - -```yaml -argocd-image-updater.argoproj.io/image-list: myimage=some/image -argocd-image-updater.argoproj.io/myimage.update-strategy: latest -argocd-image-updater.argoproj.io/myimage.allow-tags: regexp:^[0-9a-f]{7}$ -``` - -would only consider tags that match a given regular expression for update. In -this case, the regular expression matches a 7-digit hexadecimal string that -could represent the short version of a Git commit SHA, so it would match tags -like `a5fb3d3` or `f7bb2e3`, but not `latest` or `master`. - -Likewise, you can ignore a certain list of tags from your repository: - -```yaml -argocd-image-updater.argoproj.io/image-list: myimage=some/image -argocd-image-updater.argoproj.io/myimage.update-strategy: latest -argocd-image-updater.argoproj.io/myimage.ignore-tags: latest, master -``` - -This would allow for considering all tags found but `latest` and `master`. You -can read more about filtering tags -[here](../../configuration/images/#filtering-tags). - -## Update to the most recent pushed version of a tag - -Strategy name: `digest` - -```yaml -argocd-image-updater.argoproj.io/image-list: =some/image: -argocd-image-updater.argoproj.io/.update-strategy: digest -``` - -This update strategy inspects a single tag in the registry for changes, and -updates the image on any change to the previous state. The tag name to be -inspected must be specified as a version constraint in the image list. - -Use this update strategy if you want to follow a *mutable* tag, such as the -commonly used `latest` tag. - -Argo CD Image Updater will then update the image when either - -* The currently running image has a non-digest specification (e.g. uses a tag), - or -* the currently used digest differs from what is found in the registry - -!!!note "Tags and digests" - Note that the `digest` update strategy will use image digests for updating - the image tags in your applications, so the image running in your - application will appear as `some/image@sha256:` instead - of `some/image:latest`. So in your running system, the tag information will - be effectively lost. - -For example, the following specification would always update the image for an -application on each new push of the image `some/image` with the tag `latest`: - -```yaml -argocd-image-updater.argoproj.io/image-list: myimage=some/image:latest -argocd-image-updater.argoproj.io/myimage.update-strategy: digest -``` - -## Update according to lexical sort - -Strategy name: `name` - -```yaml -argocd-image-updater.argoproj.io/image-list: =some/image -argocd-image-updater.argoproj.io/.update-strategy: name -``` - -This update strategy sorts the tags returned by the registry in a lexical way -(by name, in descending order) and picks the last tag in the list for update. -This can be useful if the image you want to track uses `calver` versioning, -with tags in the format of e.g. `YYYY-MM-DD` or similar lexical sortable -strings. - -By default, this update strategy will inspect all of the tags it found in the -image's repository. If you wish to allow only certain tags to be considered -for update, you will need additional configuration. For example, - -```yaml -argocd-image-updater.argoproj.io/image-list: myimage=some/image -argocd-image-updater.argoproj.io/myimage.update-strategy: name -argocd-image-updater.argoproj.io/myimage.allow-tags: regexp:^[0-9]{4}-[0-9]{2}[0-9]{2}$ -``` - -would only consider tags that match a given regular expression for update. In -this case, only tags matching a date specification of `YYYY-MM-DD` would be -considered for update. diff --git a/docs/install/testing.md b/docs/install/testing.md new file mode 100644 index 0000000..fb2df4b --- /dev/null +++ b/docs/install/testing.md @@ -0,0 +1,132 @@ +# Testing outside the cluster + +The `argocd-image-updater` binary provides means to test its behavior using the +`test` subcommand. + +You can use this command from your workstation without any modifications to your +Argo CD installation or applications, and without having to install the image +updater in your Kubernetes cluster. The `test` command does not need to talk to +Argo CD, and only needs access to your Kubernetes cluster if you need to use +image pull secret stored in Kubernetes. + +The `test` command's main purpose is to verify the behaviour of Argo CD +Image Updater on arbitrary images and to validate your configuration. For +example, the most simple form of running a test is the following: + +```shell +argocd-image-updater test +``` + +## Testing registry access + +For example, to see what Argo CD Image Updater would consider the latest nginx +version on Docker Hub according to semantic versioning, you can run: + +```shell +$ argocd-image-updater test nginx +INFO[0000] getting image image_name=nginx registry= +INFO[0002] Fetching available tags and metadata from registry image_name=nginx +INFO[0004] Found 321 tags in registry image_name=nginx +INFO[0004] latest image according to constraint is nginx:1.19.5 +``` + +## Multi-arch images + +As stated in the section about +[multi-arch support](../basics/update.md#multi-arch), +Argo CD Image Updater by default only considers images in the registry for the +same platform as `argocd-image-updater` is executed on. + +For the `test` command, this means it takes the platform of the system you are +running it on. If you are executing it for example on your Mac workstation, most +likely no results will yield at all - because there are simple no native images +for any of the `darwin` platforms. + +You can specify the target platforms manually, using the `--platforms` command +line option, e.g. the following demonstrates no available images for the given +platform: + +```shell +$ argocd-image-updater test gcr.io/heptio-images/ks-guestbook-demo --platform darwin/amd64 --update-strategy latest +DEBU[0000] Creating in-cluster Kubernetes client +INFO[0000] retrieving information about image image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io +DEBU[0000] setting rate limit to 20 requests per second prefix=gcr.io registry="https://gcr.io" +DEBU[0000] Inferred registry from prefix gcr.io to use API https://gcr.io +INFO[0000] Fetching available tags and metadata from registry application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io +DEBU[0001] ignoring v2 manifest sha256:fe18e00a6aeece16b5b2f77a32ee60929e8a60e27c71df8df66bf804f5677f47. Manifest platform: linux/amd64, requested: darwin/amd64 application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io +DEBU[0001] No metadata found for heptio-images/ks-guestbook-demo:0.1 application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io +DEBU[0001] ignoring v2 manifest sha256:e6fbd640820c32c847a53b93eb7b404f25ffb56df1cc16d0711eec3a405d6509. Manifest platform: linux/amd64, requested: darwin/amd64 application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io +DEBU[0001] No metadata found for heptio-images/ks-guestbook-demo:0.2 application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io +INFO[0001] Found 0 tags in registry application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io +INFO[0001] no newer version of image found application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io +``` + +While setting the `platforms` to include `linux/amd64`, yields the following: + +```shell +$ argocd-image-updater test gcr.io/heptio-images/ks-guestbook-demo --platform linux/amd64 --update-strategy latest +DEBU[0000] Creating in-cluster Kubernetes client +INFO[0000] retrieving information about image image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io +DEBU[0000] setting rate limit to 20 requests per second prefix=gcr.io registry="https://gcr.io" +DEBU[0000] Inferred registry from prefix gcr.io to use API https://gcr.io +INFO[0000] Fetching available tags and metadata from registry application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io +INFO[0001] Found 2 tags in registry application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io +DEBU[0001] found 2 from 2 tags eligible for consideration image=gcr.io/heptio-images/ks-guestbook-demo +INFO[0001] latest image according to constraint is gcr.io/heptio-images/ks-guestbook-demo:0.2 application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io + +``` + +## Testing for semver constraints + +To see what it would consider the latest patch version within the 1.17 release, +run: + +```shell +$ argocd-image-updater test nginx --semver-constraint 1.17.X +INFO[0000] getting image image_name=nginx registry= +INFO[0002] Fetching available tags and metadata from registry image_name=nginx +INFO[0004] Found 321 tags in registry image_name=nginx +INFO[0004] latest image according to constraint is nginx:1.17.10 +``` + +## Testing different update strategies + +You can test the result of different +[update strategies](../basics/update-strategies.md) +using the `--update-strategy` command line option, e.g.: + +```shell +$ argocd-image-updater test ghcr.io/argoproj/argocd --update-strategy latest +DEBU[0000] Creating in-cluster Kubernetes client +INFO[0000] retrieving information about image image_alias= image_name=ghcr.io/argoproj/argocd registry_url=ghcr.io +DEBU[0000] setting rate limit to 20 requests per second prefix=ghcr.io registry="https://ghcr.io" +DEBU[0000] Inferred registry from prefix ghcr.io to use API https://ghcr.io +INFO[0000] Fetching available tags and metadata from registry application=test image_alias= image_name=ghcr.io/argoproj/argocd registry_url=ghcr.io +INFO[0139] Found 864 tags in registry application=test image_alias= image_name=ghcr.io/argoproj/argocd registry_url=ghcr.io +DEBU[0139] found 864 from 864 tags eligible for consideration image=ghcr.io/argoproj/argocd +INFO[0139] latest image according to constraint is ghcr.io/argoproj/argocd:2.4.0-f8390c94 application=test image_alias= image_name=ghcr.io/argoproj/argocd registry_url=ghcr.io +``` + +## Using credentials + +If you need to specify +[credentials](../basics/authentication.md#auth-registries), +you can do so using the `--credentials` parameter. It accepts the same values +as the corresponding +[annotation](../configuration/images.md#pull-secrets), i.e.: + +```shell +$ export GITHUB_PULLSECRET=":" +$ argocd-image-updater test docker.pkg.github.com/argoproj/argo-cd/argocd --update-strategy latest --credentials env:GITHUB_PULLSECRET +INFO[0000] getting image image_name=argoproj/argo-cd/argocd registry=docker.pkg.github.com +INFO[0000] Fetching available tags and metadata from registry image_name=argoproj/argo-cd/argocd +INFO[0040] Found 100 tags in registry image_name=argoproj/argo-cd/argocd +INFO[0040] latest image according to constraint is docker.pkg.github.com/argoproj/argo-cd/argocd:1.8.0-9fb51f7a +``` + +For a complete list of available command line parameters, run +`argocd-image-updater test --help`. + +It is recommended that you read about core updating and image concepts in the +[documentation](../../configuration/images/) +before using this command. -- cgit v1.2.3