3pp-mirror/pomerium
1
0
Fork 0
mirror of https://github.com/pomerium/pomerium.git synced 2025-06-10 06:42:45 +02:00
Code Issues Projects Releases Packages Wiki Activity

DOCS: Fixes to 16 release (#2856) (#2872)

Browse source 
* clarify upgrade notes and certificate reference

* backport updated reference to source and sort

* Apply suggestions from code review

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* update webauthn link

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

Co-authored-by: Alex Fornuto <afornuto@pomerium.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
This commit is contained in:
backport-actions-token[bot] 2021-12-29 10:36:25 -08:00 • committed by GitHub
parent 992e33fc0c
commit 0e6e15d92a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 68 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

12
docs/docs/upgrading.md
View file

@ -11,23 +11,23 @@ description: >-
### Policy for Device Identity ### 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 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 ## 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. 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 ### OIDC flow no longer sets default uri params

37
docs/reference/readme.md
View file

@ -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 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: For example, if specifying multiple certificates at once:
```yaml ```yaml
@ -189,6 +191,15 @@ certificates:
key: "$HOME/.acme.sh/prometheus.example.com_ecc/prometheus.example.com.key" 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 ### Client Certificate Authority
- Environment Variable: `CLIENT_CA` / `CLIENT_CA_FILE` - 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 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_duration_ms | Histogram | GRPC client request duration by service
grpc_client_request_size_bytes | Histogram | GRPC client request size 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 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_request_size_bytes | Histogram | HTTP server request size by service
http_server_requests_total | Counter | Total HTTP server requests handled 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 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_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_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_count_total | Counter | Total number of connections waited for
@ -547,18 +558,18 @@ Identity manager metrics have `pomerium_identity_manager` prefix.
Name | Type | Description Name | Type | Description
--------------------------------------------- | --------- | ----------------------------------------------------------------------- --------------------------------------------- | --------- | -----------------------------------------------------------------------
last_refresh_timestamp | Gauge | Timestamp of last directory refresh operation. 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_error_timestamp | Gauge | Timestamp of last session refresh ended in an error.
session_refresh_errors | Counter | Session refresh error counter. session_refresh_errors | Counter | Session refresh error counter.
session_refresh_success | Counter | Session refresh success 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 #### Envoy Proxy Metrics

43
docs/reference/settings.yaml
View file

@ -217,6 +217,8 @@ settings:
doc: | 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 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: For example, if specifying multiple certificates at once:
```yaml ```yaml
@ -228,6 +230,15 @@ settings:
- cert: "$HOME/.acme.sh/prometheus.example.com_ecc/fullchain.cer" - cert: "$HOME/.acme.sh/prometheus.example.com_ecc/fullchain.cer"
key: "$HOME/.acme.sh/prometheus.example.com_ecc/prometheus.example.com.key" 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" - name: "Client Certificate Authority"
keys: ["client_ca", "client_ca_file"] keys: ["client_ca", "client_ca_file"]
attributes: | attributes: |
@ -580,8 +591,14 @@ settings:
#### Pomerium Metrics Tracked #### Pomerium Metrics Tracked
Each metric exposed by Pomerium has a `pomerium` prefix, which is omitted in the table below for brevity.
Name | Type | Description 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_duration_ms | Histogram | GRPC client request duration by service
grpc_client_request_size_bytes | Histogram | GRPC client request size 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 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_request_size_bytes | Histogram | HTTP server request size by service
http_server_requests_total | Counter | Total HTTP server requests handled 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 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_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_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_count_total | Counter | Total number of connections waited for
redis_wait_duration_ms_total | Counter | Total time spent waiting for connections 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 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 #### 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. 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: | shortdoc: |
Expose a prometheus format HTTP endpoint on the specified port. Expose a prometheus format HTTP endpoint on the specified port.
- name: "Metrics Basic Authentication" - name: "Metrics Basic Authentication"