For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Query workload identity from applications
Use the ztunnel metadata server to retrieve your workload’s SPIFFE identity and Workload Identity Token from within an ambient mesh application.
Applications running in an ambient mesh can query the ztunnel metadata server to retrieve their own SPIFFE identity and, when WIMSE workload claims are enabled, a Workload Identity Token (WIT). Querying the metadata server lets workloads authenticate themselves to external services or pass identity tokens on outbound requests without managing certificate files directly.
About the metadata server
Note
The metadata server requires an Enterprise license for Solo Enterprise for Istio. The server returns an error when no valid Enterprise license is present. If you do not have one, contact an account representative.
The ztunnel metadata server is accessible at the fixed link-local address 169.254.169.111 from any pod enrolled in the ambient mesh. Use this address verbatim in all requests. Link-local addresses (the 169.254.0.0/16 range) are non-routable, meaning that traffic to this address never leaves the node. Ztunnel intercepts all connections to 169.254.169.111 from within enrolled pods, regardless of port. Port 80 is used by convention.
The following endpoints are available.
| Endpoint | Description |
|---|---|
GET /self-identity | Returns the calling workload’s SPIFFE identity. When WIMSE workload claims are enabled, the response also includes a Workload Identity Token (WIT). |
GET /connection?src=<addr>&dst=<addr> | Returns peer identity metadata for an established connection. The request must originate from the destination address of the specified connection. |
Note that the metadata server rejects requests if the connection is not established over mTLS, or if no current connection matches the specified source and destination addresses.
Retrieve your workload’s identity
From within an ambient-enrolled pod, send a GET /self-identity request to retrieve the workload’s SPIFFE identity.
curl http://169.254.169.111/self-identityThe metadata server returns a JSON object with the workload’s identity:
{
"identity": "spiffe://cluster.local/ns/default/sa/my-app"
}Retrieve peer identity for a connection
In an ambient mesh, communication between workloads is automatically secured via mTLS. One important property of mTLS is that it allows verification of whoever is sending traffic to a workload. Mesh authorization policies can enforce rules about which identities are allowed to access which resources.
Sometimes, though, an application benefits from knowing the peer identity directly, for example to implement application-specific authorization logic or to emit observability data tied to the caller’s identity. Applications in the ambient mesh can query the metadata server to retrieve connection metadata, including the verified peer identity.
From within an ambient-enrolled pod, you can send a GET /connection request, supplying the source and destination addresses as query parameters. The request must originate from the destination address of the specified connection.
For example, an application running on 1.2.3.4:9090 that receives a connection from 6.7.8.9:47234 can look up the peer identity:
curl "http://169.254.169.111/connection?src=6.7.8.9:47234&dst=1.2.3.4:9090"The metadata server returns the verified peer identity:
{
"peerIdentity": "spiffe://cluster.local/ns/application/sa/client"
}