Skip to content

Add Waypoint proxy L7 logging docs #2848

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alexh-tigera wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add Waypoint proxy L7 logging docs #2848

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion calico-enterprise/observability/elastic/l7/datatypes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ $[prodname] supports multiple L7 collectors that write into the same Elasticsear

- **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).

@electricjesus electricjesus Jul 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


The table below details the key/value pairs in the JSON blob, including their [Elasticsearch datatype](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html) and which collector(s) populate each field. "All" means every collector populates the field. Descriptions prefixed with _HTTP only_ or _TLS only_ mark fields that are populated for events of only that protocol family.

Expand Down
69 changes: 62 additions & 7 deletions calico-enterprise/observability/elastic/l7/enable-waypoint-collector.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,75 @@
---
description: Enable the Istio Ambient Mode Waypoint-based L7 collector.
draft: true
---

# Collect L7 logs using the Waypoint collector

@electricjesus electricjesus Jul 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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.

@electricjesus electricjesus Jul 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)?


:::note
## 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.mdx).

:::
## Enable the collector

## 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/),

Check warning on line 16 in calico-enterprise/observability/elastic/l7/enable-waypoint-collector.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'Waypoint' instead of 'waypoint'.

Raw Output:
{"message": "[Vale.Terms] Use 'Waypoint' instead of 'waypoint'.", "location": {"path": "calico-enterprise/observability/elastic/l7/enable-waypoint-collector.mdx", "range": {"start": {"line": 16, "column": 14}}}, "severity": "WARNING"}
and labeling the workload to use it.

@electricjesus electricjesus Jul 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## Enable the collector
This will create an Istio Waypoint proxy that includes a sidecar container to
capture the L7 logs.

```bash
cat << EOF | kubectl apply -n <namespace> -f -
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: <waypoint-name>
labels:
istio.io/waypoint-for: all
spec:
gatewayClassName: istio-waypoint
listeners:
- name: mesh
port: 15008
protocol: HBONE
EOF
```

```bash
kubectl label namespace <namespace> istio.io/use-waypoint=<waypoint-name>
```

Replace the following:

- `<namespace>`: The namespace your workload is in.
- `<waypoint-name>`: What you want your waypoint proxy gateway to be called.

Check warning on line 46 in calico-enterprise/observability/elastic/l7/enable-waypoint-collector.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'Waypoint' instead of 'waypoint'.

Raw Output:
{"message": "[Vale.Terms] Use 'Waypoint' instead of 'waypoint'.", "location": {"path": "calico-enterprise/observability/elastic/l7/enable-waypoint-collector.mdx", "range": {"start": {"line": 46, "column": 5}}}, "severity": "WARNING"}

## Removing the L7 Ambient Mode Collector

```bash
kubectl label namespace <namespace> istio.io/use-waypoint- 2>/dev/null

@electricjesus electricjesus Jul 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

kubectl delete gateway -n <namespace> <waypoint-name>

@electricjesus electricjesus Jul 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

```

## Disabling the L7 Ambient Mode Collector

If you are running waypoint proxies but you don't want the sidecar added, the

Check warning on line 57 in calico-enterprise/observability/elastic/l7/enable-waypoint-collector.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'Waypoint' instead of 'waypoint'.

Raw Output:
{"message": "[Vale.Terms] Use 'Waypoint' instead of 'waypoint'.", "location": {"path": "calico-enterprise/observability/elastic/l7/enable-waypoint-collector.mdx", "range": {"start": {"line": 57, "column": 20}}}, "severity": "WARNING"}
L7 Ambient Mode Collector sidecar can be disabled:

```bash
kubectl patch istio default --type=merge -p '{"spec":{"waypointLogging":"Disabled"}}'

@electricjesus electricjesus Jul 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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..

```

## View L7 logs

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.

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

## Additional information

* [L7 log data types](datatypes.mdx)