Configure the Traefik IP Allowlist

This feature was introduced in Hydrolix v6.1.5.

The traefik_ip_allowlist tunable restricts cluster access at the Traefik proxy layer. It applies to both HTTP and TCP, and it can exempt specific routes from the restriction.

Hydrolix has two IP allowlists that work together. The cluster-wide ip_allowlist filters traffic at the cloud load balancer. The traefik_ip_allowlist adds per-route control at the proxy layer.

ACME certificate issuance is an example where the cloud load balancer allowlist isn't enough. Hydrolix can obtain certificates from Let's Encrypt using HTTP challenges, but certificate authorities don't publish the addresses those challenges come from. The ip_allowlist can't allow them without opening access broadly. Setting traefik_ip_allowlist restricts every route except the always-exempt ACME challenge, which keeps certificate issuance working while the rest of the cluster stays locked down. The tradeoff is that blocked requests reach Traefik before they're rejected, rather than being stopped at the load balancer.

Prerequisites

• Hydrolix v6.1.5 and later
• Permission to modify the HydrolixCluster specification
• Client IP preservation enabled and verified on the load balancer. Follow Preserve Client IP Addresses first.

Verify client IP preservation first

The allowlist matches the source address of each request. It works only when the load balancer preserves the client IP. Verify that preservation is working before you rely on the allowlist. In some load balancer configurations, requests arrive with an internal source address instead of the client's. Traefik treats internal addresses as cluster traffic and allows them, which means an unverified setup can let blocked clients through with no error.

How it works

The traefik_ip_allowlist tunable takes a list of CIDR ranges and applies an ipAllowList middleware to the Traefik routes. The default is an empty list. All routes then accept any traffic that reaches the proxy.

When the allowlist is set, Traefik returns 403 Forbidden to any request from an address outside the list, on every route except the exempt ones.

Two rules always hold, regardless of the allowlist:

• The ACME challenge route (.well-known/acme-challenge) is always exempt, which keeps Let's Encrypt certificate issuance working. It needs no allowlist entry and answers over plain HTTP only.
• Exemptions apply by route, not by hostname. A route served under an alternate domain name, such as one from alt_names or a wildcard from issue_wildcard_cert, can't be exempted.

Set the IP allowlist

Add traefik_ip_allowlist to the HydrolixCluster specification with the CIDR ranges to allow. Ranges can be single addresses (/32) or network prefixes.

Warning

Include the CIDR ranges that need to reach the cluster's services. Leaving an address out of the allowlist blocks it from the query, ingest, and other service routes. To recover from a lockout, edit the HydrolixCluster manifest with kubectl, which reaches the cluster over the Kubernetes management interface rather than the restricted service address.

hydrolixcluster.yaml

apiVersion: hydrolix.io/v1
kind: HydrolixCluster
spec:
  traefik_ip_allowlist:
  - 203.0.113.0/24
  - 198.51.100.42/32
  - 10.0.0.0/8

An invalid CIDR is skipped with a warning in the operator log, and the cluster stays healthy. For example, traefik_ip_allowlist: bad-cidr is not a valid CIDR.

Exempt routes from the allowlist

Use traefik_ip_allowlist_exempt_routes to keep specific routes open while the rest of the cluster stays restricted. A common use is to keep an ingest or query endpoint reachable from a partner network without widening the allowlist for every route.

Set this tunable in the same specification as traefik_ip_allowlist, before you apply the change. Setting the allowlist first, without the exemptions, blocks the routes you mean to keep open.

Exempting a route removes only the IP restriction. Other access controls still apply. For example, an exempt route that requires authentication still rejects unauthenticated requests.

Exempt keys

Each entry is an exempt key that identifies one route. A key combines the route's entrypoint and its path prefix. An entrypoint is a named Traefik listener bound to an external port. For example, web-secure handles HTTPS, clickhouse-http handles the ClickHouse HTTP interface, and native handles the ClickHouse native protocol.

A key takes one of two forms:

• A route on the default entrypoint (web-secure when TLS is enabled, otherwise web) uses its path prefix alone, such as query or ingest.
• A route on any other entrypoint uses entrypoint:prefix. The prefix can be empty, as in clickhouse-http: or native:, or set, as in proxy:query (present on clusters that enable the HTTP proxy).

A prefix can front a service with many sub-paths. Exempting the prefix exempts all of them. To exempt the same prefix on more than one entrypoint, list each key separately.

This table lists the exempt keys most often used. A standard cluster exposes more routes than the table shows, including internal ones.

Service	Entrypoint	Exempt key
Query API over HTTPS	web-secure	query
Streaming ingest over HTTPS	web-secure	ingest
Config API over HTTPS	web-secure	config
ClickHouse HTTP interface	clickhouse-http	clickhouse-http:
ClickHouse native protocol	native	native:
MySQL protocol	mysql	mysql:

The Hydrolix UI is served at the root of the default entrypoint. Its exempt key is an empty string, written as "" in the list.

A cluster with custom routing, such as query-head pooling or the HTTP proxy, exposes more routes. Build their keys with the same entrypoint:prefix format.

To list every route and its exempt key for a cluster, use the hkw route service.

1. Find your cluster's Hydrolix version.

2. Post the cluster manifest to hkw, with your version in place of <version>.

   curl -F cluster-file=@hydrolixcluster.yaml https://hkw.hydrolix.live/<version>/routes
   

3. In the output, find the route and copy its EXEMPT KEY value into traefik_ip_allowlist_exempt_routes.

hydrolixcluster.yaml

apiVersion: hydrolix.io/v1
kind: HydrolixCluster
spec:
  traefik_ip_allowlist:
  - 203.0.113.0/24
  - 198.51.100.42/32
  - 10.0.0.0/8
  traefik_ip_allowlist_exempt_routes:
  - query
  - clickhouse-http:
  - proxy:query

Apply the configuration

Apply the updated specification.

kubectl apply -f hydrolixcluster.yaml

The operator reconciles the change on its own, and Traefik picks up the new configuration a few seconds later. No operator restart is needed. The operator reconciles about every 15 seconds, and enforcement takes effect within a minute.

Verify the allowlist

After the operator reconciles the change, confirm the allowlist behaves as expected:

• From an allowed address, a request to a restricted route succeeds, subject to normal authentication.
• From a blocked address, a request to a restricted route returns 403 Forbidden.
• A request to an exempt route succeeds from any address, subject to normal authentication.

Disable the allowlist

Set traefik_ip_allowlist to an empty list to remove the restriction. The operator removes the ipAllowList middleware, and all routes accept traffic from any source again.