Docs: updates HA page #1034
Docs: updates HA page #1034
Conversation
✅ Deploy Preview for pomerium-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| @@ -20,14 +20,26 @@ 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. | |||
| It may be desirable to run in **all-in-one** (AIO) mode in smaller deployments or while testing. This reduces the resource footprint and simplifies DNS configuration. An AIO instance may also be scaled for better performance. All URLs point at the same Pomerium service instance. | |||
There was a problem hiding this comment.
(optional)
Do we use the abbreviation "AIO" elsewhere? My 2 cents is that it might be clearer to keep writing out "all-in-one" throughout this section rather than abbreviating.
| @@ -20,14 +20,26 @@ 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. | |||
| It may be desirable to run in **all-in-one** (AIO) mode in smaller deployments or while testing. This reduces the resource footprint and simplifies DNS configuration. An AIO instance may also be scaled for better performance. All URLs point at the same Pomerium service instance. | |||
There was a problem hiding this comment.
I wonder if this is a bit of a mixed message. Should we rephrase "It may be desirable..." to be more direct about what the recommendation is?
| It may be desirable to run in **all-in-one** (AIO) mode in smaller deployments or while testing. This reduces the resource footprint and simplifies DNS configuration. An AIO instance may also be scaled for better performance. All URLs point at the same Pomerium service instance. | |
| We recommend running Pomerium in **all-in-one** mode for typical deployments. This reduces the resource footprint and simplifies DNS configuration (one service handles all Pomerium URLs). An all-in-one deployment may be scaled for performance and availability by running multiple instances. |
(Not sure if we still need the "tip" callout if we rephrase this section?)
|
|
||
| If your use case requires you to deploy multiple instances of a Pomerium service(s), we suggest deploying multiple replicas of an AIO configuration rather than deploying multiple instances in split-service mode. | ||
|
|
||
| ::: | ||
|
|
||
| ### 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. |
There was a problem hiding this comment.
Should we update this section accordingly? My understanding is that we do not recommend the split service mode except in exceptional cases.
| @@ -36,7 +48,7 @@ All of Pomerium's components are designed to be [stateless](/docs/internals/glos | |||
|
|
|||
| The Databroker service, which is responsible for session and identity related data, must be [configured for external persistence](/docs/internals/data-storage) to be fully stateless. | |||
|
|
|||
| Pomerium's individual components can be divided into two categories; the data plane and control plane. Regardless of which mode you run Pomerium in, we strongly recommend multiple instances of each service for fault tolerance. | |||
| Pomerium's individual components can be divided into two categories: the **Data Plane** and **Control Plane**. Regardless of which mode you run Pomerium in, we strongly recommend multiple instances of each service for fault tolerance. | |||
There was a problem hiding this comment.
(optional, may be out of scope for this PR)
I'm not sure I understand what this first sentence means. My reaction is to ask follow-up questions like "which components belong to which category?" or "what do I need to know about the data plane and control plane?" and I don't see that we come back to this concept until much later (in the "Databroker" section).
For that matter, I don't see any other references to the control plane on this page?
I wonder if makes sense to just remove the sentence here about the data plane and control plane?
|
|
||
| The following setup would demonstrate a minimum configuration for the split-service mode, using docker compose on a local host. | ||
| The following configuration demonstrates a minimum configuration for the split-service mode, using Docker Compose on a local host. |
There was a problem hiding this comment.
nit: "minimum" -> "minimal" ?
|
|
||
| This guide intentionally omits provisioning certificates for internal Pomerium interaction for simplicity. | ||
| This guide intentionally omits provisioning certificates for internal Pomerium interactions for simplicity. |
There was a problem hiding this comment.
What are "internal Pomerium interactions"? Does this refer to service-to-service communication? We might want to rephrase this to clarify.
| This should output two files: | ||
|
|
||
| - `_wildcard.localhost.pomerium.io-key.pem` | ||
| - `_wildcard.localhost.pomerium.io.pem` (This is a special domain that always resolves to `127.0.0.1`.) |
There was a problem hiding this comment.
(optional)
| - `_wildcard.localhost.pomerium.io.pem` (This is a special domain that always resolves to `127.0.0.1`.) | |
| - `_wildcard.localhost.pomerium.io.pem` | |
| (Our DNS is configured so that all sub-domains of "localhost.pomerium.io" will resolve to the loopback address `127.0.0.1`.) |
| @@ -144,7 +161,7 @@ Copy the certificate authority cert: | |||
| cp "$(mkcert --CAROOT)"/rootCA.pem . | |||
| ``` | |||
|
|
|||
| Create minimum Pomerium configuration file, filling in your identity provider parameters: | |||
| Create a minimum Pomerium configuration file, filling in your identity provider parameters: | |||
There was a problem hiding this comment.
same here: "minimum" -> "minimal" ?
| @@ -122,20 +134,25 @@ Multiple replicas of Databroker or all-in-one service are only supported with [e | |||
|
|
|||
| ::: | |||
|
|
|||
| ## Example | |||
| ## Example: Split-Service Mode | |||
There was a problem hiding this comment.
Question: should this whole section be moved into a separate guide page?
I think we're trying to emphasize that you can run a high-availability deployment in either all-in-one or split-service mode, so I don't know if it makes sense to demonstrate the split-service mode here.
Also, the example configuration below doesn't run multiple replicas of the services, does it? I'm not sure it belongs on a page about high availability at all, if we're no longer recommending that all HA deployments use split-service mode.
|
Closing this PR as it's stale. |
This PR updates the High Availability page:
Enterprisepill denoting an Enterprise feature in the Sidebar, and moves HA above the TCP section.Resolves https://github.com/pomerium/internal/issues/1549