Aller au contenu principal

Homebox sur GKE Autopilot

Homebox sur GKE Autopilot

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

Ce guide se concentre sur les services cloud qu'utilise 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, entrée, autoscaling, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, sauvegardes et cycle de vie du déploiement — reportez-vous au guide du socle App_GKE plutôt que de les répéter ici.

1. Vue d'ensemble​

Homebox s'exécute sous la forme d'un unique binaire Go (API + frontend intégré) — un seul pod, sans autre sidecar que le Cloud SQL Auth Proxy. Le déploiement assemble un ensemble restreint et ciblé de services Google Cloud :

FonctionnalitéService Google CloudRemarques
CalculGKE AutopilotPod Go/Echo, 1 vCPU / 512 MiB par défaut
Base de donnéesCloud SQL for PostgreSQL 15Homebox lit des variables d'environnement HBOX_DATABASE_* distinctes, et non un DSN construit
Stockage objetCloud StorageUn bucket data est créé pour les photos et pièces jointes des objets et monté automatiquement sur /data
Cache et file d'attenteaucunHomebox ne dépend ni de Redis ni d'une file d'attente
SecretsSecret ManagerMot de passe de la base de données plus HBOX_AUTH_API_KEY_PEPPER (un véritable secret consommé par l'application)
EntréeCloud Load BalancingLoadBalancer externe, domaine personnalisé + certificat géré facultatifs

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

  • PostgreSQL est le moteur standardisé. Homebox_Common fixe database_type = "POSTGRES_15" et définit explicitement HBOX_DATABASE_DRIVER=postgres.
  • Aucun build de conteneur personnalisé. L'image préconstruite officielle (ghcr.io/sysadminsmedia/homebox) est utilisée directement.
  • Inscription libre, et non un compte administrateur par défaut. Homebox n'est pas livré avec un identifiant codé en dur : la première personne qui soumet le formulaire « Register » sur une instance neuve devient l'utilisateur administrateur initial. Consultez le guide Common pour plus de détails. Les opérateurs doivent définir HBOX_OPTIONS_ALLOW_REGISTRATION=false une fois l'inscription effectuée.
  • workload_type = "Deployment", et non StatefulSet. Homebox ne conserve aucun état local au-delà de ce qui se trouve déjà dans Cloud SQL — ni PVC, ni montage NFS nécessaires.
  • Les photos des objets sont conservées par défaut. Homebox_Common déclare une entrée gcs_volumes qui monte le bucket GCS data sur /data, afin que les photos et pièces jointes téléversées survivent au redémarrage d'un pod.

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 for 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 entrée​

  • 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 et la base de données de l'application.
  • Migrations de schéma au démarrage. L'ORM Ent de Homebox applique automatiquement ses propres migrations internes à chaque démarrage de pod.
  • Inscription libre — aucun identifiant administrateur par défaut. Le premier visiteur qui remplit le formulaire « Register » devient l'administrateur. Il n'y a aucun identifiant à récupérer, réinitialiser ou faire tourner — définissez HBOX_OPTIONS_ALLOW_REGISTRATION=false une fois le compte administrateur créé pour fermer les inscriptions publiques.
  • Chemin de santé. Les sondes de démarrage et de vivacité ciblent /api/v1/status — le véritable point de terminaison d'état de Homebox, non authentifié.
  • Inspecter l'exécution des jobs : 
    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 propres à Homebox ou notables pour lui sont listés ; toutes les autres entrées sont héritées d'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 un véritable tag latest.

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

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

Groupe 11 — Stockage et système de fichiers​

VariableValeur par défautDescription
storage_bucketsun bucket dataCréé et monté automatiquement sur /data.
stateful_pvc_enablednull (auto, désactivé)Non utilisé — Homebox est sans état au niveau du pod.

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_HOSTAssocie la variable DB_HOST de la plateforme au nom attendu par Homebox.
db_user_env_var_nameHBOX_DATABASE_USERNAMEAlias de DB_USER.
db_password_env_var_nameHBOX_DATABASE_PASSWORDAlias de DB_PASSWORD.
db_name_env_var_nameHBOX_DATABASE_DATABASEAlias de DB_NAME.
db_port_env_var_nameHBOX_DATABASE_PORTAlias de 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 point de terminaison d'état 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 des photos et pièces jointes des objets.
kubernetes_readyIndique si la charge de travail a atteint l'état Ready.

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 en cas d'erreur
application_database_name / application_database_userDéfinir une seule foisCritiqueImmuables après le premier déploiement ; les renommer recrée la base de données et l'utilisateur et détruit toutes les données.
container_image_sourceprebuilt (par défaut)Élevé"custom" déclenche un Cloud Build inutile alors que ce module ne contient pas de Dockerfile.
Première inscriptionÀ effectuer rapidement après le déploiementMoyenLa première personne à s'inscrire sur une instance neuve accessible publiquement devient l'administrateur — tant que vous ne vous êtes pas inscrit et n'avez pas défini HBOX_OPTIONS_ALLOW_REGISTRATION=false, quiconque découvre l'URL peut s'approprier le compte administrateur.
gcs_volumes pour les photos des objetsLaisser vide (utiliser le montage /data propre au module)ÉlevéHomebox_Common monte déjà le bucket data sur /data. Fournir une liste gcs_volumes non vide remplace entièrement ce montage — si le remplacement ne couvre pas aussi /data, les photos et pièces jointes téléversées retombent sur le système de fichiers éphémère du pod et ne survivent pas à un redémarrage.
Variables db_*_env_var_nameConserver leurs valeurs par défaut propres à HomeboxCritiqueLes modifier ou les vider rompt la connexion Postgres de Homebox — il lit HBOX_DATABASE_*, et non 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 TLS et sert du texte en clair sur la boucle locale. Le client Postgres de Homebox fixe par défaut HBOX_DATABASE_SSL_MODE à require et plante au démarrage (tls error: server refused TLS connection) si on ne lui indique pas que la connexion locale n'est pas chiffrée. Homebox_GKE le définit via module_env_vars — ne le videz pas. Inutile sur Cloud Run, qui se connecte via un socket Unix (aucune négociation TLS ne s'y applique, quel que soit ce paramètre).

Pour le comportement du socle évoqué tout au long de ce guide — Workload Identity, entrée, autoscaling, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC-SC, sauvegardes et mise en miroir des images — consultez App_GKE. La configuration applicative propre à 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.

By · Google Cloud certified: ACE · PCA · PCD · PDE · PSE · CDL

Dernière mise à jour le