DEV Community

iapilgrim
iapilgrim

Posted on

Automating Container Image Updates with FluxCD (Hands-On Tutorial)

#fluxcd #cicd #kubernetes

Modern GitOps workflows aim to keep your Kubernetes cluster fully synchronized with what is defined in Git. One powerful feature of Flux is Image Automation, which automatically updates container image tags in your Git repository whenever a new image becomes available.

In this tutorial, we walk through how image automation works and how to troubleshoot a common issue involving Git authentication.

1. What is Flux Image Automation?

FluxCD provides several components that work together to automate image updates.

The workflow looks like this:

Container Registry
↓
ImageRepository (scans tags)
↓
ImagePolicy (selects allowed tags)
↓
ImageUpdateAutomation (commits updates to Git)
↓
Flux Kustomization deploys updated workload

Instead of manually updating image tags in Git, Flux automatically commits the new tag when a matching image appears in your container registry.

2. Repository Structure Used in This Lab

Example GitOps layout:

flux-minikube-lab
├── apps
│   └── web-server
│       ├── web-server.yaml
│       ├── sealed-db-pass.yaml
│       └── kustomization.yaml
│
└── clusters
    └── my-cluster
        ├── image-reflect.yaml
        ├── image-policy.yaml
        ├── web-server-sync.yaml
        └── kustomization.yaml
Enter fullscreen mode Exit fullscreen mode

The cluster Kustomization references infrastructure and application sync resources.

3. Application Deployment

The web server manifests are defined in:

apps/web-server/
Enter fullscreen mode Exit fullscreen mode

Example kustomization.yaml:

resources:
  - web-server.yaml
  - sealed-db-pass.yaml
Enter fullscreen mode Exit fullscreen mode

A Flux Kustomization sync object deploys the app:

kind: Kustomization
metadata:
  name: web-server-sync
  namespace: flux-system
spec:
  interval: 1m
  path: ./apps/web-server
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system
  targetNamespace: engineering
Enter fullscreen mode Exit fullscreen mode

This instructs Flux to deploy the web server into the engineering namespace.

4. Image Automation Setup

Three resources enable automated updates:

Image Repository

This scans container registry tags.

kind: ImageRepository
Enter fullscreen mode Exit fullscreen mode

Image Policy

Defines which tags are acceptable (e.g., semver or latest).

kind: ImagePolicy
Enter fullscreen mode Exit fullscreen mode

Image Update Automation

Updates the Git repo when a new tag matches the policy.

kind: ImageUpdateAutomation
Enter fullscreen mode Exit fullscreen mode

5. Triggering Automation

To manually trigger automation:

flux reconcile image update flux-system
Enter fullscreen mode Exit fullscreen mode

Flux will:

  1. Check registry tags
  2. Apply the image policy
  3. Update manifests in Git
  4. Commit and push the change

6. Troubleshooting a Common Error

While testing automation, the following error appeared:

failed to update source:
failed to push to remote:
ERROR: The key you are authenticating with has been marked as read only
Enter fullscreen mode Exit fullscreen mode

Checking the automation status:

flux get image update
Enter fullscreen mode Exit fullscreen mode

Output:

READY: False
MESSAGE: failed to push to remote
Enter fullscreen mode Exit fullscreen mode

7. Root Cause

ImageUpdateAutomation needs write access to the Git repository to commit updated image tags.

However, the repository authentication key was configured as read-only.

This allowed Flux to pull manifests but prevented it from pushing updates.

8. Fix: Recreate the Flux Git Secret with Write Access

Step 1 — Generate a New SSH Key 

ssh-keygen
Enter fullscreen mode Exit fullscreen mode

Step 2 — Add the Public Key to GitHub

Navigate to the repository settings:

Settings → Deploy Keys
Enter fullscreen mode Exit fullscreen mode

Add the new public key and enable:

Allow write access
Enter fullscreen mode Exit fullscreen mode

Step 3 — Recreate the Flux Git Secret 

flux create secret git flux-system \
  --url=ssh://git@github.com/pilgrim2go/flux-minikube-lab \
  --private-key-file=$PWD/fluxcd-test \
  -n flux-system
Enter fullscreen mode Exit fullscreen mode

This updates the authentication credentials used by Flux.

Step 4 — Re-run Automation 

flux reconcile image update flux-system
Enter fullscreen mode Exit fullscreen mode

Verify:

flux get image update
Enter fullscreen mode Exit fullscreen mode

Expected result:

READY: True
MESSAGE: committed and pushed update
Enter fullscreen mode Exit fullscreen mode

A new commit should appear in the repository with the updated image tag.

9. Helpful Debug Commands

Check Flux resources:

flux get all
Enter fullscreen mode Exit fullscreen mode

Inspect automation status:

flux get image update
Enter fullscreen mode Exit fullscreen mode

View controller logs:

kubectl logs -n flux-system deploy/image-automation-controller
Enter fullscreen mode Exit fullscreen mode

Trigger Git sync:

flux reconcile source git flux-system
Enter fullscreen mode Exit fullscreen mode

10. Best Practices

When using Flux image automation:

• Use a dedicated deploy key or bot account
• Ensure Git credentials allow read and write access
• Keep Git as the single source of truth
• Avoid manual cluster changes outside GitOps

Conclusion

Flux image automation eliminates manual image updates and ensures that your Kubernetes workloads always run the latest approved container images.

With the proper Git authentication setup, Flux can automatically:

• Detect new container images
• Update manifests in Git
• Trigger GitOps deployments

This enables a fully automated and auditable Kubernetes delivery pipeline.

Top comments (0)