Aller au contenu principal

Spoolman sur Google Cloud Run

Spoolman sur Google Cloud Run

Spoolman est un outil gratuit et open source de suivi de l'inventaire et de la consommation des bobines de filament d'impression 3D — fournisseurs, matériaux, poids restant, coût par bobine et consommation par impression. Il est livré sous la forme d'un backend Python/FastAPI à processus unique, accompagné d'un frontend statique Vue/Quasar intégré. Ce module déploie Spoolman sur Cloud Run v2 au-dessus du socle App_CloudRun, qui provisionne et gère l'infrastructure Google Cloud partagée.

Ce guide se concentre sur les services cloud qu'utilise Spoolman et sur la manière de les explorer et de les exploiter depuis la console Google Cloud et en ligne de commande. Pour les mécanismes communs à toutes les applications Cloud Run — identité du service, entrée et équilibrage de charge, mise à l'échelle et concurrence, 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_CloudRun plutôt que de les répéter ici.

1. Vue d'ensemble​

Spoolman s'exécute dans un unique conteneur Python/FastAPI sur Cloud Run v2 — il n'y a pas de service frontend distinct ; l'interface Vue/Quasar est intégrée et servie par le même processus. Le déploiement assemble un ensemble minimal de services Google Cloud :

FonctionnalitéService Google CloudRemarques
CalculCloud Run v2Image préconstruite ghcr.io/donkie/spoolman, 1 vCPU / 512Mi par défaut, autoscaling serverless ; mise à l'échelle jusqu'à zéro par défaut
Base de donnéesCloud SQL for PostgreSQL 15Obligatoire — ce module se standardise sur Postgres (Spoolman en amont prend aussi en charge MySQL/SQLite/CockroachDB)
Stockage objetAucunSpoolman conserve tout son état dans Postgres ; aucun bucket GCS n'est provisionné
CacheAucunSpoolman n'a aucune intégration Redis/cache
SecretsSecret ManagerUniquement le mot de passe de base de données généré automatiquement — Spoolman n'a aucun secret d'amorçage administrateur/clé API qui lui soit propre
EntréeURL Cloud RunURL run.app par défaut, publique par défaut (ingress_settings = "all")

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

  • PostgreSQL 15 est le seul moteur pris en charge par ce module. database_type est fixé par Spoolman_Common ; Spoolman en amont prend aussi en charge MySQL et CockroachDB via des variables d'environnement, mais ce module n'expose pas ce choix.
  • Aucun build personnalisé. container_image_source = "prebuilt" déploie directement ghcr.io/donkie/spoolman — pas de Dockerfile, pas d'étape Cloud Build, et aucun risque d'épinglage de application_version lié à la classe de bugs d'une image de base à l'étiquette latest.
  • Aucun job d'initialisation. Le socle crée automatiquement le rôle et la base de données Postgres ; Spoolman exécute automatiquement ses propres migrations Alembic à chaque démarrage du conteneur. Il n'y a rien à attendre au-delà du passage du conteneur à l'état sain.
  • Aucun secret applicatif. Spoolman est livré sans aucune authentification — quiconque peut atteindre l'URL dispose d'un accès complet en lecture/écriture à l'inventaire. Il n'y a aucune page de connexion à amorcer et rien n'est généré dans Secret Manager en dehors du mot de passe de base de données. Si cela n'est pas acceptable pour votre déploiement, placez le service derrière IAP (enable_iap = true) ou une liste d'adresses IP autorisées Cloud Armor.
  • La mise à l'échelle jusqu'à zéro est le comportement par défaut (min_instance_count = 0, cpu_always_allocated hérite de la valeur par défaut du socle, fondée sur les requêtes). Spoolman n'effectue aucun travail en arrière-plan — ni planificateur, ni file d'attente, ni WebSocket — il n'y a donc aucune raison de modifier l'un ou l'autre de ces paramètres.
  • Les connexions utilisent le socket Unix Cloud SQL, et non TCP. La couche SQLAlchemy de Spoolman construit sa connexion via URL.create() (un objet structuré, et non une concaténation de chaînes), de sorte que le chemin du répertoire du socket — qui contient des deux-points dans le nom de connexion de l'instance Cloud SQL — passe sans encombre, sans aucun problème d'analyse d'URL. Aucune configuration TLS/sslmode n'est nécessaire.

2. Services Google Cloud et comment les explorer​

Toutes les commandes supposent que PROJECT et REGION sont définies. Les noms des services et des ressources figurent dans les sorties du déploiement.

A. Cloud Run — le service Spoolman​

Spoolman s'exécute sous la forme d'un unique service Cloud Run v2. Chaque déploiement crée une révision immuable ; le trafic peut être réparti entre les révisions pour des déploiements progressifs sûrs.

  • Console : Cloud Run → sélectionnez le service pour consulter les révisions, le trafic, les journaux et les métriques.
  • CLI : 
    gcloud run services list --project "$PROJECT" --region "$REGION"
    gcloud run services describe <service-name> --project "$PROJECT" --region "$REGION"
    gcloud run revisions list --service <service-name> --project "$PROJECT" --region "$REGION"

Consultez App_CloudRun pour la mise à l'échelle, la concurrence, l'environnement d'exécution et la répartition du trafic.

B. Cloud SQL for PostgreSQL 15​

Spoolman stocke toutes les données d'inventaire (bobines, filaments, fournisseurs, historique de consommation) dans une instance gérée Cloud SQL for PostgreSQL 15. Le service se connecte de manière privée via le Cloud SQL Auth Proxy sur un socket Unix ; aucune adresse IP publique n'est exposée. Il n'y a pas de job d'initialisation — Spoolman applique ses propres migrations de schéma à chaque démarrage.

  • Console : SQL → sélectionnez l'instance pour consulter les connexions, les sauvegardes, les flags et les métriques.
  • CLI : 
    gcloud sql instances list --project "$PROJECT"
    gcloud sql instances describe <instance-name> --project "$PROJECT"
    gcloud sql connect <instance-name> --user=<db-user> --database=<db-name> --project "$PROJECT"

Le nom de l'instance, la base de données, l'utilisateur et le secret du mot de passe figurent dans les sorties. Consultez App_CloudRun pour le modèle de connexion, les sauvegardes et la rotation des mots de passe.

C. Secret Manager​

Seul le mot de passe de base de données généré automatiquement réside dans Secret Manager — Spoolman n'a ni compte administrateur ni clé API propre à amorcer.

  • Console : Security → Secret Manager.
  • CLI : 
    gcloud secrets list --project "$PROJECT" --filter="name~spoolman"
    gcloud secrets versions access latest --secret=<db-password-secret> --project "$PROJECT"

D. Réseau et entrée​

Le service est accessible par défaut à son URL run.app (ingress_settings = "all"). Un équilibreur de charge HTTPS externe avec un domaine personnalisé, Cloud CDN et Cloud Armor peuvent être ajoutés par-dessus.

  • Console : Cloud Run (URL du service) ; Network services → Load balancing.
  • CLI : 
    gcloud run services describe <service-name> --region "$REGION" --format='value(status.url)'

Consultez App_CloudRun.

E. Cloud Logging et Monitoring​

Les journaux des conteneurs sont envoyés vers Cloud Logging ; les métriques de Cloud Run et de Cloud SQL sont envoyées vers Cloud Monitoring, avec des tests de disponibilité et des règles d'alerte facultatifs.

  • Console : Logging → Logs Explorer ; Monitoring → Dashboards / Alerting.
  • CLI : 
    gcloud run services logs read <service-name> --project "$PROJECT" --region "$REGION" --limit 50

3. Comportement de l'application Spoolman​

  • Aucun job de configuration de la base de données au premier déploiement. Contrairement à la plupart des modules applicatifs de ce catalogue, Spoolman n'a besoin d'aucun job db-init — le socle crée le rôle et la base de données Postgres, et les migrations Alembic propres à Spoolman s'exécutent automatiquement à chaque démarrage du conteneur (y compris le tout premier).
  • Aucune authentification. Il n'y a ni page de connexion, ni compte administrateur, ni contrôle par clé API. Quiconque peut atteindre l'URL du service peut consulter et modifier l'intégralité de l'inventaire. Choisissez votre approche de contrôle d'accès (IAP, liste d'adresses autorisées Cloud Armor, ou acceptation d'un accès public en lecture/écriture) avant de partager l'URL.
  • Chemin de santé. /api/health est public et non authentifié ; il renvoie un statut JSON 200/OK une fois le serveur (et sa connexion à la base de données) opérationnel. Les sondes de démarrage et de vivacité ciblent toutes deux ce chemin.
  • Moteur de base de données verrouillé sur Postgres. La variable d'environnement SPOOLMAN_DB_TYPE propre à Spoolman sélectionne le moteur ; ce module la fixe toujours à postgres. Ne la supprimez jamais via environment_variables — sans elle, Spoolman se rabat silencieusement sur un fichier SQLite jetable, local au conteneur, sans la moindre erreur (une classe de défaillance documentée dans ce catalogue — consultez le tableau des pièges du guide de configuration).
  • Inspecter la connectivité Cloud SQL : 
    gcloud run revisions describe <revision-name> --region "$REGION" --project "$PROJECT" \
      --format='value(spec.containers[0].env)' | tr ';' '\n' | grep -i spoolman_db

4. Variables de configuration​

Les variables sont regroupées exactement comme elles apparaissent sur la plateforme de déploiement. Seuls les paramètres propres à Spoolman ou notables pour lui sont listés ; toutes les autres entrées sont héritées de App_CloudRun avec leur comportement standard.

Groupe 3 — Identité de l'application​

VariableValeur par défautDescription
application_namespoolmanNom de base des ressources. Ne le modifiez pas après le premier déploiement.
application_display_nameSpoolmanNom lisible affiché dans la console.
application_versionlatestÉtiquette de l'image récupérée depuis ghcr.io/donkie/spoolman. Réellement préconstruite — aucune préoccupation d'épinglage de Dockerfile/build-arg.
application_database_name / application_database_userspoolman / spoolmanImmuables après le premier déploiement.

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

VariableValeur par défautDescription
deploy_applicationtrueDéfinissez false pour ne provisionner que l'infrastructure.
container_image_sourceprebuiltTransmis au socle — obligatoire, sinon la valeur par défaut "custom" déclenche silencieusement une tentative Kaniko/Cloud Build sans Dockerfile.
container_port8000Port d'écoute par défaut de Spoolman.
cpu_limit / memory_limit1000m / 512MiLargement suffisant pour un outil de suivi de filament mono-locataire ; augmentez-les pour un grand inventaire multi-utilisateurs.
min_instance_count / max_instance_count0 / 1La mise à l'échelle jusqu'à zéro est sûre — Spoolman n'effectue aucun travail en arrière-plan.
enable_cloudsql_volumetrueMonte le socket Unix du Cloud SQL Auth Proxy. Nécessaire à la construction du DSN décrite au §1.

Groupe 12 — Base de données​

VariableValeur par défautDescription
db_host_env_var_nameSPOOLMAN_DB_HOSTAlias de DB_HOST du socle (le répertoire du socket Cloud SQL sur Cloud Run).
db_user_env_var_nameSPOOLMAN_DB_USERNAMEAlias de DB_USER.
db_password_env_var_nameSPOOLMAN_DB_PASSWORDAlias de DB_PASSWORD.
db_name_env_var_nameSPOOLMAN_DB_NAMEAlias de DB_NAME.
db_port_env_var_nameSPOOLMAN_DB_PORTAlias de DB_PORT.
database_password_length32Longueur du mot de passe généré (16–64).

Groupe 11 — Stockage et système de fichiers​

VariableValeur par défautDescription
create_cloud_storagefalseAucun bucket GCS nécessaire — tout l'état réside dans Cloud SQL.
enable_nfsfalseAucun système de fichiers partagé nécessaire.

Groupe 14 — Observabilité et santé​

VariableValeur par défautDescription
startup_probeHTTP /api/health, délai de 10sPublic, non authentifié.
liveness_probeHTTP /api/health, période de 30sPublic, non authentifié.

Toutes les autres entrées (CI/CD, sauvegardes, VPC-SC, Cloud Armor, IAP, Redis) sont héritées de App_CloudRun avec leur comportement standard — Spoolman n'en utilise aucune par défaut.

5. Sorties​

SortieDescription
service_nameNom du service Cloud Run.
service_urlURL run.app par défaut du service.
service_locationRégion dans laquelle s'exécute le service.
database_instance_nameNom de l'instance Cloud SQL.
database_name / database_userNom / utilisateur de la base de données de l'application.
database_password_secretSecret Secret Manager contenant le mot de passe de la base de données.
database_host / database_portPoint de terminaison / port de la base de données.
storage_bucketsToujours vide — Spoolman n'a besoin d'aucun bucket GCS.
container_image / container_registryImage déployée et dépôt Artifact Registry (lorsque la duplication est activée).
monitoring_enabled / uptime_check_namesStatut de la surveillance et tests de disponibilité.
initialization_jobsToujours vide — Spoolman n'a besoin d'aucun job d'initialisation.
deployment_id / tenant_id / resource_prefixIdentifiants de nommage.
project_id / project_numberIdentifiants du projet.
vpc_sc_enabled / vpc_sc_perimeter_name / vpc_sc_dry_run_modeStatut VPC-SC.
audit_logging_enabled / artifact_registry_cmek_enabledStatut de la journalisation d'audit et de 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).

ParamètreValeur judicieuseRisqueConséquence en cas d'erreur
Aucune authentification (intégrée)Placer derrière IAP ou Cloud Armor si nécessaireCritiqueQuiconque possède l'URL peut lire et modifier l'intégralité de l'inventaire de filament — il n'existe aucune page de connexion à désactiver.
SPOOLMAN_DB_TYPE (injectée automatiquement à postgres)Ne jamais la supprimer via environment_variablesCritiqueLa supprimer provoque un repli silencieux sur un fichier SQLite jetable, local au conteneur — aucune erreur, et toutes les données sont perdues à chaque redémarrage.
application_database_name / application_database_userÀ définir une seule foisCritiqueImmuables après le premier déploiement ; les renommer recrée la base de données/l'utilisateur et détruit toutes les données.
container_image_sourceprebuilt (ne pas remplacer par custom)CritiqueDéfinir "custom" déclenche une tentative Kaniko/Cloud Build sur un module dépourvu de Dockerfile — le build échoue purement et simplement.
enable_cloudsql_volumetrueÉlevéLe désactiver supprime le socket Unix dont dépend SPOOLMAN_DB_HOST de Spoolman pour le chemin de connexion documenté sans TLS.
SPOOLMAN_DB_QUERYLaisser vide, sauf pour un dépannageMoyenIl s'agit d'une échappatoire pour un repli TCP + sslmode — nécessaire uniquement si le chemin de connexion par socket s'avérait un jour peu fiable sur un déploiement en production ; inutile en fonctionnement normal.
ingress_settingsall (valeur par défaut)MoyenLe restreindre à internal rend le service inaccessible depuis un navigateur, sauf s'il est placé derrière un équilibreur de charge.
min_instance_count0 (valeur par défaut)FaibleSpoolman n'effectue aucun travail en arrière-plan, la mise à l'échelle jusqu'à zéro est donc sûre ; augmentez-le uniquement pour éviter la latence de démarrage à froid en usage interactif.

Pour le comportement du socle évoqué tout au long de ce guide — identité du service, mise à l'échelle et concurrence, entrée et équilibrage de charge, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC-SC, sauvegardes et mise en miroir des images — consultez App_CloudRun. La configuration applicative propre à Spoolman, partagée avec la variante GKE, est décrite dans Spoolman_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