Cette page est une traduction automatique de la page en anglais, qui fait foi. Lire la page en anglais
Importer les coûts d’utilisation du cloud
Le serveur importe, toutes les 24 heures, les frais d’utilisation des fournisseurs listés dans le paramètre billing_sources, ou d’un plugin pour un fournisseur dont il n’a pas d’adaptateur, et les ajoute aux coûts de l’instance. La valeur par défaut est vide, ce qui n’importe rien.
Il importe les frais du mois de facturation en cours et du précédent (jusqu’au 15 du mois, ou jusqu’à ce que le mois précédent soit définitif), à raison d’une ligne par service et par type de frais (utilisation, crédit, remboursement, taxe, support, frais, autre).
Tant que le fournisseur n’a pas clos un mois, les valeurs sont enregistrées comme estimations ; après la clôture, comme définitives ; et lorsqu’une valeur change après être devenue définitive, comme correction. Les enregistrements du passé ne sont jamais réécrits.
L’état des imports (le dernier succès, le type du dernier échec et le nombre de requêtes de ce mois) est affiché sur la page « Imports de facturation » de « Coûts et revenus » dans l’administration (/admin/finance/imports), qui liste aussi chaque mois de facturation comme estimé, définitif ou corrigé, avec « Importer maintenant », et par GET /api/v1/admin/billing_imports.
Les métriques comptent chaque tentative par source, résultat et type d’échec (my.billing.imports) et signalent les sources dont la dernière tentative a échoué (my.billing.import.failing) ;
Alertes et guide d’exploitation contient l’alerte correspondante.
Pour AWS et Google Cloud, aucun identifiant n’est conservé dans la configuration de ce serveur. Donnez à l’environnement d’exécution ce que lit la chaîne d’identifiants par défaut du SDK de chaque fournisseur (pour AWS, le rôle d’exécution, les variables d’environnement ou les fichiers d’identifiants partagés ; pour Google Cloud, les Application Default Credentials).
Cloudflare n’a pas de telle chaîne : son import lit donc un jeton d’API dans billing_cloudflare_api_token.
Avec les modules OpenTofu
Section intitulée « Avec les modules OpenTofu »Sur Google Cloud, la section billing de mycroblog-gcp définit billing_sources = gcp et réalise les parties de ce guide que l’API du fournisseur permet, avec billing_account_id, method (bigquery ou budget) et dataset_location. Elle n’importe que les coûts de Google Cloud. Sur AWS, le module billing-aws de l’exemple AWS fait de même pour les coûts d’AWS. Aucun des deux n’a encore été appliqué sur un compte réel.
| Étape de ce guide | Avec les modules |
|---|---|
| La politique IAM d’AWS | billing-aws |
| Activer Cost Explorer, Linked Account Access, les tags d’allocation des coûts | À la main, dans la console AWS |
| Le jeu de données de l’export, et les rôles de « Rôles IAM » | La section billing |
| Activer l’export (« Standard usage cost ») | À la main, dans la console Google Cloud, avec un rôle sur le compte de facturation |
| Le sujet et l’abonnement pull d’un budget, et le rôle d’abonné | La section billing avec method = "budget" |
| Créer le budget et le relier au sujet | À la main, dans la console Google Cloud, avec un rôle sur le compte de facturation |
| Activer l’API BigQuery ou Pub/Sub | À la main, comme dans Déployer sur Cloud Run |
| Les coûts d’AWS sur Cloud Run | Pas par mycroblog-gcp. Créez à la main le rôle de Appeler depuis Cloud Run avec une identité web, et définissez billing_sources = aws et billing_aws_role_arn dans settings, sans la section billing |
| Cloudflare | Pas par ces modules. Sur Cloud Run, sans la section billing, définissez billing_sources et billing_cloudflare_account_id dans settings, et billing_cloudflare_api_token dans secrets, comme pour un plugin |
| Un plugin | Pas par ces modules. Sur Cloud Run, sans la section billing, définissez billing_sources = plugin et les paramètres du plugin dans settings. À côté de la section billing, le module refuse billing_sources dans settings |
AWS (billing_sources = aws)
Section intitulée « AWS (billing_sources = aws) »Le serveur appelle GetCostAndUsage d’AWS Cost Explorer une fois par mois de facturation (un mois calendaire UTC), groupé par service (SERVICE) et par type d’enregistrement (RECORD_TYPE). Le point de terminaison est toujours us-east-1.
Les montants sont en USD. Tant que Cost Explorer marque un mois comme estimé (Estimated), le serveur enregistre le montant jusqu’à la veille comme une estimation, et dès qu’il ne le fait plus, comme définitif.
Coût et limites
Section intitulée « Coût et limites »L’API Cost Explorer facture 0,01 $ par requête paginée. Un petit compte a besoin d’une requête d’une page par jour, soit environ 0,31 $ par mois.
Pour éviter les frais inattendus, le serveur compte les requêtes par jour UTC (billing_aws_max_requests_per_day, 4 par défaut) et par mois calendaire UTC (billing_aws_max_requests_per_month, 120 par défaut = 1,20 $), et s’arrête sans appeler dès qu’une limite est atteinte.
Les imports planifiés, les nouvelles tentatives de tâches et « Importer maintenant » dans l’administration comptent tous. Un import qui atteint une limite est enregistré comme un échec de type request_cap, et l’import du lendemain (pour la limite quotidienne) ou du premier jour du mois suivant (pour la limite mensuelle) réessaie.
Avant d’appeler, un import met de côté les requêtes que les limites laissent, de sorte que des imports exécutés en même temps ne puissent pas dépasser ensemble les limites.
Les imports d’un même prestataire s’exécutent un à la fois : un import qui démarre alors qu’un autre n’est pas terminé réessaie une minute plus tard, et une tâche qui a déjà importé avec succès n’appelle rien quand il s’exécute de nouveau.
Un import qui s’est arrêté avant d’avoir fini (le processus s’est terminé) compte les requêtes qu’il avait mises de côté, et l’import suivant l’attend pendant 15 minutes au plus.
Activer Cost Explorer
Section intitulée « Activer Cost Explorer »- Ouvrez Cost Explorer dans la console Billing and Cost Management et activez-le. Il ne peut pas être désactivé une fois activé. Il faut jusqu’à 24 heures pour que les données soient prêtes.
- Un compte où il n’est pas activé renvoie
DataUnavailableException, et l’import échoue avecnot_enabled.
Permissions IAM
Section intitulée « Permissions IAM »La seule permission nécessaire est ce:GetCostAndUsage (ressource *).
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ce:GetCostAndUsage", "Resource": "*" } ]}Comment transmettre les identifiants dans chaque environnement d’exécution :
| Environnement d’exécution | Identifiants |
|---|---|
| AWS ECS | Attachez cette politique au rôle de la tâche. Aucune configuration n’est nécessaire |
| Google Cloud (Cloud Run) | Créez le rôle IAM de « Calling from Cloud Run with web identity » ci-dessous et définissez son ARN dans billing_aws_role_arn. Aucune clé AWS n’est nécessaire |
| Votre propre serveur | Transmettez la clé d’accès d’un utilisateur IAM ayant cette politique dans AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (ou un fichier d’identifiants partagé et AWS_PROFILE). Transmettez-la depuis un magasin de secrets |
Des permissions manquantes ou des identifiants invalides échouent avec permission.
Appeler depuis Cloud Run avec une identité web
Section intitulée « Appeler depuis Cloud Run avec une identité web »Quand billing_aws_role_arn est défini, le serveur obtient auprès du serveur de métadonnées un jeton d’identité Google du compte de service de Cloud Run (l’audience est l’ARN du rôle) et l’échange contre des identifiants temporaires de ce rôle avec AssumeRoleWithWebIdentity.
-
Dans Google Cloud, notez l’ID unique (le
uniqueIdnumérique) du compte de service du service Cloud Run :gcloud iam service-accounts describe <email> --format='value(uniqueId)'. -
Dans AWS IAM, créez un rôle avec la politique des permissions ci-dessus, et faites en sorte que sa politique d’approbation fasse confiance à
accounts.google.com.{"Version": "2012-10-17","Statement": [{"Effect": "Allow","Principal": { "Federated": "accounts.google.com" },"Action": "sts:AssumeRoleWithWebIdentity","Condition": {"StringEquals": {"accounts.google.com:aud": "<uniqueId of the service account>","accounts.google.com:oaud": "<ARN of this role>"}}}]}accounts.google.com:audcorrespond auazpdu jeton (l’ID du compte de service), etaccounts.google.com:oaudà l’auddu jeton (l’audience que demande le serveur, qui est l’ARN du rôle). -
Définissez
MY_BILLING_AWS_ROLE_ARN=arn:aws:iam::<account ID>:role/<role name>.
Cette configuration n’a pas encore été vérifiée sur un vrai compte.
Appeler depuis un compte lié d’Organizations
Section intitulée « Appeler depuis un compte lié d’Organizations »Le compte de gestion d’AWS Organizations peut voir les coûts de chaque compte membre de l’organisation. Pour appeler avec les identifiants d’un compte membre (lié),
activez « Linked Account Access » dans les préférences de Cost Explorer du compte de gestion. Quand il est désactivé, l’appel est refusé quelles que soient les permissions IAM, et l’import échoue avec not_enabled ou permission.
Choisir les coûts à importer (filtrage)
Section intitulée « Choisir les coûts à importer (filtrage) »Choisissez avec billing_aws_filter.
billing_aws_filter |
Coûts importés | Paramètres supplémentaires |
|---|---|---|
none (par défaut) |
Tous les coûts que les identifiants peuvent voir | Aucun |
linked_account |
Les coûts des comptes membres que vous nommez (LINKED_ACCOUNT) |
billing_aws_linked_accounts (ID de compte à 12 chiffres, séparés par des virgules) |
tag |
Les coûts des ressources qui portent le tag de répartition des coûts que vous nommez | billing_aws_tag (key=value, par exemple app=my) |
La configuration la plus précise est un compte AWS dédié à ce serveur (il peut être un compte membre d’Organizations), importé avec none (en appelant avec les identifiants de ce compte) ou linked_account (en appelant depuis le compte de gestion).
Les taxes, les frais de support et certains crédits ne peuvent pas porter de tag, et peuvent sortir d’un filtre par tag (pas encore vérifié sur un vrai compte).
Activer un tag de répartition des coûts (billing_aws_filter = tag)
Section intitulée « Activer un tag de répartition des coûts (billing_aws_filter = tag) »Un tag sur une ressource n’apparaît pas dans les données de facturation tant que vous ne l’avez pas activé comme tag de répartition des coûts.
- Placez le même tag (par exemple
app=my) sur les ressources de ce serveur (services ECS, RDS, buckets S3, équilibreurs de charge, etc.). - Dans « Cost allocation tags » de la console Billing and Cost Management, sélectionnez la clé du tag et activez-la. Il faut jusqu’à 24 heures pour qu’un tag apparaisse dans cette liste après que vous l’avez attaché, et jusqu’à 24 heures de plus après l’activation pour qu’il apparaisse dans les données de facturation.
- Pour refléter les coûts de la période précédant l’activation, utilisez « Backfill » sur le même écran (l’API
StartCostAllocationTagBackfill). - Définissez
MY_BILLING_AWS_FILTER=tagetMY_BILLING_AWS_TAG=app=my.
Métrique
Section intitulée « Métrique »billing_aws_metric vaut soit NetUnblendedCost (par défaut, plus proche de la facture), qui est après remises (Savings Plans, instances réservées, prix négociés), soit UnblendedCost, qui est avant elles.
Les valeurs de Cost Explorer et la facture peuvent différer à cause du moment des mises à jour et des arrondis. Quand elles diffèrent, la facture a raison.
Types d’échec
Section intitulée « Types d’échec »| Type | Réponse d’AWS | Comment corriger |
|---|---|---|
permission |
AccessDeniedException, identifiants invalides |
Vérifiez les permissions IAM et la manière dont les identifiants sont transmis |
not_enabled |
DataUnavailableException |
Activez Cost Explorer. Pour un compte lié, activez Linked Account Access |
not_found |
BillExpirationException |
Cost Explorer n’a plus les données de facturation de la période à importer |
throttled |
LimitExceededException |
La tâche réessaie après une pause (cela compte dans la limite de requêtes) |
unavailable |
5xx, défaillance réseau | La tâche réessaie après une pause (cela compte dans la limite de requêtes) |
invalid_response |
Une réponse illisible, ValidationException, et similaires |
Vérifiez les paramètres (tag, ID de compte) |
request_cap |
(aucun appel n’est effectué) | Attendez que le jour ou le mois limitant passe, ou augmentez la limite |
Une nouvelle tentative ne peut pas corriger un échec autre que throttled et unavailable : le serveur l’enregistre donc et s’arrête, et l’import planifié du lendemain réessaie.
Google Cloud (billing_sources = gcp)
Section intitulée « Google Cloud (billing_sources = gcp) »Google Cloud n’a aucune API qui renvoie les coûts réels : le serveur agrège donc l’export Cloud Billing vers BigQuery (coût d’utilisation standard) une fois par jour avec un jobs.query de BigQuery (billing_gcp_method = bigquery, la valeur par défaut).
Quand vous ne pouvez pas configurer l’export, il existe aussi une méthode simple qui n’importe qu’un total approximatif à partir des notifications Pub/Sub d’un budget (voir Importer à partir des notifications de budget).
Le mois de facturation est l’invoice.month de l’export, un mois calendaire à l’heure du Pacifique américain (avec heure d’été). Les dates sont enregistrées à l’heure du Pacifique telles quelles.
Les montants sont dans la devise du compte de facturation, sommés en NUMERIC par mois de facturation, service (service.description) et type de frais (cost_type), et les crédits (credits[]) deviennent une ligne de crédit par service. Les lignes de correction de l’export qui annulent des lignes antérieures font partie de la somme.
L’export n’a aucune marque de finalité : l’import qui s’exécute à partir du 5 (heure du Pacifique) du mois suivant traite donc le mois comme définitif, et jusque-là l’enregistre comme une estimation du premier jour du mois au jour de la dernière utilisation. Une fois définitif, l’import relit encore le mois jusqu’au 15 et enregistre toute différence comme une correction.
Coût et limites
Section intitulée « Coût et limites »Un import est une requête, et BigQuery facture les octets que chaque requête analyse (au moins 10 Mo). Un petit compte analyse environ 0,3 Go par mois, ce qui tient dans le premier 1 TiB par mois de l’offre gratuite (partagé avec les autres usages du compte de facturation) : cela coûte donc 0 $.
Pour éviter les analyses inattendues, chaque requête porte maximumBytesBilled (billing_gcp_max_bytes_billed, 1 GiB par défaut). Une requête qui le dépasserait n’est pas facturée et échoue, et elle est enregistrée comme un échec de type bytes_cap. L’administration affiche les octets facturés.
Activer l’export vers BigQuery
Section intitulée « Activer l’export vers BigQuery »L’opérateur configure cela une fois, dans la console (aucun moyen de le faire par une API n’a été trouvé).
- Dans un projet lié au compte de facturation, créez un dataset BigQuery (par exemple
billing_export). Choisissez un emplacement multirégion (USouEU). Les données du mois en cours et du précédent sont complétées rétroactivement (avec une seule région, les données commencent le jour où vous activez l’export). L’emplacement ne peut pas être changé ensuite. Ne définissez aucune expiration sur les tables. Les lignes qui expirent ne reviennent pas. - Sous « Billing > Billing export > BigQuery export », activez « Standard usage cost » et sélectionnez le dataset de l’étape 1. La configuration exige « Billing Account Costs Manager » ou « Billing Account Administrator » sur le compte de facturation et le rôle BigQuery User sur le projet.
- Au bout de quelques heures à un jour, la table
gcp_billing_export_v1_<BILLING_ACCOUNT_ID>est créée (les tirets de l’ID deviennent_). - Définissez
MY_BILLING_GCP_TABLE=<project>.billing_export.gcp_billing_export_v1_<BILLING_ACCOUNT_ID>.
Quand le dataset ou la table est introuvable, l’import échoue avec not_found.
Rôles IAM
Section intitulée « Rôles IAM »Accordez ces deux rôles au compte de service du serveur qui importe.
| Rôle | Où l’accorder | Usage |
|---|---|---|
roles/bigquery.jobUser (BigQuery Job User) |
Le projet qui exécute la requête (billing_gcp_query_project, ou le projet de la table si vide) |
bigquery.jobs.create. Les octets analysés sont facturés à ce projet |
roles/bigquery.dataViewer (BigQuery Data Viewer) |
Le dataset de l’export | bigquery.tables.getData |
gcloud projects add-iam-policy-binding <query project> \ --member=serviceAccount:<service account> --role=roles/bigquery.jobUserbq add-iam-policy-binding --member=serviceAccount:<service account> \ --role=roles/bigquery.dataViewer <project>:billing_exportQuand l’API BigQuery n’est pas activée dans le projet de la requête, l’import échoue avec not_enabled, et quand un rôle manque, avec permission.
L’authentification se fait par les Application Default Credentials (ADC).
| Environnement d’exécution | Identifiants |
|---|---|
| Google Cloud (Cloud Run) | ADC avec le compte de service du service. Aucune clé et aucune configuration |
| AWS ECS | Placez un fichier de configuration d’identifiants de Workload Identity Federation (le type AWS) et transmettez son chemin dans GOOGLE_APPLICATION_CREDENTIALS (pas encore vérifié sur un vrai compte) |
| Votre propre serveur | Workload Identity Federation, ou une clé JSON de compte de service transmise dans GOOGLE_APPLICATION_CREDENTIALS. Transmettez une clé depuis un magasin de secrets |
Choisir les coûts à importer (filtrage)
Section intitulée « Choisir les coûts à importer (filtrage) »Par défaut, le serveur importe tous les coûts du compte de facturation. La configuration la plus précise est un compte de facturation dédié à ce serveur, importé sans filtre.
| Paramètre | Coûts importés |
|---|---|
billing_gcp_projects (ID de projets, séparés par des virgules) |
Les coûts des projets que vous nommez (project.id) |
billing_gcp_label (key=value, par exemple app=my) |
Les coûts des ressources qui portent le label que vous nommez (labels) |
Quand vous définissez les deux, le serveur n’importe que les coûts qui correspondent aux deux. Les coûts au niveau de la facture, comme la taxe, peuvent ne porter ni projet ni label, et sortent alors du filtre (pas encore vérifié sur un vrai compte).
Types d’échec
Section intitulée « Types d’échec »| Type | Réponse de BigQuery | Comment corriger |
|---|---|---|
permission |
401, 403 (accessDenied) |
Vérifiez les rôles du compte de service et la manière dont les identifiants sont transmis |
not_enabled |
403 (accessNotConfigured et similaires) |
Activez l’API BigQuery dans le projet de la requête |
not_found |
404 | Vérifiez billing_gcp_table et la configuration de l’export |
bytes_cap |
400 (bytesBilledLimitExceeded) |
L’analyse a dépassé billing_gcp_max_bytes_billed. Augmentez la limite si la table est grande |
throttled |
429, 403 (rateLimitExceeded, quotaExceeded) |
La tâche réessaie après une pause |
unavailable |
5xx, défaillance réseau, une requête qui ne se termine pas | La tâche réessaie après une pause |
invalid_response |
Une réponse illisible, des lignes qui mélangent des devises au sein d’un mois, tout autre 400 | Vérifiez la table d’export (est-ce bien le coût d’utilisation standard ?) |
Une nouvelle tentative ne peut pas corriger un échec autre que throttled et unavailable : le serveur l’enregistre donc et s’arrête, et l’import planifié du lendemain réessaie.
Importer à partir des notifications de budget (billing_gcp_method = budget)
Section intitulée « Importer à partir des notifications de budget (billing_gcp_method = budget) »C’est une méthode simple pour quand vous ne pouvez pas configurer l’export BigQuery. Une fois par jour, le serveur lit, depuis un abonnement pull, les notifications qu’un budget Cloud Billing envoie vers un topic Pub/Sub. Elle utilise le pull plutôt que le push : une notification ne réveille donc jamais le serveur (Cloud Run, par exemple).
Cette méthode n’importe qu’un total approximatif fondé sur des estimations.
- Le
costAmountd’une notification est le coût cumulé estimé de la période du budget, sans ventilation par service ni par type de frais. Le serveur n’importe qu’une ligne par mois et par budget (le nom du service est le nom d’affichage du budget, le type de frais est l’utilisation, et la catégorie est autre). Les crédits et les taxes sont dans le total selon la configuration du budget. - Comme avec BigQuery, un mois devient définitif dans l’import qui s’exécute à partir du 5 (heure du Pacifique) du mois suivant. Une notification de budget ne sait rien de la clôture de la facture : même une valeur traitée comme définitive peut donc différer du montant de la facture.
- Un mois estimé est enregistré comme le coût du premier jour du mois au jour (heure du Pacifique) où la dernière notification a été publiée.
- Le filtrage est décidé par le périmètre du budget (projets, services, une clé et une valeur de label), et
billing_gcp_projectsetbilling_gcp_labelne sont pas utilisés.
Préparer le budget, le topic et l’abonnement
Section intitulée « Préparer le budget, le topic et l’abonnement »-
Créez un topic et un abonnement pull que seul ce serveur lit. Voyez « How notifications are read » ci-dessous pour les raisons de la durée de rétention et de l’expiration.
Fenêtre de terminal gcloud pubsub topics create billing-budget --project=<project>gcloud pubsub subscriptions create my-billing-budget --project=<project> \--topic=billing-budget --ack-deadline=60 \--message-retention-duration=31d --expiration-period=never -
Dans la console, sous « Billing > Budgets & alerts », créez un budget. Rendez sa période mensuelle (la notification d’un budget qui n’est pas mensuel échoue avec
invalid_response). Sélectionnez le projet de ce serveur comme périmètre, et sous « Manage notifications > Connect a Pub/Sub topic to this budget » sélectionnez le topic de l’étape 1. Créer le budget exige « Billing Account Costs Manager » ou « Billing Account Administrator » sur le compte de facturation, etpubsub.topics.setIamPolicyetpubsub.topics.listsur le projet du topic. La première notification met quelques heures à arriver, puis plusieurs arrivent par jour. -
Accordez au compte de service du serveur qui importe
roles/pubsub.subscriber(Pub/Sub Subscriber) sur l’abonnement. Il sert à tirer les messages et à les acquitter (pubsub.subscriptions.consume).Fenêtre de terminal gcloud pubsub subscriptions add-iam-policy-binding my-billing-budget --project=<project> \--member=serviceAccount:<service account> --role=roles/pubsub.subscriber -
Définissez
MY_BILLING_GCP_METHOD=budgetetMY_BILLING_GCP_BUDGET_SUBSCRIPTION=projects/<project>/subscriptions/my-billing-budget.
L’authentification est la même que pour BigQuery, les Application Default Credentials (voir le tableau de Rôles IAM ci-dessus).
Comment les notifications sont lues
Section intitulée « Comment les notifications sont lues »- Un import répète Pull jusqu’à ce qu’aucun nouveau message n’arrive, et prend, pour chaque budget et chaque mois, la notification dont l’heure de publication est la plus récente. Cela absorbe les livraisons Pub/Sub en double, les notifications répétées avec la même valeur et les réordonnancements : recevoir plusieurs fois la même notification ne compte donc qu’une fois dans le total.
Le nombre de requêtes comptées pour un import est le nombre de Pull, normalement deux : un qui renvoie des messages et un qui revient vide. Les acquittements faits à la fin (
Acknowledge,ModifyAckDeadline) ne sont pas comptés. - Le serveur n’acquitte (ack) qu’une notification qu’une notification plus récente du même budget et du même mois a remplacée, et une notification d’un mois qui n’est plus importé (le mois précédent, une fois enregistré comme définitif). La dernière notification d’un mois importé n’est pas acquittée mais rendue à l’abonnement, de sorte que l’import suivant relit la même notification, et la valeur ne change pas un jour sans nouvelle notification.
- Définissez donc la rétention des messages de l’abonnement à au moins 14 jours (31 jours recommandés). La dernière notification du budget d’un mois arrive vers le 2 du mois suivant, et le mois précédent est relu jusqu’au 15. Un mois dont les notifications ont expiré est enregistré comme un coût de 0.
- Par défaut, un abonnement expire après 31 jours sans utilisation. Définissez l’expiration sur « never » pour qu’il survive à une période pendant laquelle les imports étaient arrêtés.
- N’envoyez pas d’autres messages au topic. Un message qui ne peut pas être lu comme une notification de budget fait échouer cet import avec
invalid_response, et est acquitté pour que l’import suivant ne reste pas bloqué dessus. - Coût : quelques dizaines de messages par jour tiennent dans l’offre gratuite de Pub/Sub (10 GiB par mois), cela coûte donc 0 $. Le serveur ne fixe aucune limite.
Types d’échec (notifications de budget)
Section intitulée « Types d’échec (notifications de budget) »| Type | Réponse de Pub/Sub | Comment corriger |
|---|---|---|
permission |
PERMISSION_DENIED, UNAUTHENTICATED |
Vérifiez roles/pubsub.subscriber sur l’abonnement et la manière dont les identifiants sont transmis |
not_enabled |
PERMISSION_DENIED (SERVICE_DISABLED) |
Activez l’API Pub/Sub dans le projet de l’abonnement |
not_found |
NOT_FOUND |
Vérifiez billing_gcp_budget_subscription et si l’abonnement a expiré |
throttled |
RESOURCE_EXHAUSTED |
La tâche réessaie après une pause |
unavailable |
UNAVAILABLE, INTERNAL et similaires, défaillance réseau |
La tâche réessaie après une pause |
invalid_response |
Un message qui ne peut pas être lu comme une notification de budget, un budget qui n’est pas mensuel, deux budgets ayant le même nom d’affichage | Rendez le budget mensuel, donnez aux budgets des noms d’affichage distincts, et n’envoyez aucun autre message au topic |
Cloudflare (billing_sources = cloudflare)
Section intitulée « Cloudflare (billing_sources = cloudflare) »Le serveur lit l’utilisation facturable d’un compte Cloudflare : les frais d’utilisation de ses produits facturés à l’usage, tels que R2, Workers et D1, un enregistrement par métrique et par jour.
Il les additionne par produit (R2, Workers, D1) dans des mois calendaires UTC ; chaque produit forme donc une ligne d’utilisation par mois. L’utilisation comprise dans un quota gratuit est elle aussi importée, à 0.
Seul un compte facturé à l’usage possède ces données ; un compte sous contrat Enterprise échoue avec not_enabled.
Ce qu’il n’importe pas
Section intitulée « Ce qu’il n’importe pas »L’utilisation facturable de Cloudflare ne contient que des frais d’utilisation. Les formules et modules complémentaires à frais fixes (Pro, Business, Workers Paid, etc.), les taxes et les crédits n’y figurent pas : les coûts n’affichent donc que la partie utilisation de la facture.
Ajoutez les frais fixes comme coûts propres sur la page « Coûts » de « Coûts et revenus » (/admin/finance/costs), ou importez-les depuis un plugin.
Cycles de facturation et mois définitifs
Section intitulée « Cycles de facturation et mois définitifs »Cloudflare facture par cycles qui commencent le même jour chaque mois, le jour du premier achat du compte, en UTC (un cycle qui commencerait le 31 commence le dernier jour d’un mois plus court). La facture d’un cycle arrive à la fin du cycle ; un mois calendaire recouvre donc des parties de deux cycles. Le serveur lit chaque cycle qui chevauche les mois qu’il importe et place chaque enregistrement quotidien dans le mois calendaire de son jour ; les lignes d’un mois sont donc les frais de ses propres jours, pas ceux d’une seule facture. Un mois est définitif une fois que le cycle qui contient son dernier jour s’est terminé il y a deux jours, ou une fois que le mois suivant est écoulé, selon ce qui arrive en premier. D’ici là, c’est une estimation du premier du mois au dernier jour pour lequel il y a des données. Les données de Cloudflare ont un jour ou deux de retard.
Coût et limites
Section intitulée « Coût et limites »Cloudflare ne facture pas son API ; le serveur ne fixe donc aucun plafond de requêtes. Un import fait une requête pour les souscriptions du compte et une pour chaque cycle de facturation qu’il lit : jusqu’à quatre pour deux mois. L’API autorise 1 200 requêtes toutes les cinq minutes par utilisateur, partagées avec le tableau de bord et vos autres usages du propriétaire du jeton.
Créer le jeton d’API
Section intitulée « Créer le jeton d’API »- Dans le tableau de bord Cloudflare, ouvrez le compte et notez son identifiant de compte sur la vue d’ensemble du compte (32 chiffres hexadécimaux).
- Sous « Manage Account » → « Account API Tokens » (ou « My Profile » → « API Tokens »), créez un jeton personnalisé avec l’unique permission Account → Billing → Read, pour ce compte uniquement.
- Définissez
MY_BILLING_SOURCES=cloudflare,MY_BILLING_CLOUDFLARE_ACCOUNT_ID=<account ID>etMY_BILLING_CLOUDFLARE_API_TOKEN=<token>, le jeton provenant d’un magasin de secrets (ouMY_BILLING_CLOUDFLARE_API_TOKEN_FILE).
Donnez à l’import un jeton qui lui soit propre. Le serveur ne lit jamais CLOUDFLARE_API_TOKEN, qu’utilisent Wrangler et le fournisseur OpenTofu ; un jeton qui peut modifier le DNS ou Workers n’est donc pas repris par erreur.
Types d’échec
Section intitulée « Types d’échec »| Type | Réponse de Cloudflare | Comment corriger |
|---|---|---|
permission |
400 avec le code 9106 (un jeton invalide), 401, 403 (le jeton n’a pas Billing Read, ou l’identifiant de compte est erroné : Cloudflare répond aux deux par le code 10000) |
Vérifiez la permission du jeton et billing_cloudflare_account_id |
not_enabled |
L’utilisation facturable du compte n’est pas couverte | Le compte n’est pas facturé à l’usage (un contrat Enterprise) ; il n’y a donc rien à importer |
not_found |
404 |
Vérifiez billing_cloudflare_account_id |
throttled |
429 |
La tâche réessaie après une pause |
unavailable |
5xx, échec réseau | La tâche réessaie après une pause |
invalid_response |
Une réponse illisible, un enregistrement sur plus d’un jour, deux devises dans un même mois | Cloudflare a changé sa réponse ; signalez-le |
Réessayer ne peut pas corriger un échec autre que throttled et unavailable ; le serveur l’enregistre donc et s’arrête, et l’import planifié du lendemain réessaie.
Un plugin (billing_sources = plugin)
Section intitulée « Un plugin (billing_sources = plugin) »Pour un fournisseur dont le serveur n’a pas d’adaptateur, comme Azure, Hetzner ou Sakura, exécutez un plugin de type billing et laissez-le lire les données du fournisseur. Le serveur n’a qu’une seule source plugin. Un plugin qui gère plusieurs fournisseurs les agrège lui-même et les distingue par les noms de ses services.
billing_sources = "plugin"plugin_billing_address = "unix:///run/my/billing.sock"plugin_billing_location = "Europe/Berlin"plugin_billing_provider = "Hetzner"Les trois paramètres sont obligatoires avec cette source, et le serveur démarre sans appeler le plugin, même s’il est hors service.
plugin_billing_locationest le fuseau horaire qui découpe les mois de facturation du plugin.plugin_billing_providerest le nom du fournisseur dans les totaux, sur la page des imports de facturation et dans le journal d’audit.
Le serveur demande au plugin le mois en cours et, comme pour les autres sources, le précédent jusqu’au 15 ou jusqu’à ce qu’il soit définitif. Les plafonds des autres sources ne s’appliquent pas : max_requests vaut 2147483647, ce qui signifie aucun plafond, et le plugin décide de ce qu’il peut dépenser. Il indique les requêtes et les octets qui lui ont été facturés, que le serveur enregistre et affiche.
Ce type autorise le TCP simple, avec un avertissement au démarrage, puisqu’il ne transporte que des coûts. Un jeton bearer exige https:// ou un socket Unix : voir la destination d’un plugin.
Avec plugin_billing_protocol = json, la valeur par défaut, un plugin n’a besoin que d’un serveur HTTP et d’une bibliothèque JSON (Un plugin sans bibliothèque). Fetch dure au plus 2 minutes, ou plugin_billing_timeout, inférieur à 5 minutes.
POST /my.plugin.billing.v1.BillingService/FetchContent-Type: application/json
{"months":["2026-09","2026-10"],"maxRequests":2147483647}HTTP/1.1 200 OKContent-Type: application/json
{ "outcome": "OUTCOME_OK", "requests": 1, "lines": [ { "month": "2026-09", "coveredStart": "2026-09-01", "coveredEnd": "2026-09-30", "service": "Hetzner Cloud", "chargeType": "CHARGE_TYPE_USAGE", "category": "CATEGORY_COMPUTE", "amount": "12.3456", "currency": "EUR", "final": true } ]}- Une ligne est un mois, un service et un type de frais, avec ses lignes compensatoires, crédits et remboursements sommés.
servicea au plus 200 caractères et aucun caractère de contrôle. coveredStartetcoveredEndsont à l’intérieur du mois : le mois entier quandfinalest vrai, jusqu’au dernier jour avec des données avant cela sinon.amountest une décimale non arrondie en unités principales, qui peut être négative.currencyest un code ISO 4217.chargeTypeestCHARGE_TYPE_suivi deUSAGE,CREDIT,REFUND,TAX,SUPPORT,FEE,ADJUSTMENTouOTHER.categoryestCATEGORY_suivi deCOMPUTE,DATABASE,STORAGE,NETWORK,DOMAIN,EMAIL,SOFTWAREouOTHER.requestsest au plusmaxRequests.bytesBilledest une chaîne décimale, pour un prestataire qui facture à l’octet.- Une clé que
OUTCOME_OKne renvoie pas n’a aucun coût dans son mois : le serveur enregistre donc une révision de 0 pour elle. Un plugin qui n’a pas pu lire un prestataire doit signaler un échec, et non omettre ses lignes. - Les appels peuvent se répéter : une nouvelle tentative d’un import échoué est le même appel de nouveau.
maxRequests à 0 interdit toute requête facturée. Le serveur n’effectue aucun appel quand il enverrait 0, mais my plugin test --kind billing le fait, avec le champ omis comme le permet la correspondance de proto3, et attend OUTCOME_REQUEST_CAP sans ligne et sans requête.
Types d’échec
Section intitulée « Types d’échec »Un plugin signale un échec dans outcome. Le serveur conserve les requests d’un échec, ignore ses lignes et laisse les imports précédents tels quels, comme pour les autres sources.
| Outcome | Type | Réessayé |
|---|---|---|
OUTCOME_PERMISSION |
permission |
Non |
OUTCOME_NOT_ENABLED |
not_enabled |
Non |
OUTCOME_NOT_FOUND |
not_found |
Non |
OUTCOME_THROTTLED |
throttled |
Oui |
OUTCOME_REQUEST_CAP |
request_cap |
Non |
OUTCOME_BYTES_CAP |
bytes_cap |
Non |
OUTCOME_INVALID_RESPONSE |
invalid_response |
Non |
OUTCOME_UNAVAILABLE |
unavailable |
Oui |
| Un outcome manquant ou inconnu, ou une ligne ou un nombre qui enfreint les règles ci-dessus | invalid_response |
Non |
| Une erreur HTTP ou Connect, un délai dépassé, une réponse de plus de 4 MiB, aucune réponse | unavailable |
Oui |
Ce qui n’est pas réessayé attend l’import quotidien suivant. La raison d’un échec figure dans le journal du plugin, puisque le serveur écarte le message d’une erreur, et il est aussi compté dans my.plugin.failures.
Le tester
Section intitulée « Le tester »my plugin test --kind billing unix:///run/my/billing.sockmy plugin test --kind billing --billed unix:///run/my/billing.sockLa première n’effectue aucune requête facturée si le plugin respecte le contrat. La seconde effectue aussi une vraie récupération, qui peut coûter de l’argent auprès des prestataires du plugin. Voir Tester un plugin.
Pour les LLM et les agents de programmation :llms.txt,llms-full.txt, llms-small.txt