Aller au contenu principal

Immich sur GKE Autopilot

Immich sur GKE Autopilot

Immich est une plateforme open source de gestion de photos et de vidéos auto-hébergée, sous licence AGPL-3.0 — une alternative à Google Photos avec sauvegarde automatique mobile, une chronologie, des albums, le partage, la recherche intelligente basée sur CLIP et la reconnaissance faciale. Toutes les fonctionnalités sont gratuites : la clé de produit optionnelle à 99 $ est un badge de soutien uniquement, sans aucune restriction de fonctionnalités. Ce module déploie Immich sur GKE Autopilot au-dessus de la fondation App_GKE, qui provisionne et gère l'infrastructure partagée Google Cloud et Kubernetes.

Il n'y a délibérément pas de variante Cloud Run de ce module. La bibliothèque multimédia d'Immich est un système de fichiers local — elle n'a pas de backend de stockage S3/GCS — et les téléchargements de photos/vidéos sont régulièrement de plusieurs Go, ce qui ne correspond pas au modèle de requête de Cloud Run.

Ce guide se concentre sur les services cloud qu'Immich utilise et sur la manière de les explorer et de les exploiter depuis la console Google Cloud et la ligne de commande. Pour les mécanismes communs à chaque application GKE — Workload Identity, ingress, autoscaling, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, sauvegardes et le cycle de vie du déploiement — reportez-vous au guide de la fondation App_GKE.


Ce que coûte Immich sur RAD, et comment cela se compare​

Immich sur le module GKE de RAD coûte environ 150 $ US par mois dans votre propre projet, plus des frais de module de 300 crédits (30 $ US) une fois par déploiement — avec toutes les fonctionnalités débloquées, y compris la reconnaissance faciale et la recherche CLIP (la clé de produit Immich optionnelle à 99 $ est un badge de soutien uniquement). Si vous n'en avez besoin qu'occasionnellement, consultez la section "Mettez-le en pause gratuitement" ci-dessous pour arrêter de payer sans perdre votre bibliothèque de photos. Immich n'est livré que sous forme de module GKE sur RAD ; il n'y a pas de variante Cloud Run.

Ce que vous payez sur RAD​

Dans un projet Google Cloud que vous possédezDans un projet géré par RAD pour vous
Frais de module, une fois par déploiement300 crédits (30,00 $ US)270 crédits (10 % de moins)
BuildsInclus dans le prix : pas de frais de build pour la création, 5 mises à jour par mois (mois calendaire UTC) gratuites puis 2 crédits chacune, et rien pour la suppression ou pour un build échoué, dans la limite de 10 builds échoués par jour (UTC). Les sessions de lab et les projets clients sont l'exception : ils sont toujours facturés pour le temps de build à la minuteIdem
Coût d'exécution Google CloudFacturé par Google à votre propre compte de facturation, environ 149,81 $ US par mois pour la configuration par défaut (tableau ci-dessous)Mesuré à l'heure en crédits ; RAD publie 146 crédits par jour, environ 4 380 par mois (environ 438 $ US au prix de la recharge ; estimé à partir des prix catalogue Google, et incluant les frais de cluster)
Qui possède quoiVous possédez le projet et sa facturation ; RAD le déploie et le met à jourRAD possède le projet, avec des garde-fous, des quotas et des alertes budgétaires ; vous avez accès à la console, et un solde minimum acheté est conservé en réserve

10 crédits coûtent 1 $ US pour une recharge ponctuelle, moins sur un plan. Dans un projet géré par RAD, la base de données, le serveur de fichiers et le réseau sont partagés par chaque application du projet, donc une deuxième application n'ajoute pas une deuxième base de données.

Coût d'exécution par défaut dans votre propre projet (us-central1, prix catalogue Google) :

Ressource (par défaut du module)Par mois
Pod GKE Autopilot, 2x vCPU / 4 Gio79,35 $ US
Cloud SQL pour PostgreSQL, 1 vCPU / 3,75 Go, zonal, 10 Go SSD51,02 $ US
Serveur de fichiers NFS/cache (petite VM)13,43 $ US
Cloud NAT et réseau5,00 $ US
Cloud Storage (modules complémentaires, sauvegardes)1,00 $ US
Frais de gestion de cluster GKEpartagés entre chaque application GKE du projet ; 0 $ si c'est votre seul cluster, sinon ~73 $
Totalenviron 149,81 $ US

Comment cela se compare​

  • Immich lui-même ne propose pas de SaaS hébergé officiel — ses mainteneurs sont explicites sur le fait que l'auto-hébergement est le but — donc la comparaison honnête se fait avec les services qu'il remplace. Le stockage payant de Google Photos (Google One) commence à 1,99 $/mois pour 100 Go et 2,99 $/mois pour 200 Go, mais une bibliothèque de photos familiale partagée avec des vidéos dépasse rapidement cela, et vous renoncez au contrôle de l'auto-tagging et à la propriété des originaux en échange.
  • L'empreinte propre d'Immich (2 vCPU, 4 Gio, plus une base de données et une VM NFS) est proche d'un Hetzner CPX22 ou d'un droplet DigitalOcean 2 vCPU/4 Go (environ 24 $/mois) ou d'un GCP Compute Engine e2-standard-2 (environ 49 $/mois) — moins cher en espèces, mais vous devez alors gérer PostgreSQL, le partage NFS, les sauvegardes, les correctifs de sécurité et les mises à niveau du conteneur d'apprentissage automatique vous-même.
  • Ce que RAD ajoute par rapport à un VPS nu : Cloud SQL géré avec des sauvegardes automatisées et une récupération à un point dans le temps, Secret Manager pour les identifiants et la surveillance — les choses qui transforment un projet d'auto-hébergement de week-end en quelque chose que vous pouvez laisser fonctionner sans surveillance.

Mettez-le en pause gratuitement : supprimez un projet géré par RAD, restaurez-le quand vous en avez besoin​

Si Immich fonctionne dans un projet géré par RAD pour vous et que vous prévoyez d'y revenir — une pause entre les cours, un creux saisonnier, ou simplement ne pas savoir si vous en aurez besoin le mois prochain — c'est la meilleure option, et cela ne coûte presque rien.

Une restauration n'est pas garantie — conservez vos propres sauvegardes. Les conditions de Google Cloud ne garantissent pas qu'un projet restauré, ou les ressources qu'il contient, seront utilisables après sa restauration, de sorte que la restauration ne peut pas être invoquée comme un moyen de récupérer un projet supprimé. Avant de supprimer, assurez-vous d'avoir effectué des sauvegardes appropriées des données et de la configuration de l'application et de les avoir stockées en dehors du projet. Si une restauration échoue, ou si le projet restauré ne fonctionne pas, la solution de repli consiste à redéployer l'application (voir la section suivante) et à restaurer sa configuration et ses données à partir de ces sauvegardes.

La suppression d'un projet géré par RAD délie d'abord sa facturation, puis demande à Google de supprimer purement et simplement le projet : la suppression logicielle récupérable de 30 jours de Google. Contrairement à la suppression d'Immich en tant que module unique, cela ne supprime pas le pod GKE, la base de données Cloud SQL, le serveur de fichiers NFS et le réseau un par un — l'ensemble du projet s'arrête simplement, et rien n'est facturé pendant qu'il attend, car la facturation est déjà déliée.

La restauration, dans les 30 jours et uniquement par le propriétaire du projet, demande à Google de restaurer le projet et de rattacher son compte de facturation, puis vous demande d'exécuter une mise à jour sur chaque déploiement pour confirmer que tout est revenu. Comme rien n'a été détruit individuellement, cette mise à jour trouve les mêmes ressources déjà présentes — c'est une vérification, pas une reconstruction, et une mise à jour ne facture jamais les frais de module à nouveau. Les mises à jour sont incluses dans le prix (5 par mois pour chaque déploiement), donc une restauration ne coûte normalement aucun crédit.

Ce qu'il faut : vous devez posséder le projet (pas un projet dont RAD gère uniquement la facturation), vous devez le restaurer vous-même dans les 30 jours — après cela, Google le supprime définitivement — et la restauration est admise comme la création d'un nouveau projet, donc votre solde de crédits achetés doit toujours dépasser le seuil du palier (100 crédits pour le palier sandbox que la plupart utilisent convient). Google affirme que la plupart des services sont de nouveau pleinement fonctionnels dans les 36 heures suivant une restauration.

Un véritable manque : les sauvegardes nocturnes sont écrites dans un bucket à l'intérieur du projet, et ce bucket a la suppression logicielle de Cloud Storage explicitement désactivée, il est donc très probable qu'il disparaisse dès que vous supprimez le projet, même si le projet lui-même est récupérable pendant 30 jours. L'exportation nocturne de la base de données et des métadonnées de la bibliothèque d'Immich est conservée dans ce bucket ; les photos et vidéos originales vivent dans le stockage attaché du pod GKE et le partage NFS, qui ne sont pas détruits individuellement par ce chemin, donc votre bibliothèque elle-même survit les 30 jours intacte — c'est spécifiquement la copie de sauvegarde des métadonnées/base de données qui n'est pas récupérable à partir du bucket d'un projet supprimé.

Payez uniquement pendant que vous l'utilisez, l'autre méthode : supprimer et redéployer​

Dans votre propre projet, ou une fois que la fenêtre de 30 jours ci-dessus est passée, la solution de repli consiste à supprimer Immich purement et simplement et à le redéployer plus tard.

  • Ce que coûte un redéploiement : les frais de module à nouveau (les builds sont inclus) — les frais de module indiqués ci-dessus.
  • Quand cela en vaut la peine : la suppression permet d'économiser de l'argent seulement si Immich resterait inutilisé pendant environ 6 jours ou plus dans votre propre projet (environ 2 jours ou plus dans un projet géré par RAD). La base de données et le serveur de fichiers NFS d'Immich constituent la majeure partie du coût d'exécution ici, donc si rien d'autre dans le projet ne les partage, la suppression d'Immich supprime toute la facture ci-dessus.
  • Conservez d'abord les données. Les sauvegardes nocturnes sont écrites dans un bucket à l'intérieur du déploiement, et ce bucket est supprimé avec lui — copiez la dernière sauvegarde (vers Google Drive, ou un bucket que vous conservez) avant de supprimer si vous voulez la conserver.

Sessions de lab et environnements gérés​

  • Sessions de lab, pour la formation. Un formateur anime une session pour une classe. Chaque participant obtient l'application dans son propre projet Google Cloud pendant 15 minutes à 24 heures, dans la limite d'une allocation définie par le formateur. Le formateur peut aussi créer un seul environnement partagé pour toute la classe, et chacun utilise alors la même application et ses données. Soit le formateur finance toutes les places, soit chaque participant paie la sienne. Tout est supprimé à la fin de la session et les crédits inutilisés sont reversés au formateur.
  • Environnements gérés, pour les sociétés de conseil. Un partenaire exécute l'application pour un client à partir d'un portefeuille cloisonné qu'il finance, et règle directement avec le client. Si le portefeuille est faible, la facturation est suspendue et les données sont conservées, de sorte que personne ne reçoit de frais inattendus. À la fin, le partenaire transfère le projet et les déploiements deviennent la propriété du client.
  • Les crédits peuvent être achetés dans plus de 20 devises, y compris XAF, XOF, NGN, GHS, KES et ZAR, par carte, virement bancaire ou argent mobile.

Sources (8 octobre 2026) : Prix catalogue Google Cloud de l'API Cloud Billing Catalog ; frais RAD et estimation des crédits quotidiens de radmodules.dev/pricing ; Google Cloud : supprimer et restaurer des projets pour le mécanisme de pause/restauration. Les prix changent ; vérifiez chaque source avant de vous fier à un chiffre.


1. Vue d'ensemble​

Immich fonctionne comme deux services : le serveur Immich (API + workers en arrière-plan in-process, image personnalisée) et un conteneur d'apprentissage automatique pré-construit séparé.

CapacitéService Google CloudNotes
Calcul (serveur)GKE AutopilotImage personnalisée sur ghcr.io/immich-app/immich-server, port 2283, 2 vCPU / 4 Gio, exactement un réplica
Calcul (ML)GKE Autopilotghcr.io/immich-app/immich-machine-learning pré-construit, port 3003, interne uniquement, inférence CPU (pas de GPU), 2 vCPU / 4 Gio
Base de donnéesCloud SQL pour PostgreSQL 15Requis — avec l'extension pgvector (DB_VECTOR_EXTENSION=pgvector ; Cloud SQL n'a pas de VectorChord)
Bibliothèque multimédiaNFS (volume de plateforme partagé)Monté à /usr/src/app/upload (IMMICH_MEDIA_LOCATION) — Immich n'a pas de backend de stockage d'objets
Cache et file d'attenteRedisRequis — file d'attente de jobs et pub/sub d'Immich ; le Redis co-hébergé par le serveur NFS est injecté par défaut
Build d'imageCloud Build + Artifact RegistryBuild personnalisé léger ajoutant le point d'entrée cloud
IngressCloud Load BalancingLoadBalancer externe, domaine personnalisé optionnel + certificat géré

Valeurs par défaut judicieuses à connaître d'emblée :

  • enable_nfs = true est validé, pas seulement par défaut. Toute la bibliothèque de photos/vidéos se trouve à IMMICH_MEDIA_LOCATION ; sans NFS, ce chemin est le disque éphémère du pod et chaque redémarrage efface la bibliothèque. Le plan échoue si vous le désactivez.
  • enable_redis = true est validé. Immich refuse de démarrer sans Redis. Sans redis_host explicite, la plateforme injecte l'IP Redis co-hébergée par le serveur NFS.
  • max_instance_count = 1 est validé. Une bibliothèque multimédia NFS, un seul rédacteur ; les workers de job in-process d'Immich supposent une instance unique.
  • Le déploiement utilise la stratégie Recreate, pas RollingUpdate — App_GKE bascule automatiquement pour les applications basées sur NFS, de sorte que les mises à jour de version entraînent une courte interruption au lieu de bloquer deux pods sur la même bibliothèque.
  • application_version = "latest" se résout en tag release roulant d'Immich. Immich publie les tags release et vX.Y.Z mais pas latest ; la couche partagée mappe latest → release via l'ARG de build IMMICH_VERSION spécifique à l'application, et l'image d'apprentissage automatique utilise le même tag résolu (verrouillé).
  • pgvector est le backend vectoriel. Cloud SQL n'a pas de VectorChord (l'extension préférée d'Immich) ; Immich fonctionne sur son fallback pgvector documenté. Le job db-init pré-crée les extensions vector et earthdistance.
  • Les sondes atteignent GET /api/server/ping — le point de terminaison de vivacité non authentifié d'Immich ({"res":"pong"}).
  • Pas de secrets au niveau de l'application. Les clés de signature JWT d'Immich vivent dans la base de données ; DB_PASSWORD est injecté par la fondation sous le nom exact qu'Immich lit.
  • La première exécution est interactive. Visitez l'interface utilisateur web et créez le compte administrateur sur l'écran d'inscription ; les applications mobiles Immich (iOS/Android) se connectent ensuite à la même URL de serveur.

2. Services Google Cloud et comment les explorer​

Toutes les commandes supposent que vous avez exécuté gcloud container clusters get-credentials <cluster> --region <region> --project <project> et que PROJECT, REGION et NAMESPACE sont définis. L'espace de noms et les autres identifiants sont rapportés dans les Sorties du déploiement.

A. GKE Autopilot — le serveur Immich et les charges de travail ML​

Le déploiement du serveur exécute un seul réplica ; le service d'apprentissage automatique s'exécute comme un second déploiement dans le même espace de noms, accessible uniquement à l'intérieur du cluster.

  • Console : Kubernetes Engine → Charges de travail → filtrez par l'espace de noms pour voir les deux déploiements, pods et événements. Kubernetes Engine → Services et Ingress affiche l'IP externe.
  • CLI :
    kubectl get pods -A | grep immich                       # find the namespace fast
    kubectl get pods,svc,deploy -n "$NAMESPACE"
    kubectl logs -n "$NAMESPACE" deploy/"$(kubectl get deploy -n "$NAMESPACE" -o name | grep -v ml | head -1 | cut -d/ -f2)" --tail=100
    # The cloud entrypoint logs the resolved DB/Redis/media config on the first lines:
    kubectl logs -n "$NAMESPACE" <server-pod> | head -15
    # Confirm the ML URL wiring:
    kubectl exec -n "$NAMESPACE" deploy/<server-deploy> -- env | grep IMMICH_MACHINE_LEARNING_URL

B. Cloud SQL pour PostgreSQL 15 + pgvector​

Immich stocke toutes les métadonnées (utilisateurs, albums, assets, EXIF, embeddings de recherche intelligente, données de reconnaissance faciale) dans Cloud SQL PostgreSQL 15, accessible via le sidecar Cloud SQL Auth Proxy. Le job db-init du premier déploiement crée la base de données et l'utilisateur et pré-crée les extensions pgvector et earthdistance ; Immich fonctionne avec DB_VECTOR_EXTENSION = pgvector car Cloud SQL ne propose pas VectorChord.

  • Console : SQL → sélectionnez l'instance.
  • CLI :
    gcloud sql instances list --project "$PROJECT"
    gcloud sql connect <instance-name> --user=<db-user> --database=<db-name> --project "$PROJECT"
    # Inside psql — confirm the vector extension:
    # SELECT extname, extversion FROM pg_extension WHERE extname IN ('vector','earthdistance');

Le nom de l'instance, le nom de la base de données, l'utilisateur et le secret du mot de passe se trouvent dans les Sorties.

C. NFS — la bibliothèque multimédia​

Le volume NFS de la plateforme partagée est monté à /usr/src/app/upload (IMMICH_MEDIA_LOCATION). Chaque original, vignette et vidéo encodée y réside ; le pod lui-même est jetable.

  • CLI :
    # The NFS server is a Compute Engine VM managed by Services_GCP:
    gcloud compute instances list --project "$PROJECT" --filter="name~nfs"
    # Verify the mount and library content from inside the pod:
    kubectl exec -n "$NAMESPACE" deploy/<server-deploy> -- df -h /usr/src/app/upload
    kubectl exec -n "$NAMESPACE" deploy/<server-deploy> -- ls /usr/src/app/upload

D. Redis (file d'attente de jobs et pub/sub)​

Immich met en file d'attente chaque job en arrière-plan (génération de vignettes, extraction de métadonnées, embedding de recherche intelligente, détection de visages) via Redis. Par défaut, la VM du serveur NFS co-héberge Redis et la plateforme injecte son IP en tant que REDIS_HOST ; le point d'entrée cloud la mappe à REDIS_HOSTNAME d'Immich et échoue rapidement si elle se résout vide.

  • CLI :
    kubectl exec -n "$NAMESPACE" deploy/<server-deploy> -- env | grep -E 'REDIS_HOST'

E. Apprentissage automatique — recherche intelligente CLIP et reconnaissance faciale​

Le conteneur ghcr.io/immich-app/immich-machine-learning pré-construit sert les embeddings CLIP, la reconnaissance faciale et l'OCR via HTTP sur le port 3003 (interne uniquement). Il s'agit d'une inférence CPU — pas de GPU. Son environnement définit IMMICH_PORT = "3003" explicitement : la fondation propage l'environnement du serveur dans des services supplémentaires et l'image ML lit la même variable IMMICH_PORT — sans la surcharge, elle hérite de 2283, lie le mauvais port, et sa sonde de démarrage :3003 ne passe jamais. Le serveur la trouve via le IMMICH_MACHINE_LEARNING_URL injecté, défini via module_env_vars sur le vrai nom DNS du service Kubernetes (http://<service>-ml:3003 — le service est nommé <service>-ml) ; le mécanisme output_env_var_name de la fondation compose une URL de nom nu non résolvable (http://ml:3003), de sorte que sa sortie est placée dans la variable d'environnement inutilisée IMMICH_ML_URL_FOUNDATION_UNUSED. Les fichiers de modèle se téléchargent paresseusement lors de la première utilisation dans /cache sur le disque éphémère du pod (re-téléchargés après la replanification — accepté).

  • CLI :
    kubectl get pods -n "$NAMESPACE" | grep ml
    kubectl logs -n "$NAMESPACE" deploy/<ml-deploy> --tail=50 # model downloads + inference requests

F. Cloud Build et Artifact Registry​

L'image du serveur est une build personnalisée légère (FROM ghcr.io/immich-app/immich-server plus le point d'entrée cloud) produite par Cloud Build et stockée dans Artifact Registry. L'ARG de build IMMICH_VERSION contient le tag résolu — spécifique à l'application à dessein, car la fondation injecte APP_VERSION et gagne la fusion, et Immich n'a pas de tag latest.

  • CLI :
    gcloud builds list --project "$PROJECT" --limit 5
    gcloud artifacts docker images list <region>-docker.pkg.dev/"$PROJECT"/<repo> 2>/dev/null | grep immich

G. Réseau, journalisation et surveillance​

L'accès externe se fait via une IP Cloud Load Balancing (service_type = LoadBalancer) ; un domaine personnalisé avec un certificat géré et une IP statique réservée sont activés par défaut (enable_custom_domain = true, reserve_static_ip = true).

  • CLI :
    kubectl get svc -n "$NAMESPACE"
    gcloud compute addresses list --project "$PROJECT"
    gcloud logging read 'resource.type="k8s_container" AND resource.labels.namespace_name="'"$NAMESPACE"'"' \
    --project "$PROJECT" --limit 50

3. Comportement de l'application Immich​

  • Le point d'entrée cloud mappe les noms d'environnement à l'exécution. Le cloud-entrypoint.sh de l'image personnalisée mappe les DB_HOST/DB_IP injectés par la fondation → DB_HOSTNAME (réécrivant un chemin de répertoire de socket Auth Proxy en TCP 127.0.0.1), DB_USER → DB_USERNAME, DB_NAME → DB_DATABASE_NAME, et REDIS_HOST → REDIS_HOSTNAME/REDIS_PORT — la fondation peut injecter REDIS_HOST comme host ou host:port, donc le point d'entrée le divise en un nom d'hôte nu plus un port (par défaut 6379 quand aucun n'est présent). Les références $(VAR) de Kubernetes ne pourraient pas faire cela : K8s résout $(VAR) uniquement par rapport aux entrées d'environnement définies plus tôt dans la liste rendue alphabétiquement, et DB_DATABASE_NAME trie avant DB_NAME, donc $(DB_NAME) resterait une chaîne littérale. DB_PASSWORD n'a pas besoin de mappage. Le point d'entrée résout également le script de démarrage amont à travers les dispositions d'image — Immich v3 a déplacé l'application vers /usr/src/app/server (script de démarrage à server/bin/start.sh) tandis que les images plus anciennes conservent /usr/src/app/start.sh ; les deux sont sondés et le répertoire de travail ajusté avant exec. Le point d'entrée imprime la configuration résolue en haut du journal du pod — toujours le premier endroit où regarder.
  • Configuration de la base de données au premier déploiement. Le job db-init (postgres:15-alpine) exécute db-init.sh de manière idempotente : utilisateur, base de données, privilèges, extensions pgvector + earthdistance, et un privilège cloudsqlsuperuser afin que les migrations amont puissent gérer les extensions elles-mêmes. Immich applique ses propres migrations de schéma à chaque démarrage.
  • Déploiements en mode "Recreate" avec un seul rédacteur. Étant donné que la bibliothèque multimédia est un seul système de fichiers NFS et que les workers de job s'exécutent en interne, un seul réplica est autorisé (validé au moment du plan), et les mises à jour de version remplacent le pod par Recreate (brève interruption) plutôt que par une montée en puissance progressive.
  • La recherche intelligente et la reconnaissance faciale sont asynchrones. Après un téléchargement, le serveur met en file d'attente des jobs qui appellent le service ML ; la première requête de recherche intelligente déclenche également le téléchargement du modèle CLIP, elle est donc sensiblement lente une fois par durée de vie du pod ML. La progression des jobs est visible dans l'interface utilisateur web sous Administration → Jobs.
  • Administrateur à la première exécution. Lors de la première visite, l'interface utilisateur web affiche l'écran d'inscription ; le premier compte enregistré devient l'administrateur. Les applications iOS/Android d'Immich se connectent à la même URL de serveur pour la sauvegarde automatique mobile.
  • La télémétrie est désactivée (IMMICH_TELEMETRY_INCLUDE = "") et IMMICH_ENV = production ; l'API et les workers en arrière-plan s'exécutent dans un seul conteneur (l'amont a fusionné le conteneur de microservices en v1.106).

4. Variables de configuration​

Les variables sont regroupées exactement comme elles apparaissent sur la plateforme de déploiement. Seuls les paramètres spécifiques ou notables pour Immich sont listés ; toutes les autres entrées sont héritées de App_GKE avec son comportement et ses valeurs par défaut standard.

Groupe 1 — Projet et identité​

VariableValeur par défautDescription
project_id(requis)Projet Google Cloud cible.
regionus-central1Région de secours lorsque la découverte réseau ne peut pas la déterminer.

Groupe 2 — Environnement de déploiement​

VariableValeur par défautDescription
tenant_iddemoSuffixe court qui rend les noms de ressources uniques par environnement.
support_users[]E-mails auxquels sont accordés l'accès au projet et les alertes de surveillance.
resource_labels{}Étiquettes appliquées à toutes les ressources.

Groupe 3 — Identité de l'application​

VariableValeur par défautDescription
application_nameimmichNom de base des ressources. Ne pas modifier après le premier déploiement.
application_versionlatestTag d'image du serveur + ML, maintenu synchronisé. latest se résout en tag release roulant d'Immich (aucun tag latest n'existe en amont) ; épinglez vX.Y.Z en production.

Groupe 4 — Exécution et mise à l'échelle​

VariableValeur par défautDescription
deploy_applicationtrueDéfinissez false pour provisionner uniquement l'infrastructure.
cpu_limit / memory_limit2000m / 4GiRessources du conteneur du serveur.
container_port2283Port natif d'Immich (IMMICH_PORT).
min_instance_count1Maintenez à 1 pour qu'Immich soit toujours disponible.
max_instance_count1Doit être 1 — validé au moment du plan (rédacteur NFS unique, workers in-process).
ml_cpu_limit / ml_memory_limit2000m / 4GiRessources du conteneur d'apprentissage automatique. Les modèles CLIP + visage nécessitent ~2–3 Gio résidents ; 4 Gio est la valeur par défaut sûre.
enable_cloudsql_volumetrueSidecar Cloud SQL Auth Proxy.
enable_image_mirroringtrueMettre en miroir les images dans Artifact Registry.

Groupe 5 — Variables d'environnement et secrets​

VariableValeur par défautDescription
environment_variables{}Paramètres supplémentaires fusionnés sur les valeurs par défaut d'Immich (IMMICH_PORT, IMMICH_MEDIA_LOCATION, DB_VECTOR_EXTENSION, IMMICH_ENV, télémétrie). Ne définissez pas DB_*/REDIS_* ici — le point d'entrée gère le mappage.
secret_environment_variables{}Mappage de la variable d'environnement → nom du secret Secret Manager.

Groupe 6 — Backend GKE et cluster​

VariableValeur par défautDescription
service_typeLoadBalancerIP externe pour l'interface utilisateur web et les applications mobiles.
session_affinityClientIPRoutage persistant (réplica unique, donc la plupart du temps sans objet).
network_tags["nfsserver"]Requis pour la connectivité NFS.
termination_grace_period_seconds60Délai de grâce avant l'arrêt forcé.
deployment_timeout1800Secondes pendant lesquelles Terraform attend le déploiement.

Groupe 10 — Observabilité et santé​

VariableValeur par défautDescription
startup_probeHTTP /api/server/ping, délai de 30s, 30×10sSonde de démarrage de l'application (Groupe 14 sur la plateforme).
liveness_probeHTTP /api/server/ping, délai de 30sSonde de vivacité de l'application.
uptime_check_configdésactivé, chemin /api/server/pingTest de disponibilité Cloud Monitoring optionnel.

Groupe 11 — Jobs et services additionnels​

VariableValeur par défautDescription
initialization_jobs[]Laissez vide pour le job db-init intégré. Immich migre son propre schéma au démarrage.
additional_services[]Ajouté après le service d'apprentissage automatique intégré.

Groupe 13 — Système de fichiers (NFS)​

VariableValeur par défautDescription
enable_nfstrueDoit rester vrai — validé au moment du plan. Toute la bibliothèque multimédia réside sur NFS ; Immich n'a pas de backend S3/GCS.
nfs_mount_path/usr/src/app/uploadMonté exactement à IMMICH_MEDIA_LOCATION.

Groupe 16 — Backend de base de données​

VariableValeur par défautDescription
db_nameimmich_dbNom de la base de données PostgreSQL. Immuable après le premier déploiement.
db_userimmich_userUtilisateur de la base de données de l'application. Immuable après le premier déploiement.
database_password_length32Longueur du mot de passe généré (16–64).

Groupe 17 — Sauvegarde et maintenance​

VariableValeur par défautDescription
backup_schedule0 2 * * *Cron de sauvegarde automatique de la base de données et de NFS (UTC).
backup_retention_days7Augmenter pour la production — la bibliothèque NFS est la seule copie de vos photos.

Groupe 19 — Domaine personnalisé, IP statique et réseau​

VariableValeur par défautDescription
enable_custom_domaintrueAPI Gateway + certificat géré.
application_domains[]Noms d'hôtes à servir.
reserve_static_iptrueIP externe stable entre les redéploiements.

Groupe 20 — Proxy conscient de l'identité (IAP)​

Avertissement : les applications mobiles Immich s'authentifient auprès du serveur Immich, et non de Google — IAP devant l'API interrompt la sauvegarde automatique mobile à moins que chaque appareil ne puisse effectuer le flux de connexion Google.

VariableValeur par défautDescription
enable_iapfalseNécessite un domaine personnalisé et les deux identifiants OAuth (validés).

Groupe 21 — Redis et Cloud Armor​

VariableValeur par défautDescription
enable_redistrueDoit rester vrai — validé au moment du plan ; Immich refuse de démarrer sans Redis.
redis_host""Vide = l'IP Redis co-hébergée par le serveur NFS est injectée.
enable_cloud_armorfalseAttacher une politique WAF au backend Ingress.

Groupe 22 — VPC Service Controls et journalisation d'audit​

Entrées App_GKE standard : enable_vpc_sc, vpc_cidr_ranges, vpc_sc_dry_run, organization_id, enable_audit_logging. Voir App_GKE.


5. Sorties​

SortieDescription
service_nameNom du service Kubernetes.
namespaceEspace de noms dans lequel les charges de travail s'exécutent.
service_cluster_ip / stage_service_cluster_ipsClusterIPs intra-cluster.
service_external_ipIP externe du LoadBalancer (lorsqu'une IP statique est réservée).
web_urlURL de l'interface utilisateur web d'Immich — IP externe du LoadBalancer si disponible, sinon URL interne du cluster.
database_instance_name / database_name / database_userIdentifiants Cloud SQL.
database_password_secretSecret Secret Manager contenant le mot de passe de la base de données.
database_host / database_portPoint de terminaison de la base de données (127.0.0.1 via le proxy d'authentification) / port.
storage_bucketsBuckets Cloud Storage créés.
network_name / network_exists / regionsDétails du réseau VPC.
container_image / container_registryImage déployée et dépôt Artifact Registry.
monitoring_enabled / monitoring_notification_channelsÉtat et canaux de surveillance.
initialization_jobs / db_import_jobNoms des jobs de configuration et d'importation (optionnel).
deployment_id / tenant_id / resource_prefixIdentifiants de nommage.
project_id / project_numberIdentifiants de projet.
cicd_enabled / cicd_configuration et sorties GitHub/triggerÉtat et détails CI/CD.
kubernetes_readyIndique si toutes les ressources Kubernetes ont été déployées (faux lors du premier apply d'un nouveau cluster inline).
vpc_sc_enabled / vpc_sc_perimeter_name / vpc_sc_dry_run_modeÉtat VPC-SC.
audit_logging_enabled / artifact_registry_cmek_enabledJournalisation d'audit et état CMEK.

6. Pièges de configuration et valeurs par défaut judicieuses​

Risque : Critique (perte de données / panne / sécurité) — Élevé (service dégradé) — Moyen (coût ou dégradation partielle) — Faible (mineur).

Validation au moment du plan. Immich_GKE comporte ses propres gardes de validation en plus des vérifications de la fondation App_GKE : enable_nfs = false, enable_redis = false, max_instance_count > 1, Redis sans source d'hôte, et IAP sans identifiants OAuth échouent tous le plan avec une erreur nommée avant qu'aucune ressource ne soit créée.

ParamètreValeur judicieuseRisqueConséquence si incorrect
enable_nfstrue (validé)CritiqueAvec NFS désactivé, toute la bibliothèque multimédia se trouve sur le disque éphémère du pod — chaque replanification de pod efface toutes les photos et vidéos. Immich n'a pas de backend S3/GCS pour se rabattre. Bloqué au moment du plan.
max_instance_count1 (validé)CritiquePlus d'un réplica signifie plusieurs rédacteurs sur une seule bibliothèque NFS et des workers de job in-process dupliqués — corruption de la bibliothèque et jobs en concurrence. Bloqué au moment du plan.
db_name / db_userDéfinir une foisCritiqueImmuable après le premier déploiement ; le renommage recrée la base de données/l'utilisateur et orpheline toutes les métadonnées d'actifs, les albums et les utilisateurs.
backup_retention_daysAugmenter pour la productionÉlevéLa bibliothèque NFS est la seule copie des médias ; 7 jours de sauvegardes sont minces pour une archive photo.
enable_redis / redis_hosttrue / "" (validé)ÉlevéSans Redis, le serveur se termine au démarrage (le point d'entrée échoue rapidement avec une erreur claire). Avec Redis activé mais sans NFS et sans hôte explicite, REDIS_HOST est vide — également bloqué au moment du plan.
Surcharge ML IMMICH_PORTConserver le IMMICH_PORT = "3003" intégré sur le service MLÉlevéLa fondation propage l'environnement du serveur dans des services supplémentaires, et l'image ML lit la même variable IMMICH_PORT que le serveur — sans la surcharge, le conteneur ML hérite de 2283, lie le mauvais port, et sa sonde de démarrage :3003 ne passe jamais (le déploiement ML ne devient jamais Prêt).
IMMICH_MACHINE_LEARNING_URLLaisser l'URL DNS réelle injectée telle quelleÉlevéLe mécanisme output_env_var_name de la fondation compose l'URL à partir du nom nu du service additionnel (http://ml:3003), mais le service qu'il crée est nommé <service>-ml — le nom nu ne se résout pas et la recherche intelligente/reconnaissance faciale échouent. Le module injecte l'URL DNS réelle du service via module_env_vars et place la valeur composée par la fondation dans la variable inutilisée IMMICH_ML_URL_FOUNDATION_UNUSED.
ml_memory_limit4Gi (par défaut ; à considérer comme le minimum)MoyenEn dessous des ~2–3 Gio dont les modèles CLIP + visage ont besoin en mémoire, le chargement du modèle provoque des OOM-kills du pod ML — la recherche intelligente et la reconnaissance faciale échouent silencieusement tandis que l'application principale semble parfaitement saine (les téléchargements et la navigation fonctionnent toujours). Surveillez les redémarrages OOMKilled sur le pod ML.
enable_iapfalse sauf si l'accès mobile est géréMoyenIAP intercepte l'API que les applications mobiles appellent ; la sauvegarde automatique est interrompue pour les appareils qui ne peuvent pas effectuer la connexion Google.
application_versionlatest (→ release) ou un vX.Y.Z épingléMoyenDéfinir un tag qui n'existe pas en amont fait échouer le build/pull ; les tags du serveur et du ML sont maintenus synchronisés automatiquement — ne les pointez pas manuellement vers des versions différentes.
Mises à jour de versionAttendez-vous à une brève interruptionFaibleLes applications basées sur NFS se déploient avec la stratégie Recreate — l'ancien pod s'arrête avant que le nouveau ne démarre. C'est intentionnel (les mises à jour progressives se bloquent sur la bibliothèque partagée).
pgvector vs VectorChordAccepter pgvector sur Cloud SQLFaibleLes builds et les requêtes d'index de recherche intelligente sont plus lents que le VectorChord préféré d'Immich — attendu sur Cloud SQL, qui ne propose pas VectorChord. Fonctionnellement complet, juste plus lent sur les grandes bibliothèques.
Latence de la première requête MLAttendez-vous à une première recherche lenteFaibleLes modèles CLIP/visage se téléchargent à la première utilisation (cache sur disque éphémère, re-téléchargés après la replanification du pod ML) — la première requête de recherche intelligente après un déploiement est lente.
Chemin de la sonde de démarrage/api/server/pingFaibleTout point de terminaison authentifié renvoie 401/403 à la sonde kubelet non authentifiée et bloque le déploiement ; conservez la valeur par défaut.

Pour le comportement de la fondation référencé tout au long — IAM et Workload Identity, autoscaling, ingress et certificats, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC-SC, sauvegardes et mise en miroir d'images — voir App_GKE. La couche d'application partagée spécifique à Immich (image, point d'entrée, amorçage de la base de données, sondes) est décrite dans Immich_Common.

Need RAD to do something it does not do yet? Request it on the roadmap, or vote on what is already there.