Skip to main content

Image Automation

Table of Contents​

  1. Concept
  2. Image Reflector Controller
  3. Image Automation Controller
  4. Complete configuration
  5. Best practices
  6. Hands-on exercises

1 - Concept​

What is Image Automation?​

Image Automation allows Flux to:

  1. Scan registries for new images
  2. Automatically update the references in Git
  3. Trigger a GitOps deployment

Benefits​

BenefitDescription
True GitOpsEven images are in Git
AuditabilityEvery change is a commit
Easy rollbackgit revert
No CI credentialsCI has no access to the cluster

Required components​

# Installer les controllers d'image
flux install --components-extra=image-reflector-controller,image-automation-controller

🔝 Back to table of contents​

2 - Image Reflector Controller​

ImageRepository​

Scans a registry for available tags.

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  image: ghcr.io/my-org/my-app
  interval: 1m

With authentication​

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  image: registry.example.com/my-app
  interval: 1m
  secretRef:
    name: registry-credentials
---
apiVersion: v1
kind: Secret
metadata:
  name: registry-credentials
  namespace: flux-system
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64-encoded>

ImagePolicy​

Defines the tag selection criteria.

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: my-app
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: my-app
  policy:
    semver:
      range: ">=1.0.0 <2.0.0"

Selection policies​

# Semver - choisir le plus récent dans la range
policy:
  semver:
    range: ">=1.0.0"

# Alphabétique - dernier par ordre alpha
policy:
  alphabetical:
    order: asc

# Numérique - pour les build numbers
policy:
  numerical:
    order: asc

# Filtrage par regex
filterTags:
  pattern: '^main-[a-f0-9]+-(?P<ts>.*)'
  extract: '$ts'
policy:
  numerical:
    order: asc

🔝 Back to table of contents​

3 - Image Automation Controller​

ImageUpdateAutomation​

Configures the automatic update in Git.

apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 1m
  sourceRef:
    kind: GitRepository
    name: my-repo
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        email: [email protected]
        name: Flux
      messageTemplate: |
        Auto-update images
        
        {{range .Updated.Images}}
        - {{.}}
        {{end}}
    push:
      branch: main
  update:
    path: ./apps
    strategy: Setters

Markers in the manifests​

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
        - name: app
          image: ghcr.io/my-org/my-app:1.0.0 # {"$imagepolicy": "flux-system:my-app"}

The comment {"$imagepolicy": "flux-system:my-app"} tells Flux where to update the image.

🔝 Back to table of contents​

4 - Complete configuration​

Complete example​

# 1. GitRepository pour l'application
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-app-config
  namespace: flux-system
spec:
  interval: 1m
  url: ssh://[email protected]/my-org/my-app-config.git
  ref:
    branch: main
  secretRef:
    name: git-ssh
---
# 2. ImageRepository - scanner le registry
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  image: ghcr.io/my-org/my-app
  interval: 1m
---
# 3. ImagePolicy - critères de sélection
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: my-app
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: my-app
  policy:
    semver:
      range: ">=1.0.0"
---
# 4. ImageUpdateAutomation - commit vers Git
apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 1m
  sourceRef:
    kind: GitRepository
    name: my-app-config
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        email: flux@my-org.com
        name: Flux Bot
      messageTemplate: |
        chore: update images
        
        {{range .Updated.Images}}
        - {{.}}
        {{end}}
    push:
      branch: main
  update:
    path: ./apps/my-app
    strategy: Setters
---
# 5. Kustomization - déployer
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  path: ./apps/my-app
  prune: true
  sourceRef:
    kind: GitRepository
    name: my-app-config

Complete workflow​

🔝 Back to table of contents​

5 - Best practices​

Separate the repos​

# Repo de code source (CI)
my-app/
├── src/
├── Dockerfile
└── .github/workflows/build.yaml

# Repo GitOps (Flux)
my-app-config/
├── apps/my-app/
│   ├── deployment.yaml
│   └── service.yaml
└── clusters/...

Tagging convention​

# Tags semver pour production
v1.0.0, v1.1.0, v2.0.0

# Tags avec SHA pour staging
main-abc1234-1699999999

Limit updates​

# Ne mettre à jour que les tags stables
spec:
  filterTags:
    pattern: '^v[0-9]+\.[0-9]+\.[0-9]+$'
  policy:
    semver:
      range: ">=1.0.0"

🔝 Back to table of contents​

6 - Hands-on exercises​

Exercise 1: Scan a registry​

# Créer l'ImageRepository
flux create image repository podinfo \
  --image=ghcr.io/stefanprodan/podinfo \
  --interval=1m

# Créer l'ImagePolicy
flux create image policy podinfo \
  --image-ref=podinfo \
  --select-semver=">=6.0.0"

# Vérifier
flux get image repository
flux get image policy

Quiz​

Q1. What is the difference between ImageRepository and ImagePolicy?

Answer
  • ImageRepository: Scans a registry and lists all available tags
  • ImagePolicy: Defines the criteria to select the "right" tag among those found

ImageRepository collects, ImagePolicy selects.

Q2. How do you tell Flux where to update the image in a manifest?

Answer

With a marker comment:

image: my-image:1.0.0 # {"$imagepolicy": "flux-system:my-policy"}

The format is {"$imagepolicy": "<namespace>:<policy-name>"}.

🔝 Back to table of contents​

Key takeaways​

  • Image Automation = true GitOps (images in Git)
  • ImageRepository: scans registries
  • ImagePolicy: selects versions
  • ImageUpdateAutomation: commits to Git
  • Markers to indicate where to update

← Previous chapter | Next chapter: Notifications →