Geolocation (GeoIP)

Airlock Microgateway uses a GeoIP database to determine the country associated with a request’s remote IP address. You can use this information in country-based request conditions and HTTP headers. Country information is also available in access logs and on metrics that provide a country label.

Prerequisites

A Gateway Deployment.
Permissions to modify the applicable Microgateway and Kubernetes resources.
For a custom GeoIP database: a compatible database that can be made available to the Microgateway Engine.

Configuration

Configure client IP detection

GeoIP lookups use the remote IP address selected by Microgateway’s client IP detection. Configure spec.defaults.downstream.remoteIP in the applicable GatewayParameters resource to match your deployment topology.

Notice

An incorrect remote-IP configuration can cause Microgateway to look up the address of a proxy or load balancer instead of the intended client address. Country-based request conditions, headers, logs, and metrics then use country information for that intermediary.

Verify client IP detection before relying on GeoIP information.

For client IP detection settings, see GatewayParameters.spec.defaults.downstream.remoteIP. To verify the address used for GeoIP lookups, see Validation below.

Select the GeoIP database

Use the bundled database

Airlock Microgateway includes the DB-IP IP to Country Lite database in MMDB format.

The database contains country-related information for IPv4 and IPv6 address ranges. For details about the information available in the database, see the DB-IP IP to Country Lite documentation.

Airlock Microgateway does not expose all information contained in the database. It exposes only the GeoIP fields supported by Microgateway. These are the same fields that can be included in the access log.

For the supported GeoIP fields, see Metrics, Logs and Tracing — Access log — Log field reference table.

Use a custom database

You can provide a compatible GeoIP database instead of using the bundled database. Airlock Microgateway supports GeoIP databases in MMDB format. There are no different requirements for IPv4 and IPv6. The database must contain entries for the IP versions that you want to look up.

A custom database can contain additional GeoIP information. Microgateway only exposes fields that it supports. For example, when using the DB-IP IP to City Lite database, Microgateway can provide both country_iso_code and city_name.

Mount a volume containing the database at /app/data/geo-ip in the Engine container.

The database file must be named location.mmdb.

The following GatewayParameters example uses a persistent volume claim and mounts it read-only:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


apiVersion: microgateway.airlock.com/v1alpha1
kind: GatewayParameters
metadata:
  name: gateway-parameters-example
  namespace: example
spec:
  kubernetes:
    deployment:
      volumes:
        - name: geoip-database
          persistentVolumeClaim:
            claimName: geoip-database-v1
      engineContainer:
        volumeMounts:
          - name: geoip-database
            mountPath: /app/data/geo-ip
            readOnly: true

Configure the volume through spec.kubernetes.deployment.volumes and its mount through spec.kubernetes.deployment.engineContainer.volumeMounts in the applicable GatewayParameters resource.
Apply the configuration and verify that the Engine uses the expected database.

A database can contain more information than Microgateway exposes. Using a more comprehensive database does not automatically make additional GeoIP fields available through Microgateway.

Caution

Overwriting, truncating, or otherwise modifying a database volume that is already in use can cause the Engine to crash and interrupt request processing.

Do not modify a volume that is already in use.
To update a custom GeoIP database, create a new volume containing the complete replacement database and update the corresponding GatewayParameters configuration to reference it.

Configure country-based request conditions

Use requestConditions.remoteIP.geoLocation.countryISOCodes to match requests by country code.

For example, the following configuration fragment matches requests for which the GeoIP lookup returns CH:

1
2
3
4
5


requestConditions:
  remoteIP:
    geoLocation:
      countryISOCodes:
        - CH

If no corresponding country information is found, the condition does not match. The condition itself neither allows nor denies a request; the resulting behavior depends on the rule or policy in which it is used.

GeoIP and CIDR range conditions can be combined, although they are typically used independently.

For the available configuration fields, see AccessControlPolicy.spec.policies[].requestConditions.remoteIP.geoLocation.

Configure GeoIP values in HTTP headers

Use GeoIP command operators to insert GeoIP information associated with the request’s remote IP address into a header value.

The following GeoIP properties are available:
- country_iso_code – available with the bundled DB-IP IP to Country Lite database
- city_name – requires a custom database that contains city information, e.g., the DB-IP IP to City Lite database
- region_iso_code – requires a custom database that contains the corresponding region information
  
  For example, use %GEO(country_iso_code)% to insert the country code.

Configure the value in a header-add rule in HeaderRewrites. The operator can be used in the value fields under spec.request.add.custom[].headers[] and spec.response.add.custom[].headers[].

The handling of missing country information depends on whether the command operator defines the entire value or only part of it:

Configured header value	Country information available: `CH`	Country information unavailable
`%GEO(country_iso_code)%`	`CH`	No header is generated by this rule.
`country=%GEO(country_iso_code)%`	`country=CH`	`country=`

If the operator defines the entire value and no country information is available, the header is omitted. If the operator is embedded in a longer value, only the operator is replaced with an empty string. The surrounding text is retained.

For header configuration, see HeaderRewrites.

Configure GeoIP information in access logs

GeoIP command operators can also provide country information in access logs. If no corresponding GeoIP information is available, the associated property is omitted from the JSON log entry.

To include GeoIP information in a custom access log format, configure the corresponding properties under spec.logging.accessLog.format.json in Telemetry. For the default log structure, available fields, and GeoIP command operators, see Metrics, Logs and Tracing — Access log — Log field reference table.

Validation

Use a test address for which the configured database contains a known country entry. Send requests through the network path used by your application.

Verify the remote IP address.
- Inspect network.forwarded_ip in the default access log. It must contain the address intended for the GeoIP lookup. In contrast, source.ip records the direct downstream connection address.
Verify the country information.
- Inspect the GeoIP information in the access log and compare it with the entry in the configured database. Also test a request for which no corresponding country information is available and verify that the associated property is omitted.
Verify request conditions and header values.
- Check that country-based conditions match the intended requests and that the fallback policy handles requests without matching country information. For header rules, verify both cases described in “Configure GeoIP values in HTTP headers”.
Verify country labels on metrics.
- For metrics that expose country_iso_code, check the label values against the behavior described in Metrics, Logs and Tracing — Engine metrics — Country information.