Skip to content

Traefik Authentication

Hydrolix clusters use Traefik as a reverse proxy and API gateway.

Only one authentication service can be active at a time.

hdx-auth is a native Traefik plugin (Go) introduced in v5.8.6, with full RBAC parity added in v5.10. It offers better performance than the legacy sidecar by eliminating the extra container.

hdx-traefik-auth is the legacy sidecar container in the traefik pod, enabled by default.

Feature hdx-traefik-auth hdx-auth
Type Sidecar container in the traefik pod Native Traefik plugin (Go)
Default Yes No - opt in with use_auth_traefik_plugins
Available since Legacy v5.8.6
RBAC support Yes Yes (parity added in v5.10)
Performance Sidecar adds overhead Better - no sidecar container

Enable the native plugin⚓︎

The hdx-auth native plugin is disabled by default. To enable it, set the use_auth_traefik_plugins tunable to true in the hydrolixcluster.yaml.

Enable hdx-auth Plugin
1
2
3
spec:
  tunables:
    use_auth_traefik_plugins: true

Review before enabling

Enabling this tunable switches the active authentication mechanism for all protected paths. Hydrolix production clusters currently use hdx-traefik-auth. Test in a non-production cluster before enabling in production.

Once enabled, hdx-auth handles authentication in place of hdx-traefik-auth for all protected paths.

Protected paths⚓︎

Both hdx-auth and hdx-traefik-auth enforce authentication on the same Traefik-routed service endpoints. For the complete list of endpoints and their required RBAC permissions when enable_traefik_authorization is enabled, see Traefik route authorization.

Authentication redirect behavior⚓︎

When an unauthenticated user accesses a protected path, both hdx-auth and hdx-traefik-auth store the original URL and redirect the user back to that path after successful login, provided they have the required permissions.

Troubleshooting⚓︎

Debug logging⚓︎

Both hdx-traefik-auth and hdx-auth include the username and email address in debug-level logs to aid troubleshooting of authentication failures.

See Logging Configuration for how to adjust log levels.

HTN targeting⚓︎

The hdx-auth plugin uses the traefik HTN target.