Proper Implementation of GeoIP/GeoIP2 in NGINX Gateway Fabric

[weiyi_lai]

My issue: I am looking for the official or recommended way to implement GeoIP/GeoIP2 module support within NGINX Gateway Fabric (NGF). Specifically, how to correctly load the module and define GeoIP-based variables (like country codes) for traffic filtering.

How I encountered the problem:

We are migrating from ingress-nginx to NGINX Gateway Fabric. In our previous setup, GeoIP was used for regional access control. After deploying NGF, I noticed that while the .so module files (e.g., ngx_http_geoip_module.so) exist in the container under /etc/nginx/modules/, there is no clear documentation on how to load them and use the geoip_country or geoip2 directives without causing NGINX configuration errors.

Solutions I’ve tried:

Enabled snippetsFilters via Helm.

Attempted to use SnippetsFilter with context: main to load_module. This resulted in the Gateway resource status becoming Programmed: False due to NGINX configuration syntax errors (likely because load_module must be at the very top of the config).

Verified the presence of modules in the Pod: I see ngx_http_geoip_module.so and ngx_stream_geoip_module.so in /etc/nginx/modules/, as well as a /etc/nginx/main-includes directory.

Version of NGF and/or NGINX:

NGF Version: 2.3.0

Deployment environment:

Kubernetes Version: v1.35.0
Environment: (On-premise / Proxmox VE)

[salonichf5]

Hey @weiyi_lai,
I took a look at the geoip module, and it seems all of its directives are only valid in the http context. Try applying your directives from the main context into the http context — this should resolve the configuration errors.

[weiyi_lai]

Thanks for the suggestion! I’ll try moving the directives to the http context and see if that resolves the config errors.

is there a way to self-compile and use GeoIP2 with NGF? For example, building a custom NGINX image with the GeoIP2 module enabled.

[salonichf5]

Yes, you can build custom images for NGINX using this guide