Adds a custom domains Capabilities page/guide #1343

ZPain8464 · 2024-04-02T20:16:58Z

This PR adds a first draft of the Custom Domains capabilities page.

TODOs:

Add Cluster Concepts link once that's published
Add a Next Steps section
Possibly add a video? or add the guide portion as a separate Guide
Determine Reference page requirements for this

Related to https://github.com/pomerium/internal/issues/1766

netlify · 2024-04-02T20:17:13Z

✅ Deploy Preview for pomerium-docs ready!

Name	Link
🔨 Latest commit	`d1485c8`
🔍 Latest deploy log	https://app.netlify.com/sites/pomerium-docs/deploys/661822b999df460008fe4a31
😎 Deploy Preview	https://deploy-preview-1343--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.

desimone

Few comments. Would defer to @calebdoxsey for a technical review and @cmo-pomerium for copy.

content/docs/capabilities/custom-domains.mdx

desimone · 2024-04-02T20:47:43Z

content/docs/capabilities/custom-domains.mdx

+
+:::info
+
+See the Clusters Concepts page for more information about clusters in Pomerium Zero.


Assume link is coming?

Suggested change

See the Clusters Concepts page for more information about clusters in Pomerium Zero.

See the [Clusters] Concepts page for more information about clusters in Pomerium Zero.

desimone · 2024-04-02T20:48:44Z

sidebars.js

@@ -56,6 +56,8 @@ const sidebars = {
      type: 'category',
      label: 'Capabilities',
      items: [
+        // zero
+        'docs/capabilities/custom-domains',


Eventually we should probably put these all collected together with a prepended highlight like ent or something.

desimone · 2024-04-02T20:49:58Z

content/docs/capabilities/custom-domains.mdx

+
+### DNS validation
+
+In order for Pomerium to issue certificates on behalf of a custom domain, you must prove that you control the domain name specified in the certificate through DNS validation. Per the [ACME protocol](https://datatracker.ietf.org/doc/html/rfc8555#section-2), Pomerium uses its own ACME client to communicate with Let's Encrypt, a free Certificate Authority, to validate a domain's DNS records.


I think it's a nice detail we cover how.

Co-authored-by: bobby <[email protected]>

calebdoxsey · 2024-04-03T17:03:52Z

content/docs/capabilities/custom-domains.mdx

+Let's Encrypt provides several [challenge types](https://letsencrypt.org/docs/challenge-types/) to validate a domain, including the [DNS-01 challenge](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge). At a high level, this challenge consists of two steps:
+
+1. A TXT record containing a specific token value must be placed into the `_acme-challenge.<YOUR_DOMAIN>` endpoint
+1. A **wildcard CNAME record** must be added under the custom domain that points to your cluster's **Starter Domain**


It's more of an either/or.

Either a TXT record must be placed at _acme-challenge.<YOUR_DOMAIN>, or a CNAME record must be placed at _acme-challenge.<YOUR_DOMAIN> that points to another domain that has the TXT record. Since we own the .pomerium.app sub-domain, we can write the TXT record for them.

Using a *.<YOUR_DOMAIN> CNAME record also works for this. We recommend it because it also allows client requests to be forwarded to Pomerium.

calebdoxsey · 2024-04-03T17:06:28Z

content/docs/capabilities/custom-domains.mdx

+
+In the context of Pomerium Zero, an FQDN is the complete domain name of a custom domain. The example below resembles a valid FQDN, where `service` is the hostname, `mycorp` is the subdomain, and `example.com` is the domain name:
+
+`service.mycorp.example.com`


I'm not sure what the best example here would be. Maybe we should give some example routes?

For example, given routes like:

verify.mycorp.example.com

internal-tool.mycorp.example.com

authenticate.mycorp.example.com

You would want to use mycorp.example.com as the custom domain.

ZPain8464 · 2024-04-05T13:37:17Z

@calebdoxsey could you review this again when you have a second?

kenjenkins · 2024-04-10T16:06:01Z

content/docs/capabilities/custom-domains.mdx

+
+Each starter subdomain comes with its own DNS records and TLS certificates, which makes it easier for new users to quickly build and test routes and policies in Pomerium Zero.
+
+After testing Pomerium Zero with your starter domain, you may want to add a custom domain for use by your cluster's routes to secure your apps and services.


suggestion: "you may want" -> "you'll likely want"

content/docs/capabilities/custom-domains.mdx

kenjenkins · 2024-04-10T16:17:29Z

content/docs/capabilities/custom-domains.mdx

+
+In Pomerium Zero, a valid **Custom Domain** is a fully qualified domain name (FQDN) where the domain owner can demonstrate control over the domain through DNS validation.
+
+After you successfully add a custom domain to your cluster, Pomerium will automatically issue and renew X.509 wildcard certificates on behalf of the domain to secure the connection over TLS.


I'd suggest removing this paragraph if you like my suggestion for the previous paragraph.

(Otherwise, I'd suggest using "TLS certificate" rather than "X.509 certificate" as that's the terminology first used in the Overview section.)

kenjenkins · 2024-04-10T16:20:55Z

content/docs/capabilities/custom-domains.mdx

+### Fully Qualified Domain Names
+
+In the context of Pomerium Zero, an FQDN is the complete domain name of a custom domain. The example below resembles a valid custom domain, where `mycorp` is the subdomain and `example.com` is the domain name:
+
+`mycorp.example.com`
+
+If you build routes with this custom domain to upstream services with hostnames like `verify`, `internal-tool`, and `authenticate`, your routes would look like:


I wonder if we should skip some of the jargon where possible?

Maybe just:

Suggested change

### Fully Qualified Domain Names

In the context of Pomerium Zero, an FQDN is the complete domain name of a custom domain. The example below resembles a valid custom domain, where `mycorp` is the subdomain and `example.com` is the domain name:

`mycorp.example.com`

If you build routes with this custom domain to upstream services with hostnames like `verify`, `internal-tool`, and `authenticate`, your routes would look like:

Say you want to use Pomerium Zero with the domain `mycorp.example.com`. After adding this custom domain, you'll be able to build routes like:

kenjenkins · 2024-04-10T16:23:47Z

content/docs/capabilities/custom-domains.mdx

+- `internal-tool.mycorp.example.com`
+- `authenticate.mycorp.example.com`
+
+### DNS validation


I'd suggest moving this section further down, after "How to add a custom domain", and possibly renaming this section to "How it works". (I expect more users will want to know "how do I do this" compared to "what's going on behind the scenes".)

kenjenkins · 2024-04-10T16:25:15Z

content/docs/capabilities/custom-domains.mdx

+
+### DNS validation
+
+In order for Pomerium to issue certificates on behalf of a custom domain, you must prove that you control the domain name specified in the certificate through DNS validation. Per the [ACME protocol](https://datatracker.ietf.org/doc/html/rfc8555#section-2), Pomerium uses its own ACME client to communicate with Let's Encrypt, a free Certificate Authority, to validate a domain's DNS records.


one terminology nit: Pomerium doesn't "issue" certificates itself (only a "certificate authority" can do that), so if we want to be more precise I might suggest using "request" or "provision" instead of "issue".

kenjenkins · 2024-04-10T16:34:54Z

content/docs/capabilities/custom-domains.mdx

+
+## How to add a custom domain
+
+Add a wildcard CNAME record that points to your starter domain:


I wonder if we should include a little code snippet too?

Suggested change

Add a wildcard CNAME record that points to your starter domain:

Add a wildcard CNAME record that points to your starter domain, for example:

*.mycorp.example.com CNAME unique-jellyfish-3578.pomerium.app

In Google Cloud Platform, this looks something like:

For example, one of Cloudflare's help pages does something similar when giving instructions for adding a CNAME:

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

ZPain8464 added 4 commits April 2, 2024 13:53

adds first draft of custom domains

aa0478b

updates text

215c3e7

expands guide

cd2b2b3

runs prettier

e01d20a

ZPain8464 requested review from desimone, kenjenkins and cmo-pomerium April 2, 2024 20:16

ZPain8464 requested a review from a team as a code owner April 2, 2024 20:16

ZPain8464 added 2 commits April 2, 2024 16:19

fixes cspell error

1cd979c

fixes precommit failure

b344236

desimone reviewed Apr 2, 2024

View reviewed changes

ZPain8464 requested a review from calebdoxsey April 2, 2024 22:37

ZPain8464 and others added 3 commits April 3, 2024 10:59

Update content/docs/capabilities/custom-domains.mdx

dc1e3cb

Co-authored-by: bobby <[email protected]>

Update content/docs/capabilities/custom-domains.mdx

99ea94f

Co-authored-by: bobby <[email protected]>

Update content/docs/capabilities/custom-domains.mdx

3980d97

Co-authored-by: bobby <[email protected]>

calebdoxsey reviewed Apr 3, 2024

View reviewed changes

ZPain8464 added 2 commits April 3, 2024 14:10

updates text based on feedback

ebe2a43

updates description

a114898

ZPain8464 requested a review from calebdoxsey April 3, 2024 18:37

calebdoxsey approved these changes Apr 5, 2024

View reviewed changes

kenjenkins reviewed Apr 10, 2024

View reviewed changes

ZPain8464 and others added 3 commits April 11, 2024 09:43

Update content/docs/capabilities/custom-domains.mdx

35bb4df

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

updates guide based on feedback

7fed536

updates text

d1485c8

ZPain8464 merged commit 399a21c into main Apr 11, 2024
8 checks passed

ZPain8464 deleted the zpain/custom-domains-guide branch April 11, 2024 17:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adds a custom domains Capabilities page/guide #1343

Adds a custom domains Capabilities page/guide #1343

ZPain8464 commented Apr 2, 2024 •

edited

Loading

netlify bot commented Apr 2, 2024 •

edited

Loading

desimone left a comment

desimone Apr 2, 2024

ZPain8464 Apr 3, 2024

desimone Apr 2, 2024

desimone Apr 2, 2024

calebdoxsey Apr 3, 2024

calebdoxsey Apr 3, 2024

ZPain8464 commented Apr 5, 2024

kenjenkins Apr 10, 2024

kenjenkins Apr 10, 2024

kenjenkins Apr 10, 2024

kenjenkins Apr 10, 2024

kenjenkins Apr 10, 2024

kenjenkins Apr 10, 2024


		:::info

		See the Clusters Concepts page for more information about clusters in Pomerium Zero.

	See the Clusters Concepts page for more information about clusters in Pomerium Zero.
	See the [Clusters] Concepts page for more information about clusters in Pomerium Zero.


		### DNS validation

		In order for Pomerium to issue certificates on behalf of a custom domain, you must prove that you control the domain name specified in the certificate through DNS validation. Per the [ACME protocol](https://datatracker.ietf.org/doc/html/rfc8555#section-2), Pomerium uses its own ACME client to communicate with Let's Encrypt, a free Certificate Authority, to validate a domain's DNS records.


		In the context of Pomerium Zero, an FQDN is the complete domain name of a custom domain. The example below resembles a valid FQDN, where `service` is the hostname, `mycorp` is the subdomain, and `example.com` is the domain name:

		`service.mycorp.example.com`


		Each starter subdomain comes with its own DNS records and TLS certificates, which makes it easier for new users to quickly build and test routes and policies in Pomerium Zero.

		After testing Pomerium Zero with your starter domain, you may want to add a custom domain for use by your cluster's routes to secure your apps and services.


		In Pomerium Zero, a valid Custom Domain is a fully qualified domain name (FQDN) where the domain owner can demonstrate control over the domain through DNS validation.

		After you successfully add a custom domain to your cluster, Pomerium will automatically issue and renew X.509 wildcard certificates on behalf of the domain to secure the connection over TLS.


		## How to add a custom domain

		Add a wildcard CNAME record that points to your starter domain:

-Add a wildcard CNAME record that points to your starter domain:
+Add a wildcard CNAME record that points to your starter domain, for example:
+    *.mycorp.example.com CNAME unique-jellyfish-3578.pomerium.app
+In Google Cloud Platform, this looks something like:

Adds a custom domains Capabilities page/guide #1343

Adds a custom domains Capabilities page/guide #1343

Conversation

ZPain8464 commented Apr 2, 2024 • edited Loading

netlify bot commented Apr 2, 2024 • edited Loading

✅ Deploy Preview for pomerium-docs ready!

desimone left a 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 Apr 5, 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

ZPain8464 commented Apr 2, 2024 •

edited

Loading

netlify bot commented Apr 2, 2024 •

edited

Loading