# Automatisation update Portainer (Node-RED + Home Assistant)

Documentation du flow `pveSystem`, section mise à jour automatique des conteneurs Portainer.

## Objectif

Détecter automatiquement quand un nombre suffisant de conteneurs Portainer ont une image à jour disponible, lancer la mise à jour de tous ces conteneurs d'un coup, et notifier (Telegram + notification persistante HA) avant et après.

## Déclenchement

Node-RED, node inject **`triggerWedSun-1300`**, planification cron : `30 13 * * 3,0`.

Cela signifie : tous les **mercredis et dimanches à 13h30**. C'est ce planning qui limite les jours où l'automatisation se déclenche, pas une vérification à l'exécution.

## Pipeline Node-RED (onglet pveSystem)

1. **triggerWedSun-1300** (inject, cron) déclenche tout le pipeline.
2. **portainer_auto** (node Get Entities) récupère les entités `update.*` qui remplissent deux conditions à la fois :
   - `state == on` (une mise à jour est disponible)
   - label registry `name == portainer_auto`
3. **updateContainer>=10** (node switch), propriété `payload.length`, règle `gte 10`. En dessous de 10 mises à jour en attente, le pipeline s'arrête ici.
4. Si le seuil est atteint, trois actions partent en parallèle :
   - **containerUpdateAll** → appelle le service `update.install`, ciblé par label `portainer_auto`. C'est l'action qui lance les mises à jour.
   - **portainerUpdateAllMsg** → déclenche l'automation HA `automation.portainerupdateallmsg` (notification "avant").
   - Un délai de **10 minutes**, puis **portainerUpdatedAllMsg** → déclenche l'automation HA `automation.portainerupdatedallmsg` (message de suivi).

La notification "avant" et le lancement de `update.install` partent au même instant : le message Telegram est un avertissement envoyé en parallèle de l'action, pas une alerte qu'on peut annuler avant exécution.

## Les deux automations Home Assistant

### `automation.portainerupdateallmsg` — notification "avant"

Titre : 🚨Update is available!🚨
Liste, triée alphabétiquement par nom de conteneur, tous les conteneurs actuellement en attente de mise à jour :

```
{% for e in label_entities('portainer_auto') if states(e) == 'on' %}
```

Envoyée en parallèle via :

- `telegram_bot.send_message` (avec `parse_mode: plain_text`, requis car les noms de conteneurs contiennent des underscores qui cassent le Markdown Telegram)
- `persistent_notification.create`

### `automation.portainerupdatedallmsg` — message de suivi, +10 min

Titre : ✅Update is Done✅
Utilise le même filtre (`states(e) == 'on'`) que l'automation précédente. Elle recompte, 10 minutes après le lancement, ce qui est encore en attente et affiche "X update(s) remain!". Un résultat proche de 0 indique un succès ; un nombre non nul signale des conteneurs pas encore à jour.

## Le label HA `portainer_auto`

Créé dans HA (Paramètres > Zones, étiquettes et emplacements > Étiquettes). Appliqué en masse aux 54 entités `update.*` de l'intégration Portainer (Paramètres > Appareils et services > Entités, filtré par intégration "Portainer", sélection groupée + Add label).

Toutes les entités Portainer portent ce label, qu'une mise à jour soit disponible ou non ; c'est le filtre `state == on`, présent à la fois côté Node-RED et côté Jinja, qui isole celles ayant réellement une mise à jour en attente.

## Comment ajuster les paramètres

| Paramètre | Où le changer |
|---|---|
| Jours / heure de déclenchement | Champ crontab du node `triggerWedSun-1300` (syntaxe cron, jours 0-6, 0 = dimanche) |
| Seuil de déclenchement (actuellement 10) | Node `updateContainer>=10`, valeur de la règle `gte` |
| Délai avant le message de suivi (actuellement 10 min) | Node delay entre le switch et `portainerUpdatedAllMsg` |
| Conteneur à inclure/exclure du périmètre | Ajouter/retirer le label `portainer_auto` sur l'entité `update.*` correspondante dans HA |

## Notes techniques (pièges connus)

- `attributes.labels` n'est pas le bon champ pour filtrer par label sur le node Get Entities. Utiliser le type de règle dédié "Label Property" (bouton `+ add label`).
- Le nom de propriété exact pour compter un tableau dans un node switch est `payload.length`.
- L'action générique `notify.send_message` ne supporte pas le champ `parse_mode`. Utiliser `telegram_bot.send_message`, avec `entity_id` à plat dans `data:` (pas sous `target:`).
- `persistent_notification.create` n'accepte pas `parse_mode`.
- Dans un template YAML plié (`>-`), séparer chaque bloc Jinja (`{% %}` / `{{ }}`) par une ligne vide pour préserver les sauts de ligne du message final.
- `label_entities('label')` est la fonction de template HA pour récupérer les entity_id portant un label donné.

## Limites connues

- Aucun mécanisme de rollback automatique si un conteneur ne redémarre pas correctement après `update.install`.
- Le délai de 10 minutes avant le message de suivi est fixe, pas adaptatif ; sur une connexion lente avec beaucoup d'images à tirer, il peut être insuffisant.