diff --git a/docs/docs/upgrading.md b/docs/docs/upgrading.md index 0c8e425d7..5745855fc 100644 --- a/docs/docs/upgrading.md +++ b/docs/docs/upgrading.md @@ -11,23 +11,23 @@ description: >- ### Policy for Device Identity -This release of Pomerium adds the ability to set policy based on system registration via [WebAuthN](https://www.w3.org/TR/webauthn-2/#registration-extension). +This release of Pomerium adds the ability to set policy based on system registration via [WebAuthN](https://en.wikipedia.org/wiki/WebAuthn). -See [device identity](/docs/topics/device-identity.md) for more details. +See [Device Identity](/docs/topics/device-identity.md) for more details. ### HTTP PPL Criteria -`http_path` and `http_method` are now supported for matching HTTP requests in policies. See [PPL](/docs/topics/ppl.md#criteria) for more details. +`http_path` and `http_method` are now supported for matching HTTP requests in policies. See [Pomerium Policy Language](/docs/topics/ppl.md#criteria) for more details. ## Breaking -### Self Signed fallback certificates +### Self-signed fallback certificates -When selecting a TLS certificate for a listener, Pomerium attempts to locate one by iterating through the provide certs and searching for a SAN match against a service URL such as `databroker_service_url`. +When selecting a TLS certificate for a listener, Pomerium attempts to locate one by iterating through the provided certs and searching for a SAN match. This applies to all listeners, including internal service URLs like `databroker_service_url` and public endpoints like `authenticate.example.com`. Previously, when no match was found, Pomerium would select the "first" certificate in the list. However, the definition of "first" might change based on runtime configuration, so the certificate selection was non-deterministic. -Starting in v0.16, Pomerium will instead generate a self signed certificate if it cannot locate an appropriate certificate from the provided configuration. If you discover that you are receiving a self signed certificate rather than a certificate from `certificate`/`certificate_file`/`certs`, you have a mismatch between your service URL and the names covered in your certificates. +Starting in v0.16, Pomerium will instead generate a self-signed certificate if it cannot locate an appropriate certificate from the provided configuration or system key/trust store. If you discover that you are receiving a self-signed certificate rather than a certificate from [`certificate`/`certificates`/`certificate_file`](/reference/readme.md#certificates) or the trust store, you have a mismatch between your service URL and the names covered in your certificates. ### OIDC flow no longer sets default uri params diff --git a/docs/reference/readme.md b/docs/reference/readme.md index 806ee197d..dea93d252 100644 --- a/docs/reference/readme.md +++ b/docs/reference/readme.md @@ -177,6 +177,8 @@ The Autocert Trusted Certificate Authority is the x509 CA (bundle) used when com Certificates are the x509 _public-key_ and _private-key_ used to establish secure HTTP and gRPC connections. Any combination of the above can be used together, and are additive. You can also use any of these settings in conjunction with `Autocert` to get OCSP stapling. +Certificates loaded into Pomerium from these config values are used to attempt secure connections between end users and services, between Pomerium services, and to upstream endpoints. + For example, if specifying multiple certificates at once: ```yaml @@ -189,6 +191,15 @@ certificates: key: "$HOME/.acme.sh/prometheus.example.com_ecc/prometheus.example.com.key" ``` +Or to set a single certificate and key covering multiple domains and/or a wildcard subdomain: + +```yaml +certificate_file: "$HOME/.acme.sh/*.example.com/fullchain.crt" +certificate_key: "$HOME/.acme.sh/*.example.com/*.example.com.key" +``` + +**Note:** Pomerium will check your system's trust/key store for valid certificates first. If your certificate solution imports into the system store, you don't need to also specify them with these configuration keys. + ### Client Certificate Authority - Environment Variable: `CLIENT_CA` / `CLIENT_CA_FILE` @@ -514,6 +525,10 @@ Each metric exposed by Pomerium has a `pomerium` prefix, which is omitted in the Name | Type | Description --------------------------------------------- | --------- | ----------------------------------------------------------------------- +build_info | Gauge | Pomerium build metadata by git revision, service, version and goversion +config_checksum_int64 | Gauge | Currently loaded configuration checksum by service +config_last_reload_success | Gauge | Whether the last configuration reload succeeded by service +config_last_reload_success_timestamp | Gauge | The timestamp of the last successful configuration reload by service grpc_client_request_duration_ms | Histogram | GRPC client request duration by service grpc_client_request_size_bytes | Histogram | GRPC client request size by service grpc_client_requests_total | Counter | Total GRPC client requests made by service @@ -530,10 +545,6 @@ http_server_request_duration_ms | Histogram | HTTP server request http_server_request_size_bytes | Histogram | HTTP server request size by service http_server_requests_total | Counter | Total HTTP server requests handled by service http_server_response_size_bytes | Histogram | HTTP server response size by service -build_info | Gauge | Pomerium build metadata by git revision, service, version and goversion -config_checksum_int64 | Gauge | Currently loaded configuration checksum by service -config_last_reload_success | Gauge | Whether the last configuration reload succeeded by service -config_last_reload_success_timestamp | Gauge | The timestamp of the last successful configuration reload by service redis_conns | Gauge | Number of total connections in the pool redis_idle_conns | Gauge | Total number of times free connection was found in the pool redis_wait_count_total | Counter | Total number of connections waited for @@ -547,18 +558,18 @@ Identity manager metrics have `pomerium_identity_manager` prefix. Name | Type | Description --------------------------------------------- | --------- | ----------------------------------------------------------------------- last_refresh_timestamp | Gauge | Timestamp of last directory refresh operation. -user_refresh_success_timestamp | Gauge | Timestamp of last successful user refresh. -user_refresh_error_timestamp | Gauge | Timestamp of last user refresh ended in an error. -user_refresh_errors | Counter | User refresh error counter. -user_refresh_success | Counter | User refresh success counter. -user_group_refresh_success_timestamp | Gauge | Timestamp of last group successful user refresh. -user_group_refresh_error_timestamp | Gauge | Timestamp of last user group refresh ended in an error. -user_group_refresh_errors | Counter | User group refresh error counter. -user_group_refresh_success | Counter | User group refresh success counter. -session_refresh_success_timestamp | Gauge | Timestamp of last successful session refresh. session_refresh_error_timestamp | Gauge | Timestamp of last session refresh ended in an error. session_refresh_errors | Counter | Session refresh error counter. session_refresh_success | Counter | Session refresh success counter. +session_refresh_success_timestamp | Gauge | Timestamp of last successful session refresh. +user_group_refresh_error_timestamp | Gauge | Timestamp of last user group refresh ended in an error. +user_group_refresh_errors | Counter | User group refresh error counter. +user_group_refresh_success | Counter | User group refresh success counter. +user_group_refresh_success_timestamp | Gauge | Timestamp of last group successful user refresh. +user_refresh_error_timestamp | Gauge | Timestamp of last user refresh ended in an error. +user_refresh_errors | Counter | User refresh error counter. +user_refresh_success | Counter | User refresh success counter. +user_refresh_success_timestamp | Gauge | Timestamp of last successful user refresh. #### Envoy Proxy Metrics diff --git a/docs/reference/settings.yaml b/docs/reference/settings.yaml index 4a7866bcf..8cc74db64 100644 --- a/docs/reference/settings.yaml +++ b/docs/reference/settings.yaml @@ -217,6 +217,8 @@ settings: doc: | Certificates are the x509 _public-key_ and _private-key_ used to establish secure HTTP and gRPC connections. Any combination of the above can be used together, and are additive. You can also use any of these settings in conjunction with `Autocert` to get OCSP stapling. + Certificates loaded into Pomerium from these config values are used to attempt secure connections between end users and services, between Pomerium services, and to upstream endpoints. + For example, if specifying multiple certificates at once: ```yaml @@ -228,6 +230,15 @@ settings: - cert: "$HOME/.acme.sh/prometheus.example.com_ecc/fullchain.cer" key: "$HOME/.acme.sh/prometheus.example.com_ecc/prometheus.example.com.key" ``` + + Or to set a single certificate and key covering multiple domains and/or a wildcard subdomain: + + ```yaml + certificate_file: "$HOME/.acme.sh/*.example.com/fullchain.crt" + certificate_key: "$HOME/.acme.sh/*.example.com/*.example.com.key" + ``` + + **Note:** Pomerium will check your system's trust/key store for valid certificates first. If your certificate solution imports into the system store, you don't need to also specify them with these configuration keys. - name: "Client Certificate Authority" keys: ["client_ca", "client_ca_file"] attributes: | @@ -580,8 +591,14 @@ settings: #### Pomerium Metrics Tracked + Each metric exposed by Pomerium has a `pomerium` prefix, which is omitted in the table below for brevity. + Name | Type | Description --------------------------------------------- | --------- | ----------------------------------------------------------------------- + build_info | Gauge | Pomerium build metadata by git revision, service, version and goversion + config_checksum_int64 | Gauge | Currently loaded configuration checksum by service + config_last_reload_success | Gauge | Whether the last configuration reload succeeded by service + config_last_reload_success_timestamp | Gauge | The timestamp of the last successful configuration reload by service grpc_client_request_duration_ms | Histogram | GRPC client request duration by service grpc_client_request_size_bytes | Histogram | GRPC client request size by service grpc_client_requests_total | Counter | Total GRPC client requests made by service @@ -598,21 +615,37 @@ settings: http_server_request_size_bytes | Histogram | HTTP server request size by service http_server_requests_total | Counter | Total HTTP server requests handled by service http_server_response_size_bytes | Histogram | HTTP server response size by service - pomerium_build_info | Gauge | Pomerium build metadata by git revision, service, version and goversion - pomerium_config_checksum_int64 | Gauge | Currently loaded configuration checksum by service - pomerium_config_last_reload_success | Gauge | Whether the last configuration reload succeeded by service - pomerium_config_last_reload_success_timestamp | Gauge | The timestamp of the last successful configuration reload by service redis_conns | Gauge | Number of total connections in the pool redis_idle_conns | Gauge | Total number of times free connection was found in the pool redis_wait_count_total | Counter | Total number of connections waited for redis_wait_duration_ms_total | Counter | Total time spent waiting for connections storage_operation_duration_ms | Histogram | Storage operation duration by operation, result, backend and service + #### Identity Manager + + Identity manager metrics have `pomerium_identity_manager` prefix. + + Name | Type | Description + --------------------------------------------- | --------- | ----------------------------------------------------------------------- + last_refresh_timestamp | Gauge | Timestamp of last directory refresh operation. + session_refresh_error_timestamp | Gauge | Timestamp of last session refresh ended in an error. + session_refresh_errors | Counter | Session refresh error counter. + session_refresh_success | Counter | Session refresh success counter. + session_refresh_success_timestamp | Gauge | Timestamp of last successful session refresh. + user_group_refresh_error_timestamp | Gauge | Timestamp of last user group refresh ended in an error. + user_group_refresh_errors | Counter | User group refresh error counter. + user_group_refresh_success | Counter | User group refresh success counter. + user_group_refresh_success_timestamp | Gauge | Timestamp of last group successful user refresh. + user_refresh_error_timestamp | Gauge | Timestamp of last user refresh ended in an error. + user_refresh_errors | Counter | User refresh error counter. + user_refresh_success | Counter | User refresh success counter. + user_refresh_success_timestamp | Gauge | Timestamp of last successful user refresh. + #### Envoy Proxy Metrics As of `v0.9`, Pomerium uses [envoy](https://www.envoyproxy.io/) for the data plane. As such, proxy related metrics are sourced from envoy, and use envoy's internal [stats data model](https://www.envoyproxy.io/docs/envoy/latest/operations/stats_overview). Please see Envoy's documentation for information about specific metrics. - All metrics coming from envoy will be labeled with `service="pomerium"` or `service="pomerium-proxy"`, depending if you're running all-in-one or distributed service mode. + All metrics coming from envoy will be labeled with `service="pomerium"` or `service="pomerium-proxy"`, depending if you're running all-in-one or distributed service mode and have `pomerium` prefix added to the standard envoy metric name. shortdoc: | Expose a prometheus format HTTP endpoint on the specified port. - name: "Metrics Basic Authentication"