Add Waypoint proxy L7 logging docs by alexh-tigera · Pull Request #2848 · tigera/docs

alexh-tigera · 2026-07-10T22:27:45Z

Adds docs for Waypoint proxy L7 logging.

Product Version(s):

Calico Enterprise v3.24-1

Issue:
https://tigera.atlassian.net/browse/EV-6388

Link to docs preview:
https://deploy-preview-2848--calico-docs-preview-next.netlify.app/calico-enterprise/next/observability/elastic/l7/enable-waypoint-collector

SME review:

An SME has approved this change.

DOCS review:

A member of the docs team has approved this change.

Additional information:

Merge checklist:

Deploy preview inspected wherever changes were made
Build completed successfully
Test have passed

netlify · 2026-07-10T22:27:50Z

✅ Deploy Preview for calico-docs-preview-next ready!

Name	Link
🔨 Latest commit	`e618432`
🔍 Latest deploy log	https://app.netlify.com/projects/calico-docs-preview-next/deploys/6a57eda76c12140008f7cd36
😎 Deploy Preview	https://deploy-preview-2848--calico-docs-preview-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-07-10T22:27:51Z

✅ Deploy Preview succeeded!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`e618432`
🔍 Latest deploy log	https://app.netlify.com/projects/tigera/deploys/6a57eda7a1228400086091e6
😎 Deploy Preview	https://deploy-preview-2848--tigera.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 94 (🟢 up 20 from production) Accessibility: 98 (no change from production) Best Practices: 92 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot

Pull request overview

Adds Calico Enterprise documentation for enabling and viewing L7 logs collected via Istio Ambient Mode Waypoint proxies (EV-6388), and updates the L7 data types page to list the Waypoint collector alongside existing collectors.

Changes:

Publishes the previously-draft Waypoint collector page with enable/disable/remove steps and viewing guidance.
Updates the L7 collector list in datatypes.mdx to include the new Waypoint collector entry.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
calico-enterprise/observability/elastic/l7/enable-waypoint-collector.mdx	Adds end-user instructions for enabling Waypoint-based L7 logging and where to view logs.
calico-enterprise/observability/elastic/l7/datatypes.mdx	Adds Waypoint to the list of supported L7 collectors.

+## Prerequisites

-This page is a placeholder. Content for L7 log collection via Istio Ambient Mode Waypoint proxies is pending.
+- A workload running in an [Istio Service Mesh](compliance/istio/deploy-istio-ambient).


+Once a workload is set up to be in the service mesh, L7 collection is enabled
+by adding a [waypoint proxy](https://istio.io/latest/docs/ambient/usage/waypoint/),
+and labeling the workload to use it.


+L7 Ambient Mode logs are viewed in the [UI for L7
+logs](observability/elastic/l7/configure#view-l7-logs-in-the-web-console) along
+with the other types of L7 logs.


+They will be labeled with the `collector_type`: `envoy-access-log` and the
+`collector_name`: `waypoint`.


electricjesus · 2026-07-10T23:11:42Z

 - **Envoy** — the legacy sidecar/proxy-based collector. See [Enable Envoy collector](configure.mdx).
 - **eBPF** — kernel TCP-layer probes capturing HTTP request/response and TLS handshake metadata. See [Enable eBPF collector](enable-ebpf-collector.mdx).
-{/* TODO: re-add the Waypoint collector bullet when the Waypoint PR lands. */}
+- **Waypoint** — Istio Ambient Mode HTTP logging via the Waypoint Proxy. See [Enable Waypoint collector](enable-waypoint-collector.mdx).


nice.. one follow-on though: the table below still tags collector_type/collector_name as eBPF only (ebpf / ebpf-tcp), so someone landing here for the envoy-access-log / waypoint values won't find them. could we add waypoint to the Populated-by column? protocol/protocol_version look eBPF-only too.

electricjesus · 2026-07-10T23:11:42Z

-draft: true
 ---

 # Collect L7 logs using the Waypoint collector


now that this page exists, overview.mdx still has three placeholders pointing at it: lines 24, 31, 45 all say "re-add ... when the Waypoint PR lands" (the collector bullet, the comparison-table column, the Next steps link). since this is that PR, could we wire those up here too? otherwise the overview page has no path to this one.

Fixed in 7558e78

electricjesus · 2026-07-10T23:11:42Z

 # Collect L7 logs using the Waypoint collector

-Enable the Istio Ambient Mode Waypoint-based L7 collector to capture HTTP/1, HTTP/2, and gRPC traffic routed through a Waypoint proxy. For background on what the collector does and how it compares to other options, see [L7 logs overview](overview.mdx).
+Enable the Istio Ambient Mode Waypoint-based L7 collector to capture HTTP traffic.


tiny: waypoint rides Envoy access logs so it also picks up HTTP/2 and gRPC, not just HTTP/1. the old draft on this line said "HTTP/1, HTTP/2, and gRPC".. worth keeping that (and matching the datatypes bullet)?

Fixed in 89d8cbf

electricjesus · 2026-07-10T23:11:42Z

-## Before you begin
+Once a workload is set up to be in the service mesh, L7 collection is enabled
+by adding a [waypoint proxy](https://istio.io/latest/docs/ambient/usage/waypoint/),
+and labeling the workload to use it.


nit: this says label the workload, but the command below labels the namespace.. match the wording?

Fixed in 89d8cbf

electricjesus · 2026-07-10T23:11:42Z

+## Removing the L7 Ambient Mode Collector
+
+```bash
+kubectl label namespace <namespace> istio.io/use-waypoint- 2>/dev/null


tiny: the 2>/dev/null here also swallows real errors, like a wrong context or missing RBAC. maybe drop it so failures show?

Fixed in 89d8cbf

electricjesus · 2026-07-10T23:11:42Z

+
+```bash
+kubectl label namespace <namespace> istio.io/use-waypoint- 2>/dev/null
+kubectl delete gateway -n <namespace> <waypoint-name>


heads up: kubectl delete gateway removes the waypoint proxy itself, so this tears down mesh L7 routing for the namespace, not just log collection. the Disabling section below is the logs-only path, might be worth a line on when to pick which.. also gateway can be ambiguous with istio's networking.istio.io Gateway in an ambient cluster, deploy-istio-ambient qualifies its delete as istio.operator.tigera.io.

I've removed the delete gateway line entirely, WDYT?

yeah, dropping it entirely is the right call.. removing the label is the clean per-namespace path, and delete gateway was pulling down mesh routing for the whole ns, not just logs. thanks for catching that.

electricjesus · 2026-07-10T23:11:42Z

+L7 Ambient Mode Collector sidecar can be disabled:
+
+```bash
+kubectl patch istio default --type=merge -p '{"spec":{"waypointLogging":"Disabled"}}'


small thing: this patches the istio singleton (it has to be named default), so it turns the sidecar off on every istio-waypoint gateway, not just this namespace. worth saying it's cluster-wide so nobody expects it scoped..

Fixed in 89d8cbf

Waypoint can also do `protocol_version`, `protocol`, `collector_name`, `collector_type`.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.


 - **eBPF collector** — kernel TCP-layer probes that capture HTTP and TLS metadata with no data path proxy or sidecar. Enable once at the cluster level. Works with any data plane — you do not need the eBPF data plane to use it. See [Enable eBPF collector](enable-ebpf-collector.mdx).
-{/* TODO: re-add Istio Waypoint collector bullet when the Waypoint PR lands. */}
+- **Waypoint collector** - Waypoint Proxy based Envoy sidecar. See [Enable Waypoint collector](enable-waypoint-collector.mdx)


+|                            | eBPF                              | Envoy (legacy)                    | Waypoint                           |
+| -------------------------- | --------------------------------- | --------------------------------- | ---------------------------------- |
+| Additional infrastructure  | None — runs inside Felix          | Sidecar Envoy per workload        | Sidecar Envoy per Waypoint proxy   |
+| Protocol coverage          | HTTP/1.x, TLS handshake           | HTTP                              | HTTP                               |


+| -------------------------- | --------------------------------- | --------------------------------- | ---------------------------------- |
+| Additional infrastructure  | None — runs inside Felix          | Sidecar Envoy per workload        | Sidecar Envoy per Waypoint proxy   |
+| Protocol coverage          | HTTP/1.x, TLS handshake           | HTTP                              | HTTP                               |
+| Opt-in granularity         | Cluster-wide (FelixConfiguration) | Per workload (label + annotation) | Per workload (label + annotiation) |


+- `<namespace>`: The namespace your workload is in.
+- `<waypoint-name>`: What you want your waypoint proxy gateway to be called.
+
+## Removing the L7 Ambient Mode Collector


+kubectl label namespace <namespace> istio.io/use-waypoint-
+```
+
+## Disabling the L7 Ambient Mode Collector


+L7 Ambient Mode logs are viewed in the [UI for L7
+logs](configure.mdx#view-l7-logs-in-the-web-console) along
+with the other types of L7 logs.


electricjesus · 2026-07-14T18:17:52Z

+| `user_agent`             | keyword  | All          | _HTTP only._ User agent of the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `type`                   | keyword  | All          | Type of request made. Possible values include `tcp`, `tls`, and `html/<version>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `protocol`               | keyword  | All          | Wire-protocol family of the captured event. Possible values: `http`, `tls`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `protocol_version`       | keyword  | All          | Wire-protocol version. For HTTP events, possible values include `1.0` and `1.1`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |


nit: now that waypoint feeds this row too, 2 is a possible protocol_version (HTTP/2, and gRPC rides HTTP/2).. worth adding to the examples?

electricjesus · 2026-07-14T18:17:52Z

 ## Collectors

-A *collector* is the component that observes traffic in your cluster and emits L7 log entries. $[prodname] supports multiple collectors. They all feed the same aggregation and reporting pipeline; each entry on the log file is tagged with `collector_type` so consumers can filter or join sources as needed.
+A _collector_ is the component that observes traffic in your cluster and emits L7 log entries. $[prodname] supports multiple collectors. They all feed the same aggregation and reporting pipeline; each entry on the log file is tagged with `collector_type` so consumers can filter or join sources as needed.


tiny: this "tagged with collector_type so consumers can filter or join" line shows up again at the end of the "Why more than one collector?" section just below.. maybe drop one?

alexh-tigera requested a review from a team as a code owner July 10, 2026 22:27

Copilot AI review requested due to automatic review settings July 10, 2026 22:27

Copilot started reviewing on behalf of alexh-tigera July 10, 2026 22:28 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Add Waypoint proxy L7 logging docs

b325f0b

alexh-tigera force-pushed the add-waypoint-l7-logging branch from 9b6bf1b to b325f0b Compare July 10, 2026 22:38

electricjesus reviewed Jul 10, 2026

View reviewed changes

alexh-tigera added 4 commits July 13, 2026 14:11

Add waypoint notes to the L7 overview

7558e78

Clarify Envoy vs Waypoint collectors as both being Envoy-based

34ed856

Clean up waypoint collector details

89d8cbf

Add Waypoint details to datatype table

8867185

Waypoint can also do `protocol_version`, `protocol`, `collector_name`, `collector_type`.

alexh-tigera requested a review from Copilot July 13, 2026 21:45

Copilot started reviewing on behalf of alexh-tigera July 13, 2026 21:45 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

More waypoint cleanup

0723c99

electricjesus reviewed Jul 14, 2026

View reviewed changes

electricjesus approved these changes Jul 14, 2026

View reviewed changes

alexh-tigera added 2 commits July 15, 2026 13:28

Add 2 to protocol version as Waypoint can do HTTP/2

cabaa3d

Clean up redundant collector details

e618432

		They will be labeled with the `collector_type`: `envoy-access-log` and the
		`collector_name`: `waypoint`.

Uh oh!

Conversation

alexh-tigera commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for calico-docs-preview-next ready!

Uh oh!

netlify Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview succeeded!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexh-tigera commented Jul 10, 2026 •

edited

Loading

netlify Bot commented Jul 10, 2026 •

edited

Loading

netlify Bot commented Jul 10, 2026 •

edited

Loading