From 7d72a8dc91870c89d6d6b22c8874da59dd983be4 Mon Sep 17 00:00:00 2001 From: Joe Afflerbach Date: Tue, 26 Jul 2022 10:44:56 +0200 Subject: [PATCH] Docs for `environment` block, setting and variable --- CHANGELOG.md | 3 + .../2.configuration/4.block/environment.md | 56 ++++++++++--------- .../2.configuration/4.block/settings.md | 7 ++- .../content/2.configuration/5.variables.md | 7 ++- 4 files changed, 40 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e597e2bd4..33f6f1322 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,9 @@ Unreleased changes are available as `avenga/couper:edge` container. +* **Added** + * [`environment` block](https://docs.couper.io/configuration/block/environment), [setting](https://docs.couper.io/configuration/block/settings) and [`couper.environment` variable](https://docs.couper.io/configuration/variables#couper) ([#521](https://github.com/avenga/couper/pull/521), ([#534](https://github.com/avenga/couper/pull/534), [#545](https://github.com/avenga/couper/pull/545)) + * **Fixed** * Disallow empty path parameters ([#526](https://github.com/avenga/couper/pull/526)) * Basic Auth client authentication with OAuth2 (client ID and secret must be URL encoded) ([#537](https://github.com/avenga/couper/pull/537)) diff --git a/docs/website/content/2.configuration/4.block/environment.md b/docs/website/content/2.configuration/4.block/environment.md index 1a3254e77..9bc49643c 100644 --- a/docs/website/content/2.configuration/4.block/environment.md +++ b/docs/website/content/2.configuration/4.block/environment.md @@ -1,52 +1,54 @@ -# Environment Block +# Environment The `environment` block lets you refine the Couper configuration based on the set -[environment](/configuration/command-linemd#global-options). +[environment](../command-line#global-options). | Block name | Context | Label | Nested block(s) | | :------------ | :------- | :----------------------------------------------- | :---------------------------------- | | `environment` | Overall. | ⚠ required, multiple labels are supported. | All configuration blocks of Couper. | The `environment` block works like a preprocessor. If the label of an `environment` -block do not match the set [environment](./CLI.md#global-options) value, the preprocessor -removes this block and their content. Otherwise, the content of the block is applied +block does not match the set [`COUPER_ENVIRONMENT`](../command-line#global-options) value, the preprocessor +removes this block and its content. Otherwise, the content of the block is added to the configuration. -If the [environment](/configuration/command-linemd#global-options) value set to `prod`, the following configuration +## Example + +Considering the following configuration with the `COUPER_ENVIRONMENT` value set to `prod` ```hcl server { - api "protected" { - endpoint "/secure" { - environment "prod" { - access_control = ["jwt"] - } - - proxy { - environment "prod" { - url = "https://protected-resource.org" - } - environment "stage" { - url = "https://test-resource.org" - } - } + api "protected" { + endpoint "/secure" { + environment "prod" { + access_control = ["jwt"] + } + + proxy { + environment "prod" { + url = "https://protected-resource.org" + } + environment "stage" { + url = "https://test-resource.org" } + } } + } } ``` -produces after the preprocessing the following configuration: +the result will be: ```hcl server { - api "protected" { - endpoint "/secure" { - access_control = ["jwt"] + api "protected" { + endpoint "/secure" { + access_control = ["jwt"] - proxy { - url = "https://protected-resource.org" - } - } + proxy { + url = "https://protected-resource.org" + } } + } } ``` diff --git a/docs/website/content/2.configuration/4.block/settings.md b/docs/website/content/2.configuration/4.block/settings.md index 937c61cc5..c72b8d2f8 100644 --- a/docs/website/content/2.configuration/4.block/settings.md +++ b/docs/website/content/2.configuration/4.block/settings.md @@ -7,6 +7,7 @@ gateway instance. |:--------------------------------|:---------------|:--------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------| | `accept_forwarded_url` | tuple (string) | `[]` | Which `X-Forwarded-*` request headers should be accepted to change the [request variables](../modifiers#request) `url`, `origin`, `protocol`, `host`, `port`. Valid values are `"proto"`, `"host"` and `"port"`. The port in `X-Forwarded-Port` takes precedence over a port in `X-Forwarded-Host`. | Affects relative url values for [`sp_acs_url`](saml) attribute and `redirect_uri` attribute within [beta_oauth2](oauth2) & [oidc](oidc). | `["proto","host","port"]` | | `default_port` | number | `8080` | Port which will be used if not explicitly specified per host within the [`hosts`](server) list. | - | - | +| `environment` | string | `""` | [Environment](../command-line#global-options) Couper is to run in. | - | `"prod"` | | `health_path` | string | `"/healthz"` | Health path which is available for all configured server and ports. | - | - | | `https_dev_proxy` | tuple (string) | `[]` | List of tls port mappings to define the tls listen port and the target one. A self-signed certificate will be generated on the fly based on given hostname. | Certificates will be hold in memory and are generated once. | `["443:8080", "8443:8080"]` | | `log_format` | string | `"common"` | Switch for tab/field based colored view or JSON log lines. Valid values are `"common"` and `"json"`. | - | - | @@ -16,10 +17,10 @@ gateway instance. | `request_id_accept_from_header` | string | `""` | Name of a client request HTTP header field that transports the `request.id` which Couper takes for logging and transport to the backend (if configured). | - | `X-UID` | | `request_id_backend_header` | string | `Couper-Request-ID` | Name of a HTTP header field which Couper uses to transport the `request.id` to the backend. | - | - | | `request_id_client_header` | string | `Couper-Request-ID` | Name of a HTTP header field which Couper uses to transport the `request.id` to the client. | - | - | -| `request_id_format` | string | `"common"` | Valid values are `"common"` and `"uuid4"`. If set to `"uuid4"` a rfc4122 uuid is used for `request.id` and related log fields. | - | - | +| `request_id_format` | string | `"common"` | Valid values are `"common"` and `"uuid4"`. If set to `"uuid4"` a RFC 4122 uuid is used for `request.id` and related log fields. | - | - | | `secure_cookies` | string | `""` | Valid values are `""` and `"strip"`. If set to `"strip"`, the `Secure` flag is removed from all `Set-Cookie` HTTP header fields. | - | - | | `xfh` | bool | `false` | Option to use the `X-Forwarded-Host` header as the request host. | - | - | -| `beta_metrics` | bool | `false` | Option to enable the Prometheus [metrics](METRICS.md) exporter. | - | - | +| `beta_metrics` | bool | `false` | Option to enable the Prometheus [metrics](/observation/metrics) exporter. | - | - | | `beta_metrics_port` | number | `9090` | Prometheus exporter listen port. | - | - | | `beta_service_name` | string | `"couper"` | The service name which applies to the `service_name` metric labels. | - | - | -| `ca_file` | string | `""` | Option for adding the given PEM encoded ca-certificate to the existing system certificate pool for all outgoing connections. | - | - | +| `ca_file` | string | `""` | Option for adding the given PEM encoded CA certificate to the existing system certificate pool for all outgoing connections. | - | - | diff --git a/docs/website/content/2.configuration/5.variables.md b/docs/website/content/2.configuration/5.variables.md index dad922c23..559f34d9f 100644 --- a/docs/website/content/2.configuration/5.variables.md +++ b/docs/website/content/2.configuration/5.variables.md @@ -11,9 +11,10 @@ The second evaluation will happen during the request/response handling. ## `couper` -| Variable | Type | Description | Example | -| :------------------------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- | -| `version` | string | Couper's version number | `"1.3.1"` | +| Variable | Type | Description | Example | +| :------------------------------- | :----- | :------------------------------------------------------------------------- | :-------- | +| `version` | string | Couper's version number | `"1.9.2"` | +| `environment` | string | the [environment](../command-line#global-options) Couper currently runs in | `"prod"` | ## `env`