Mises à jour d'images

Composia détecte les nouvelles balises d’images et peut appliquer les mises à jour automatiquement. Les tâches de vérification d’images s’exécutent sur l’agent et rapportent les résultats au contrôleur.

Fonctionnement

Le contrôleur planifie des tâches image_check périodiques selon la configuration de mise à jour du service. Chaque vérification :

1. L’agent télécharge le bundle de service.
2. Lit docker compose config --format json pour découvrir les images en cours d’exécution.
3. Rapporte les empreintes locales et distantes pour chaque image.
4. Pour les images configurées dans update.images, vérifie les nouvelles balises candidates en utilisant les sources de découverte configurées.
5. Rapporte les résultats au contrôleur. Le contrôleur enregistre les mises à jour disponibles et peut les appliquer automatiquement.

Planification et fréquence des vérifications

La planification de vérification des images est sélectionnée dans l’ordre suivant, les paramètres les plus spécifiques étant prioritaires :

update.images.<name>.check_schedule
→ update.check_schedule
→ controller.updates.default_check_schedule

Si aucun de ces trois paramètres n’est configuré, ou si le paramètre sélectionné vaut none, aucune vérification automatique des images n’est exécutée. La valeur d’exemple 0 */6 * * * n’est pas une valeur par défaut intégrée.

Valeurs par défaut du contrôleur

Les valeurs par défaut globales sont définies dans la configuration du contrôleur :

controller:
  updates:
    default_check_schedule: "0 */6 * * *"
    auto_apply: false
    backup_before_update: true
    digest_pin: false
    semver:
      default_allow:
        - patch
        - minor
    forge_auth:
      github:
        url: "https://github.com"
        token: "REPLACE"

La section update au niveau du service remplace ces valeurs par défaut.

Authentification des API Forge

forge_auth est utilisé uniquement par le contrôleur pour interroger les API Release de GitHub, GitLab et Forgejo. Il ne sert pas à s’authentifier auprès des registres Docker. Les Release publiques ne nécessitent pas de jeton ; configurez l’authentification pour les Release privées ou pour augmenter les limites de requêtes API. Les jetons restent sur le contrôleur et ne sont pas envoyés aux agents.

Sans api_url, le contrôleur utilise l’URL d’API standard de la plateforme selon url :

• GitHub.com : https://api.github.com.
• GitHub Enterprise Server : {url}/api/v3.
• GitLab : {url}/api/v4.
• Forgejo : {url}/api/v1.

Définissez api_url uniquement pour les déploiements particuliers, comme un proxy inverse, un domaine d’API distinct ou un chemin non standard. Chaque type de forge accepte un objet unique ou un tableau d’instances. Par exemple, la configuration minimale d’une instance Forgejo auto-hébergée est :

controller:
  updates:
    forge_auth:
      forgejo:
        url: "https://forgejo.example.com"
        token_file: "/run/secrets/forgejo-token"

Un déploiement particulier peut remplacer l’URL de l’API :

forge_auth:
  forgejo:
    url: "https://forgejo.example.com"
    api_url: "https://api.forgejo.example.com/v1"
    token_file: "/run/secrets/forgejo-token"

Configuration du service

update:
  enabled: true
  auto_apply: false
  check_schedule: "0 */6 * * *"
  backup_before_update: true
  digest_pin: false
  backup_data:
    - name: db
      enabled: true
  discovery_sources:
    upstream-gh:
      sources:
        - type: github
          repo: owner/repo
      combine: first_success
      include_prerelease: false
  images:
    api:
      image: ghcr.io/example/api
      current:
        env:
          file: .env
          key: API_VERSION
      discovery: upstream-gh
      filter:
        type: semver
        allow:
          - patch
          - minor

update niveau supérieur

images.<nom>

current

Exactement une de ces sources doit être spécifiée :

Balise statique :

current:
  tag: "v1.2.3"

Fichier d’environnement :

current:
  env:
    file: .env
    key: APP_VERSION

Le chemin file est relatif au répertoire du service. Composia lit le fichier, cherche les lignes CLE=VALEUR et extrait la valeur.

Fichier YAML :

current:
  yaml:
    file: values.yaml
    path: app.image.tag

Le path est un chemin séparé par des points dans l’arborescence du document YAML. La valeur à ce chemin doit être un scalaire.

Découverte

Les sources de découverte peuvent être :

Référence nommée vers une entrée discovery_sources :

discovery: upstream-gh

Définition en ligne :

discovery:
  sources:
    - type: probe
  combine: first_success
  include_prerelease: false

Types de sources de découverte :

combine accepte merge (union de tous les résultats des sources) ou first_success (la première source qui retourne des résultats gagne).

include_prerelease inclut les versions préliminaires dans les requêtes de releases GitHub, GitLab et Forgejo.

Filtre

Sondage semver

Avec type: probe et un filtre semver, Composia recherche les balises candidates en construisant des numéros de version et en vérifiant si le manifeste du registre correspondant existe. Il sonde les incréments patch, minor et major selon la liste allow, en utilisant une recherche exponentielle avec raffinement binaire pour trouver la version disponible la plus élevée.

Mode empreinte

Lorsque toutes les sources de découverte dans une configuration ont type: digest, aucune comparaison de balises n’est effectuée. Composia compare uniquement l’empreinte de l’image distante avec l’empreinte locale :

discovery:
  sources:
    - type: digest

Lorsque digest est défini comme mode de découverte, filter doit être omis. Si une empreinte diffère, une mise à jour est considérée comme disponible.

Observations d’images

Pendant les tâches de déploiement et de mise à jour, l’agent collecte également des observations d’images pour tous les services Compose. Celles-ci incluent les empreintes locales et distantes, rapportées au contrôleur indépendamment de la présence de update.images. Cela fournit une visibilité sur l’état des images dans l’interface web et la CLI.