What is Argo CD Image Updater?<\/h2>\n
Argo CD Image Updater is an additional tool in Argo CD that helps to automate the process of updating new container images on applications managed by Argo CD.<\/p>\n
Image Updater supports popular container registries like AWS ECR, Docker Hub, GCR, etc, and can even access their private repositories with proper authentication.<\/p>\n
Using Argo CD Image Updater is simple, you just have to install Image Updater and specify the annotation on the application manifest file, which we will see about later in this blog.<\/p>\n
Image Updater only works with applications that are in Helm or Kustomize, not any other deployment format like plain YAML<\/a>.<\/p>\n The Image Updater continuously monitors the configured container registry for new images. When it detects a new tag that matches the allowed version rules, it updates the application using one of two write-back methods<\/strong>.<\/p>\n Once updated, Argo CD rolls out a new pod with the latest image. If auto-sync is enabled, this happens automatically. Or else, you need to trigger a manual sync.<\/p>\n The workflow of the Argo CD Image Updater with ECR registry is shown in the below image.<\/p>\n Here is how it works.<\/p>\n Below are the prerequisites for this setup<\/p>\n For the Image Updater to access the ECR registry, the default installation is not enough. We have to create a custom script and mount it in the Image Updater deployment.<\/p>\n The custom script contains the command to login to ECR registry.<\/p>\n We have already created every file and kept it in our GitHub repo<\/a>, fork it and clone it to your local.<\/p>\n Run the following command to clone it.<\/p>\n You can see the following folder structure.<\/p>\n Lets get started with the setup.<\/p>\n First, let’s create a pod identity association for the Argo CD Image Updater service account, which is required for it to monitor and update new images from ECR.<\/p>\n Run the following command to create a trust policy JSON file.<\/p>\n Then, create a role with the trust policy from the We are going to use the Run the following command to attach the container registry read-only policy to the role.<\/p>\n Then, save the ARN of the role as an environment variable, which will be useful in the next step.<\/p>\n Now, update your cluster name in the command below and run it.<\/p>\n We will be using the offical You can download and modify the official Helm values file using the following command.<\/p>\n Or you can use the custom values file inside the I am using the custom values file.<\/p>\n Open the values file and update your In this, Also, it refreshes the authentication token every 6 hours.<\/p>\n The best method for installing Image Updater is to install it on the same namespace as Argo CD, so the Image Updater can make use of the Argo CD ServiceAccount for permissions.<\/p>\n By installing it in the same namespace, you can simply use the Image Updater by using annotations on the manifest file.<\/p>\n To deploy the Argo CD Image Updater, run the following Helm install command with the custom values file from the root directory.<\/p>\n Then, run the following command to check if the Image Updater is installed.<\/p>\n You can also install Image Updater on another namespace, but for that, you need to create a new account with the API key and ServiceAccount, which will be used to connect Image Updater with Argo CD.<\/p>\n You can check the official document for Image updater installation<\/a> on other namespaces.<\/p>\n To test the Image Updater, we are going to do the following.<\/p>\n You can find a Python file for a Flask application and a Dockerfile<\/a> to dockerize<\/a> it inside the The Flask application is a simple one that says “This is image version 1.0.0”.<\/p>\n Go inside the Update the registry URL before running the command.<\/p>\n Once the build is completed, run the following command to push it to ECR.<\/p>\n We are going to use Helm to deploy the application, since only Helm and Kustomize<\/a> work with the Image Updater.<\/p>\n You can find the Helm charts inside Open the To create an application, you can find the manifest file inside the The application resource will be created on the Argo CD namespace, and the Flask application will be deployed on the default namespace.<\/p>\n The annotations enable the Argo CD Image Updater to monitor the specified registry and update new images.<\/p>\n What the annotations for:<\/p>\n At the end, the tag is given as For example, if we specify the allowed version as Image Updater will not update the images with tags other than the version specified in the configuration, in our case it is ~1.0, so it will not update the images with tags 2.0.0, 1.2.0, etc.<\/p>\n We are going to use the We will look into write-back methods in detail later in this blog.<\/p>\n We are going to use the Now, run the following command from the root directory to deploy the application.<\/p>\n Then run the following commands to check if your application resource and Flask application are created.<\/p>\n You will get the following output.<\/p>\n Also, in the Argo CD UI, you can see the following.<\/p>\n Since the Flask application will be exposed using Now, we are going to check what the Argo CD Image updater does when a new image is pushed to ECR.<\/p>\n To update the new image, just do the The only thing you need to change is the tag in the Docker build and push command, as below.<\/p>\n Also, change the message inside the Flask application file You can see I have changed the message from Then, build the new image from the same directory where the Dockerfile is and push it to ECR.<\/p>\n Once the new image tag is updated, you can see the Pod with the old version get terminated and a Pod with the new version comes up as shown below<\/p>\n And refresh the flask application, you can see the message changed as shown below.<\/p>\n This is how the Image Updater continually monitors and updates the image to the application.<\/p>\n If you no longer need the Argo CD Image Updater setup, run the following commands.<\/p>\n Run the following command to delete the application.<\/p>\n Run the following command to uninstall the Image Updater.<\/p>\n To delete the pod identity association, update your cluster name in the command below and run it.<\/p>\n And finally, delete the role created by running the following commands.<\/p>\n Image Updater has multiple update strategies,<\/strong> which are used to update the image. The available update strategies are listed below:<\/p>\n This strategy updates the tag which has the highest allowed version according to the configuration. <\/p>\n For example, let’s say you have configured to allow version 1.0, and your repository has image tags as 1.0.2, 1.0.3, and 1.0.4.<\/p>\n While using this strategy, it updates the tag 1.0.4<\/strong> because it is the highest allowed version available on the registry.<\/p>\n This strategy updates the latest created image tag.<\/p>\n For example, you have pushed the image in the order 1.0.1, 1.0.4, 1.0.3.<\/p>\n While using this strategy, it updates the tag 1.0.3<\/strong> because it is the latest pushed tag.<\/p>\n This strategy is used when a tag is in alphabetical letters and it updates the tag with the highest letter.<\/p>\n For example, you have tags as dev, stage, and prod.<\/p>\n While using this strategy, it updates the tag stage<\/strong> because it has the highest alphabetical letter ‘S’<\/strong>.<\/p>\n This strategy updates the latest mutable image tag.<\/p>\n For example, you have already pushed an image with tag 1.0.4 and again you pushed the image with the same tag it becomes a mutable image.<\/p>\n Your repo has tags such as 1.0.1, 1.0.4, and 1.0.6, in this 1.0.4 is a mutable image.<\/p>\n While using this strategy, it updates the tag 1.0.4<\/strong> because it is the latest pushed mutable image tag.<\/p>\n You need to use annotations of Image Updater on your application’s manifest file to monitor and update by Image Updater.<\/p>\n Make sure to use the prefix This is the mandatory annotation, here you have to specify your image repository with your preferred tag version.<\/p>\n For example, if my image repository is You can also use an alias for this annotation as given below.<\/strong><\/p>\n This annotation is used to specify the update strategy we see in the above feature.<\/p>\n For example, if you are using the This annotation is used when you want to update images with two or more tag versions.<\/p>\n For example, if you want to update images within the tag range This annotation is used when you don’t want to update a specific tag version.<\/p>\n For example, if the ignored image tag is With this annotation, you can specify the credentials of your private image repository stored as a secret in Kubernetes.<\/a><\/p>\n For example, I have stored the credentials of my private image repository as a secret in Kubernetes named Image Updater has two types of write-back methods argocd and git<\/p>\n This method directly modifies the application resource on Argo CD. Once it’s updated, Argo CD rolls out the application pod with the new image tag.<\/p>\n The annotation used to specify this method is:<\/p>\n This method creates a file named Then Argo CD notices the change in GitHub and updates the application pod.<\/p>\n The annotation used to specify this method is:<\/p>\n For detailed information on the write-back method, refer to the official documentation<\/a>.<\/p>\n You have installed Argo CD Image Updater, connected it to ECR<\/strong>, deployed a sample Flask<\/strong> app, and verified automatic tag updates and rollouts. <\/p>\n Also you learned common annotations and strategies to fine\u2011tune updates.<\/p>\n I hope this blog gives you an understanding of Argo CD Image Updater. For more information and edge cases, refer to the official documentation<\/a>.<\/p>\nHow does Argo CD Image Updater work?<\/h2>\n
\n
![\"Argo](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/09\/image-updater.png\")
<\/figure>\n\n
Setup Prerequisites<\/h2>\n
\n
Install Argo CD Image Updater on Kubernetes<\/h2>\n
git clone https:\/\/github.com\/devopscube\/argocd-image-updater.git<\/code><\/pre>\nCD<\/code> into the argocd-image-updater<\/code> folder.<\/p>\ncd argocd-image-updater<\/code><\/pre>\nargocd-image-updater\n \u251c\u2500\u2500 README.md\n \u251c\u2500\u2500 app\n \u2502 \u251c\u2500\u2500 Dockerfile\n \u2502 \u2514\u2500\u2500 app.py\n \u251c\u2500\u2500 flask-app\n \u2502 \u251c\u2500\u2500 Chart.yaml\n \u2502 \u251c\u2500\u2500 templates\n \u2502 \u2502 \u251c\u2500\u2500 deployment.yaml\n \u2502 \u2502 \u2514\u2500\u2500 service.yaml\n \u2502 \u2514\u2500\u2500 values.yaml\n \u2514\u2500\u2500 manifest\n \u251c\u2500\u2500 application.yaml\n \u2514\u2500\u2500 values.yaml\n<\/code><\/pre>\nStep1: Create Pod Identity Association<\/h2>\n
cat <<EOF > trust-policy.json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Principal\": {\n \"Service\": \"pods.eks.amazonaws.com\"\n },\n \"Action\": [\n \"sts:AssumeRole\",\n \"sts:TagSession\"\n ]\n }\n ]\n}\nEOF<\/code><\/pre>\ntrust-policy.json<\/code> file<\/p>\naws iam create-role \\\n --role-name ecr-auth-role \\\n --assume-role-policy-document file:\/\/trust-policy.json<\/code><\/pre>\nAmazonEC2ContainerRegistryReadOnly<\/code> policy, which has every permission Image Updater needs.<\/p>\naws iam attach-role-policy \\\n --role-name ecr-auth-role \\\n --policy-arn arn:aws:iam::aws:policy\/AmazonEC2ContainerRegistryReadOnly<\/code><\/pre>\nROLE_ARN=$(aws iam get-role --role-name ecr-auth-role --query 'Role.Arn' --output text)\n<\/code><\/pre>\neksctl create podidentityassociation \\\n --cluster <cluster-name> \\\n --namespace argocd \\\n --service-account-name argocd-image-updater \\\n --role-arn $ROLE_ARN<\/code><\/pre>\nStep 2: Deploy Argo CD Image Updater<\/h2>\n
argocd-image-updater<\/code><\/strong> helm chart for the installation.<\/p>\nhelm show values argo\/argocd-image-updater > values.yaml<\/code><\/pre>\nmanifest<\/code> folder as values.yaml<\/code>.<\/p>\nAWS account ID<\/code> in it. If your ECR is in a different region, change that as well.<\/p>\nconfig:\n registries:\n - name: ECR\n api_url: https:\/\/<account-id>.dkr.ecr.us-west-2.amazonaws.com\n prefix: <account-id>.dkr.ecr.us-west-2.amazonaws.com\n ping: yes\n insecure: no\n credentials: ext:\/scripts\/login.sh\n credsexpire: 6h\n\nauthScripts:\n enabled: true\n scripts:\n login.sh: |\n #!\/bin\/sh\n aws ecr --region \"us-west-2\" get-authorization-token --output text --query 'authorizationData[].authorizationToken' | base64 -d<\/code><\/pre>\nregistries<\/code> and authScripts<\/code> are default configuration is available in the Image Updater, which we can use to specify the image registry it has to monitor and the authentication script.<\/p>\nhelm install argocd-image-updater argo\/argocd-image-updater -n argocd -f manifest\/values.yaml<\/code><\/pre>\nkubectl get po -n argocd<\/code><\/pre>\n![\"checking](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/07\/image-234.png\")
<\/figure>\nStep 3: Test Argo CD Image Updater<\/h2>\n
\n
Create a Python Flask Docker Image<\/h3>\n
app<\/code> folder.<\/p>\nflask-app<\/code> in ECR<\/div>\n<\/div>\napp<\/code> folder and run the following command to dockerize the application.<\/p>\ndocker build -t <registry-url>:1.0.0 .<\/code><\/pre>\ndocker push <registry-url>:1.0.0<\/code><\/pre>\n![\"image](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/07\/image-286.png\")
<\/figure>\nModify Helm Values File<\/h3>\n
flask-app<\/code> folder.<\/p>\nvalues.yaml<\/code> file ,update your image registry URL, and then push it to your repository.<\/p>\n![\"helm](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/08\/image.png\")
<\/figure>\nCreate an Application on Argo CD<\/h3>\n
manifest<\/code> folder as application.yaml<\/code>.<\/p>\napiVersion: argoproj.io\/v1alpha1\nkind: Application\nmetadata:\n name: flask-app\n namespace: argocd\n annotations:\n argocd-image-updater.argoproj.io\/image-list: <account-id>.dkr.ecr.us-west-2.amazonaws.com\/flask-app:~1.0\n argocd-image-updater.argoproj.io\/write-back-method: argocd\n argocd-image-updater.argoproj.io\/update-strategy: newest-build\n finalizers:\n - resources-finalizer.argocd.argoproj.io\nspec:\n project: default\n source:\n repoURL: https:\/\/github.com\/devopscube\/argocd-image-updater.git\n targetRevision: main\n path: flask-app\n destination:\n server: https:\/\/kubernetes.default.svc\n namespace: default\n syncPolicy:\n automated:\n prune: true\n selfHeal: true\n<\/code><\/pre>\n annotations:\n argocd-image-updater.argoproj.io\/image-list: <account-id>.dkr.ecr.us-west-2.amazonaws.com\/flask-app:~1.0\n argocd-image-updater.argoproj.io\/write-back-method: argocd\n argocd-image-updater.argoproj.io\/update-strategy: newest-build<\/code><\/pre>\nargocd-image-updater.argoproj.io\/image-list<\/code> – for specifying the registry URL Image Updater needs to monitor.<\/p>\n~1.0<\/code> , which means it will update the images that are tagged as 1.0.1, 1.0.2, 1.0.3,….<\/p>\n~1.0<\/code> in the annotation, the Image Updater will automatically update the image that is pushed with tags like 1.0.1, 1.0.2,…<\/p>\nargocd-image-updater.argoproj.io\/write-back-method<\/code> – specify the write-back method need to use.<\/p>\nargocd<\/code> write-back method, and there is also a git method.<\/p>\nargocd-image-updater.argoproj.io\/update-strategy<\/code> – specify how new images need to be updated.<\/p>\nnewest-build<\/code> update strategy. Apart from this, there are three more strategies that we will see about later in this blog.<\/p>\nkubectl apply -f manifest\/application.yaml<\/code><\/pre>\nkubectl get applications -n argocd\n\nkubectl get po <\/code><\/pre>\n![\"checking](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/07\/image-295.png\")
<\/figure>\n![\"verifying](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/07\/image-297.png\")
<\/figure>\nNodePort 30050<\/code>, you can check the application on a browser using the URL <your-node-ip>:30050<\/code> as shown below.<\/p>\n![\"accessing](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/07\/image-296.png\")
<\/figure>\nUpload New Image to ECR<\/h3>\n
Create a Python Flask Docker Image<\/code> step again.<\/p>\ndocker build -t <registry-url>:1.0.2 .\n\ndocker push <registry-url>:1.0.2 .<\/code><\/pre>\n\/app\/app.py<\/code> as shown below.<\/p>\nfrom flask import Flask\n\napp = Flask(__name__)\n\n@app.route('\/')\ndef version():\n return \"This is image version 1.0.2\"\n\nif __name__ == '__main__':\n app.run(host='0.0.0.0', port=5000)\n<\/code><\/pre>\nThis is image version 1.0.0<\/code> to This is image version 1.0.2<\/code><\/p>\n![\"checking](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/07\/image-298.png\")
<\/figure>\n![\"checking](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/07\/image-299.png\")
<\/figure>\nClean Up<\/h2>\n
kubectl delete -f manifest\/application.yaml<\/code><\/pre>\nhelm delete argocd-image-updater -n argocd<\/code><\/pre>\neksctl delete podidentityassociation \\\n --cluster <cluster-name> \\\n --namespace argocd \\\n --service-account-name argocd-image-updater\n<\/code><\/pre>\naws iam list-attached-role-policies \\\n --role-name ecr-auth-role \\\n --query 'AttachedPolicies[*].PolicyArn' \\\n --output text | \\\n xargs -n 1 -I {} aws iam detach-role-policy \\\n --role-name ecr-auth-role \\\n --policy-arn {}\n\naws iam delete-role --role-name ecr-auth-role<\/code><\/pre>\nImage Update Strategies<\/h2>\n
semver<\/h3>\n
newest-build<\/h3>\n
name<\/h3>\n
digest<\/h3>\n
Image Updater Annotations<\/h2>\n
argocd-image-updater.argoproj.io\/<\/code> before every annotation.
Some of the commonly used annotations are given below:<\/p>\nimage-list<\/h3>\n
image\/dev<\/code> and the preferred tag version is 1.0<\/code>, then my annotation will be:<\/p>\nargocd-image-updater.argoproj.io\/image-list: image\/dev:~1.0<\/code><\/pre>\nargocd-image-updater.argoproj.io\/image-list: nginx=image\/dev:~1.0<\/code><\/pre>\nupdate-strategy<\/h3>\n
newest-build<\/code> update-strategy your annotation will be:<\/p>\nargocd-image-updater.argoproj.io\/update-strategy: newest-build<\/code><\/pre>\nallow-tags<\/h3>\n
1.1<\/code> and 2.1<\/code>, then your annotation will be:<\/p>\nargocd-image-updater.argoproj.io\/allow-tags: 1\\.1\\.[0-9]+|2\\.1\\.[0-9]+<\/code><\/pre>\nignore-tags<\/h3>\n
1.0<\/code>, then Image Updater will not update the tag version that comes under the 1.0 version such as 1.0.1, 1.0.2, 1.0.3, … these tag versions will be ignored.<\/p>\npull-secret<\/h3>\n
docker-cred<\/code> then my annotation will be:<\/p>\nargocd-image-updater.argoproj.io\/pull-secret: docker-cred<\/code><\/pre>\nwrite-back-method<\/h3>\n
argocd<\/h4>\n
argocd-image-updater.argoproj.io\/write-back-method: argocd<\/code><\/pre>\ngit<\/h4>\n
.argocd-source-<app-name>.yaml<\/code> in GitHub and writes the parameters that have changed in the file.<\/p>\nargocd-image-updater.argoproj.io\/write-back-method: git<\/code><\/pre>\nConclusion<\/h2>\n
\n