-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #32 from cortexproject/governance
Documentation
- Loading branch information
Showing
7 changed files
with
189 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
## `auth-gateway` Community Code of Conduct | ||
|
||
`auth-gateway` follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
# Contributing | ||
|
||
Welcome! | ||
We are excited that you are interested in contributing. | ||
`auth-gateway` is an extention project of [Cortex](https://github.com/cortexproject/cortex/), and we follow the same [contributing guidelines](https://cortexmetrics.io/docs/contributing/) as Cortex. | ||
Everything you read on that page applies to `auth-gateway` as well except the documentation part since we do not have any documentation yet. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
# `auth-gateway` Governance | ||
|
||
This document defines project governance for the project. | ||
|
||
## Voting | ||
|
||
In the event of an important decision that needs to be taken, both maintainers must come to a consensus for the decision to be approved. | ||
If a consensus cannot be reached, the matter shall be put on hold until such a time where a consensus can be agreed upon. | ||
|
||
## Changes in Maintainership | ||
|
||
Contributors who are interested in becoming a maintainer, if performing relevant responsibilities, should discuss their interest with the existing maintainers. | ||
New maintainers must be nominated by an existing maintainer and unanimously approved by the current maintainers. | ||
|
||
We do not expect anyone to make a permanent commitment to be a `auth-gateway` maintainer forever. | ||
Circumstances change, people get new jobs, new interests, and may not be able to continue contributing to the project. | ||
However, to maintain effective governance, we need to keep the list of maintainers current. | ||
People may be removed from the current list of maintainers via one of the following ways: | ||
|
||
* They can resign | ||
* If they stop contributing to the project for a period of 6 months or more | ||
* By unanimous agreement of the other active maintainers | ||
|
||
Former maintainers are recognized with an honorary *Emeritus Maintainer* status, and have their names permanently listed in the README as a form of gratitude for their contributions. | ||
|
||
## Approving PRs | ||
|
||
PRs may be merged after receiving approval from both maintainers. | ||
If the PR author is a maintainer, the approval of the other maintainer is required. | ||
|
||
## Changes in Governance | ||
|
||
All changes in Governance require unanimous agreement of the maintainers. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
Friedrich Gonzalez, Adobe <friedrichg@gmail.com> (@friedrichg) | ||
Doğukan Teber, <dogukanteber1@hotmail.com> (@dogukanteber) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,145 @@ | ||
# auth-gateway | ||
<p align="center"><img src="images/logo.png" alt="auth-gateway Logo"></p> | ||
|
||
[![CI](https://github.com/cortexproject/auth-gateway/workflows/ci/badge.svg)](https://github.com/cortexproject/auth-gateway/actions) | ||
[![GoDoc](https://godoc.org/github.com/cortexproject/auth-gateway?status.svg)](https://godoc.org/github.com/cortexproject/auth-gateway) | ||
<a href="https://goreportcard.com/report/github.com/cortexproject/auth-gateway"><img src="https://goreportcard.com/badge/github.com/cortexproject/auth-gateway" alt="Go Report Card" /></a> | ||
<a href="https://cloud-native.slack.com/messages/cortex/"><img src="https://img.shields.io/badge/join%20slack-%23cortex-brightgreen.svg" alt="Slack" /></a> | ||
<!-- <a href="https://bestpractices.coreinfrastructure.org/projects/6681"><img src="https://bestpractices.coreinfrastructure.org/projects/6681/badge"></a> --> | ||
|
||
# auth-gateway: Microservice that helps you debugistrating and operating your [Cortex](https://github.com/cortexproject/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](https://github.com/cortexproject/cortex-helm-chart/blob/master/templates/nginx/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. | ||
|
||
[//]: <> (diagram url -> https://viewer.diagrams.net/?tags=%7B%7D&highlight=0000ff&edit=_blank&layers=1&nav=1&title=#R7V1pd6o6F%2F41Xeu%2BH8piHj461I6eDh572vvlLMSIVCSWwaG%2F%2Fk0QrCSpIkWLve096yoBI%2B797J09hhOpMZ6f%2B%2BZk2IZ94J6IfH9%2BIjVPRFGQZBW94JFFMqLhQzxi%2B04%2FGXsf6DhvIBnkk9HI6YMgc2EIoRs6k%2BygBT0PWGFmzPR9OMteNoBu9lsnpg2ogY5luvToH6cfDpNRgeffT1wAxx4mX60ryYmxmV6cDARDsw9na0PS2YnU8CEMl%2B%2FG8wZwMfVSuiw%2F1%2Frg7OrGfOCFeT5gv9mP9ftLf6h2W%2FB5Lrhv0%2BtTSVpOMzXdKPnFyd2Gi5QEaBpEbXRQRz9hggctF0Zo1vps6ISgMzEtPDhDCEBjw3DsoiMBXz4CoYWJwONx0xpGPjjHFzVlNPDi2Hb8FYgS9QH0wpY5dlyMkwYcOxa6h47pBeil3UkuSNAhqOiY%2FvUJQabAD8F8bSihxjmAYxD6C3RJgsXTFGOzNcbqydhwjaeCnAyaCZjs1Vzv9EZvEpKzyT%2F1vLO%2BaV8rjt7RBOO8PZpEp5qcg%2Fxev4aBHNPdDAJEmgyVfRh5fdBPjkg6gbkTPiXn8PvnhB34fXO%2BfrBIDzz0y57WD%2BLPcKqgpAPvH4yP0k%2F2zWC4upEg9OEINKAL%2Ffh3SPX4v9WZVJrEdJo74DuIqsBPZtsKiRW8hE14CGDkW2ADD1Q9USumb4Nw04XL60A%2FozFoeK3BSWGgKR3zgWuGzjSrZ1gIS77hDjrop4l8im0tmSdBsygRIF3%2B8ORT63qBmEg2shNJkpKdaEkYaiIESnOxdtkEXxBQIrEiTHEpSSX7XUiaDgKR04tCBC5SXrLysEVFkeJSEuhyKKHkrCgTbOQZSklkwGhvOoleEe4jEN9yy0fUQeqoXJJntMbB6a%2BKVaM%2FvSRcejYIsGL8XlCXpa8mtcKEunP0lCZBLQnKF1NapSj94Hg2JsA%2FyHIPIjRBAxvNYNwDvou0O15oQ4v7H20OrazRLVwwg8nSIRg4c8w5ii204XRQJskCoXkUhjjIhzVHKS7R5C%2FfGuWUAvaosC9b9FBmZ6Lmj8zqVPQsaBWhoNWp8AbHSzqvGAj5uibLWYWl85yhCobMa5omiIqa%2FZIvt0iNQwkKX0RQhJOM47Y3t%2B1QoqIcpahI%2FAfmzs4OmkKs5nLlHDTakKrAwlF5XKfxzCPDtVISrjcvAaLOPFsdzB%2FMWCphDTj2FUA6TkkhVgDKvcq9AqgbJcWouKTQ1lInhD5AQ%2BdmCGbmghKc43a3vz6wIdIh08oqp6P35FJ8H5l2UglXThaLruN61e1TOU%2BWcydxoHDI84YhNz%2FEYUZ0VgGNd9cszyrNzJKt5HAleyuZ%2BlAOqxbiSIFXEcEQSXVedNlWiIlUnphoZ8HIZ2coZCUAaU6QQZzs9ejN8g6KyiCz0oCxJEUTF5p9jBBIiyPCwo3ZAy4R1HUd28MiisCIZaCOV2nHMt1acmLs9Pt4jroPAufN7MXzYdAnRESTK%2FUTpVnEbqAlYbO2IQ2IVZVKclsn64UgLMPilOeQu6VlmJV6jZ8FuZqdlZwBDgYBCAlYlKOM6WAB4lXk4puzTGsIKCysyk4WroN0sC9ttwl7S21901sNmNbIjnX4bRSiaUCqyBMAKNVLEOhEvmxVm7JuVvIMPajvy6yU6TQOZsgcTWYNI2%2F0w8HNHJRZFUeH5WDpUQuGJaS1Wq18llAB46Wo9VS1UIVSKZuHROqqjHFXm8fgt0z0gc1T2uqiHzvAq5ZVSd3bH6SWjNTSk4jHooq%2FtNwzd7SmYl6pIZWFe6MY7nf1Ssn40javVNH265WylWAJQvgZscsKcHnlMduz%2Fl8qhHmNJLlaVpKmEJkXraAM6oQwi2Tsdc9rj0o7cmWvPa0Wj%2F52WnuysBeL4V7cBvzK9RXIlcI4tTwUTQsIvLJlpn2DnPZ1ay7y3cemZ9pl1%2Fh%2BbRV75ZoIVNoNe4jcb030r8%2F6pqtRtYyZgh6FlnEptiWJK6fUK%2BY1l%2BY9CDxRti6TNlBJ7oNAuOepO%2FHRjWnC565XlB2vFw7gnqhH4J5oxew07cdO%2B5xE66VJ9LaI2p7tNJFetuoutEaY0bhQDHfoi6qLyFfv%2BRnsq68R7p6PoXK6zAPV0AWCOpnHkEjPo3c2fv2ngxzP1nmjg9nI7C76jyaqZJVQbirDlmElqgSy%2F6M8Y0b8vOrbvaY8r3myW6yl8iVsqat0ZCVsEqEDv3EPfFrVW62IzXdK3ObtxqiWGUDZ4zpZZJbfDtC2zLRnO0Dbf1BylypNJsQ3b51SOZM11esVAStlsxbtHqVtVnKm8rDKrGZkdLzNfGQmYk7jakbVHGMz0esFkxWnv0d140pKS6luFNVsdaP4OZztv3pRz7EOp06EM443F1txMeb4HQyc0IGYmz0YhnCMLnDxifrKbUgVVh8MzCj2e0gchBDDitrhIP7CWjrKpyPo%2FTAM8YZpNUwPsbUsvOVmzsgZg75jctC30TA%2BnuBjXM8Hx2OIwdEKh9G4h16x6yQhxdO68zEVhyAK%2FgZwEM4QYv660IZcMMWziLyK%2FK%2FTTVdxE8%2BunhMkqkoGi6cKxyeJyjX1qDHUo2pw6UZqn%2FGDFKae6CSH0A%2BHiH6e6Z69jxI0e7%2FmBmKIxIMvIAwXCZ3NCGknRnhofSXcEDBap7gV%2BVPQcsLQwcxcftP6lm7MlafYemcwOgkkNi9za45POacGrQWayMfrQdPvo%2BF%2FAGdz6PXcNwemZ9JhhlhdA%2F9sCpZaO2ZEuj9gxmPkNwXzPIiDC%2FWB47pr7JIlWZYVln5wCQVErTMfaqgPFBC5XsFlwKOx2oyRP3nfNXA8t%2FEmkdx02ue8YP63v6JYeaqAL0cVrIrM1gRflbg0JpExjQxOVPcEs1XIpWo1YmIBt2%2FHXSmqVgZZLbdPJQMWKhGwyGtJkxNRzU5lVYORuwZsqwYj00y7Xp9N5%2BwnPYOcb0o%2BEVQnpvUNNiYUs9aQYnz1HmJCao2VnA3LHRIgsmFFC%2B%2BKFvl9WcUsnzc0VrGSWSLaIBSNjJFR5gPHGugcsA9w22QrjjicMNsnkZCHO1qOyVD%2BGARLg72LCE%2BaZSVvAB0fJz%2BYL0HfaUQKjNVtpzKwSqYcytvDIUc49LiWFJ0o6dBYVjaDxGTdYHkkpisEffAaOT7AXlwA%2FKlj0c2Mn5ctFwxYUZ2cklUNXhrbeblSlIdhZo5amSOuNqSEJ6d%2B2hu9U8W3Rm84wXED0%2F0Rnh2Fh8HLwwpPrudA%2FOd28KuMHZuFiyHzHE%2Fs8pXbllWpubITfXmlg0Sn1hBrkKw7E3OZYHM8TFMcdv7RLjm0i8EoTD%2Bwdtl%2FU%2FYOxSvfWzkU7tchNcOh23Uk2n5z4gcf4FQE5gAi5o%2B855B3nbHLyGHlXS5h%2B8Hyyta%2FubyrZck7OdG%2B9z8QKZC8Jg%2Ba%2BZH13LLOeGjEYWVdp9lIse5zYSqaoQcnu0ZkrzSGipWYZC9jJyd2Bdp%2Bmv0KJkO%2BuY41DK5gfpXSsvRU%2By5VpBdjGA5xK%2B6Pns2vZ40D6lk2G2kfqg9nXrKDpomfysZv2lDz%2B2eESmC7xBNJb5mR9FYUmu3GvtieavWf7F%2FZvCYTfjJj04R9JfzYrN5PecN%2FfC%2BiipgUGrlbhFzcpNg%2B1Z5NCvE4i%2BD7ZmieSLXlodjCRehiw3ms3z7M%2BOtzG9bQ369Od3jWtdG7Jv5fTW7U2uilMfjTDgI88Nyqtx%2FPuud%2B82VZTI%2F%2B6bXXl7o7k%2Bzaa8MJpd7jYi53HEGFtcni4k4Nf2MW3KGzb%2FdRwCvS4nkI5xeLq7fJn4WkTdDJBRTHol%2BrwVntX%2F8NDTSU9vBpOpbmJ2J9cAmD7sujFvqXahvfuBG9WZqBa%2FFD4fWOnwj303PQ1F7VEb5Dpeue3T8%2BXDpAfBTv1eZlvd4SH18nsOEIf8bR0%2Bq2b5zXoWBaV7XB7b3%2B27tsNK%2BsOuy%2BjM7bdqc26I%2F6U6V%2BBayzqKXeCtq9%2B7vR7fZ49%2B3C%2BdfxavX2tfr8MlJHz91fD093bvNh%2FNb1%2F5WiEFxN%2FlzevJ2%2Fzq666D4eJ2FN%2Fq2Nfp89GLfAG4TGM%2Fr25%2FEI9i%2Bb6Hf2Jh3rtnHdvAT9kRkh9vvzi5en2cXrYGS1PPnKBFqzOetJ6jy6bjemzzLfmFqDsH5r81aE6PP2oM359rSN36tnTR6%2BXbU851f02DhT3pz%2Bnemq3tUFeNZC874ZLc4uwPRShhfO9cVT%2B2kRiB1rBOH5g8M%2F2IPauebVvNHNxY0yusfUrF89dJUzf3Rl27jMPf5XTst1RojF9xaCNYXEevxjGfV1bKnO8RSvCkp1trVlCFwHBqcONzbRvfZcwFnoPsRWfDUmUivOJbk4kdTiZa0bPN40%2FGjSHY%2BDyAknnuDN4ml8eBp%2FhsNWEod79%2F8KoqzPNV7kpoIqSpImG6qStLKU4nJwaaHdRkxoPGcYB4SFRPuPS29jHD%2FD58f0LGB6Zhdwlcnng9qejKSrB0Nn4ICgDBv0IFGlIh27603p2a50zihktX6IjkJ7MLB5JVXKstWJynuDL27ZalunKs%2ByFejVrUD7XNFdDVjp7I1NeO8J7l2a8Aq17DDhtRXUefd0%2FQCsn22IEbONxIqYC4I7t7EQkeG0pvwjRJOP5iGu%2F3RbSvoUysP2jL6jStv%2F%2Fh8Va1DNC%2FPP9qcWg6ci7QRPco%2FusuHJimgtd%2FLqO9N0V650CK%2F2GSjvur0XAurw1E4fKbmcFN3hct7sd6HhzB0QMrRTwrIA6BibJ1Cw%2B9B6JDdK1ziJX%2F8TKFNSYGUqZJlTS2hcrVRpV5GgZZE4Yyld7cutJL7KbJMIs00rWFCqEGF00kUpz2Bj9UGNYZwDSXIhjJXwwLusfD4rnntflSzo9I0qA2%2B1okvZ6IJQCoyILlHi86Xsw8J4cuDOS4ZOLRn8wLSyn2kgxDtxXvwXmNGry2%2FgmfG31dZ3o6SWlexqU8noSAlrkKhk%2BZ4uSWu6y9hT%2FCJdYKoCh%2FoPHERdVDk9G9BmFEyUhAh06EPMi3d9gvcVacM%2B1vRn%2Fwc%3D) | ||
|
||
![auth-gateway architecture](images/architecture.png) | ||
|
||
## 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 | ||
|
||
```yaml | ||
|
||
# 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. | ||
|
||
```yaml | ||
# 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. | ||
|
||
```yaml | ||
- 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](#default_timeout_values) section. | ||
|
||
```yaml | ||
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 | ||
``` | ||
|
||
### <a name="default_timeout_values"></a> 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](CONTRIBUTING.md). | ||
|
||
## <a name="help"></a> Getting Help | ||
|
||
If you have any questions about `auth-gateway`: | ||
|
||
- Ask a question on the [Cortex Slack channel](https://cloud-native.slack.com/messages/cortex/). | ||
To invite yourself to the CNCF Slack, visit http://slack.cncf.io/. | ||
- <a href="https://github.com/cortexproject/auth-gateway/issues/new">File an issue.</a> | ||
- Send an email to <a href="mailto:cortex-users@lists.cncf.io">cortex-users@lists.cncf.io</a> | ||
|
||
Your feedback is always welcomed! |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.