Geoip (proto)

This extension has the qualified name envoy.filters.network.geoip

Note

This extension is work-in-progress. Functionality is incomplete and it is not intended for production use.

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

Tip

This extension extends and can be used with the following extension category:

This extension must be configured with one of the following type URLs:

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

Geoip configuration overview.

extensions.filters.network.geoip.v3.Geoip

[extensions.filters.network.geoip.v3.Geoip proto]

The network geolocation filter performs IP geolocation lookups on incoming connections and stores the results in the connection’s filter state under the well-known key envoy.geoip. The stored data is a GeoipInfo object that supports serialization for access logging and field-level access.

See well known filter state for details on accessing the geolocation data.

{
  "stat_prefix": ...,
  "provider": {...},
  "client_ip": ...
}
stat_prefix

(string) The prefix to use when emitting statistics. This is useful when there are multiple listeners configured with geoip filters, allowing stats to be grouped per listener. For example, with stat_prefix: "listener_1.", stats would be emitted as listener_1.geoip.total.

provider

(config.core.v3.TypedExtensionConfig, REQUIRED) Geoip driver specific configuration which depends on the driver being instantiated.

Tip

This extension category has the following known extensions:

client_ip

(string) Configuration for dynamically extracting the client IP address used for geolocation lookups.

This field accepts the same format specifiers as used for HTTP access logging to extract the client IP. The formatted result must be a valid IPv4 or IPv6 address string. For example:

  • %FILTER_STATE(my.custom.client.ip:PLAIN)% - Read from filter state populated by a preceding filter.

  • %DYNAMIC_METADATA(namespace:key)% - Read from dynamic metadata.

  • %REQ(X-Forwarded-For)% - Extract from request header (if applicable in context).

If not specified, defaults to the downstream connection’s remote address. If specified but the result is empty, -, or not a valid IP address, the filter falls back to the downstream connection’s remote address.

Example reading from filter state:

client_ip: "%FILTER_STATE(my.custom.client.ip:PLAIN)%"