Diese Seite ist eine maschinelle Übersetzung der englischen Seite, die maßgeblich ist. Englische Seite lesen
Cloud-Nutzungskosten importieren
Der Server importiert alle 24 Stunden die Nutzungsentgelte der Anbieter, die in der Einstellung billing_sources aufgeführt sind, oder bei einem Anbieter, für den er keinen Adapter hat, von einem Plugin und fügt sie den Kosten der Instanz hinzu. Der Standard ist leer, was nichts importiert.
Er importiert die Entgelte des aktuellen und des vorigen Abrechnungsmonats (bis zum 15. des Monats oder bis der vorige Monat endgültig ist), als eine Zeile pro Dienst und Entgeltart (Nutzung, Gutschrift, Erstattung, Steuer, Support, Gebühr, Sonstiges).
Bis der Anbieter einen Monat abschließt, werden die Werte als Schätzungen erfasst; nach dem Abschluss als endgültig; und ändert sich ein Wert, nachdem er endgültig ist, als Korrektur. Datensätze der Vergangenheit werden nie umgeschrieben.
Der Zustand der Importe (der letzte Erfolg, die Art des letzten Fehlers und die Zahl der Anfragen in diesem Monat) wird auf der Seite „Abrechnungsimporte“ unter „Kosten und Einnahmen“ in der Administration (/admin/finance/imports) angezeigt, die auch jeden Abrechnungsmonat als geschätzt, endgültig oder korrigiert auflistet, mit „Jetzt importieren“, sowie von GET /api/v1/admin/billing_imports.
Die Metriken zählen jeden Versuch nach Quelle, Ergebnis und Fehlerart (my.billing.imports) und melden die Quellen, deren neuester Versuch fehlgeschlagen ist (my.billing.import.failing);
Alarme und Runbook hat den Alarm dazu.
Für AWS und Google Cloud werden in der Konfiguration dieses Servers keine Zugangsdaten gehalten. Gib der Laufzeitumgebung das, was die Standard-Credential-Chain des SDK jedes Anbieters liest (bei AWS die Ausführungsrolle, Umgebungsvariablen oder gemeinsame Credential-Dateien; bei Google Cloud Application Default Credentials).
Cloudflare hat keine solche Chain, daher liest sein Import ein API-Token aus billing_cloudflare_api_token.
Mit den OpenTofu-Modulen
Abschnitt betitelt „Mit den OpenTofu-Modulen“Auf Google Cloud setzt der Abschnitt billing von mycroblog-gcp billing_sources = gcp und erledigt die Teile dieser Anleitung, die die API des Anbieters erlaubt, mit billing_account_id, method (bigquery oder budget) und dataset_location. Er importiert nur die Kosten von Google Cloud. Auf AWS tut das Modul billing-aws des AWS-Beispiels dasselbe für die Kosten von AWS. Keines wurde bisher auf einem echten Konto angewendet.
| Schritt in dieser Anleitung | Mit den Modulen |
|---|---|
| Die IAM-Richtlinie von AWS | billing-aws |
| Cost Explorer, Linked Account Access und Cost-Allocation-Tags aktivieren | Von Hand, in der AWS-Konsole |
| Das Dataset des Exports und die Rollen von „IAM roles“ | Der Abschnitt billing |
| Den Export aktivieren („Standard usage cost“) | Von Hand, in der Google-Cloud-Konsole, mit einer Rolle auf dem Rechnungskonto |
| Das Topic und die Pull-Subscription eines Budgets sowie die Subscriber-Rolle | Der Abschnitt billing mit method = "budget" |
| Das Budget erstellen und mit dem Topic verbinden | Von Hand, in der Google-Cloud-Konsole, mit einer Rolle auf dem Rechnungskonto |
| Die BigQuery- oder Pub/Sub-API aktivieren | Von Hand, wie unter Auf Cloud Run bereitstellen |
| Die Kosten von AWS auf Cloud Run | Nicht durch mycroblog-gcp. Erstelle die Rolle von Calling from Cloud Run with web identity von Hand und setze billing_sources = aws und billing_aws_role_arn in settings, ohne den Abschnitt billing |
| Cloudflare | Nicht durch diese Module. Setze auf Cloud Run ohne den Abschnitt billing billing_sources und billing_cloudflare_account_id in settings und billing_cloudflare_api_token in secrets, wie bei einem Plugin |
| Ein Plugin | Nicht durch diese Module. Setze auf Cloud Run ohne den Abschnitt billing billing_sources = plugin und die Einstellungen des Plugins in settings. Neben dem Abschnitt billing lehnt das Modul billing_sources in settings ab |
AWS (billing_sources = aws)
Abschnitt betitelt „AWS (billing_sources = aws)“Der Server ruft GetCostAndUsage von AWS Cost Explorer einmal pro Abrechnungsmonat (ein UTC-Kalendermonat) auf, gruppiert nach Dienst (SERVICE) und Datensatzart (RECORD_TYPE). Der Endpunkt ist immer us-east-1.
Beträge sind in USD. Solange Cost Explorer einen Monat als geschätzt markiert (Estimated), erfasst der Server den Betrag bis zum Vortag als Schätzung, und sobald er das nicht mehr tut, als endgültig.
Kosten und Limits
Abschnitt betitelt „Kosten und Limits“Die Cost-Explorer-API berechnet 0,01 $ für jede seitenweise Anfrage. Ein kleines Konto braucht pro Tag eine Anfrage mit einer Seite, etwa 0,31 $ im Monat.
Um unerwartete Kosten zu vermeiden, zählt der Server die Anfragen pro UTC-Tag (billing_aws_max_requests_per_day, Standard 4) und pro UTC-Kalendermonat (billing_aws_max_requests_per_month, Standard 120 = 1,20 $) und hält an, ohne aufzurufen, sobald ein Limit erreicht ist.
Geplante Importe, Job-Wiederholungen und „Jetzt importieren“ in der Administration zählen alle. Ein Import, der ein Limit erreicht, wird als Fehler der Art request_cap erfasst, und der Import des nächsten Tages (beim Tageslimit) oder des ersten Tages des nächsten Monats (beim Monatslimit) versucht es erneut.
Bevor er aufruft, reserviert ein Import die Anfragen, die die Limits übrig lassen, sodass gleichzeitig laufende Importe die Limits nicht gemeinsam überschreiten können.
Importe eines Anbieters laufen nacheinander: Ein Import, der startet, während ein anderer noch nicht fertig ist, versucht es eine Minute später erneut, und ein Job, der bereits erfolgreich importiert hat, ruft nichts auf, wenn er erneut läuft.
Ein Import, der vor dem Ende abgebrochen wurde (der Prozess wurde beendet), zählt die Anfragen, die er reserviert hat, und der nächste Import wartet bis zu 15 Minuten auf ihn.
Cost Explorer aktivieren
Abschnitt betitelt „Cost Explorer aktivieren“- Öffne Cost Explorer in der Konsole Billing and Cost Management und aktiviere ihn. Er lässt sich nach der Aktivierung nicht mehr deaktivieren. Es dauert bis zu 24 Stunden, bis Daten bereit sind.
- Ein Konto, bei dem er nicht aktiviert ist, gibt
DataUnavailableExceptionzurück, und der Import schlägt mitnot_enabledfehl.
IAM-Berechtigungen
Abschnitt betitelt „IAM-Berechtigungen“Die einzige benötigte Berechtigung ist ce:GetCostAndUsage (Ressource *).
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ce:GetCostAndUsage", "Resource": "*" } ]}So übergibst du Zugangsdaten in jeder Laufzeitumgebung:
| Laufzeit | Zugangsdaten |
|---|---|
| AWS ECS | Hänge diese Richtlinie an die Task-Rolle. Es ist keine Konfiguration nötig |
| Google Cloud (Cloud Run) | Lege die IAM-Rolle aus „Von Cloud Run mit Web Identity aufrufen“ unten an und setze ihren ARN in billing_aws_role_arn. Es sind keine AWS-Schlüssel nötig |
| Dein eigener Server | Übergib den Zugriffsschlüssel eines IAM-Benutzers mit dieser Richtlinie in AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (oder eine gemeinsame Credentials-Datei und AWS_PROFILE). Übergib ihn aus einem Secret Store |
Fehlende Berechtigungen oder ungültige Zugangsdaten schlagen mit permission fehl.
Von Cloud Run mit Web Identity aufrufen
Abschnitt betitelt „Von Cloud Run mit Web Identity aufrufen“Wenn billing_aws_role_arn gesetzt ist, bezieht der Server vom Metadatenserver ein Google-ID-Token des Cloud-Run-Dienstkontos (die Audience ist der ARN der Rolle) und tauscht es mit AssumeRoleWithWebIdentity gegen temporäre Zugangsdaten dieser Rolle ein.
-
Notiere in Google Cloud die eindeutige ID (die numerische
uniqueId) des Dienstkontos des Cloud-Run-Dienstes:gcloud iam service-accounts describe <email> --format='value(uniqueId)'. -
Lege in AWS IAM eine Rolle mit der Richtlinie der obigen Berechtigungen an und lass ihre Trust Policy
accounts.google.comvertrauen.{"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:audentspricht demazpdes Tokens (der ID des Dienstkontos) undaccounts.google.com:oauddemauddes Tokens (der Audience, die der Server anfordert und die der ARN der Rolle ist). -
Setze
MY_BILLING_AWS_ROLE_ARN=arn:aws:iam::<account ID>:role/<role name>.
Dieses Setup wurde noch nicht auf einem echten Konto überprüft.
Von einem verknüpften Konto in Organizations aufrufen
Abschnitt betitelt „Von einem verknüpften Konto in Organizations aufrufen“Das Verwaltungskonto von AWS Organizations kann die Kosten jedes Mitgliedskontos der Organisation sehen. Um mit den Zugangsdaten eines Mitgliedskontos (verknüpften Kontos) aufzurufen,
schalte „Linked Account Access“ in den Cost-Explorer-Einstellungen des Verwaltungskontos ein. Ist es aus, wird der Aufruf unabhängig von den IAM-Berechtigungen abgelehnt, und der Import schlägt mit not_enabled oder permission fehl.
Auswählen, welche Kosten importiert werden (Filter)
Abschnitt betitelt „Auswählen, welche Kosten importiert werden (Filter)“Wähle mit billing_aws_filter.
billing_aws_filter |
Importierte Kosten | Zusätzliche Einstellungen |
|---|---|---|
none (Standard) |
Alle Kosten, die die Zugangsdaten sehen können | Keine |
linked_account |
Die Kosten der Mitgliedskonten, die du benennst (LINKED_ACCOUNT) |
billing_aws_linked_accounts (12-stellige Konto-IDs, kommagetrennt) |
tag |
Die Kosten von Ressourcen, die den Cost-Allocation-Tag tragen, den du benennst | billing_aws_tag (key=value, zum Beispiel app=my) |
Das genaueste Setup ist ein AWS-Konto, das diesem Server vorbehalten ist (es kann ein Mitgliedskonto von Organizations sein), importiert mit none (Aufruf mit den Zugangsdaten dieses Kontos) oder linked_account (Aufruf vom Verwaltungskonto).
Steuern, Support-Gebühren und manche Gutschriften können keinen Tag tragen und können aus einem Tag-Filter herausfallen (noch nicht auf einem echten Konto überprüft).
Einen Cost-Allocation-Tag aktivieren (billing_aws_filter = tag)
Abschnitt betitelt „Einen Cost-Allocation-Tag aktivieren (billing_aws_filter = tag)“Ein Tag auf einer Ressource erscheint erst in den Abrechnungsdaten, wenn du ihn als Cost-Allocation-Tag aktivierst.
- Setze denselben Tag (zum Beispiel
app=my) auf die Ressourcen dieses Servers (ECS-Dienste, RDS, S3-Buckets, Load Balancer und so weiter). - Wähle in „Cost allocation tags“ der Konsole Billing and Cost Management den Tag-Schlüssel aus und aktiviere ihn. Es dauert bis zu 24 Stunden, bis ein Tag in dieser Liste erscheint, nachdem du ihn angehängt hast, und weitere bis zu 24 Stunden nach der Aktivierung, bis er in den Abrechnungsdaten erscheint.
- Um die Kosten des Zeitraums vor der Aktivierung zu berücksichtigen, nutze „Backfill“ auf demselben Bildschirm (die API
StartCostAllocationTagBackfill). - Setze
MY_BILLING_AWS_FILTER=tagundMY_BILLING_AWS_TAG=app=my.
billing_aws_metric ist entweder NetUnblendedCost (der Standard, näher an der Rechnung), also nach Rabatten (Savings Plans, Reserved Instances, ausgehandelte Preise), oder UnblendedCost, also vor ihnen.
Die Werte von Cost Explorer und die Rechnung können sich wegen des Zeitpunkts der Aktualisierung und wegen Rundung unterscheiden. Wenn sie sich unterscheiden, hat die Rechnung recht.
Fehlerarten
Abschnitt betitelt „Fehlerarten“| Art | AWS-Antwort | Behebung |
|---|---|---|
permission |
AccessDeniedException, ungültige Zugangsdaten |
Prüfe die IAM-Berechtigungen und wie die Zugangsdaten übergeben werden |
not_enabled |
DataUnavailableException |
Aktiviere Cost Explorer. Aktiviere bei einem verknüpften Konto Linked Account Access |
not_found |
BillExpirationException |
Cost Explorer hat die Abrechnungsdaten des zu importierenden Zeitraums nicht mehr |
throttled |
LimitExceededException |
Der Job versucht es nach einer Pause erneut (es zählt für das Anfragelimit) |
unavailable |
5xx, Netzwerkfehler | Der Job versucht es nach einer Pause erneut (es zählt für das Anfragelimit) |
invalid_response |
Eine unlesbare Antwort, ValidationException und Ähnliches |
Prüfe die Einstellungen (Tag, Konto-IDs) |
request_cap |
(es wird kein Aufruf gemacht) | Warte, bis der Tag oder Monat des Limits vorbei ist, oder erhöhe das Limit |
Eine Wiederholung kann einen anderen Fehler als throttled und unavailable nicht beheben, daher erfasst der Server ihn und hält an, und der geplante Import des nächsten Tages versucht es erneut.
Google Cloud (billing_sources = gcp)
Abschnitt betitelt „Google Cloud (billing_sources = gcp)“Google Cloud hat keine API, die tatsächliche Kosten liefert, daher aggregiert der Server den Cloud-Billing-Export nach BigQuery (Standard usage cost) einmal am Tag mit einem BigQuery-jobs.query (billing_gcp_method = bigquery, der Standard).
Wenn du den Export nicht einrichten kannst, gibt es auch eine einfache Methode, die nur eine ungefähre Summe aus den Pub/Sub-Benachrichtigungen eines Budgets importiert (siehe Aus Budget-Benachrichtigungen importieren).
Der Abrechnungsmonat ist der invoice.month des Exports, ein Kalendermonat in US-Pazifikzeit (mit Sommerzeit). Daten werden unverändert in Pazifikzeit erfasst.
Beträge sind in der Währung des Rechnungskontos und werden als NUMERIC pro Abrechnungsmonat, Dienst (service.description) und Gebührenart (cost_type) summiert; Gutschriften (credits[]) werden zu einer Gutschriftzeile pro Dienst. Die Korrekturzeilen des Exports, die frühere Zeilen aufheben, gehören zur Summe.
Der Export hat keine Markierung für Endgültigkeit, daher behandelt der Import, der ab dem 5. (Pazifikzeit) des Folgemonats läuft, den Monat als endgültig und erfasst ihn bis dahin als Schätzung vom ersten Tag des Monats bis zum Tag der letzten Nutzung. Nachdem er endgültig ist, liest der Import den Monat bis zum 15. weiterhin erneut und erfasst jede Differenz als Korrektur.
Kosten und Limits
Abschnitt betitelt „Kosten und Limits“Ein Import ist eine Abfrage, und BigQuery berechnet die Bytes, die jede Abfrage scannt (mindestens 10 MB). Ein kleines Konto scannt etwa 0,3 GB im Monat, was in die ersten 1 TiB pro Monat des kostenlosen Kontingents passt (geteilt mit anderen Nutzungen des Rechnungskontos), er kostet also 0 $.
Um unerwartete Scans zu vermeiden, trägt jede Abfrage maximumBytesBilled (billing_gcp_max_bytes_billed, Standard 1 GiB). Eine Abfrage, die es überschreiten würde, wird nicht berechnet und schlägt fehl, und sie wird als Fehler der Art bytes_cap erfasst. Die Administration zeigt die abgerechneten Bytes.
Den Export nach BigQuery aktivieren
Abschnitt betitelt „Den Export nach BigQuery aktivieren“Der Betreiber richtet das einmal in der Konsole ein (es wurde kein Weg gefunden, es über eine API einzurichten).
- Lege in einem Projekt, das mit dem Rechnungskonto verknüpft ist, ein BigQuery-Dataset an (zum Beispiel
billing_export). Wähle einen Multi-Region-Standort (USoderEU). Die Daten des laufenden und des vorherigen Monats werden nachgefüllt (bei einer einzelnen Region beginnen die Daten an dem Tag, an dem du ihn aktivierst). Der Standort lässt sich später nicht ändern. Setze kein Ablaufdatum für die Tabellen. Zeilen, die ablaufen, kommen nicht zurück. - Aktiviere unter „Billing > Billing export > BigQuery export“ „Standard usage cost“ und wähle das Dataset aus Schritt 1. Die Einrichtung braucht „Billing Account Costs Manager“ oder „Billing Account Administrator“ für das Rechnungskonto und die Rolle BigQuery User für das Projekt.
- Nach einigen Stunden bis einem Tag wird die Tabelle
gcp_billing_export_v1_<BILLING_ACCOUNT_ID>angelegt (die Bindestriche der ID werden zu_). - Setze
MY_BILLING_GCP_TABLE=<project>.billing_export.gcp_billing_export_v1_<BILLING_ACCOUNT_ID>.
Wenn das Dataset oder die Tabelle nicht gefunden werden kann, schlägt der Import mit not_found fehl.
IAM-Rollen
Abschnitt betitelt „IAM-Rollen“Gib dem Dienstkonto des importierenden Servers diese beiden Rollen.
| Rolle | Wo sie vergeben wird | Verwendung |
|---|---|---|
roles/bigquery.jobUser (BigQuery Job User) |
Das Projekt, das die Abfrage ausführt (billing_gcp_query_project, oder das Projekt der Tabelle, wenn leer) |
bigquery.jobs.create. Die gescannten Bytes werden diesem Projekt berechnet |
roles/bigquery.dataViewer (BigQuery Data Viewer) |
Das Dataset des Exports | 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_exportWenn die BigQuery-API im Abfrageprojekt nicht aktiviert ist, schlägt der Import mit not_enabled fehl, und wenn eine Rolle fehlt, mit permission.
Die Authentifizierung erfolgt über Application Default Credentials (ADC).
| Laufzeit | Zugangsdaten |
|---|---|
| Google Cloud (Cloud Run) | ADC mit dem Dienstkonto des Dienstes. Kein Schlüssel und keine Konfiguration |
| AWS ECS | Lege eine Credential-Konfigurationsdatei der Workload Identity Federation (Typ AWS) ab und übergib ihren Pfad in GOOGLE_APPLICATION_CREDENTIALS (noch nicht auf einem echten Konto überprüft) |
| Dein eigener Server | Workload Identity Federation oder ein JSON-Schlüssel eines Dienstkontos, übergeben in GOOGLE_APPLICATION_CREDENTIALS. Übergib einen Schlüssel aus einem Secret Store |
Auswählen, welche Kosten importiert werden (Filter)
Abschnitt betitelt „Auswählen, welche Kosten importiert werden (Filter)“Standardmäßig importiert der Server alle Kosten des Rechnungskontos. Das genaueste Setup ist ein Rechnungskonto, das diesem Server vorbehalten ist, importiert ohne Filter.
| Einstellung | Importierte Kosten |
|---|---|
billing_gcp_projects (Projekt-IDs, kommagetrennt) |
Die Kosten der Projekte, die du benennst (project.id) |
billing_gcp_label (key=value, zum Beispiel app=my) |
Die Kosten von Ressourcen, die das Label tragen, das du benennst (labels) |
Wenn du beide setzt, importiert der Server nur die Kosten, die auf beide zutreffen. Kosten auf Rechnungsebene, wie Steuern, tragen möglicherweise weder ein Projekt noch ein Label und fallen dann aus dem Filter heraus (noch nicht auf einem echten Konto überprüft).
Fehlerarten
Abschnitt betitelt „Fehlerarten“| Art | BigQuery-Antwort | Behebung |
|---|---|---|
permission |
401, 403 (accessDenied) |
Prüfe die Rollen des Dienstkontos und wie die Zugangsdaten übergeben werden |
not_enabled |
403 (accessNotConfigured und Ähnliches) |
Aktiviere die BigQuery-API im Abfrageprojekt |
not_found |
404 | Prüfe billing_gcp_table und die Einrichtung des Exports |
bytes_cap |
400 (bytesBilledLimitExceeded) |
Der Scan hat billing_gcp_max_bytes_billed überschritten. Erhöhe das Limit, wenn die Tabelle groß ist |
throttled |
429, 403 (rateLimitExceeded, quotaExceeded) |
Der Job versucht es nach einer Pause erneut |
unavailable |
5xx, Netzwerkfehler, eine Abfrage, die nicht endet | Der Job versucht es nach einer Pause erneut |
invalid_response |
Eine unlesbare Antwort, Zeilen, die Währungen innerhalb eines Monats mischen, jedes andere 400 | Prüfe die Exporttabelle (ist es der Standard usage cost?) |
Eine Wiederholung kann einen anderen Fehler als throttled und unavailable nicht beheben, daher erfasst der Server ihn und hält an, und der geplante Import des nächsten Tages versucht es erneut.
Aus Budget-Benachrichtigungen importieren (billing_gcp_method = budget)
Abschnitt betitelt „Aus Budget-Benachrichtigungen importieren (billing_gcp_method = budget)“Das ist eine einfache Methode für den Fall, dass du den BigQuery-Export nicht einrichten kannst. Einmal am Tag liest der Server aus einer Pull-Subscription die Benachrichtigungen, die ein Cloud-Billing-Budget an ein Pub/Sub-Topic sendet. Sie nutzt Pull statt Push, sodass eine Benachrichtigung den Server (zum Beispiel Cloud Run) nie aufweckt.
Diese Methode importiert nur eine ungefähre Summe auf Basis von Schätzungen.
- Der
costAmounteiner Benachrichtigung sind die geschätzten kumulierten Kosten des Budgetzeitraums, ohne Aufschlüsselung nach Dienst oder Gebührenart. Der Server importiert nur eine Zeile pro Monat und Budget (der Dienstname ist der Anzeigename des Budgets, die Gebührenart ist usage und die Kategorie ist other). Gutschriften und Steuern stecken in der Summe, wie das Budget konfiguriert ist. - Wie bei BigQuery wird ein Monat in dem Import endgültig, der ab dem 5. (Pazifikzeit) des Folgemonats läuft. Eine Budget-Benachrichtigung weiß nichts vom Rechnungsabschluss, daher kann sich auch ein als endgültig behandelter Wert vom Rechnungsbetrag unterscheiden.
- Ein geschätzter Monat wird als die Kosten vom ersten Tag des Monats bis zu dem Tag (Pazifikzeit) erfasst, an dem die letzte Benachrichtigung veröffentlicht wurde.
- Die Filterung bestimmt der Geltungsbereich des Budgets (Projekte, Dienste, ein Label-Schlüssel und -Wert);
billing_gcp_projectsundbilling_gcp_labelwerden nicht verwendet.
Das Budget, das Topic und die Subscription vorbereiten
Abschnitt betitelt „Das Budget, das Topic und die Subscription vorbereiten“-
Lege ein Topic und eine Pull-Subscription an, die nur dieser Server liest. Die Gründe für die Aufbewahrungsdauer und den Ablauf findest du unten unter „So werden Benachrichtigungen gelesen“.
Terminal-Fenster 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 -
Lege in der Konsole unter „Billing > Budgets & alerts“ ein Budget an. Mache seinen Zeitraum monatlich (eine Benachrichtigung eines Budgets, das nicht monatlich ist, schlägt mit
invalid_responsefehl). Wähle das Projekt dieses Servers als Geltungsbereich und wähle unter „Manage notifications > Connect a Pub/Sub topic to this budget“ das Topic aus Schritt 1. Das Anlegen des Budgets braucht „Billing Account Costs Manager“ oder „Billing Account Administrator“ für das Rechnungskonto sowiepubsub.topics.setIamPolicyundpubsub.topics.listfür das Projekt des Topics. Die erste Benachrichtigung braucht einige Stunden, bis sie ankommt, und danach kommen mehrere pro Tag an. -
Gib dem Dienstkonto des importierenden Servers
roles/pubsub.subscriber(Pub/Sub Subscriber) für die Subscription. Es wird zum Abrufen von Nachrichten und zu ihrer Bestätigung verwendet (pubsub.subscriptions.consume).Terminal-Fenster gcloud pubsub subscriptions add-iam-policy-binding my-billing-budget --project=<project> \--member=serviceAccount:<service account> --role=roles/pubsub.subscriber -
Setze
MY_BILLING_GCP_METHOD=budgetundMY_BILLING_GCP_BUDGET_SUBSCRIPTION=projects/<project>/subscriptions/my-billing-budget.
Die Authentifizierung erfolgt über dieselben Application Default Credentials wie bei BigQuery (siehe die Tabelle unter IAM-Rollen oben).
So werden Benachrichtigungen gelesen
Abschnitt betitelt „So werden Benachrichtigungen gelesen“- Ein Import wiederholt Pull, bis keine neue Nachricht mehr eintrifft, und nimmt für jedes Budget und jeden Monat die Benachrichtigung mit der jüngsten Veröffentlichungszeit. Das fängt doppelte Pub/Sub-Zustellungen, wiederholte Benachrichtigungen mit demselben Wert und Umsortierungen ab, sodass eine mehrfach empfangene Benachrichtigung nur einmal in die Summe eingeht.
Die Zahl der für einen Import gezählten Anfragen ist die Zahl der Pulls, normalerweise zwei: einer, der Nachrichten liefert, und einer, der leer zurückkommt. Die Bestätigungen am Ende (
Acknowledge,ModifyAckDeadline) werden nicht gezählt. - Der Server bestätigt (ackt) nur eine Benachrichtigung, die durch eine neuere Benachrichtigung desselben Budgets und Monats ersetzt wurde, und eine Benachrichtigung eines Monats, der nicht mehr importiert wird (der Vormonat, sobald er als endgültig erfasst wurde). Die jüngste Benachrichtigung eines importierten Monats wird nicht geackt, sondern an die Subscription zurückgegeben, sodass der nächste Import dieselbe Benachrichtigung erneut liest und sich der Wert an einem Tag ohne neue Benachrichtigung nicht ändert.
- Setze daher die Nachrichtenaufbewahrung der Subscription auf mindestens 14 Tage (31 Tage empfohlen). Die letzte Benachrichtigung des Budgets eines Monats kommt um den 2. des Folgemonats an, und der Vormonat wird bis zum 15. erneut gelesen. Ein Monat, dessen Benachrichtigungen abgelaufen sind, wird als Kosten von 0 erfasst.
- Standardmäßig läuft eine Subscription nach 31 Tagen ohne Nutzung ab. Setze den Ablauf auf „never“, damit sie einen Zeitraum übersteht, in dem Importe gestoppt waren.
- Sende keine anderen Nachrichten an das Topic. Eine Nachricht, die sich nicht als Budget-Benachrichtigung lesen lässt, lässt diesen Import mit
invalid_responsefehlschlagen und wird geackt, damit der nächste Import nicht an ihr hängen bleibt. - Kosten: Einige Dutzend Nachrichten pro Tag passen in das kostenlose Pub/Sub-Kontingent (10 GiB pro Monat), es kostet also 0 $. Der Server setzt kein Limit.
Fehlerarten (Budget-Benachrichtigungen)
Abschnitt betitelt „Fehlerarten (Budget-Benachrichtigungen)“| Art | Pub/Sub-Antwort | Behebung |
|---|---|---|
permission |
PERMISSION_DENIED, UNAUTHENTICATED |
Prüfe roles/pubsub.subscriber für die Subscription und wie die Zugangsdaten übergeben werden |
not_enabled |
PERMISSION_DENIED (SERVICE_DISABLED) |
Aktiviere die Pub/Sub-API im Projekt der Subscription |
not_found |
NOT_FOUND |
Prüfe billing_gcp_budget_subscription und ob die Subscription abgelaufen ist |
throttled |
RESOURCE_EXHAUSTED |
Der Job versucht es nach einer Pause erneut |
unavailable |
UNAVAILABLE, INTERNAL und Ähnliches, Netzwerkfehler |
Der Job versucht es nach einer Pause erneut |
invalid_response |
Eine Nachricht, die sich nicht als Budget-Benachrichtigung lesen lässt, ein Budget, das nicht monatlich ist, zwei Budgets mit demselben Anzeigenamen | Mache das Budget monatlich, gib den Budgets verschiedene Anzeigenamen und sende keine anderen Nachrichten an das Topic |
Cloudflare (billing_sources = cloudflare)
Abschnitt betitelt „Cloudflare (billing_sources = cloudflare)“Der Server liest die abrechenbare Nutzung eines Cloudflare-Kontos: die Nutzungsentgelte seiner nutzungsabhängig abgerechneten Produkte wie R2, Workers und D1, ein Datensatz pro Metrik und Tag.
Er summiert sie nach Produkt (R2, Workers, D1) in UTC-Kalendermonate, sodass jedes Produkt eine Nutzungszeile pro Monat ist. Auch Nutzung innerhalb eines Freikontingents wird importiert, mit 0.
Nur ein nutzungsabhängig abgerechnetes Konto hat diese Daten; ein Konto mit Enterprise-Vertrag schlägt mit not_enabled fehl.
Was nicht importiert wird
Abschnitt betitelt „Was nicht importiert wird“Die abrechenbare Nutzung von Cloudflare enthält nur Nutzungsentgelte. Tarife und Add-ons mit einer festen Gebühr (Pro, Business, Workers Paid und dergleichen), Steuern und Gutschriften sind nicht darin, daher zeigen die Kosten nur den Nutzungsanteil der Rechnung.
Füge die festen Gebühren als eigene Kosten auf der Seite „Kosten“ unter „Kosten und Einnahmen“ (/admin/finance/costs) hinzu oder importiere sie von einem Plugin.
Abrechnungszyklen und endgültige Monate
Abschnitt betitelt „Abrechnungszyklen und endgültige Monate“Cloudflare rechnet in Zyklen ab, die an jedem Monat am selben Tag beginnen, dem Tag des ersten Kaufs des Kontos, in UTC (ein Zyklus, der am 31. beginnen würde, beginnt in einem kürzeren Monat am letzten Tag). Die Rechnung eines Zyklus kommt, wenn der Zyklus endet, sodass ein Kalendermonat Teile zweier Zyklen umfasst. Der Server liest jeden Zyklus, der sich mit den Monaten überschneidet, die er importiert, und ordnet jeden Tagesdatensatz dem Kalendermonat seines Tages zu, sodass die Zeilen eines Monats die Entgelte seiner eigenen Tage sind, nicht die einer Rechnung. Ein Monat ist endgültig, sobald der Zyklus, der seinen letzten Tag enthält, vor zwei Tagen geendet hat, oder sobald der nächste Monat vorbei ist, je nachdem, was zuerst eintritt. Bis dahin ist er eine Schätzung vom Ersten des Monats bis zum letzten Tag mit Daten. Die Daten von Cloudflare hinken ein bis zwei Tage hinterher.
Kosten und Limits
Abschnitt betitelt „Kosten und Limits“Cloudflare berechnet seine API nicht, daher setzt der Server keine Obergrenze für die Anfragen. Ein Import stellt eine Anfrage für die Abonnements des Kontos und eine für jeden Abrechnungszyklus, den er liest: bis zu vier für zwei Monate. Die API erlaubt 1.200 Anfragen alle fünf Minuten pro Benutzer, geteilt mit dem Dashboard und deinen anderen Verwendungen durch den Inhaber des Tokens.
Das API-Token erstellen
Abschnitt betitelt „Das API-Token erstellen“- Öffne im Cloudflare-Dashboard das Konto und notiere seine Konto-ID in der Übersicht des Kontos (32 Hexadezimalziffern).
- Erstelle unter „Manage Account“ → „Account API Tokens“ (oder „My Profile“ → „API Tokens“) ein benutzerdefiniertes Token mit der einzigen Berechtigung Account → Billing → Read, nur für dieses Konto.
- Setze
MY_BILLING_SOURCES=cloudflare,MY_BILLING_CLOUDFLARE_ACCOUNT_ID=<account ID>undMY_BILLING_CLOUDFLARE_API_TOKEN=<token>, das Token aus einem Secret-Store (oderMY_BILLING_CLOUDFLARE_API_TOKEN_FILE).
Gib dem Import ein eigenes Token. Der Server liest nie CLOUDFLARE_API_TOKEN, das Wrangler und der OpenTofu-Provider verwenden, sodass ein Token, das DNS oder Workers bearbeiten kann, nicht versehentlich aufgegriffen wird.
Fehlerarten
Abschnitt betitelt „Fehlerarten“| Art | Antwort von Cloudflare | So behebst du es |
|---|---|---|
permission |
400 mit Code 9106 (ein ungültiges Token), 401, 403 (dem Token fehlt Billing Read, oder die Konto-ID ist falsch: Cloudflare antwortet auf beides mit Code 10000) |
Prüfe die Berechtigung des Tokens und billing_cloudflare_account_id |
not_enabled |
Die abrechenbare Nutzung des Kontos wird nicht abgedeckt | Das Konto wird nicht nutzungsabhängig abgerechnet (ein Enterprise-Vertrag), es gibt also nichts zu importieren |
not_found |
404 |
Prüfe billing_cloudflare_account_id |
throttled |
429 |
Der Job wiederholt nach einer Pause |
unavailable |
5xx, Netzwerkfehler | Der Job wiederholt nach einer Pause |
invalid_response |
Eine unlesbare Antwort, ein Datensatz über mehr als einen Tag, zwei Währungen in einem Monat | Cloudflare hat seine Antwort geändert; melde es |
Eine Wiederholung kann keinen anderen Fehler als throttled und unavailable beheben, daher erfasst der Server ihn und hält an, und der geplante Import des nächsten Tages versucht es erneut.
Ein Plugin (billing_sources = plugin)
Abschnitt betitelt „Ein Plugin (billing_sources = plugin)“Für einen Anbieter, für den der Server keinen Adapter hat, etwa Azure, Hetzner oder Sakura, betreibe ein Plugin der Art billing und lass es die Daten des Anbieters lesen. Der Server hat eine einzige Quelle plugin. Ein Plugin mit mehreren Anbietern aggregiert sie selbst und unterscheidet sie an den Namen seiner Dienste.
billing_sources = "plugin"plugin_billing_address = "unix:///run/my/billing.sock"plugin_billing_location = "Europe/Berlin"plugin_billing_provider = "Hetzner"Die drei Einstellungen sind bei dieser Quelle erforderlich, und der Server startet, ohne das Plugin aufzurufen, auch wenn es ausgefallen ist.
plugin_billing_locationist die Zeitzone, die die Abrechnungsmonate des Plugins abgrenzt.plugin_billing_providerist der Name des Anbieters in den Summen, auf der Seite der Abrechnungsimporte und im Audit-Log.
Der Server fragt das Plugin nach dem aktuellen Monat und, wie bei den anderen Quellen, nach dem vorigen bis zum 15. oder bis er endgültig ist. Die Limits der anderen Quellen gelten nicht: max_requests ist 2147483647, was kein Limit bedeutet, und das Plugin entscheidet, was es ausgeben darf. Es meldet die Anfragen und die Bytes, die ihm berechnet wurden, die der Server erfasst und anzeigt.
Die Art erlaubt einfaches TCP, mit einer Warnung beim Start, da sie nur Kosten überträgt. Ein Bearer-Token braucht https:// oder einen Unix-Socket: siehe das Ziel eines Plugins.
Der Aufruf
Abschnitt betitelt „Der Aufruf“Mit plugin_billing_protocol = json, dem Standard, braucht ein Plugin allein einen HTTP-Server und eine JSON-Bibliothek (Ein Plugin ohne Bibliothek). Fetch dauert höchstens 2 Minuten oder plugin_billing_timeout, unter 5 Minuten.
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 } ]}- Eine Zeile ist ein Monat, ein Dienst und eine Gebührenart, mit ihren ausgleichenden Zeilen, Gutschriften und Erstattungen summiert.
servicehat höchstens 200 Zeichen und keine Steuerzeichen. coveredStartundcoveredEndliegen innerhalb des Monats: der ganze Monat, wennfinalwahr ist, sonst bis zum letzten Tag mit Daten.amountist eine ungerundete Dezimalzahl in Hauptwährungseinheiten, die negativ sein kann.currencyist ein ISO-4217-Code.chargeTypeistCHARGE_TYPE_und eines vonUSAGE,CREDIT,REFUND,TAX,SUPPORT,FEE,ADJUSTMENT,OTHER.categoryistCATEGORY_und eines vonCOMPUTE,DATABASE,STORAGE,NETWORK,DOMAIN,EMAIL,SOFTWARE,OTHER.requestsist höchstensmaxRequests.bytesBilledist ein Dezimal-String, für einen Anbieter, der nach Bytes abrechnet.- Ein Schlüssel, den
OUTCOME_OKnicht zurückgibt, hat in seinem Monat keine Kosten, daher erfasst der Server dafür eine Revision von 0. Ein Plugin, das einen Anbieter nicht lesen konnte, muss einen Fehler melden, nicht seine Zeilen weglassen. - Aufrufe dürfen sich wiederholen: Eine Wiederholung eines fehlgeschlagenen Imports ist derselbe Aufruf noch einmal.
maxRequests 0 verbietet jede abgerechnete Anfrage. Der Server macht keinen Aufruf, wenn er 0 senden würde, aber my plugin test --kind billing tut es, mit weggelassenem Feld, wie es das Mapping von proto3 erlaubt, und erwartet OUTCOME_REQUEST_CAP ohne Zeilen und ohne Anfragen.
Fehlerarten
Abschnitt betitelt „Fehlerarten“Ein Plugin meldet einen Fehler in outcome. Der Server behält die requests eines Fehlers, ignoriert seine Zeilen und lässt die früheren Importe unverändert, wie bei den anderen Quellen.
| Outcome | Art | Wiederholt |
|---|---|---|
OUTCOME_PERMISSION |
permission |
Nein |
OUTCOME_NOT_ENABLED |
not_enabled |
Nein |
OUTCOME_NOT_FOUND |
not_found |
Nein |
OUTCOME_THROTTLED |
throttled |
Ja |
OUTCOME_REQUEST_CAP |
request_cap |
Nein |
OUTCOME_BYTES_CAP |
bytes_cap |
Nein |
OUTCOME_INVALID_RESPONSE |
invalid_response |
Nein |
OUTCOME_UNAVAILABLE |
unavailable |
Ja |
| Ein fehlendes oder unbekanntes Outcome oder eine Zeile oder Zahl, die die obigen Regeln verletzt | invalid_response |
Nein |
| Ein HTTP- oder Connect-Fehler, eine Deadline, eine Antwort über 4 MiB, keine Antwort | unavailable |
Ja |
Was nicht wiederholt wird, wartet auf den nächsten täglichen Import. Der Grund eines Fehlers steht im Log des Plugins, da der Server die Meldung eines Fehlers verwirft, und er zählt außerdem in my.plugin.failures.
my plugin test --kind billing unix:///run/my/billing.sockmy plugin test --kind billing --billed unix:///run/my/billing.sockDer erste macht keine abgerechnete Anfrage, wenn das Plugin den Vertrag einhält. Der zweite macht außerdem einen echten Abruf, der bei den Anbietern des Plugins Geld kosten kann. Siehe Ein Plugin testen.
Für LLMs und Coding-Agenten:llms.txt,llms-full.txt, llms-small.txt