Skip to content

Commit

Permalink
Document usage event validation (#47094)
Browse files Browse the repository at this point in the history
Closes #46392

Clarify whether it is possible to independently validate Teleport's
usage event data by describing the usage event aggregation service. Note
that validation is not possible. To add this information, split up the
"Anonymized usage data" section of the Usage and Billing page, then add
a subsection related to validating reports.
  • Loading branch information
ptgott authored Oct 7, 2024
1 parent ac293e7 commit 384dd62
Showing 1 changed file with 31 additions and 3 deletions.
34 changes: 31 additions & 3 deletions docs/pages/usage-billing.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: Usage Reporting and Billing
description: Provides a detailed breakdown of Teleport usage reporting and billing.
tocDepth: 3
---

Commercial editions of Teleport send anonymized usage data to Teleport so we can
Expand All @@ -10,8 +11,12 @@ the billing metrics we calculate.
## Anonymized usage data

The commercial editions of Teleport send anonymized information to Teleport's
cloud infrastructure at `reporting-teleport.teleportinfra.sh:443`.
This information contains the following:
cloud infrastructure at `reporting-teleport.teleportinfra.sh:443`. This section
describes the usage reporting system.

### Usage reports

Teleport usage reports contain the following information:

- Teleport license identifier.
- Anonymized cluster name and Teleport Auth Service host ID.
Expand All @@ -26,20 +31,24 @@ The count of interactions includes the following:

- Teleport logins
- SSH and Kubernetes exec sessions
- Desktop and Database sessions
- Desktop and database sessions
- Web sessions with registered HTTP applications
- Connections with registered TCP applications
- SSH port forwards
- Kubernetes API requests
- SFTP actions

### Anonymization

The anonymization is done by passing names and IDs through HMAC-SHA-256.
Teleport Cloud clusters use an HMAC key that's randomly generated when
the cluster is initialized. Self-hosted Teleport deployments use an
anonymization key that's generated and embedded in the license file at
download time and never shared with us. This makes it infeasible for anyone
without access to the cluster to deanonymize the data we store.

### How reporting takes place

Each cluster in a [Trusted Clusters](reference/architecture/trustedclusters.mdx) setup
is responsible for reporting about the interactions with its own resources;
therefore, all clusters will periodically reach out to Teleport Cloud to report
Expand All @@ -55,6 +64,25 @@ Set the `TELEPORT_REPORTING_HTTPS_PROXY` and `TELEPORT_REPORTING_HTTP_PROXY`
environment variables to your proxy address. That will apply as the HTTP connect
proxy setting overriding `HTTPS_PROXY` and `HTTP_PROXY` just for outbound usage reporting.

### Validating usage reports

The system that Teleport uses for submitting usage reports is independent of the
system that Teleport uses for submitting audit events.

Teleport processes submit audit events to the Teleport Auth Service, which
stores them on its audit event backend for retrieval by Teleport API clients. In
contrast, usage reports are aggregated on a submission service that runs either
on self-hosted Teleport infrastructure or Teleport Cloud, depending on the
user's plan. The submission service persists usage reports in the case of a
submission failure. After a successful submission, the submission service
deletes the reports.

It is not possible for Teleport users to independently validate usage event
data, as there is no way to set up a third-party usage event destination or
retrieve usage events from a Teleport backend. Reach out to
[email protected] if you have questions about usage reporting on your
Teleport account.

## Billing metrics

Teleport uses the anonymized usage data described in the previous section to
Expand Down

0 comments on commit 384dd62

Please sign in to comment.