From b9b66ec20feb21fab0747b2119304e9815ffcbfd Mon Sep 17 00:00:00 2001 From: Travis Groth Date: Tue, 5 May 2020 21:13:28 -0400 Subject: [PATCH] deploy: autocert documentation and defaults (#658) * Define AUTOCERT_DIR in dockerfiles * Add autocert example and compose file * Update reference docs for defaults --- .github/Dockerfile-release | 1 + .github/Dockerfile-release.arm32v6 | 1 + .github/Dockerfile-release.arm32v7 | 1 + .github/Dockerfile-release.arm64v8 | 1 + Dockerfile | 1 + .../examples/config/config.minimal.yaml | 3 + .../docker/autocert.docker-compose.yml | 18 +++ docs/configuration/readme.md | 139 +++++++++--------- docs/docs/quick-start/readme.md | 16 +- 9 files changed, 112 insertions(+), 69 deletions(-) create mode 100644 docs/configuration/examples/docker/autocert.docker-compose.yml diff --git a/.github/Dockerfile-release b/.github/Dockerfile-release index 490a374da..8767ba0ef 100644 --- a/.github/Dockerfile-release +++ b/.github/Dockerfile-release @@ -2,6 +2,7 @@ FROM busybox:latest as build RUN touch /config.yaml FROM gcr.io/distroless/static +ENV AUTOCERT_DIR /data/autocert WORKDIR /pomerium COPY pomerium* /bin/ COPY --from=build /config.yaml /pomerium/config.yaml diff --git a/.github/Dockerfile-release.arm32v6 b/.github/Dockerfile-release.arm32v6 index 940eb4d0a..f695f051e 100644 --- a/.github/Dockerfile-release.arm32v6 +++ b/.github/Dockerfile-release.arm32v6 @@ -2,6 +2,7 @@ FROM busybox:latest as build RUN touch /config.yaml FROM arm32v7/alpine +ENV AUTOCERT_DIR /data/autocert WORKDIR /pomerium COPY --from=multiarch/qemu-user-static /usr/bin/qemu-aarch64-static /usr/bin/ RUN apk --no-cache add ca-certificates diff --git a/.github/Dockerfile-release.arm32v7 b/.github/Dockerfile-release.arm32v7 index 940eb4d0a..f695f051e 100644 --- a/.github/Dockerfile-release.arm32v7 +++ b/.github/Dockerfile-release.arm32v7 @@ -2,6 +2,7 @@ FROM busybox:latest as build RUN touch /config.yaml FROM arm32v7/alpine +ENV AUTOCERT_DIR /data/autocert WORKDIR /pomerium COPY --from=multiarch/qemu-user-static /usr/bin/qemu-aarch64-static /usr/bin/ RUN apk --no-cache add ca-certificates diff --git a/.github/Dockerfile-release.arm64v8 b/.github/Dockerfile-release.arm64v8 index fa98cc92d..75e8e500a 100644 --- a/.github/Dockerfile-release.arm64v8 +++ b/.github/Dockerfile-release.arm64v8 @@ -2,6 +2,7 @@ FROM busybox:latest as build RUN touch /config.yaml FROM arm64v8/alpine +ENV AUTOCERT_DIR /data/autocert WORKDIR /pomerium COPY --from=multiarch/qemu-user-static /usr/bin/qemu-aarch64-static /usr/bin/ RUN apk --no-cache add ca-certificates diff --git a/Dockerfile b/Dockerfile index 81a21b736..ad4f4b70e 100644 --- a/Dockerfile +++ b/Dockerfile @@ -11,6 +11,7 @@ RUN make RUN touch /config.yaml FROM gcr.io/distroless/base:debug +ENV AUTOCERT_DIR /data/autocert WORKDIR /pomerium COPY --from=build /go/src/github.com/pomerium/pomerium/bin/* /bin/ COPY --from=build /config.yaml /pomerium/config.yaml diff --git a/docs/configuration/examples/config/config.minimal.yaml b/docs/configuration/examples/config/config.minimal.yaml index c759fde9f..7760fc46a 100644 --- a/docs/configuration/examples/config/config.minimal.yaml +++ b/docs/configuration/examples/config/config.minimal.yaml @@ -6,6 +6,9 @@ authenticate_service_url: https://authenticate.localhost.pomerium.io # certificate settings: https://www.pomerium.io/docs/reference/certificates.html autocert: true +# REMOVE FOR PRODUCTION +autocert_use_staging: true + # identity provider settings : https://www.pomerium.io/docs/identity-providers.html idp_provider: google idp_client_id: REPLACE_ME diff --git a/docs/configuration/examples/docker/autocert.docker-compose.yml b/docs/configuration/examples/docker/autocert.docker-compose.yml new file mode 100644 index 000000000..a3e95aac5 --- /dev/null +++ b/docs/configuration/examples/docker/autocert.docker-compose.yml @@ -0,0 +1,18 @@ +version: "3" +services: + pomerium: + image: pomerium/pomerium:v0.7.0 + environment: + # Generate new secret keys. e.g. `head -c32 /dev/urandom | base64` + - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI= + volumes: + # Use a volume to store ACME certificates + - pomerium:/data:rw + ports: + - 443:443 + + # https://httpbin.corp.beyondperimeter.com --> Pomerium --> http://httpbin + httpbin: + image: kennethreitz/httpbin:latest + expose: + - 80 diff --git a/docs/configuration/readme.md b/docs/configuration/readme.md index 77ca6741e..c27bd70f0 100644 --- a/docs/configuration/readme.md +++ b/docs/configuration/readme.md @@ -150,15 +150,18 @@ Autocert requires that port `443` be accessible from the internet in order to co ::: -### Autocert Foler +### Autocert Directory - Environmental Variable: either `AUTOCERT_DIR` - Config File Key: `autocert_dir` -- Type: `string` pointing to the path of the folder +- Type: `string` pointing to the path of the directory - Required if using Autocert setting -- Default: [$XDG_DATA_HOME](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) or `$HOME/.local/share/pomerium` +- Default: + - `/data/autocert` in published Pomerium docker images + - [$XDG_DATA_HOME](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) + - `$HOME/.local/share/pomerium` -Autocert folder is path in which autocert will store x509 certificate data. +Autocert directory is path in which autocert will store x509 certificate data. ### Autocert Use Staging @@ -371,62 +374,62 @@ Expose a prometheus format HTTP endpoint on the specified port. Disabled by defa **Metrics tracked** -Name | Type | Description ---------------------------------------------- | --------- | ----------------------------------------------------------------------- -boltdb_free_alloc_size_bytes | Gauge | Bytes allocated in free pages -boltdb_free_page_n | Gauge | Number of free pages on the freelist -boltdb_freelist_inuse_size_bytes | Gauge | Bytes used by the freelist -boltdb_open_txn | Gauge | number of currently open read transactions -boltdb_pending_page_n | Gauge | Number of pending pages on the freelist -boltdb_txn | Gauge | total number of started read transactions -boltdb_txn_cursor_total | Counter | Total number of cursors created -boltdb_txn_node_deref_total | Counter | Total number of node dereferences -boltdb_txn_node_total | Counter | Total number of node allocations -boltdb_txn_page_alloc_size_bytes_total | Counter | Total bytes allocated -boltdb_txn_page_total | Counter | Total number of page allocations -boltdb_txn_rebalance_duration_ms_total | Counter | Total time spent rebalancing -boltdb_txn_rebalance_total | Counter | Total number of node rebalances -boltdb_txn_spill_duration_ms_total | Counter | Total time spent spilling -boltdb_txn_spill_total | Counter | Total number of nodes spilled -boltdb_txn_split_total | Counter | Total number of nodes split -boltdb_txn_write_duration_ms_total | Counter | Total time spent writing to disk -boltdb_txn_write_total | Counter | Total number of writes performed -groupcache_cache_hits_total | Counter | Total cache hits in local or cluster cache -groupcache_cache_hits_total | Counter | Total cache hits in local or cluster cache -groupcache_gets_total | Counter | Total get request, including from peers -groupcache_loads_deduped_total | Counter | gets without cache hits after duplicate suppression -groupcache_loads_total | Counter | Total gets without cache hits -groupcache_local_load_errs_total | Counter | Total local load errors -groupcache_local_loads_total | Counter | Total good local loads -groupcache_peer_errors_total | Counter | Total errors from peers -groupcache_peer_loads_total | Counter | Total remote loads or cache hits without error -groupcache_server_requests_total | Counter | Total gets from peers -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 -grpc_client_response_size_bytes | Histogram | GRPC client response size by service -grpc_server_request_duration_ms | Histogram | GRPC server request duration by service -grpc_server_request_size_bytes | Histogram | GRPC server request size by service -grpc_server_requests_total | Counter | Total GRPC server requests made by service -grpc_server_response_size_bytes | Histogram | GRPC server response size by service -http_client_request_duration_ms | Histogram | HTTP client request duration by service -http_client_request_size_bytes | Histogram | HTTP client request size by service -http_client_requests_total | Counter | Total HTTP client requests made by service -http_client_response_size_bytes | Histogram | HTTP client response size by service -http_server_request_duration_ms | Histogram | HTTP server request duration 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_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_hits_total | Counter | Total number of times free connection was found in the pool -redis_idle_conns | Gauge | Number of idle connections in the pool -redis_misses_total | Counter | Total number of times free connection was NOT found in the pool -redis_stale_conns_total | Counter | Total number of stale connections removed from the pool -redis_timeouts_total | Counter | Total number of times a wait timeout occurred +| Name | Type | Description | +| --------------------------------------------- | --------- | ----------------------------------------------------------------------- | +| boltdb_free_alloc_size_bytes | Gauge | Bytes allocated in free pages | +| boltdb_free_page_n | Gauge | Number of free pages on the freelist | +| boltdb_freelist_inuse_size_bytes | Gauge | Bytes used by the freelist | +| boltdb_open_txn | Gauge | number of currently open read transactions | +| boltdb_pending_page_n | Gauge | Number of pending pages on the freelist | +| boltdb_txn | Gauge | total number of started read transactions | +| boltdb_txn_cursor_total | Counter | Total number of cursors created | +| boltdb_txn_node_deref_total | Counter | Total number of node dereferences | +| boltdb_txn_node_total | Counter | Total number of node allocations | +| boltdb_txn_page_alloc_size_bytes_total | Counter | Total bytes allocated | +| boltdb_txn_page_total | Counter | Total number of page allocations | +| boltdb_txn_rebalance_duration_ms_total | Counter | Total time spent rebalancing | +| boltdb_txn_rebalance_total | Counter | Total number of node rebalances | +| boltdb_txn_spill_duration_ms_total | Counter | Total time spent spilling | +| boltdb_txn_spill_total | Counter | Total number of nodes spilled | +| boltdb_txn_split_total | Counter | Total number of nodes split | +| boltdb_txn_write_duration_ms_total | Counter | Total time spent writing to disk | +| boltdb_txn_write_total | Counter | Total number of writes performed | +| groupcache_cache_hits_total | Counter | Total cache hits in local or cluster cache | +| groupcache_cache_hits_total | Counter | Total cache hits in local or cluster cache | +| groupcache_gets_total | Counter | Total get request, including from peers | +| groupcache_loads_deduped_total | Counter | gets without cache hits after duplicate suppression | +| groupcache_loads_total | Counter | Total gets without cache hits | +| groupcache_local_load_errs_total | Counter | Total local load errors | +| groupcache_local_loads_total | Counter | Total good local loads | +| groupcache_peer_errors_total | Counter | Total errors from peers | +| groupcache_peer_loads_total | Counter | Total remote loads or cache hits without error | +| groupcache_server_requests_total | Counter | Total gets from peers | +| 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 | +| grpc_client_response_size_bytes | Histogram | GRPC client response size by service | +| grpc_server_request_duration_ms | Histogram | GRPC server request duration by service | +| grpc_server_request_size_bytes | Histogram | GRPC server request size by service | +| grpc_server_requests_total | Counter | Total GRPC server requests made by service | +| grpc_server_response_size_bytes | Histogram | GRPC server response size by service | +| http_client_request_duration_ms | Histogram | HTTP client request duration by service | +| http_client_request_size_bytes | Histogram | HTTP client request size by service | +| http_client_requests_total | Counter | Total HTTP client requests made by service | +| http_client_response_size_bytes | Histogram | HTTP client response size by service | +| http_server_request_duration_ms | Histogram | HTTP server request duration 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_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_hits_total | Counter | Total number of times free connection was found in the pool | +| redis_idle_conns | Gauge | Number of idle connections in the pool | +| redis_misses_total | Counter | Total number of times free connection was NOT found in the pool | +| redis_stale_conns_total | Counter | Total number of stale connections removed from the pool | +| redis_timeouts_total | Counter | Total number of times a wait timeout occurred | ### Tracing @@ -436,10 +439,10 @@ Each unit work is called a Span in a trace. Spans include metadata about the wor #### Shared Tracing Settings -Config Key | Description | Required -:--------------- | :---------------------------------------------------------------- | -------- -tracing_provider | The name of the tracing provider. (e.g. jaeger) | ✅ -tracing_debug | Will disable [sampling](https://opencensus.io/tracing/sampling/). | ❌ +| Config Key | Description | Required | +| :--------------- | :---------------------------------------------------------------- | -------- | +| tracing_provider | The name of the tracing provider. (e.g. jaeger) | ✅ | +| tracing_debug | Will disable [sampling](https://opencensus.io/tracing/sampling/). | ❌ | #### Jaeger @@ -451,10 +454,10 @@ tracing_debug | Will disable [sampling](https://opencensus.io/tracing/samplin - Service dependency analysis - Performance / latency optimization -Config Key | Description | Required -:-------------------------------- | :------------------------------------------ | -------- -tracing_jaeger_collector_endpoint | Url to the Jaeger HTTP Thrift collector. | ✅ -tracing_jaeger_agent_endpoint | Send spans to jaeger-agent at this address. | ✅ +| Config Key | Description | Required | +| :-------------------------------- | :------------------------------------------ | -------- | +| tracing_jaeger_collector_endpoint | Url to the Jaeger HTTP Thrift collector. | ✅ | +| tracing_jaeger_agent_endpoint | Send spans to jaeger-agent at this address. | ✅ | #### Example diff --git a/docs/docs/quick-start/readme.md b/docs/docs/quick-start/readme.md index ce6e76c69..94011fc74 100644 --- a/docs/docs/quick-start/readme.md +++ b/docs/docs/quick-start/readme.md @@ -26,7 +26,21 @@ Create a [configuration file] (e.g `config.yaml`) for defining Pomerium's config Ensure the `docker-compose.yml` contains the correct path to your `config.yaml`. -### Docker-compose +### Autocert Docker-compose +Ensure you have set up the requisite DNS and port forwarding in [TLS certificates] + +Download the following `docker-compose.yml` file and modify it to: + +- generate new secrets +- mount your [TLS certificates] +- mount your `config.yaml` [configuration file] +- Set `autocert_use_staging` to `false` once you have finished testing + +<<< @/docs/configuration/examples/docker/autocert.docker-compose.yml + +Please note that you should use a persistent volume to store certificate data, or you may exhaust your domain quota on Let's Encrypt. + +### Wildcard Docker-compose Download the following `docker-compose.yml` file and modify it to: