Aller au contenu principal

Homebox sur GKE Autopilot

Homebox sur GKE Autopilot

Homebox est un système open-source d'inventaire et d'organisation domestique auto-hébergé, doté d'un backend API Go REST (style Echo, ORM Ent) et d'un frontend Vue 3/Nuxt intégré au même binaire — suivez les articles, joignez des photos et organisez-les par emplacement. Ce module déploie Homebox sur GKE Autopilot sur la base de la fondation App_GKE, qui provisionne et gère l'infrastructure partagée Google Cloud et Kubernetes.

Ce guide se concentre sur les services cloud utilisés par Homebox 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 à toutes les applications GKE — Workload Identity, ingress, autoscaling, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, sauvegardes et cycle de vie du déploiement — reportez-vous au guide de la fondation App_GKE plutôt que de les répéter ici.


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

L'exécution d'un pod Homebox sur GKE Autopilot dans votre propre projet Google Cloud coûte environ 91,31 $/mois en frais Google Cloud, en plus d'un forfait unique de 40 crédits pour le module RAD facturé une seule fois au moment du déploiement. Homebox est une petite application d'inventaire domestique avec une modeste base de données Postgres derrière elle — il n'y a pas de SaaS commercial hébergé pour ce projet open-source exact à nommer. Dans un projet géré par RAD, les frais de module tombent à 36 crédits (10 % de moins) et le coût d'exécution est mesuré à l'heure en crédits au lieu d'être facturé directement par Google — voir Mettez-le en pause gratuitement ci-dessous pour le seul avantage géré par RAD qu'un VPS auto-hébergé ne peut égaler — ou voir le guide Cloud Run pour l'option à moindre coût.

Ce que vous payez sur RAD​

Votre propre projetProjet géré par RAD
Frais de module (unique)40 crédits36 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 à la minute pour le temps de buildIdentique
Coût d'exécution Google Cloud91,31 $/mois, facturé par Google au prix catalogue~115 crédits/jour, mesuré au prix catalogue plus la marge de RAD

Votre premier déploiement réussi sur RAD est exempt de frais de module, quel que soit le montant : une fois par compte, pour un module que vous déployez et payez vous-même (dans une solution, les frais d'une application : la première à réussir ; jamais une session de lab ou un projet client).

Coût d'exécution par défaut dans votre propre projet

RessourceUS$/mois (prix catalogue Google, us-central1)
Pod GKE Autopilot, 1x vCPU / 0,5 GiB34,29 $
Cloud SQL pour PostgreSQL, 1 vCPU / 3,75 Go, zonal, 10 Go SSD51,02 $
Cloud NAT et réseau5,00 $
Cloud Storage (modules complémentaires, sauvegardes)1,00 $
Frais de gestion de cluster GKEpartagés entre toutes les applications GKE du projet ; 0 $ si c'est votre seul cluster, sinon ~73 $
Total91,31 $

Les frais de gestion de cluster GKE sont exclus du total ci-dessus car ils sont partagés entre toutes les applications GKE du projet — 0 $ si c'est le seul, sinon environ 73 $/mois répartis entre le nombre d'applications que vous exécutez.

Comment cela se compare​

  • Une comparaison autogérée : Hetzner CPX22 (2 vCPU/4 Go) coûte environ 24 $/mois, un Droplet DigitalOcean 2 vCPU/4 Go coûte le même prix de 24 $/mois, et un GCP Compute Engine e2-standard-2 (2 vCPU/8 Go) coûte environ 49 $/mois — plus que ce dont cette application 1 vCPU/0,5 GiB a besoin seule, mais le point de référence le plus petit et le plus souvent cité ; une classe de vCPU partagée moins chère l'exécuterait également confortablement.
  • La majeure partie du coût d'exécution ci-dessus est l'instance Postgres dédiée, qu'une boîte autogérée devrait également exécuter (et sauvegarder) elle-même.
  • Le compromis habituel s'applique : moins cher en termes d'argent sur un VPS, sauvegardes et correctifs gérés sur RAD.

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

C'est l'avantage principal d'un projet géré par RAD, et il ne coûte rien pendant la pause. La suppression d'un projet géré par RAD délie d'abord sa facturation, puis demande à Google de supprimer complètement le projet — la suppression logicielle récupérable de 30 jours de Google. Contrairement à la suppression d'un module, cela ne démolit pas Cloud SQL, aucune VM, ou la ressource de calcul une par une : 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.

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 considéré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 restauration, dans les 30 jours et uniquement par le propriétaire du projet, demande à Google de récupérer 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 pour cela : vous devez être propriétaire du 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, de sorte que votre solde de crédits achetés doit toujours dépasser le seuil du palier (100 crédits pour le palier sandbox qui convient à la plupart des utilisations d'étude/démo). Google indique que la plupart des services sont à 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. Si vous avez personnalisé Homebox et que vous souhaitez conserver ce travail, copiez une sauvegarde (vers Google Drive, ou un bucket en dehors du projet) avant de supprimer. Pour une installation par défaut sans rien d'irremplaçable, cela n'a pas d'importance.

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

Dans votre propre projet, ou une fois que 30 jours se sont écoulés sur un projet géré par RAD, il n'y a pas de pause gratuite — la suppression supprime définitivement les ressources, et la remise en service de Homebox signifie un redéploiement à partir de zéro. Cela coûte 40 crédits (les frais de module ; les builds sont inclus).

La suppression ne permet d'économiser de l'argent que si Homebox restait inutilisé assez longtemps pour compenser ce coût de redéploiement par rapport à son propre coût d'exécution — pour Homebox, c'est environ 2 jours ou plus. La majeure partie de ce coût d'exécution est généralement la base de données (et, lorsque ce module en utilise un, la VM de serveur de fichiers partagé ou le cluster GKE) — ceux-ci ne s'arrêtent que lorsque rien d'autre dans le projet ne les utilise, donc la suppression de cette application alors que quelque chose d'autre partage le projet n'économise que sa propre part de calcul.

Conservez d'abord les données : les sauvegardes nocturnes vont dans un bucket à l'intérieur du déploiement et sont supprimées avec lui, alors copiez la dernière sauvegarde avant de la 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, afin que personne ne reçoive 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 de l'API Google Cloud Billing Catalog ; radmodules.dev/pricing pour les propres frais de RAD et les estimations de crédits quotidiens ; documentation de Google sur la suppression/restauration de projets pour les affirmations de pause/restauration.

1. Vue d'ensemble​

Homebox s'exécute comme un seul binaire Go (API + frontend intégré) — un pod, pas de sidecars au-delà du proxy d'authentification Cloud SQL. Le déploiement relie un petit ensemble ciblé de services Google Cloud :

CapacitéService Google CloudNotes
CalculGKE AutopilotPod Go/Echo, 1 vCPU / 512 Mio par défaut
Base de donnéesCloud SQL pour PostgreSQL 15Homebox lit des variables d'environnement discrètes HBOX_DATABASE_*, pas un DSN construit
Stockage d'objetsCloud StorageUn bucket data est créé pour les photos/pièces jointes des articles et monté automatiquement à /data
Cache et file d'attenteaucunHomebox n'a pas de dépendance Redis ou de file d'attente
SecretsSecret ManagerMot de passe de la base de données plus HBOX_AUTH_API_KEY_PEPPER (un vrai secret consommé par l'application)
IngressCloud Load BalancingÉquilibreur de charge externe, domaine personnalisé facultatif + certificat géré

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

  • PostgreSQL est le moteur standardisé. Homebox_Common corrige database_type = "POSTGRES_15" et définit HBOX_DATABASE_DRIVER=postgres explicitement.
  • Pas de build de conteneur personnalisé. L'image pré-construite officielle (ghcr.io/sysadminsmedia/homebox) est utilisée directement.
  • Auto-inscription ouverte, pas de compte administrateur par défaut. Homebox ne fournit pas de credential codé en dur : la première personne à soumettre le formulaire "Register" sur une instance fraîche devient l'utilisateur administrateur initial. Voir le guide commun pour plus de détails. Les opérateurs doivent définir HBOX_OPTIONS_ALLOW_REGISTRATION=false après avoir terminé l'inscription.
  • workload_type = "Deployment", pas StatefulSet. Homebox ne conserve aucun état local au-delà de ce qui est déjà dans Cloud SQL — pas de PVC, pas de montage NFS requis.
  • Les photos d'articles sont persistantes par défaut. Homebox_Common déclare une entrée gcs_volumes montant le bucket GCS data à /data, de sorte que les photos et pièces jointes d'articles téléchargées survivent à un redémarrage du pod. Si vous activez le bloc PVC à la place (stateful_pvc_enabled = true, monté à /data), le montage GCS FUSE est automatiquement supprimé afin que les deux n'entrent jamais en collision.

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.

A. GKE Autopilot — la charge de travail Homebox​

  • CLI :
    kubectl get pods,svc -n "$NAMESPACE"
    kubectl logs -n "$NAMESPACE" deploy/<service-name> --tail=100

B. Cloud SQL pour PostgreSQL 15​

Les pods atteignent la base de données en privé via le sidecar cloud-sql-proxy sur 127.0.0.1.

  • CLI :
    gcloud sql instances list --project "$PROJECT"
    gcloud sql connect <instance-name> --user=<db-user> --database=<db-name> --project "$PROJECT"

C. Cloud Storage​

  • CLI :
    gcloud storage buckets list --project "$PROJECT" --filter="name~homebox"

D. Secret Manager​

  • CLI :
    gcloud secrets list --project "$PROJECT" --filter="name~homebox"
    gcloud secrets versions access latest --secret=<secret-name> --project "$PROJECT"

E. Réseau et ingress​

  • CLI :
    kubectl get svc -n "$NAMESPACE" -o wide

F. Cloud Logging et Monitoring​

  • CLI :
    kubectl logs -n "$NAMESPACE" deploy/<service-name> --tail=100 -f

3. Comportement de l'application Homebox​

  • Configuration de la base de données au premier déploiement. Un job d'initialisation exécute create-db-and-user.sh, créant de manière idempotente le rôle d'application et la base de données.
  • Migrations de schéma au démarrage. L'ORM Ent de Homebox applique ses propres migrations internes automatiquement à chaque démarrage de pod.
  • Auto-inscription ouverte — pas de credential admin par défaut. Le premier visiteur à compléter le formulaire "Register" devient l'administrateur. Il n'y a pas de credential à récupérer, réinitialiser ou faire pivoter — définissez HBOX_OPTIONS_ALLOW_REGISTRATION=false une fois que le compte admin existe pour fermer les inscriptions publiques.
  • Chemin de santé. Les sondes de démarrage et de vivacité ciblent /api/v1/status — le véritable endpoint de statut non authentifié de Homebox.
  • Inspecter l'exécution du job :
    kubectl get jobs -n "$NAMESPACE"
    kubectl logs -n "$NAMESPACE" job/<job-name>

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 Homebox sont listés ; toutes les autres entrées sont héritées de App_GKE avec leur comportement standard.

Groupe 3 — Identité de l'application​

VariableValeur par défautDescription
application_namehomeboxNom de base des ressources.
application_versionlatestHomebox publie une véritable balise latest.

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

VariableValeur par défautDescription
container_image_sourceprebuiltPas de build personnalisé nécessaire.
container_port7745Port natif par défaut de Homebox.
min_instance_count / max_instance_count0 / 1Limites de mise à l'échelle HPA.

Groupe 11 — Stockage et système de fichiers​

VariableValeur par défautDescription
storage_bucketsun bucket dataCréé et monté automatiquement à /data.
stateful_pvc_enablednull (auto, désactivé)Facultatif. La définition de true monte un PVC de bloc à /data et supprime le montage GCS FUSE à cet endroit ; le montage de bucket par défaut persiste déjà les photos.

Groupe 12 (16) — Backend de base de données​

VariableValeur par défautDescription
database_typePOSTGRES_15Fixé par Homebox_Common.
db_host_env_var_nameHBOX_DATABASE_HOSTAliasse la plateforme DB_HOST sur le nom attendu de Homebox.
db_user_env_var_nameHBOX_DATABASE_USERNAMEAliasse DB_USER.
db_password_env_var_nameHBOX_DATABASE_PASSWORDAliasse DB_PASSWORD.
db_name_env_var_nameHBOX_DATABASE_DATABASEAliasse DB_NAME.
db_port_env_var_nameHBOX_DATABASE_PORTAliasse DB_PORT.

Groupe 14 — Observabilité et santé​

VariableValeur par défautDescription
startup_probe_config / health_check_configHTTP /api/v1/statusLes sondes ciblent le véritable endpoint de statut de Homebox.

5. Sorties​

SortieDescription
service_name / service_url / service_external_ipIdentité et adresse du service Kubernetes.
database_instance_name / database_name / database_user / database_host / database_portDétails de connexion Cloud SQL.
storage_bucketsLe bucket data pour les photos et pièces jointes des articles.
kubernetes_readyIndique si la charge de travail a atteint l'état Prêt.

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).

ParamètreValeur judicieuseRisqueConséquence si incorrect
application_database_name / application_database_userDéfinir une foisCritiqueImmuable après le premier déploiement ; le renommage recrée la base de données/l'utilisateur et détruit toutes les données.
container_image_sourceprebuilt (par défaut)Élevé"custom" déclenche un Cloud Build inutile sans Dockerfile dans ce module.
Première inscriptionCompléter rapidement après le déploiementMoyenLa première personne à s'inscrire sur une instance fraîche et publiquement accessible devient l'administrateur — tant que vous ne vous inscrivez pas et ne définissez pas HBOX_OPTIONS_ALLOW_REGISTRATION=false, toute personne qui découvre l'URL peut revendiquer le compte administrateur.
gcs_volumes pour les photos d'articlesLaisser vide (utiliser le montage /data propre au module)ÉlevéHomebox_Common monte déjà le bucket data à /data. Fournir une liste gcs_volumes non vide remplace entièrement ce montage — si le remplacement ne couvre pas également /data, les photos et pièces jointes d'articles téléchargées reviennent au système de fichiers éphémère du pod et ne survivent pas à un redémarrage.
Variables db_*_env_var_nameLaisser leurs valeurs par défaut spécifiques à HomeboxCritiqueLa modification/suppression de ces variables interrompt la connexion Postgres de Homebox — elle lit HBOX_DATABASE_*, pas DB_*.
HBOX_DATABASE_SSL_MODEdisable (déjà défini par ce module)CritiqueSur GKE, DB_HOST se résout en 127.0.0.1 (le sidecar cloud-sql-proxy), qui termine lui-même le TLS et sert du texte brut sur la boucle locale. Le client Postgres de Homebox définit par défaut HBOX_DATABASE_SSL_MODE à require et panique au démarrage (tls error: server refused TLS connection) à moins qu'on ne lui dise que la connexion locale n'est pas chiffrée. Homebox_GKE définit cela via module_env_vars — ne le supprimez pas. Non nécessaire sur Cloud Run, qui se connecte via un socket Unix (aucune négociation TLS ne s'applique là-bas, quelle que soit cette configuration).

Pour le comportement de la fondation référencé tout au long — Workload Identity, ingress, autoscaling, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC-SC, sauvegardes et mise en miroir d'images — voir App_GKE. La configuration d'application spécifique à Homebox partagée avec la variante Cloud Run est décrite dans Homebox_Common.

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