From 0aa6855c8fc164fb0a6cd97732c7e4662e87108b Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Fri, 18 Mar 2022 14:19:36 -0400 Subject: [PATCH] Add notes about wildcard certificates (#9454) * Add notes about wildcard certificates Guides to getting started with Teleport on various platforms recommend creating a DNS record for *.teleport.com. It would help prospective users to know why this is needed. This change adds context for why Application Access requires a wildcard subdomain. Fixes #5378 * Respond to PR feedback - Move information into a partial - Mention that you can create a DNS A record for each application- specific subdomain * Restore DNS-related cloud provider commands --- docs/pages/application-access/getting-started.mdx | 8 ++++++-- .../application-access/guides/connecting-apps.mdx | 4 ++++ docs/pages/database-access/getting-started.mdx | 6 ++++++ docs/pages/getting-started/linux-server.mdx | 1 + docs/pages/includes/acme.mdx | 14 ++++++++++---- docs/pages/includes/dns-app-access.mdx | 4 ++++ docs/pages/includes/dns.mdx | 8 ++++++-- docs/pages/kubernetes-access/helm/guides/aws.mdx | 8 +++++--- docs/pages/kubernetes-access/helm/guides/gcp.mdx | 7 +++++-- docs/pages/kubernetes-access/helm/reference.mdx | 7 +++++-- 10 files changed, 52 insertions(+), 15 deletions(-) create mode 100644 docs/pages/includes/dns-app-access.mdx diff --git a/docs/pages/application-access/getting-started.mdx b/docs/pages/application-access/getting-started.mdx index 2a74d86521cd8..64f5f84ab118d 100644 --- a/docs/pages/application-access/getting-started.mdx +++ b/docs/pages/application-access/getting-started.mdx @@ -18,12 +18,16 @@ Let's connect to Grafana using Teleport Application Access in three steps: - A Docker installation, which we will use to launch Grafana in a container. Alternatively, if you have another web application you'd like to protect with Application Access, you can use that instead. - A host where you will run the Teleport Application Service. -We will assume your Teleport cluster is accessible at `teleport.example.com` and `*.teleport.example.com`. You can substitute the address of your Teleport Proxy Service. (For Teleport Cloud customers, this will be similar to `mytenant.teleport.sh`.) - If you have not yet deployed the Auth Service and Proxy Service, you should follow one of our [getting started guides](../getting-started.mdx). +We will assume your Teleport cluster is accessible at `teleport.example.com` and `*.teleport.example.com`. You can substitute the address of your Teleport Proxy Service. (For Teleport Cloud customers, this will be similar to `mytenant.teleport.sh`.) + + +(!docs/pages/includes/dns-app-access.mdx!) + + ## Step 1/3. Start Grafana We've picked Grafana for this tutorial since it's very easy to run with zero diff --git a/docs/pages/application-access/guides/connecting-apps.mdx b/docs/pages/application-access/guides/connecting-apps.mdx index e13f68ec7af53..d3c74ae36b496 100644 --- a/docs/pages/application-access/guides/connecting-apps.mdx +++ b/docs/pages/application-access/guides/connecting-apps.mdx @@ -54,6 +54,10 @@ applications. When setting up Teleport, the minimum requirement is a certificate for the proxy and a wildcard certificate for its sub-domain. This is where everyone will log into Teleport. + +(!docs/pages/includes/dns-app-access.mdx!) + + In our example: - `teleport.example.com` will host the Access Plane. diff --git a/docs/pages/database-access/getting-started.mdx b/docs/pages/database-access/getting-started.mdx index 7bf0d0d550b71..736f67050c1a5 100644 --- a/docs/pages/database-access/getting-started.mdx +++ b/docs/pages/database-access/getting-started.mdx @@ -88,6 +88,12 @@ using Let's Encrypt. (!docs/pages/includes/acme.mdx!) +We will assume that you have configured a DNS record for `teleport.example.com` to point to the node where you're launching Teleport. + +
+(!docs/pages/includes/dns-app-access.mdx!) +
+ ### Start Teleport Now start Teleport and point it to your Aurora database instance. Make sure to diff --git a/docs/pages/getting-started/linux-server.mdx b/docs/pages/getting-started/linux-server.mdx index c26235d62f8bb..a8f598e171d18 100644 --- a/docs/pages/getting-started/linux-server.mdx +++ b/docs/pages/getting-started/linux-server.mdx @@ -37,6 +37,7 @@ Take a look at the [Installation Guide](../installation.mdx) for more options. (!docs/pages/includes/permission-warning.mdx!) ### Configure DNS +Teleport uses TLS to provide secure access to its Proxy Service and Auth Service, and this requires a domain name that clients can use to verify Teleport's certificate. (!docs/pages/includes/dns.mdx!) diff --git a/docs/pages/includes/acme.mdx b/docs/pages/includes/acme.mdx index fb33518d61cdd..1f797f8594660 100644 --- a/docs/pages/includes/acme.mdx +++ b/docs/pages/includes/acme.mdx @@ -1,14 +1,20 @@ -Let's Encrypt verifies that you control the domain name of your Teleport deployment by communicating with the HTTPS server listening on port 443 of your Teleport Proxy Service. +Let's Encrypt verifies that you control the domain name of your Teleport cluster +by communicating with the HTTPS server listening on port 443 of your Teleport +Proxy Service. -You can configure the Teleport Proxy service to complete the Let's Encrypt verification process when it starts up. +You can configure the Teleport Proxy Service to complete the Let's Encrypt +verification process when it starts up. -Run the following `teleport configure` command, where `tele.example.com` is the domain name of your Teleport cluster and `user@example.com` is an email address used for notifications (you can use any domain): +Run the following `teleport configure` command, where `tele.example.com` is the +domain name of your Teleport cluster and `user@example.com` is an email address +used for notifications (you can use any domain): ```code teleport configure --acme --acme-email=user@example.com --cluster-name=tele.example.com > /etc/teleport.yaml ``` -The `--acme`, `--acme-email`, and `--cluster-name` flags will add the following settings to your Teleport configuration file: +The `--acme`, `--acme-email`, and `--cluster-name` flags will add the following +settings to your Teleport configuration file: ```yaml proxy_service: diff --git a/docs/pages/includes/dns-app-access.mdx b/docs/pages/includes/dns-app-access.mdx new file mode 100644 index 0000000000000..2e82bf6d8f64b --- /dev/null +++ b/docs/pages/includes/dns-app-access.mdx @@ -0,0 +1,4 @@ +Teleport assigns a subdomain to each application you have configured for Application +Access (e.g., `grafana.teleport.example.com`), so you will need to ensure that a DNS A record exists for each application-specific subdomain so clients can access your applications via Teleport. + +You should create either a separate DNS A record for each subdomain or a single record with a wildcard subdomain such as `*.teleport.example.com`. This way, your certificate authority (e.g., Let's Encrypt) can issue a certificate for each subdomain, enabling clients to verify your Teleport hosts regardless of the application they are accessing. diff --git a/docs/pages/includes/dns.mdx b/docs/pages/includes/dns.mdx index ba05ee3092ae6..cc2ebd938b822 100644 --- a/docs/pages/includes/dns.mdx +++ b/docs/pages/includes/dns.mdx @@ -1,5 +1,9 @@ -Set up two `A` DNS records - `tele.example.com` for all traffic and `*.tele.example.com` -for web apps using application access. +Set up two `A` DNS records: `tele.example.com` for all traffic and `*.tele.example.com` +for web apps using Application Access. + +
+(!docs/pages/includes/dns-app-access.mdx!) +
diff --git a/docs/pages/kubernetes-access/helm/guides/aws.mdx b/docs/pages/kubernetes-access/helm/guides/aws.mdx index 40df493c0aaaf..937f0a7d5a44b 100644 --- a/docs/pages/kubernetes-access/helm/guides/aws.mdx +++ b/docs/pages/kubernetes-access/helm/guides/aws.mdx @@ -314,9 +314,11 @@ $ kubectl --namespace teleport get all ## Step 6/7. Set up DNS -You'll need to set up two DNS `A` records: `teleport.example.com` for the web UI, and `*.teleport.example.com` -for web apps using [application access](../../../application-access/introduction.mdx). In our example, both records are -aliases to an ELB. +You'll need to set up a DNS `A` record for `teleport.example.com`. In our example, this record is an alias to an ELB. + +
+(!docs/pages/includes/dns-app-access.mdx!) +
Here's how to do this in a hosted zone with AWS Route 53: diff --git a/docs/pages/kubernetes-access/helm/guides/gcp.mdx b/docs/pages/kubernetes-access/helm/guides/gcp.mdx index d24c698b390ca..7cd82598e7aa8 100644 --- a/docs/pages/kubernetes-access/helm/guides/gcp.mdx +++ b/docs/pages/kubernetes-access/helm/guides/gcp.mdx @@ -358,8 +358,11 @@ $ kubectl --namespace teleport get all ## Step 6/7. Set up DNS -You'll need to set up two DNS `A` records: `teleport.example.com` for the web UI, and `*.teleport.example.com` -for web apps using [application access](../../../application-access/introduction.mdx). +You'll need to set up a DNS `A` record for `teleport.example.com`. + +
+(!docs/pages/includes/dns-app-access.mdx!) +
Here's how to do this using Google Cloud DNS: diff --git a/docs/pages/kubernetes-access/helm/reference.mdx b/docs/pages/kubernetes-access/helm/reference.mdx index 8e93667e1f8f4..8bcc67c2eb133 100644 --- a/docs/pages/kubernetes-access/helm/reference.mdx +++ b/docs/pages/kubernetes-access/helm/reference.mdx @@ -44,8 +44,11 @@ This reference details available values for the `teleport-cluster` chart. (!docs/pages/kubernetes-access/helm/includes/kubernetes-externaladdress.mdx!) - You will need to manually add DNS records pointing `teleport.example.com` and `*.teleport.example.com` to either the IP or hostname - of the Kubernetes load balancer. + You will need to manually add a DNS A record pointing `teleport.example.com` to either the IP or hostname of the Kubernetes load balancer. + +
+(!docs/pages/includes/dns-app-access.mdx!) +
If you are not using ACME certificates, you may also need to accept insecure warnings in your browser to view the page successfully.