From b945ff26e0344c9153034c869d2818197110e97e Mon Sep 17 00:00:00 2001 From: Ross Smith Date: Wed, 5 Mar 2025 16:59:53 -0500 Subject: [PATCH 1/5] rewrite all-in-one vs split-service --- content/docs/internals/configuration.mdx | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/content/docs/internals/configuration.mdx b/content/docs/internals/configuration.mdx index dca6379d0..64a22e257 100644 --- a/content/docs/internals/configuration.mdx +++ b/content/docs/internals/configuration.mdx @@ -7,13 +7,14 @@ keywords: - configuration - settings - environment variables - - split service mode - docker compose - all-in-one mode - advanced pomerium config lang: en-US --- +import InstallMkcert from '@site/content/docs/admonitions/_install-mkcert.md'; + # Configuration & Settings Pomerium can be configured using a configuration file ([YAML]/[JSON]/[TOML]) or [environmental variables]. In general, environmental variable keys are identical to config file keys but are uppercase. Enterprise users will be able to set these settings in the GUI, or using the API. @@ -32,15 +33,13 @@ See the [reference](/docs/reference) page for a complete list of available optio ## All-In-One vs Split Service mode -When running Pomerium as a single system service or container, all the options on this page can be set in a single `config.yaml` file, or passed to the single instance as environment variables. +Pomerium's default mode is all-in-one mode. It run all the indivudual [components](/docs/internals/architecture#component-level) in a single container or under a single system service. This is our suggested way to run Pomerium. Alternatively, each of those component services can be configured and run separately in split mode. -When running Pomerium in a distributed environment where there are multiple processes, each handling separate [components](/docs/internals/architecture#component-level), all services can still share a single config file or set of environment variables. +All-in-one mode has the easiest configuration and successfully used in large production environments. All the configuration goes in a single `config.yaml` file or single set of environment variables. +When running Pomerium as a single system service or container, all the options on this page can be set in a single `config.yaml` file, or passed to the single instance as environment variables. Internal communication is configured automatically requiring no addtional setup. -Alternately, you can create individual config files or sets of environment variables for each service. When doing so, each file or set can define which component a process will run as using the [service mode](/docs/reference/service-mode) key. +Alternatively, each component can be run separately in split-mode using the [service mode](/docs/reference/service-mode) key to specify which component to run. Each of these needs to be configured separately, and communication between components must be explicitly configured including managing tls certificates. -The table contains all config options for Pomerium Core. You can also browse each key using the index on the left. - -import InstallMkcert from '@site/content/docs/admonitions/_install-mkcert.md'; ## Service Mode @@ -56,10 +55,13 @@ Any production deployment with more than one instance of Pomerium (in any combin ### All-in-One -It may be desirable to run in "all-in-one" mode in smaller deployments or while testing. This reduces the resource footprint and simplifies DNS configuration. An all-in-one instances may also be scaled for better performance. All URLs point at the same Pomerium service instance. +For almost all use cases it's desirable to run in "all-in-one" mode. This reduces the resource footprint and simplifies DNS configuration. An all-in-one instances may also be scaled for better performance. All URLs point at the same Pomerium service instance. ### Discrete Services +Split service mode is only advised for learning how the components interact, extremely security constrained environments or to workaround constraints in host environment. + +The split service mode can limit the blast radius in the event of a compromised container and can enable independet scaling of components. These features come with some downsides. There will be increased latency to the authorize service, which is consulted on every request. In addition to complicating upgrades, the additional configuration makes debugging configuration errors more difficult. In larger footprints, it is recommended to run Pomerium as a collection of discrete service clusters. This limits blast radius in the event of vulnerabilities and allows for per-service [scaling](#scaling) and monitoring. Please also see [Architecture](/docs/internals/architecture) for information on component interactions. From 816a2c61b1747aa0f63bf83be4f2124c379cf55a Mon Sep 17 00:00:00 2001 From: Ross Smith Date: Wed, 5 Mar 2025 17:16:27 -0500 Subject: [PATCH 2/5] pre-commit changes --- content/docs/internals/configuration.mdx | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/content/docs/internals/configuration.mdx b/content/docs/internals/configuration.mdx index 64a22e257..db62796f8 100644 --- a/content/docs/internals/configuration.mdx +++ b/content/docs/internals/configuration.mdx @@ -33,13 +33,11 @@ See the [reference](/docs/reference) page for a complete list of available optio ## All-In-One vs Split Service mode -Pomerium's default mode is all-in-one mode. It run all the indivudual [components](/docs/internals/architecture#component-level) in a single container or under a single system service. This is our suggested way to run Pomerium. Alternatively, each of those component services can be configured and run separately in split mode. +Pomerium's default mode is all-in-one mode. It run all the individual [components](/docs/internals/architecture#component-level) in a single container or under a single system service. This is our suggested way to run Pomerium. Alternatively, each of those component services can be configured and run separately in split mode. -All-in-one mode has the easiest configuration and successfully used in large production environments. All the configuration goes in a single `config.yaml` file or single set of environment variables. -When running Pomerium as a single system service or container, all the options on this page can be set in a single `config.yaml` file, or passed to the single instance as environment variables. Internal communication is configured automatically requiring no addtional setup. - -Alternatively, each component can be run separately in split-mode using the [service mode](/docs/reference/service-mode) key to specify which component to run. Each of these needs to be configured separately, and communication between components must be explicitly configured including managing tls certificates. +All-in-one mode has the easiest configuration and successfully used in large production environments. All the configuration goes in a single `config.yaml` file or single set of environment variables. When running Pomerium as a single system service or container, all the options on this page can be set in a single `config.yaml` file, or passed to the single instance as environment variables. Internal communication is configured automatically requiring no additional setup. +Alternatively, each component can be run separately in split-mode using the [service mode](/docs/reference/service-mode) key to specify which component to run. Each of these needs to be configured separately, and communication between components must be explicitly configured including managing tls certificates. ## Service Mode @@ -61,8 +59,7 @@ For almost all use cases it's desirable to run in "all-in-one" mode. This reduce Split service mode is only advised for learning how the components interact, extremely security constrained environments or to workaround constraints in host environment. -The split service mode can limit the blast radius in the event of a compromised container and can enable independet scaling of components. These features come with some downsides. There will be increased latency to the authorize service, which is consulted on every request. In addition to complicating upgrades, the additional configuration makes debugging configuration errors more difficult. -In larger footprints, it is recommended to run Pomerium as a collection of discrete service clusters. This limits blast radius in the event of vulnerabilities and allows for per-service [scaling](#scaling) and monitoring. +The split service mode can limit the blast radius in the event of a compromised container and can enable independent scaling of components. These features come with some downsides. There will be increased latency to the authorize service, which is consulted on every request. In addition to complicating upgrades, the additional configuration makes debugging configuration errors more difficult. In larger footprints, it is recommended to run Pomerium as a collection of discrete service clusters. This limits blast radius in the event of vulnerabilities and allows for per-service [scaling](#scaling) and monitoring. Please also see [Architecture](/docs/internals/architecture) for information on component interactions. From 94ce4d3ecb4aa6af1be1feb8c8c987b5202fbad8 Mon Sep 17 00:00:00 2001 From: Ross Smith Date: Thu, 6 Mar 2025 19:11:51 -0800 Subject: [PATCH 3/5] Update content/docs/internals/configuration.mdx Co-authored-by: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com> --- content/docs/internals/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/internals/configuration.mdx b/content/docs/internals/configuration.mdx index db62796f8..dfc92fbe0 100644 --- a/content/docs/internals/configuration.mdx +++ b/content/docs/internals/configuration.mdx @@ -57,7 +57,7 @@ For almost all use cases it's desirable to run in "all-in-one" mode. This reduce ### Discrete Services -Split service mode is only advised for learning how the components interact, extremely security constrained environments or to workaround constraints in host environment. +Split service mode is only advised for learning how the components interact, extremely security constrained environments or to work around constraints in host environment. The split service mode can limit the blast radius in the event of a compromised container and can enable independent scaling of components. These features come with some downsides. There will be increased latency to the authorize service, which is consulted on every request. In addition to complicating upgrades, the additional configuration makes debugging configuration errors more difficult. In larger footprints, it is recommended to run Pomerium as a collection of discrete service clusters. This limits blast radius in the event of vulnerabilities and allows for per-service [scaling](#scaling) and monitoring. From c46c3a0103407b25a7aabe69a21b819db1366e56 Mon Sep 17 00:00:00 2001 From: Ross Smith Date: Thu, 6 Mar 2025 19:13:50 -0800 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com> --- content/docs/internals/configuration.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/internals/configuration.mdx b/content/docs/internals/configuration.mdx index dfc92fbe0..ce116cc68 100644 --- a/content/docs/internals/configuration.mdx +++ b/content/docs/internals/configuration.mdx @@ -33,11 +33,11 @@ See the [reference](/docs/reference) page for a complete list of available optio ## All-In-One vs Split Service mode -Pomerium's default mode is all-in-one mode. It run all the individual [components](/docs/internals/architecture#component-level) in a single container or under a single system service. This is our suggested way to run Pomerium. Alternatively, each of those component services can be configured and run separately in split mode. +Pomerium's default mode is all-in-one mode. It runs all the individual [components](/docs/internals/architecture#component-level) in a single container or under a single system service. This is our suggested way to run Pomerium. Alternatively, each of those component services can be configured and run separately in split mode. -All-in-one mode has the easiest configuration and successfully used in large production environments. All the configuration goes in a single `config.yaml` file or single set of environment variables. When running Pomerium as a single system service or container, all the options on this page can be set in a single `config.yaml` file, or passed to the single instance as environment variables. Internal communication is configured automatically requiring no additional setup. +All-in-one mode has the easiest configuration and is successfully used in large production environments. All the configuration goes in a single `config.yaml` file or single set of environment variables. When running Pomerium as a single system service or container, all the options on this page can be set in a single `config.yaml` file, or passed to the single instance as environment variables. Internal communication is configured automatically requiring no additional setup. -Alternatively, each component can be run separately in split-mode using the [service mode](/docs/reference/service-mode) key to specify which component to run. Each of these needs to be configured separately, and communication between components must be explicitly configured including managing tls certificates. +Alternatively, each component can be run separately in split-mode using the [service mode](/docs/reference/service-mode) key to specify which component to run. Each of these needs to be configured separately, and communication between components must be explicitly configured including managing TLS certificates. ## Service Mode From a6759a4796c50eec38597737f65348a934e58ff7 Mon Sep 17 00:00:00 2001 From: Ross Smith Date: Thu, 6 Mar 2025 19:16:25 -0800 Subject: [PATCH 5/5] remove redundant sentence --- content/docs/internals/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/internals/configuration.mdx b/content/docs/internals/configuration.mdx index ce116cc68..d785d6373 100644 --- a/content/docs/internals/configuration.mdx +++ b/content/docs/internals/configuration.mdx @@ -35,7 +35,7 @@ See the [reference](/docs/reference) page for a complete list of available optio Pomerium's default mode is all-in-one mode. It runs all the individual [components](/docs/internals/architecture#component-level) in a single container or under a single system service. This is our suggested way to run Pomerium. Alternatively, each of those component services can be configured and run separately in split mode. -All-in-one mode has the easiest configuration and is successfully used in large production environments. All the configuration goes in a single `config.yaml` file or single set of environment variables. When running Pomerium as a single system service or container, all the options on this page can be set in a single `config.yaml` file, or passed to the single instance as environment variables. Internal communication is configured automatically requiring no additional setup. +All-in-one mode has the easiest configuration and is successfully used in large production environments. All the configuration goes in a single `config.yaml` file or single set of environment variables. Internal communication is configured automatically requiring no additional setup. Alternatively, each component can be run separately in split-mode using the [service mode](/docs/reference/service-mode) key to specify which component to run. Each of these needs to be configured separately, and communication between components must be explicitly configured including managing TLS certificates.