Esta página es una traducción automática de la página en inglés, que es la versión de referencia. Leer la página en inglés
Importar los costes de uso de la nube
El servidor importa los cargos de uso de los proveedores enumerados en el ajuste billing_sources, o de un plugin para un proveedor del que no tiene adaptador, cada 24 horas y los añade a los costes de la instancia. El valor predeterminado está vacío, lo que no importa nada.
Importa los cargos del mes de facturación actual y del anterior (hasta el día 15 del mes, o hasta que el mes anterior sea definitivo), como una línea por servicio y tipo de cargo (uso, crédito, reembolso, impuesto, soporte, tarifa, otro).
Hasta que el proveedor cierra un mes, los valores se registran como estimaciones; cuando lo cierra, como definitivos; y cuando un valor cambia después de ser definitivo, como una corrección. Los registros del pasado nunca se reescriben.
El estado de las importaciones (el último éxito, el tipo del último fallo y el número de solicitudes de este mes) se muestra en la página «Importaciones de facturación» de «Costes e ingresos» en la administración (/admin/finance/imports), que también enumera cada mes de facturación como estimado, definitivo o corregido, con «Importar ahora», y mediante GET /api/v1/admin/billing_imports.
Las métricas cuentan cada intento por fuente, resultado y tipo de fallo (my.billing.imports) e informan de las fuentes cuyo último intento falló (my.billing.import.failing);
Alertas y runbook tiene la alerta sobre ellas.
Para AWS y Google Cloud, no se guardan credenciales en la configuración de este servidor. Da al entorno de ejecución lo que lee la cadena de credenciales predeterminada del SDK de cada proveedor (para AWS, el rol de ejecución, las variables de entorno o los archivos de credenciales compartidos; para Google Cloud, las Application Default Credentials).
Cloudflare no tiene tal cadena, así que su importación lee un token de API de billing_cloudflare_api_token.
Con los módulos de OpenTofu
Sección titulada «Con los módulos de OpenTofu»En Google Cloud, la sección billing de mycroblog-gcp fija billing_sources = gcp y hace las partes de esta guía que permite la API del proveedor, con billing_account_id, method (bigquery o budget) y dataset_location. Importa solo los costes de Google Cloud. En AWS, el módulo billing-aws del ejemplo de AWS hace lo mismo para los costes de AWS. Ninguno se ha aplicado todavía en una cuenta real.
| Paso de esta guía | Con los módulos |
|---|---|
| La política IAM de AWS | billing-aws |
| Activar Cost Explorer, Linked Account Access, las etiquetas de asignación de costes | A mano, en la consola de AWS |
| El dataset de la exportación y los roles de «Roles de IAM» | La sección billing |
| Activar la exportación («Standard usage cost») | A mano, en la consola de Google Cloud, con un rol en la cuenta de facturación |
| El topic y la suscripción pull de un presupuesto, y el rol de suscriptor | La sección billing con method = "budget" |
| Crear el presupuesto y conectarlo al topic | A mano, en la consola de Google Cloud, con un rol en la cuenta de facturación |
| Activar la API de BigQuery o Pub/Sub | A mano, como en Desplegar en Cloud Run |
| Los costes de AWS en Cloud Run | No con mycroblog-gcp. Crea a mano el rol de Llamar desde Cloud Run con identidad web y define billing_sources = aws y billing_aws_role_arn en settings, sin la sección billing |
| Cloudflare | No con estos módulos. En Cloud Run, sin la sección billing, define billing_sources, billing_cloudflare_account_id en settings y billing_cloudflare_api_token en secrets, como para un plugin |
| Un plugin | No con estos módulos. En Cloud Run, sin la sección billing, define billing_sources = plugin y los ajustes de el plugin en settings. Junto a la sección billing, el módulo rechaza billing_sources en settings |
AWS (billing_sources = aws)
Sección titulada «AWS (billing_sources = aws)»El servidor llama a GetCostAndUsage de AWS Cost Explorer una vez por mes de facturación (un mes natural en UTC), agrupando por servicio (SERVICE) y tipo de registro (RECORD_TYPE). El endpoint es siempre us-east-1.
Los importes están en USD. Mientras Cost Explorer marca un mes como estimado (Estimated), el servidor registra como estimación el importe hasta el día anterior, y cuando deja de hacerlo, como definitivo.
Costo y límites
Sección titulada «Costo y límites»La API de Cost Explorer cobra 0,01 $ por cada solicitud paginada. Una cuenta pequeña necesita una solicitud de una página al día, unos 0,31 $ al mes.
Para evitar cargos inesperados, el servidor cuenta las solicitudes por día UTC (billing_aws_max_requests_per_day, por defecto 4) y por mes natural UTC (billing_aws_max_requests_per_month, por defecto 120 = 1,20 $), y se detiene sin llamar cuando se alcanza un límite.
Cuentan las importaciones programadas, los reintentos de trabajos y «Importar ahora» en la administración. Una importación que alcanza un límite se registra como un fallo del tipo request_cap, y la importación del día siguiente (para el límite diario) o del primer día del mes siguiente (para el límite mensual) lo intenta de nuevo.
Antes de llamar, una importación reserva las solicitudes que dejan los límites, de modo que las importaciones que se ejecutan a la vez no pueden superarlos en conjunto.
Las importaciones de un proveedor se ejecutan de una en una: una importación que empieza mientras otra no ha terminado lo intenta de nuevo un minuto después, y un trabajo que ya importó con éxito no llama a nada cuando se ejecuta otra vez.
Una importación que se detuvo antes de terminar (el proceso salió) cuenta las solicitudes que había reservado, y la siguiente importación la espera hasta 15 minutos.
Activar Cost Explorer
Sección titulada «Activar Cost Explorer»- Abre Cost Explorer en la consola de Billing and Cost Management y actívalo. No se puede desactivar una vez activado. Los datos tardan hasta 24 horas en estar listos.
- Una cuenta donde no está activado devuelve
DataUnavailableException, y la importación falla connot_enabled.
Permisos de IAM
Sección titulada «Permisos de IAM»El único permiso necesario es ce:GetCostAndUsage (recurso *).
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ce:GetCostAndUsage", "Resource": "*" } ]}Cómo pasar las credenciales en cada entorno de ejecución:
| Entorno de ejecución | Credenciales |
|---|---|
| AWS ECS | Adjunta esta política al rol de la tarea. No hace falta ninguna configuración |
| Google Cloud (Cloud Run) | Crea el rol de IAM de «Llamada desde Cloud Run con identidad web» que aparece más abajo y define su ARN en billing_aws_role_arn. No hacen falta claves de AWS |
| Tu propio servidor | Pasa la clave de acceso de un usuario de IAM con esta política en AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (o un archivo de credenciales compartido y AWS_PROFILE). Pásala desde un almacén de secretos |
Si faltan permisos o las credenciales no son válidas, se falla con permission.
Llamada desde Cloud Run con identidad web
Sección titulada «Llamada desde Cloud Run con identidad web»Cuando billing_aws_role_arn está definido, el servidor obtiene del servidor de metadatos un token de ID de Google de la cuenta de servicio de Cloud Run (la audiencia es el ARN del rol) y lo intercambia por credenciales temporales de ese rol con AssumeRoleWithWebIdentity.
-
En Google Cloud, anota el ID único (el
uniqueIdnumérico) de la cuenta de servicio del servicio de Cloud Run:gcloud iam service-accounts describe <email> --format='value(uniqueId)'. -
En AWS IAM, crea un rol con la política de los permisos anteriores y haz que su política de confianza confíe en
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:audcorresponde alazpdel token (el ID de la cuenta de servicio), yaccounts.google.com:oaudalauddel token (la audiencia que solicita el servidor, que es el ARN del rol). -
Define
MY_BILLING_AWS_ROLE_ARN=arn:aws:iam::<account ID>:role/<role name>.
Esta configuración aún no se ha verificado en una cuenta real.
Llamada desde una cuenta vinculada de Organizations
Sección titulada «Llamada desde una cuenta vinculada de Organizations»La cuenta de administración de AWS Organizations puede ver los costos de todas las cuentas miembro de la organización. Para llamar con las credenciales de una cuenta miembro (vinculada),
activa «Linked Account Access» en las preferencias de Cost Explorer de la cuenta de administración. Mientras está desactivado, la llamada se rechaza sean cuales sean los permisos de IAM, y la importación falla con not_enabled o permission.
Elegir qué costos importar (filtrado)
Sección titulada «Elegir qué costos importar (filtrado)»Elige con billing_aws_filter.
billing_aws_filter |
Costos importados | Configuración adicional |
|---|---|---|
none (por defecto) |
Todos los costos que pueden ver las credenciales | Ninguno |
linked_account |
Los costos de las cuentas miembro que indiques (LINKED_ACCOUNT) |
billing_aws_linked_accounts (IDs de cuenta de 12 dígitos, separados por comas) |
tag |
Los costos de los recursos que llevan la etiqueta de asignación de costos que indiques | billing_aws_tag (key=value, por ejemplo app=my) |
La configuración más precisa es una cuenta de AWS dedicada a este servidor (puede ser una cuenta miembro de Organizations), importada con none (llamando con las credenciales de esa cuenta) o linked_account (llamando desde la cuenta de administración).
Los impuestos, las tarifas de soporte y algunos créditos no pueden llevar etiqueta, y pueden quedar fuera de un filtro por etiqueta (aún no verificado en una cuenta real).
Activar una etiqueta de asignación de costos (billing_aws_filter = tag)
Sección titulada «Activar una etiqueta de asignación de costos (billing_aws_filter = tag)»Una etiqueta de un recurso no aparece en los datos de facturación hasta que la activas como etiqueta de asignación de costos.
- Pon la misma etiqueta (por ejemplo
app=my) en los recursos de este servidor (servicios de ECS, RDS, buckets de S3, balanceadores de carga, etcétera). - En «Cost allocation tags» de la consola de Billing and Cost Management, selecciona la clave de la etiqueta y actívala. Una etiqueta tarda hasta 24 horas en aparecer en esta lista tras adjuntarla, y hasta otras 24 horas tras la activación en aparecer en los datos de facturación.
- Para reflejar los costos del periodo anterior a la activación, usa «Backfill» en la misma pantalla (la API
StartCostAllocationTagBackfill). - Define
MY_BILLING_AWS_FILTER=tagyMY_BILLING_AWS_TAG=app=my.
Métrica
Sección titulada «Métrica»billing_aws_metric es NetUnblendedCost (por defecto, más cercana a la factura), que es el costo tras los descuentos (Savings Plans, instancias reservadas, precios negociados), o UnblendedCost, que es el costo antes de ellos.
Los valores de Cost Explorer y la factura pueden diferir por el momento de la actualización y el redondeo. Cuando difieren, la factura es la que vale.
Tipos de fallo
Sección titulada «Tipos de fallo»| Tipo | Respuesta de AWS | Cómo solucionarlo |
|---|---|---|
permission |
AccessDeniedException, credenciales no válidas |
Comprueba los permisos de IAM y cómo se pasan las credenciales |
not_enabled |
DataUnavailableException |
Activa Cost Explorer. Para una cuenta vinculada, activa Linked Account Access |
not_found |
BillExpirationException |
Cost Explorer ya no tiene los datos de facturación del periodo que se va a importar |
throttled |
LimitExceededException |
El trabajo reintenta tras una pausa (cuenta para el límite de solicitudes) |
unavailable |
5xx, fallo de red | El trabajo reintenta tras una pausa (cuenta para el límite de solicitudes) |
invalid_response |
Una respuesta ilegible, ValidationException y similares |
Comprueba la configuración (etiqueta, IDs de cuenta) |
request_cap |
(no se hace ninguna llamada) | Espera a que pase el día o el mes que limita, o sube el límite |
Reintentar no puede solucionar un fallo que no sea throttled ni unavailable, así que el servidor lo registra y se detiene, y la importación programada del día siguiente lo intenta de nuevo.
Google Cloud (billing_sources = gcp)
Sección titulada «Google Cloud (billing_sources = gcp)»Google Cloud no tiene ninguna API que devuelva los costos reales, así que el servidor agrega una vez al día la exportación de Cloud Billing a BigQuery (costo de uso estándar) con un jobs.query de BigQuery (billing_gcp_method = bigquery, el valor por defecto).
Cuando no puedes configurar la exportación, hay también un método sencillo que importa solo un total aproximado a partir de las notificaciones de Pub/Sub de un presupuesto (consulta Importar desde las notificaciones de un presupuesto).
El mes de facturación es el invoice.month de la exportación, un mes natural en hora del Pacífico de EE. UU. (con horario de verano). Las fechas se registran en hora del Pacífico tal cual.
Los importes están en la moneda de la cuenta de facturación, sumados como NUMERIC por mes de facturación, servicio (service.description) y tipo de cargo (cost_type), y los créditos (credits[]) pasan a ser una línea de crédito por servicio. Las filas de corrección de la exportación que anulan filas anteriores forman parte de la suma.
La exportación no tiene ninguna marca de cierre, así que la importación que se ejecuta a partir del día 5 (hora del Pacífico) del mes siguiente trata el mes como definitivo, y hasta entonces lo registra como una estimación desde el primer día del mes hasta el día del último uso. Una vez definitivo, la importación sigue leyendo el mes hasta el día 15 y registra cualquier diferencia como una corrección.
Costo y límites
Sección titulada «Costo y límites»Una importación es una consulta, y BigQuery factura los bytes que analiza cada consulta (como mínimo 10 MB). Una cuenta pequeña analiza unos 0,3 GB al mes, lo que cabe en el primer 1 TiB mensual del nivel gratuito (compartido con los demás usos de la cuenta de facturación), así que cuesta 0 $.
Para evitar análisis inesperados, cada consulta lleva maximumBytesBilled (billing_gcp_max_bytes_billed, por defecto 1 GiB). Una consulta que lo superara no se factura y falla, y se registra como un fallo del tipo bytes_cap. La administración muestra los bytes facturados.
Activar la exportación a BigQuery
Sección titulada «Activar la exportación a BigQuery»El operador lo configura una sola vez, en la consola (no se ha encontrado ninguna forma de configurarlo mediante una API).
- En un proyecto vinculado a la cuenta de facturación, crea un conjunto de datos de BigQuery (por ejemplo
billing_export). Elige una ubicación multirregión (USoEU). Se rellenan con datos retroactivos el mes actual y el anterior (con una sola región, los datos empiezan el día en que lo activas). La ubicación no se puede cambiar después. No establezcas caducidad en las tablas. Las filas que caducan no vuelven. - En «Billing > Billing export > BigQuery export», activa «Standard usage cost» y selecciona el conjunto de datos del paso 1. La configuración requiere «Billing Account Costs Manager» o «Billing Account Administrator» en la cuenta de facturación y el rol BigQuery User en el proyecto.
- Tras unas horas o un día, se crea la tabla
gcp_billing_export_v1_<BILLING_ACCOUNT_ID>(los guiones del ID pasan a ser_). - Define
MY_BILLING_GCP_TABLE=<project>.billing_export.gcp_billing_export_v1_<BILLING_ACCOUNT_ID>.
Cuando no se encuentra el conjunto de datos o la tabla, la importación falla con not_found.
Roles de IAM
Sección titulada «Roles de IAM»Da a la cuenta de servicio del servidor que importa estos dos roles.
| Rol | Dónde concederlo | Uso |
|---|---|---|
roles/bigquery.jobUser (BigQuery Job User) |
El proyecto que ejecuta la consulta (billing_gcp_query_project, o el proyecto de la tabla cuando está vacío) |
bigquery.jobs.create. Los bytes analizados se facturan a este proyecto |
roles/bigquery.dataViewer (BigQuery Data Viewer) |
El conjunto de datos de la exportación | 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_exportCuando la API de BigQuery no está activada en el proyecto de la consulta, la importación falla con not_enabled, y cuando falta un rol, con permission.
La autenticación usa Application Default Credentials (ADC).
| Entorno de ejecución | Credenciales |
|---|---|
| Google Cloud (Cloud Run) | ADC con la cuenta de servicio del servicio. Sin clave y sin configuración |
| AWS ECS | Coloca un archivo de configuración de credenciales de Workload Identity Federation (el tipo de AWS) y pasa su ruta en GOOGLE_APPLICATION_CREDENTIALS (aún no verificado en una cuenta real) |
| Tu propio servidor | Workload Identity Federation, o una clave JSON de cuenta de servicio pasada en GOOGLE_APPLICATION_CREDENTIALS. Pasa la clave desde un almacén de secretos |
Elegir qué costos importar (filtrado)
Sección titulada «Elegir qué costos importar (filtrado)»Por defecto el servidor importa todos los costos de la cuenta de facturación. La configuración más precisa es una cuenta de facturación dedicada a este servidor, importada sin filtros.
| Configuración | Costos importados |
|---|---|
billing_gcp_projects (IDs de proyecto, separados por comas) |
Los costos de los proyectos que indiques (project.id) |
billing_gcp_label (key=value, por ejemplo app=my) |
Los costos de los recursos que llevan la etiqueta que indiques (labels) |
Cuando defines ambos, el servidor importa solo los costos que coinciden con los dos. Los costos a nivel de factura, como los impuestos, pueden no llevar ni proyecto ni etiqueta, y entonces quedan fuera del filtro (aún no verificado en una cuenta real).
Tipos de fallo
Sección titulada «Tipos de fallo»| Tipo | Respuesta de BigQuery | Cómo solucionarlo |
|---|---|---|
permission |
401, 403 (accessDenied) |
Comprueba los roles de la cuenta de servicio y cómo se pasan las credenciales |
not_enabled |
403 (accessNotConfigured y similares) |
Activa la API de BigQuery en el proyecto de la consulta |
not_found |
404 | Comprueba billing_gcp_table y la configuración de la exportación |
bytes_cap |
400 (bytesBilledLimitExceeded) |
El análisis superó billing_gcp_max_bytes_billed. Sube el límite si la tabla es grande |
throttled |
429, 403 (rateLimitExceeded, quotaExceeded) |
El trabajo reintenta tras una pausa |
unavailable |
5xx, fallo de red, una consulta que no termina | El trabajo reintenta tras una pausa |
invalid_response |
Una respuesta ilegible, filas que mezclan monedas dentro de un mes, cualquier otro 400 | Comprueba la tabla de exportación (¿es el costo de uso estándar?) |
Reintentar no puede solucionar un fallo que no sea throttled ni unavailable, así que el servidor lo registra y se detiene, y la importación programada del día siguiente lo intenta de nuevo.
Importar desde las notificaciones de un presupuesto (billing_gcp_method = budget)
Sección titulada «Importar desde las notificaciones de un presupuesto (billing_gcp_method = budget)»Es un método sencillo para cuando no puedes configurar la exportación a BigQuery. Una vez al día, el servidor lee desde una suscripción pull las notificaciones que un presupuesto de Cloud Billing envía a un tema de Pub/Sub. Usa pull en lugar de push, de modo que una notificación nunca despierta al servidor (Cloud Run, por ejemplo).
Este método importa solo un total aproximado basado en estimaciones.
- El
costAmountde una notificación es el costo acumulado estimado del periodo del presupuesto, sin desglose por servicio ni tipo de cargo. El servidor importa solo una línea por mes y presupuesto (el nombre del servicio es el nombre visible del presupuesto, el tipo de cargo es uso y la categoría es otra). Los créditos y los impuestos están en el total según esté configurado el presupuesto. - Igual que con BigQuery, un mes pasa a ser definitivo en la importación que se ejecuta a partir del día 5 (hora del Pacífico) del mes siguiente. Una notificación de presupuesto no sabe nada del cierre de la factura, así que incluso un valor tratado como definitivo puede diferir del importe de la factura.
- Un mes estimado se registra como el costo desde el primer día del mes hasta el día (hora del Pacífico) en que se publicó la última notificación.
- El filtrado lo decide el alcance del presupuesto (proyectos, servicios, una clave y un valor de etiqueta), y no se usan
billing_gcp_projectsnibilling_gcp_label.
Preparar el presupuesto, el tema y la suscripción
Sección titulada «Preparar el presupuesto, el tema y la suscripción»-
Crea un tema y una suscripción pull que lea solo este servidor. Consulta «Cómo se leen las notificaciones» más abajo para saber el porqué del periodo de retención y de la caducidad.
Ventana 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 -
En la consola, en «Billing > Budgets & alerts», crea un presupuesto. Haz que su periodo sea mensual (una notificación de un presupuesto que no sea mensual falla con
invalid_response). Selecciona el proyecto de este servidor como alcance y, en «Manage notifications > Connect a Pub/Sub topic to this budget», selecciona el tema del paso 1. Crear el presupuesto requiere «Billing Account Costs Manager» o «Billing Account Administrator» en la cuenta de facturación, ypubsub.topics.setIamPolicyypubsub.topics.listen el proyecto del tema. La primera notificación tarda unas horas en llegar y, después, llegan varias al día. -
Da a la cuenta de servicio del servidor que importa
roles/pubsub.subscriber(Pub/Sub Subscriber) en la suscripción. Se usa para extraer mensajes y confirmarlos (pubsub.subscriptions.consume).Ventana de terminal gcloud pubsub subscriptions add-iam-policy-binding my-billing-budget --project=<project> \--member=serviceAccount:<service account> --role=roles/pubsub.subscriber -
Define
MY_BILLING_GCP_METHOD=budgetyMY_BILLING_GCP_BUDGET_SUBSCRIPTION=projects/<project>/subscriptions/my-billing-budget.
La autenticación son las mismas Application Default Credentials que para BigQuery (consulta la tabla de Roles de IAM más arriba).
Cómo se leen las notificaciones
Sección titulada «Cómo se leen las notificaciones»- Una importación repite Pull hasta que no llega ningún mensaje nuevo, y toma, para cada presupuesto y mes, la notificación con la hora de publicación más reciente. Esto absorbe las entregas duplicadas de Pub/Sub, las notificaciones repetidas con el mismo valor y los cambios de orden, así que recibir la misma notificación muchas veces cuenta una sola vez en el total.
El número de solicitudes contadas por una importación es el número de Pull, normalmente dos: uno que devuelve mensajes y otro que vuelve vacío. Las confirmaciones hechas al final (
Acknowledge,ModifyAckDeadline) no se cuentan. - El servidor confirma (ack) solo una notificación que ha sustituido otra más reciente del mismo presupuesto y mes, y una notificación de un mes que ya no se importa (el mes anterior, una vez registrado como definitivo). La última notificación de un mes importado no se confirma sino que se devuelve a la suscripción, de modo que la siguiente importación vuelve a leer la misma notificación y el valor no cambia en un día sin ninguna notificación nueva.
- Por eso, define la retención de mensajes de la suscripción en al menos 14 días (se recomiendan 31 días). La última notificación del presupuesto de un mes llega hacia el día 2 del mes siguiente, y el mes anterior se vuelve a leer hasta el día 15. Un mes cuyas notificaciones han caducado se registra como un costo de 0.
- Por defecto una suscripción caduca tras 31 días sin uso. Define la caducidad en «never» para que sobreviva a un periodo en el que se detuvieron las importaciones.
- No envíes otros mensajes al tema. Un mensaje que no se puede leer como notificación de presupuesto hace fallar esa importación con
invalid_response, y se confirma para que la siguiente importación no se quede atascada en él. - Costo: unas pocas decenas de mensajes al día caben en el nivel gratuito de Pub/Sub (10 GiB al mes), así que cuesta 0 $. El servidor no establece ningún límite.
Tipos de fallo (notificaciones de presupuesto)
Sección titulada «Tipos de fallo (notificaciones de presupuesto)»| Tipo | Respuesta de Pub/Sub | Cómo solucionarlo |
|---|---|---|
permission |
PERMISSION_DENIED, UNAUTHENTICATED |
Comprueba roles/pubsub.subscriber en la suscripción y cómo se pasan las credenciales |
not_enabled |
PERMISSION_DENIED (SERVICE_DISABLED) |
Activa la API de Pub/Sub en el proyecto de la suscripción |
not_found |
NOT_FOUND |
Comprueba billing_gcp_budget_subscription y si la suscripción ha caducado |
throttled |
RESOURCE_EXHAUSTED |
El trabajo reintenta tras una pausa |
unavailable |
UNAVAILABLE, INTERNAL y similares, fallo de red |
El trabajo reintenta tras una pausa |
invalid_response |
Un mensaje que no se puede leer como notificación de presupuesto, un presupuesto que no es mensual, dos presupuestos con el mismo nombre visible | Haz el presupuesto mensual, da a los presupuestos nombres visibles distintos y no envíes otros mensajes al tema |
Cloudflare (billing_sources = cloudflare)
Sección titulada «Cloudflare (billing_sources = cloudflare)»El servidor lee el uso facturable de una cuenta de Cloudflare: los cargos de uso de sus productos de pago por uso, como R2, Workers y D1, un registro por métrica y día.
Los suma por producto (R2, Workers, D1) en meses naturales UTC, de modo que cada producto es una línea de uso al mes. El uso dentro de una franja gratuita también se importa, con valor 0.
Solo una cuenta facturada por pago por uso tiene estos datos; una cuenta con contrato Enterprise falla con not_enabled.
Lo que no importa
Sección titulada «Lo que no importa»El uso facturable de Cloudflare contiene solo cargos de uso. Los planes y complementos con tarifa fija (Pro, Business, Workers Paid y similares), los impuestos y los créditos no están en él, así que los costes muestran solo la parte de uso de la factura.
Añade las tarifas fijas como costes propios en la página «Costes» de «Costes e ingresos» (/admin/finance/costs), o impórtalas desde un plugin.
Ciclos de facturación y meses definitivos
Sección titulada «Ciclos de facturación y meses definitivos»Cloudflare factura en ciclos que empiezan el mismo día de cada mes, el día de la primera compra de la cuenta, en UTC (un ciclo que empezaría el 31 empieza el último día de un mes más corto). La factura de un ciclo llega cuando el ciclo termina, así que un mes natural abarca partes de dos ciclos. El servidor lee cada ciclo que se solapa con los meses que importa y coloca cada registro diario en el mes natural de su día, de modo que las líneas de un mes son los cargos de sus propios días, no de una factura. Un mes es definitivo cuando el ciclo que contiene su último día terminó hace dos días, o cuando termina el mes siguiente, lo que ocurra primero. Hasta entonces es una estimación desde el primer día del mes hasta el último día con datos. Los datos de Cloudflare van uno o dos días por detrás.
Costo y límites
Sección titulada «Costo y límites»Cloudflare no cobra por su API, así que el servidor no fija ningún tope de solicitudes. Una importación hace una solicitud para las suscripciones de la cuenta y una por cada ciclo de facturación que lee: hasta cuatro para dos meses. La API permite 1200 solicitudes cada cinco minutos por usuario, compartidas con el panel y con tus demás usos del propietario del token.
Crear el token de API
Sección titulada «Crear el token de API»- En el panel de Cloudflare, abre la cuenta y anota su ID de cuenta en la vista general de la cuenta (32 dígitos hexadecimales).
- En «Manage Account» → «Account API Tokens» (o «My Profile» → «API Tokens»), crea un token personalizado con el único permiso Account → Billing → Read, solo para esta cuenta.
- Define
MY_BILLING_SOURCES=cloudflare,MY_BILLING_CLOUDFLARE_ACCOUNT_ID=<account ID>yMY_BILLING_CLOUDFLARE_API_TOKEN=<token>, con el token procedente de un almacén de secretos (oMY_BILLING_CLOUDFLARE_API_TOKEN_FILE).
Da a la importación un token propio. El servidor nunca lee CLOUDFLARE_API_TOKEN, que usan Wrangler y el proveedor de OpenTofu, de modo que un token que puede editar DNS o Workers no se toma por error.
Tipos de fallo
Sección titulada «Tipos de fallo»| Tipo | Respuesta de Cloudflare | Cómo solucionarlo |
|---|---|---|
permission |
400 con el código 9106 (un token no válido), 401, 403 (el token no tiene Billing Read, o el ID de cuenta es incorrecto: Cloudflare responde a ambos con el código 10000) |
Comprueba el permiso del token y billing_cloudflare_account_id |
not_enabled |
El uso facturable de la cuenta no está cubierto | La cuenta no se factura por pago por uso (un contrato Enterprise), así que no hay nada que importar |
not_found |
404 |
Comprueba billing_cloudflare_account_id |
throttled |
429 |
El trabajo reintenta tras una pausa |
unavailable |
5xx, fallo de red | El trabajo reintenta tras una pausa |
invalid_response |
Una respuesta ilegible, un registro de más de un día, dos monedas en un mes | Cloudflare cambió su respuesta; infórmalo |
Reintentar no puede arreglar un fallo que no sea throttled ni unavailable, así que el servidor lo registra y se detiene, y la importación programada del día siguiente lo intenta de nuevo.
Un plugin (billing_sources = plugin)
Sección titulada «Un plugin (billing_sources = plugin)»Para un proveedor del que el servidor no tiene adaptador, como Azure, Hetzner o Sakura, ejecuta un plugin del tipo billing y deja que lea los datos del proveedor. El servidor tiene una sola fuente plugin. Un plugin con varios proveedores los agrega por sí mismo y los distingue por los nombres de sus servicios.
billing_sources = "plugin"plugin_billing_address = "unix:///run/my/billing.sock"plugin_billing_location = "Europe/Berlin"plugin_billing_provider = "Hetzner"Los tres ajustes son obligatorios con esta fuente, y el servidor arranca sin llamar al plugin, incluso cuando está caído.
plugin_billing_locationes la zona horaria que delimita los meses de facturación del plugin.plugin_billing_provideres el nombre del proveedor en los totales, en la página de importaciones de facturación y en el registro de auditoría.
El servidor pide al plugin el mes actual y, como con las otras fuentes, el anterior hasta el día 15 o hasta que sea definitivo. Los topes de las otras fuentes no se aplican: max_requests es 2147483647, lo que significa sin tope, y el plugin decide lo que puede gastar. Informa de las solicitudes y de los bytes por los que se le facturó, que el servidor registra y muestra.
El tipo permite TCP sin cifrar, con una advertencia al arrancar, ya que solo transporta costes. Un token bearer necesita https:// o un socket Unix: consulta el destino de un plugin.
La llamada
Sección titulada «La llamada»Con plugin_billing_protocol = json, el valor por defecto, un plugin solo necesita un servidor HTTP y una biblioteca JSON (Un plugin sin biblioteca). Fetch dura 2 minutos como máximo, o plugin_billing_timeout, por debajo de 5 minutos.
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 } ]}- Una línea es un mes, un servicio y un tipo de cargo, con sus líneas compensatorias, créditos y reembolsos sumados.
servicetiene como máximo 200 caracteres y ningún carácter de control. coveredStartycoveredEndestán dentro del mes: el mes entero cuandofinales true, hasta el último día con datos antes.amountes un decimal sin redondear en unidades mayores, que puede ser negativo.currencyes un código ISO 4217.chargeTypeesCHARGE_TYPE_y uno deUSAGE,CREDIT,REFUND,TAX,SUPPORT,FEE,ADJUSTMENT,OTHER.categoryesCATEGORY_y una deCOMPUTE,DATABASE,STORAGE,NETWORK,DOMAIN,EMAIL,SOFTWARE,OTHER.requestses como máximomaxRequests.bytesBilledes una cadena decimal, para un proveedor que factura por bytes.- Una clave que
OUTCOME_OKno devuelve no tiene costo en su mes, así que el servidor registra para ella una revisión de 0. Un plugin que no pudo leer un proveedor debe informar de un fallo, no omitir sus líneas. - Las llamadas pueden repetirse: un reintento de una importación fallida es la misma llamada otra vez.
maxRequests 0 prohíbe cualquier solicitud facturada. El servidor no hace ninguna llamada cuando enviaría 0, pero my plugin test --kind billing sí la hace, con el campo omitido como permite la asignación de proto3, y espera OUTCOME_REQUEST_CAP sin líneas y sin solicitudes.
Tipos de fallo
Sección titulada «Tipos de fallo»Un plugin informa de un fallo en outcome. El servidor conserva los requests de un fallo, ignora sus líneas y deja las importaciones anteriores como están, igual que con los demás orígenes.
| Resultado | Tipo | Se reintenta |
|---|---|---|
OUTCOME_PERMISSION |
permission |
No |
OUTCOME_NOT_ENABLED |
not_enabled |
No |
OUTCOME_NOT_FOUND |
not_found |
No |
OUTCOME_THROTTLED |
throttled |
Sí |
OUTCOME_REQUEST_CAP |
request_cap |
No |
OUTCOME_BYTES_CAP |
bytes_cap |
No |
OUTCOME_INVALID_RESPONSE |
invalid_response |
No |
OUTCOME_UNAVAILABLE |
unavailable |
Sí |
| Un resultado ausente o desconocido, o una línea o un recuento que incumple las reglas anteriores | invalid_response |
No |
| Un error HTTP o de Connect, un plazo vencido, una respuesta de más de 4 MiB, ninguna respuesta | unavailable |
Sí |
Lo que no se reintenta espera a la siguiente importación diaria. El motivo de un fallo está en el registro del plugin, ya que el servidor descarta el mensaje de un error, y también cuenta en my.plugin.failures.
Probarlo
Sección titulada «Probarlo»my plugin test --kind billing unix:///run/my/billing.sockmy plugin test --kind billing --billed unix:///run/my/billing.sockLa primera no hace ninguna solicitud facturada si el plugin cumple el contrato. La segunda hace además una obtención real, que puede costar dinero en los proveedores del plugin. Consulta Probar un plugin.
Para LLM y agentes de programación:llms.txt,llms-full.txt, llms-small.txt