Updates configuration page #1532

ZPain8464 · 2024-07-22T19:47:18Z

This PR update the location and some of the content in the "Configuration" page. This page was originally in /docs/internals/configuration.

I've intentionally left the "All In One and Split Service modes" sections sparse, as this a Draft PR. We could expand on this section in a separate capabilities page or even a guide, but for now, I didn't change much besides adding a "Our recommendation" tip, which could also be fine tuned.

TODOs:

Fix breaking anchors

Resolves https://github.com/pomerium/internal/issues/1853

netlify · 2024-07-22T19:47:36Z

✅ Deploy Preview for pomerium-docs ready!

Name	Link
🔨 Latest commit	`35ccd63`
🔍 Latest deploy log	https://app.netlify.com/sites/pomerium-docs/deploys/66ce400d3b0a8200084e3afa
😎 Deploy Preview	https://deploy-preview-1532--pomerium-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

kenjenkins

Thanks, I think this is a step in the right direction. I've left some comments, but please let me know if you're looking for more high-level feedback first.

content/docs/core/configuration.md

kenjenkins · 2024-07-25T22:57:57Z

content/docs/core/configuration.md

+
+See the [Reference](/docs/reference) page for a comprehensive list of Pomerium's configuration settings.
+
+## All In One and Split Service modes


I think we hyphenate "all-in-one" most other places in the docs. Should we stick with that here too?

So this is a style question, and a product one. We're very inconsistent in our docs with either of these modes. It's frequently used as a compound adjective, in which case "all-in-one mode" or "split-service mode" makes sense.

Take this page for example:

For all-in-one deployments, no changes are required...

For split-service deployments, you will need to deploy an additional service called cache...

This is fine in this context.

When we refer to these modes as a deployment type, it's actually a noun, if not a proper noun. For example, this page shows the inconsistency and how it's used as both a compound adjective and a noun:
"The other service URL settings are needed only for split service deployments. When running in all-in-one mode (which is the recommended mode), these settings are not needed."

We have the liberty to decide how it should be used in our docs. In my opinion, these modes should be referred to as proper nouns, so "All In One mode" or "Split Service mode". I don't mind changing it to "All-in-One" mode and "Split-Service" mode, or "All in One" mode (we don't have to capitalize "in" either) and "Split Service" mode, but we should define it and stick to it.

I can be lazy about it as well. This is where a style guide would help enforce the decision. Thoughts?

content/docs/core/configuration.md

kenjenkins · 2024-07-25T23:00:08Z

content/docs/core/configuration.md

+
+See the [Reference](/docs/reference) page for a comprehensive list of Pomerium's configuration settings.
+
+## All In One and Split Service modes


Actually, should we have a separate page to talk about all-in-one and split service mode? This almost feels like a different topic to me.

@desimone would love to hear your thoughts on this.

Yeah, if we moved this topic to a separate page, we could offload some of the content in High Availability as well.

It begs the question of where we'd put a All In One vs Split Services mode page, though. Capabilities doesn't seem like the best place.

should we have a separate page to talk about all-in-one and split service mode? This almost feels like a different topic to me.

Yes, I think that makes a lot of sense.

I've created a separate issue for work on a new All in One vs Split Services Mode page:

https://github.com/pomerium/internal/issues/1879

I'll move the Settings Modes section in a separate PR addressing the aforementioned ticket.

Co-authored-by: Kenneth Jenkins <[email protected]>

ZPain8464 · 2024-08-27T14:08:58Z

Hey @kenjenkins, I created a ticket for a new All in one vs. Split services mode page, but I moved it to backlog for now. To move this along, I also removed the dashes you mentioned earlier. We can address style guide decisions in the other ticket.

kenjenkins · 2024-08-27T19:29:34Z

content/docs/capabilities/high-availability.mdx

@@ -10,7 +10,7 @@ import InstallMkcert from '@site/content/_install-mkcert.md';

 Pomerium is designed to be run in two modes: All-In-One or Split Service. These modes are not mutually exclusive, meaning you can run one or multiple instances of Pomerium in all-in-one mode, and spin up additional instances for specific components as needed.

-Each instance of Pomerium runs in all-in-one mode unless specified to run as a specific component by the `services` key. See [All-In-One vs. Split Service mode](/docs/internals/configuration#all-in-one-vs-split-service-mode) for more details.
+Each instance of Pomerium runs in all-in-one mode unless specified to run as a specific component by the `services` key. See [All-In-One vs. Split Service mode](/docs/core/configuration#all-in-one-and-split-service-modes-split-service-mode) for more details.


Does this link target exist? Should it be #all-in-one-and-split-service-modes instead?

(ditto throughout this PR)

kenjenkins · 2024-08-27T19:32:57Z

content/docs/core/configuration.md

+
+Both configuration file keys and environment variables are case sensitive.
+
+Configuration file keys are always lowercase. Environmental variables are identical to configuration file keys, except they are always uppercase.


Environmental -> environment here if we want to be consistent with this.

I missed this instance and updated it for this page. But, there are many instances elsewhere in our docs that use "environmental". I'll note this decision for future PRs, though.

kenjenkins · 2024-08-27T19:36:39Z

content/docs/core/configuration.md

+
+### All-In-One mode
+
+All-In-One mode means all of Pomerium's configuration settings are set in a single configuration file. You can use All-In-One mode when running Pomerium:


For me this is not a clear explanation of the difference between all-in-one and split service mode.

In all-in-one mode, a single Pomerium process runs all of the four logical services. In split service mode, each logical service runs as its own process.

kenjenkins · 2024-08-27T19:39:52Z

content/docs/core/configuration.md

+
+### All-In-One mode
+
+All-In-One mode means all of Pomerium's configuration settings are set in a single configuration file. You can use All-In-One mode when running Pomerium:


I would prefer we pick one way to write "all-in-one" mode and use it consistently. By my count the existing docs have:

49 instances of "all-in-one"

3 instances of "All-in-One"

1 instance each of "All-in-one" and "All-in-One"

Based on the existing usage "All-In-One" looks out of place to me here.

OK. I left a comment earlier which explains my position on this. But, I've updated this page so that is uses "All-in-One".

For the record, I'm saying "all-in-one" (lowercase) would be most consistent with the existing documentation. If you don't think we should aim to be consistent I won't argue the point any further.

kenjenkins · 2024-08-27T21:21:10Z

content/docs/core/configuration.md

+All-in-One mode means a single Pomerium process runs all of the [four logical services](/docs/internals/architecture#component-level). You can use All-in-One mode when running Pomerium:
+
+- As a single system service or container, or
+- In a distributed environment where there are multiple processes that each handle separate [Pomerium services](/docs/internals/architecture#component-level).


I don't understand what this is saying. In all-in-one mode the services are combined, not separate.

kenjenkins · 2024-08-27T21:32:02Z

content/docs/core/configuration.md

+
+:::tip Our recommendation
+
+We recommend All-in-One mode to configure Pomerium for the following reasons:


The word order here feels backwards to me.

Suggested change

We recommend All-in-One mode to configure Pomerium for the following reasons:

We recommend running Pomerium in all-in-one mode for the following reasons:

kenjenkins · 2024-08-27T21:35:41Z

content/docs/core/configuration.md

+
+### Split-Service mode
+
+Alternately, you can create individual configuration files (or sets of environment variables) for each Pomerium service. In Split-Service mode, each configuration file (or set of environment variables) defines which service a process will run by using the [service mode](/docs/reference/service-mode) key.


I think it would be good to start with a brief explanation of how split service mode differs from all-in-one mode. Probably also good to link to the Service URL Settings page here. Maybe something like this?

Suggested change

Alternately, you can create individual configuration files (or sets of environment variables) for each Pomerium service. In Split-Service mode, each configuration file (or set of environment variables) defines which service a process will run by using the [service mode](/docs/reference/service-mode) key.

Alternatively, you can run each Pomerium service as its own process. You might want to do this in order to scale each service independently, or so that you can enforce different permissions on each service.

To configure Pomerium in this mode, you will need to create individual configuration files (or sets of environment variables) for each Pomerium service. Each configuration should set the [Service Mode](/docs/reference/service-mode) option to tell Pomerium which service to run. You will also need the [Service URL Settings](/docs/reference/service-urls) to tell each Pomerium service how to communicate with the other Pomerium services.

ZPain8464 added 5 commits July 18, 2024 15:00

moves config page

e9c281a

updates content

ecb37ef

updates configuration page

ab2c3c6

updates modes section

858b3cc

updates text

1316379

ZPain8464 added the backport 0-26-0 label Jul 22, 2024

ZPain8464 requested a review from kenjenkins July 22, 2024 19:47

ZPain8464 added 2 commits July 22, 2024 15:52

adds redirect

8bba5e7

fixes breaking links to pass build

9945d62

kenjenkins reviewed Jul 25, 2024

View reviewed changes

ZPain8464 and others added 2 commits July 26, 2024 11:34

Update content/docs/core/configuration.md

61c45f1

Co-authored-by: Kenneth Jenkins <[email protected]>

adds feedback

3ba9a2a

ZPain8464 marked this pull request as ready for review August 5, 2024 14:52

ZPain8464 requested a review from a team as a code owner August 5, 2024 14:52

ZPain8464 requested review from cmo-pomerium and removed request for a team August 5, 2024 14:52

merges main

fc8136a

fixes broken links

ff27ba5

kenjenkins reviewed Aug 27, 2024

View reviewed changes

ZPain8464 added 2 commits August 27, 2024 16:46

updates links

b9790e1

text updates

35ccd63

kenjenkins reviewed Aug 27, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updates configuration page #1532

Updates configuration page #1532

ZPain8464 commented Jul 22, 2024 •

edited

Loading

netlify bot commented Jul 22, 2024 •

edited

Loading

kenjenkins left a comment

kenjenkins Jul 25, 2024

ZPain8464 Jul 26, 2024 •

edited

Loading

kenjenkins Jul 25, 2024

ZPain8464 Jul 26, 2024

desimone Aug 4, 2024

ZPain8464 Aug 5, 2024

ZPain8464 Aug 5, 2024

ZPain8464 commented Aug 27, 2024

kenjenkins Aug 27, 2024

ZPain8464 Aug 27, 2024

kenjenkins Aug 27, 2024

ZPain8464 Aug 27, 2024

kenjenkins Aug 27, 2024

ZPain8464 Aug 27, 2024

kenjenkins Aug 27, 2024

ZPain8464 Aug 27, 2024

kenjenkins Aug 27, 2024

kenjenkins Aug 27, 2024

kenjenkins Aug 27, 2024

kenjenkins Aug 27, 2024


		See the [Reference](/docs/reference) page for a comprehensive list of Pomerium's configuration settings.

		## All In One and Split Service modes


		Both configuration file keys and environment variables are case sensitive.

		Configuration file keys are always lowercase. Environmental variables are identical to configuration file keys, except they are always uppercase.


		### All-In-One mode

		All-In-One mode means all of Pomerium's configuration settings are set in a single configuration file. You can use All-In-One mode when running Pomerium:


		:::tip Our recommendation

		We recommend All-in-One mode to configure Pomerium for the following reasons:

	We recommend All-in-One mode to configure Pomerium for the following reasons:
	We recommend running Pomerium in all-in-one mode for the following reasons:


		### Split-Service mode

		Alternately, you can create individual configuration files (or sets of environment variables) for each Pomerium service. In Split-Service mode, each configuration file (or set of environment variables) defines which service a process will run by using the [service mode](/docs/reference/service-mode) key.

-Alternately, you can create individual configuration files (or sets of environment variables) for each Pomerium service. In Split-Service mode, each configuration file (or set of environment variables) defines which service a process will run by using the [service mode](/docs/reference/service-mode) key.
+Alternatively, you can run each Pomerium service as its own process. You might want to do this in order to scale each service independently, or so that you can enforce different permissions on each service.
+To configure Pomerium in this mode, you will need to create individual configuration files (or sets of environment variables) for each Pomerium service. Each configuration should set the [Service Mode](/docs/reference/service-mode) option to tell Pomerium which service to run. You will also need the [Service URL Settings](/docs/reference/service-urls) to tell each Pomerium service how to communicate with the other Pomerium services.

Updates configuration page #1532

Are you sure you want to change the base?

Updates configuration page #1532

Conversation

ZPain8464 commented Jul 22, 2024 • edited Loading

netlify bot commented Jul 22, 2024 • edited Loading

✅ Deploy Preview for pomerium-docs ready!

kenjenkins left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ZPain8464 Jul 26, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ZPain8464 commented Aug 27, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ZPain8464 commented Jul 22, 2024 •

edited

Loading

netlify bot commented Jul 22, 2024 •

edited

Loading

ZPain8464 Jul 26, 2024 •

edited

Loading