From be6fff8329954eb2f52bb85d4824225772e55c8b Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Tue, 17 Dec 2024 13:27:46 -0500 Subject: [PATCH] Fix Vale warnings in three guides - Getting started guide for auto-discovering Kubernetes applications. - DynamoDB (as an application) guide. This change does not address one Vale warning with `tsh aws dymamodb`, which is a false positive. - Getting started guide for protecting applications. --- .../application-access/getting-started.mdx | 28 +++++++++++++++---- .../application-access/guides/dynamodb.mdx | 11 ++++---- .../kubernetes-applications/get-started.mdx | 16 ++++++++--- 3 files changed, 39 insertions(+), 16 deletions(-) diff --git a/docs/pages/enroll-resources/application-access/getting-started.mdx b/docs/pages/enroll-resources/application-access/getting-started.mdx index 28a23fad24da2..3fe1756f69c93 100644 --- a/docs/pages/enroll-resources/application-access/getting-started.mdx +++ b/docs/pages/enroll-resources/application-access/getting-started.mdx @@ -1,6 +1,6 @@ --- -title: Getting Started with Teleport Application Access -description: Getting started with Teleport application access. +title: Protect a Web Application with Teleport +description: Provides instructions to set up the Teleport Application Service and enable secure access to a web application. videoBanner: cvW4b96aPL0 --- @@ -20,6 +20,21 @@ At a high level, configuring access for applications involves the following step - Install and configure Teleport on the application host. - Add a user to verify access to the application. +## How it works + +In the setup we demonstrate in this guide, the Teleport Application Service +joins your Teleport cluster with a secure token. You configure the Application +Service to protect a web application using a configuration file. After the +Application Service joins the cluster, the Teleport Proxy Service routes +requests from end users to the Teleport Application Service, and responses from +the Application Serve back to end users. + +The Application Service authenticates user requests by validating a JSON web +token (JWT) in the request against a CA maintained by the Teleport Auth Service. +The requesting user's roles are encoded in the JWT, allowing the Application +Service to determine whether the user has permissions to make a request to a +Teleport-protected application. + ## Prerequisites For this tutorial, verify your environment meets the following requirements: @@ -179,7 +194,7 @@ $ helm install teleport-kube-agent teleport/teleport-kube-agent \ - Change `apps[0].name` and `apps[0].uri` if you're configuring access to a different web application. -Make sure that the Teleport agent pod is running. You should see one +Make sure that the Teleport Agent pod is running. You should see one `teleport-kube-agent` pod with a single ready container: ```code @@ -203,8 +218,9 @@ To assign to the `access` role to a new local user named `alice`, run the follow $ tctl users add --roles=access alice ``` -The command generates an invitation URL for the new user. You can use the URL to choose -a password, set up a second factor for authentication, and sign in to the Teleport Web UI. +The command generates an invitation URL for the new user. You can use the URL to +choose a password, set up multi-factor authentication, and sign in to the +Teleport Web UI. ## Step 5/5. Access the application @@ -225,5 +241,5 @@ Learn more about protecting applications with Teleport in the following topics: - [Connecting applications](./guides/connecting-apps.mdx). - Integrating with [JWT tokens](./jwt/introduction.mdx). - Accessing applications with [RESTful APIs](./guides/api-access.mdx). -- Setting configuration options AND running CLI commands in the [Application Access reference](../../reference/agent-services/application-access.mdx). +- Setting configuration options AND running CLI commands in the [Application Service reference](../../reference/agent-services/application-access.mdx). - Using the Let's Encrypt [ACME protocol](https://letsencrypt.org/how-it-works/). diff --git a/docs/pages/enroll-resources/application-access/guides/dynamodb.mdx b/docs/pages/enroll-resources/application-access/guides/dynamodb.mdx index 58d846981d619..681752478ecb5 100644 --- a/docs/pages/enroll-resources/application-access/guides/dynamodb.mdx +++ b/docs/pages/enroll-resources/application-access/guides/dynamodb.mdx @@ -22,15 +22,15 @@ This guide will help you to: - +## How it works The Teleport Application Service enables secure access to DynamoDB via its [integration](../cloud-apis/aws-console.mdx) with the AWS management console and API. This is an alternative to accessing DynamoDB through the Teleport Database -service, as described in our [Database Access with AWS -DynamoDB](../../database-access/enroll-aws-databases/aws-dynamodb.mdx) guide. +service, as described in our [Protect Amazon DynamoDB with +Teleport](../../database-access/enroll-aws-databases/aws-dynamodb.mdx) guide. + The Application Service's integration with AWS is not designed specifically for DynamoDB, while the Database Service has a purpose-built DynamoDB integration. As a result, we recommend using the Database Service to enable secure access to @@ -40,7 +40,6 @@ It is worth noting that the Database Service will allow you to connect with GUI clients, whereas the Application Service does not. On the other hand, a single Application Service configuration can access DynamoDB across regions, while database resources must be configured for each region with DynamoDB databases. - ## Prerequisites @@ -173,6 +172,6 @@ $ tsh apps logout aws ``` ## Next steps -- More information on [AWS Management and API with Teleport Application Access](../../application-access/cloud-apis/aws-console.mdx). +- More information on [protecting AWS Console with Teleport](../../application-access/cloud-apis/aws-console.mdx). - Learn more about [AWS service endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html). diff --git a/docs/pages/enroll-resources/auto-discovery/kubernetes-applications/get-started.mdx b/docs/pages/enroll-resources/auto-discovery/kubernetes-applications/get-started.mdx index fd9a5d9fa8c19..62f4d807c3f35 100644 --- a/docs/pages/enroll-resources/auto-discovery/kubernetes-applications/get-started.mdx +++ b/docs/pages/enroll-resources/auto-discovery/kubernetes-applications/get-started.mdx @@ -11,6 +11,14 @@ setup step. In this guide, we show you how to enable Kubernetes application auto-discovery. +## How it works + +The Teleport Discovery Service queries the API server of the Kubernetes cluster +in which you want to detect applications, maintaining dynamic `app` resources to +match the Kubernetes services that it detects within the cluster. The Teleport +Application Service queries the Teleport Auth Service to fetch `app` resources, +and proxies applications based the dynamically generated configuration. + ## Prerequisites (!docs/pages/includes/edition-prereqs-tabs.mdx!) @@ -26,7 +34,7 @@ In this guide, we show you how to enable Kubernetes application auto-discovery. ## Step 1/2. Create a join token -Create a join token for a new Teleport agent that will run the Teleport +Create a join token for a new Teleport Agent that will run the Teleport Kubernetes Service, Application Service, and Discovery Service: ```code @@ -40,15 +48,15 @@ Teleport applications created from discovered Kubernetes services. ## Step 2/2. Deploy the agent -If you want to install a new Teleport agent in your Kubernetes cluster, you can -use the `teleport-kube-agent` Helm chart. If you already have a Teleport agent +If you want to install a new Teleport Agent in your Kubernetes cluster, you can +use the `teleport-kube-agent` Helm chart. If you already have a Teleport Agent installed, you can upgrade it to enable the Kubernetes Application Discovery by adding the `kube`, `app`, and `discovery` to roles as shown below. -Deploy a new Teleport agent running your configured services by installing the +Deploy a new Teleport Agent running your configured services by installing the `teleport-kube-agent` Helm chart: ```code