Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rewrite all-in-one vs split-service #1800

Merged
merged 1 commit into from
Mar 7, 2025
Merged

rewrite all-in-one vs split-service #1800

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 9 additions & 10 deletions content/docs/internals/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -32,15 +33,11 @@ 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.

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.
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.

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.
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.

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';
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

Expand All @@ -56,11 +53,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

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.
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.

Please also see [Architecture](/docs/internals/architecture) for information on component interactions.

Expand Down
Loading