auth-gateway: Microservice that helps you debugistrating and operating your Cortex cluster in multi-tenant environments

auth-gateway is an entry point for all requests towards Cortex. This gateway is responsible for handling multi-tenancy features without complicated proxy configuration.

What problem does auth-gateway solve?

When operating Cortex with numerous tenants, it's crucial to distinguish your tenants each time they make requests to a specific component. This differentiation is essential to ensure that each component processes its own requests independently.

To achieve this, Cortex microservices necessitate the inclusion of a header named X-Scope-OrgID in each request. According to the Cortex Kubernetes (k8s) manifests, it's recommended to implement an NGINX server (eg. nginx-config.yaml) within each tenant's infrastructure, serving as a reverse proxy.

The primary function of this server is to route the traffic and establish the X-Scope-OrgID header for the corresponding tenant However, setting up an NGINX server for each tenant is complex and has limitations. For instance, you cannot define custom timeouts separately for each tenant.

So, we created auth-gateway, a microservice that helps you debugistrating and operating your Cortex cluster in multi-tenant environments with just a simple configuration.

Features

• Enabling multi-tenancy feature of Cortex with just a simple configuration
• Supporting HTTP basic authentication
• Defining custom timeouts for each of your components
• Load balancing

Configuration

Generic Placeholders

• <int>: any integer matching the regular expression [1-9]+[0-9]*
• <duration>: a duration matching the regular expression [0-9]+(ns|us|µs|ms|s|m|h|d|w|y) where y = 365 days.
• <string>: a regular string
• <url>: a URL

# The main server that auth-gateway will listen on. Any request that comes to this server will be forwarded to the corresponding component. Requires authentication.
server: <server_config>

# A supporting server that exposes metrics, ready and pprof endpoints. Does not require authentication.
debug: <server_config>

# List of all tenants that auth-gateway will serve.
tenants: <tenant_config>

distributor: <component_config>

frontend: <component_config>

alertmanager: <component_config>

ruler: <component_config>

server_config

The server_config configures the servers.

# hostname or IP address that auth-gateway will listen on, not a url
address: <string>
port: <int>
http_server_read_timeout: <duration> | default = 30s
http_server_write_timeout: <duration> | default = 30s
http_server_idle_timeout: <duration> | default = 120s

tenant_config

The tenant_config configures the tenants.

- authentication: basic
  username: <string>
  password: <string>
  id: <string>
- ... # more tenants

component_config

The component_config configures the components. Although the default timeout values are defined below, these default values differ depending on the component. To learn each component's timeout values, please refer to the default timeout values section.

url: <url>
  dns_refresh_interval: <duration> | default = 1s
  paths:
    - <string>
    - <string>
  http_client_timeout: <duration> | default = 15s
  http_client_dialer_timeout: <duration> | default = 5s
  http_client_tls_handshake_timeout: <duration> | default = 5s
  http_client_response_header_timeout: <duration> | default = 5s

Default Timeout Values

Each component in the component_config has different default timeout values. They are as follows:

Component	http_client_timeout	http_client_dialer_timeout	http_client_tls_handshake_timeout	http_client_response_header_timeout
Distributor	15s	5s	5s	5s
Frontend	1m	5s	5s	5s
Alertmanager	15s	5s	5s	5s
Ruler	15s	5s	5s	5s

You can override these default values by specifying your desired timeout values in the component_config for each component.

Contributing

We welcome contributions. Please follow the contributing guidelines.

Getting Help

If you have any questions about auth-gateway:

• Ask a question on the Cortex Slack channel. To invite yourself to the CNCF Slack, visit http://slack.cncf.io/.
• File an issue.
• Send an email to cortex-users@lists.cncf.io

Your feedback is always welcomed!