From 6db3e877f3a89655c7b74b1866d80d155271b29e Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Wed, 30 Oct 2024 17:18:51 -0400 Subject: [PATCH] Add intro paragraphs to docs pages Closes #44532 Ensure that all docs pages include an introductory paragraph, which spells out the scope of a page and indicates to a reader whether the page is appropriate for their needs. In some pages, the "How it works" section functions like an introductory paragraph. In these cases, turn the "How it works" section into an introductory paragraph and add a new "How it works" section. Other pages already include an introductory paragraph with the H2 "Introduction". Standardize the docs on not including a heading before the introductory paragraph. --- .../access-request-plugins/datadog-hosted.mdx | 11 +++++++-- .../notification-routing-rules.mdx | 22 +++++++++++------- .../device-trust/device-management.mdx | 4 ++++ .../guides/hardware-key-support.mdx | 2 -- .../access-controls/idps/saml-guide.mdx | 9 ++++---- .../multi-region-blueprint.mdx | 2 -- .../auto-user-provisioning/mysql.mdx | 23 +++++++++++++++++++ .../enroll-resources/database-access/faq.mdx | 4 ++++ .../pages/enroll-resources/machine-id/faq.mdx | 4 ++++ .../machine-id/troubleshooting.mdx | 3 +++ docs/pages/faq.mdx | 4 ++++ .../agent-services/application-access.mdx | 4 ++++ .../configuration.mdx | 3 +++ .../database-access-reference/labels.mdx | 3 +++ .../desktop-access-reference/audit.mdx | 6 +++++ .../kubernetes-application-discovery.mdx | 5 ++++ docs/pages/reference/agent-services/okta.mdx | 4 ++++ .../architecture/api-architecture.mdx | 6 +++++ .../reference/architecture/authentication.mdx | 5 ++-- .../reference/architecture/authorization.mdx | 4 +--- .../teleport-cloud-architecture.mdx | 8 +++++++ .../architecture/trustedclusters.mdx | 2 -- docs/pages/reference/cloud-faq.mdx | 4 ++++ .../tracing-service-configuration.mdx | 8 +++---- docs/pages/reference/networking.mdx | 8 +++++++ 25 files changed, 127 insertions(+), 31 deletions(-) diff --git a/docs/pages/admin-guides/access-controls/access-request-plugins/datadog-hosted.mdx b/docs/pages/admin-guides/access-controls/access-request-plugins/datadog-hosted.mdx index 1baa8b091e0df..419937a61cc83 100644 --- a/docs/pages/admin-guides/access-controls/access-request-plugins/datadog-hosted.mdx +++ b/docs/pages/admin-guides/access-controls/access-request-plugins/datadog-hosted.mdx @@ -3,8 +3,6 @@ title: Access Requests with Datadog Incident Management description: How to set up Teleport's Datadog Incident Management plugin for privilege elevation approvals. --- -## How it works - With Teleport's Datadog Incident Management integration, engineers can access the infrastructure they need to resolve incidents without longstanding admin permissions that can become a vector for attacks. @@ -15,6 +13,15 @@ and approve or deny the requests via Teleport. This guide will explain how to set up Teleport's Access Request plugin for Datadog. +## How it works + +The Teleport Datadog Incident Management integration connects to the Teleport +gRPC API and listens for Role Access Requests. When the integration receives a +status change for a Role Access Request, it either creates a new incident in +Datadog or, if an incident exists, updates it. The integration also reads +annotations on each Teleport Access Request and, depending on the annotations, +may approve the Access Request automatically. + ## Prerequisites (!docs/pages/includes/commercial-prereqs-tabs.mdx!) diff --git a/docs/pages/admin-guides/access-controls/access-request-plugins/notification-routing-rules.mdx b/docs/pages/admin-guides/access-controls/access-request-plugins/notification-routing-rules.mdx index fb76c05c19a2a..15b85449dd8b5 100644 --- a/docs/pages/admin-guides/access-controls/access-request-plugins/notification-routing-rules.mdx +++ b/docs/pages/admin-guides/access-controls/access-request-plugins/notification-routing-rules.mdx @@ -3,17 +3,23 @@ title: Routing Access Request notifications description: How to set up Teleport's Access Monitoring Rules to route Access Request notifications --- +With Teleport's Access Monitoring Rules, Access Request notifications can be +routed to plugins based on based on several conditions. For example, you may +wish to send notifications to different Slack channels based on what roles or +resources are being accessed, or based on what user is making the request. + ## How it works -With Teleport's Access Monitoring Rules, Access Request notifications -can be routed to plugins based on based on several conditions. -For example, you may wish to send notifications to different Slack channels -based on what roles or resources are being accessed, or based on what user -is making the request. +The Access Monitoring Rule (AMR) is a dynamic Teleport resource that matches +audit events with certain characteristics and instructs Teleport plugins to take +action when it receives these events. Teleport plugins connect to the Teleport +Auth Service and listen for AMRs. If an AMR matches the plugin, the plugin loads +the the AMR and uses it to process incoming events. -Currently, only a subset of hosted plugins support notification routing rules. -We are working on extending support to the rest of hosted plugins. Keep an eye -on Teleport [changelog](../../../changelog.mdx) to learn about new plugins being added. +Plugins implement AMR handling logic separately from one another. Currently, +only a subset of hosted plugins support notification routing rules. We are +working on extending support to the rest of hosted plugins. Keep an eye on +Teleport [changelog](../../../changelog.mdx) to learn about new plugins. ## Prerequisites diff --git a/docs/pages/admin-guides/access-controls/device-trust/device-management.mdx b/docs/pages/admin-guides/access-controls/device-trust/device-management.mdx index 35ef6b00286e7..bf0d0a9a419da 100644 --- a/docs/pages/admin-guides/access-controls/device-trust/device-management.mdx +++ b/docs/pages/admin-guides/access-controls/device-trust/device-management.mdx @@ -3,6 +3,10 @@ title: Manage Trusted Devices description: Learn how to manage Trusted Devices --- +This guide provides instructions for performing Device Trust management +operations, such as registering a trusted device, creating a device enrollment +token, and removing a trusted device. + ## Prerequisites (!docs/pages/includes/commercial-prereqs-tabs.mdx!) diff --git a/docs/pages/admin-guides/access-controls/guides/hardware-key-support.mdx b/docs/pages/admin-guides/access-controls/guides/hardware-key-support.mdx index 4aefa5d2a096a..7749f44ee445f 100644 --- a/docs/pages/admin-guides/access-controls/guides/hardware-key-support.mdx +++ b/docs/pages/admin-guides/access-controls/guides/hardware-key-support.mdx @@ -3,8 +3,6 @@ title: Hardware Key Support description: Hardware Key Support --- -## Introduction - Hardware Key Support requires Teleport Enterprise. diff --git a/docs/pages/admin-guides/access-controls/idps/saml-guide.mdx b/docs/pages/admin-guides/access-controls/idps/saml-guide.mdx index 9e8a67c3d59b9..79a748fc2a60b 100644 --- a/docs/pages/admin-guides/access-controls/idps/saml-guide.mdx +++ b/docs/pages/admin-guides/access-controls/idps/saml-guide.mdx @@ -4,10 +4,9 @@ description: How to configure and use Teleport as a SAML identity provider. h1: Teleport as a SAML identity provider --- -## How to use Teleport as an identity provider - -This guide details an example on how to use Teleport as an identity provider to -authenticate to external services. +This guide details an example on how to use Teleport as a SAML identity provider +(IdP). You can set up the Teleport SAML IdP to enable Teleport users to +authenticate to external services through Teleport. ## Prerequisites @@ -226,4 +225,4 @@ Next, add the role to your user. (!docs/pages/includes/add-role-to-user.mdx role="sp-manager"!) ## Next steps -- Configure [SAML Attribute Mapping](./saml-attribute-mapping.mdx). \ No newline at end of file +- Configure [SAML Attribute Mapping](./saml-attribute-mapping.mdx). diff --git a/docs/pages/admin-guides/deploy-a-cluster/multi-region-blueprint.mdx b/docs/pages/admin-guides/deploy-a-cluster/multi-region-blueprint.mdx index 62f7d46829841..23ec859601a34 100644 --- a/docs/pages/admin-guides/deploy-a-cluster/multi-region-blueprint.mdx +++ b/docs/pages/admin-guides/deploy-a-cluster/multi-region-blueprint.mdx @@ -3,8 +3,6 @@ title: "Multi-region Blueprint" description: "Blueprint describing how to deploy a multi-region Teleport Enterprise cluster using CockroachDB." --- -## Introduction - This page describes how to deploy a Teleport cluster in multiple regions to improve resiliency and sustain regional failure. This is not a step-by-step guide but a blueprint on how to build a multi-region Teleport cluster. This diff --git a/docs/pages/enroll-resources/database-access/auto-user-provisioning/mysql.mdx b/docs/pages/enroll-resources/database-access/auto-user-provisioning/mysql.mdx index a9ad54cca3f2a..5c911c0f8b10e 100644 --- a/docs/pages/enroll-resources/database-access/auto-user-provisioning/mysql.mdx +++ b/docs/pages/enroll-resources/database-access/auto-user-provisioning/mysql.mdx @@ -3,6 +3,29 @@ title: MySQL Automatic User Provisioning description: Configure automatic user provisioning for MySQL. --- +Teleport can automatically create an account in your MySQL database when a +Teleport user connects to the database, removing the need for creating +individual user accounts in advance or using the same set of shared database +accounts for all users. This guide shows you how to set up automatic user +provisioning for MySQL. + +## How it works + +Before enrolling a MySQL database with Teleport, you set up an admin user on the +database with permissions to manage users. You then enroll the database in your +Teleport cluster with a configuration field that includes the name of the admin +user. + +When a Teleport user connects to the database with a role that enables automatic +user provisioning, the Teleport Database Service first connects to the database +as the admin user, creates a temporary user in the database, then initiates a +database session for the Teleport user as the temporary database user. + +When the Teleport user closes the session, the Teleport Database Service +prevents the temporary database user from accessing the database by, depending +on the configuration, either removing the database user or disabling it and +stripping its privileges. + ## Prerequisites - Teleport cluster v14.1 or higher with a configured [self-hosted diff --git a/docs/pages/enroll-resources/database-access/faq.mdx b/docs/pages/enroll-resources/database-access/faq.mdx index eaf628f7fbf4e..624e8c7e5c3e2 100644 --- a/docs/pages/enroll-resources/database-access/faq.mdx +++ b/docs/pages/enroll-resources/database-access/faq.mdx @@ -3,6 +3,10 @@ title: Database Access FAQ description: Frequently asked questions about Teleport database access. --- +This page provides the answers to common questions about enrolling databases +with Teleport. For a list of frequently asked questions about Teleport in +general, see [Frequently Asked Questions](../../faq.mdx). + ## Which database protocols does Teleport the Database Service support? The Teleport Database Service currently supports the following protocols: diff --git a/docs/pages/enroll-resources/machine-id/faq.mdx b/docs/pages/enroll-resources/machine-id/faq.mdx index bd48f409c32e6..1685773dc41cd 100644 --- a/docs/pages/enroll-resources/machine-id/faq.mdx +++ b/docs/pages/enroll-resources/machine-id/faq.mdx @@ -3,6 +3,10 @@ title: Machine ID FAQ description: Frequently asked questions about Teleport Machine ID --- +This page provides answers to frequently asked questions about Machine ID. For a +list of frequently asked questions about Teleport in general, see [Frequently +Asked Questions](../../faq.mdx). + ## Can Machine ID be used within CI/CD jobs? On CI/CD platforms where your workflow runs in an ephemeral environment (e.g diff --git a/docs/pages/enroll-resources/machine-id/troubleshooting.mdx b/docs/pages/enroll-resources/machine-id/troubleshooting.mdx index ede717d90962c..05c37fc759fa0 100644 --- a/docs/pages/enroll-resources/machine-id/troubleshooting.mdx +++ b/docs/pages/enroll-resources/machine-id/troubleshooting.mdx @@ -3,6 +3,9 @@ title: Machine ID Troubleshooting Guide description: Troubleshooting common issues with Machine ID --- +This page provides resolution steps for issues that you may come across when +setting up Machine ID. + ## A bot failed to renew a certificate due to a "generation mismatch" ### Symptoms diff --git a/docs/pages/faq.mdx b/docs/pages/faq.mdx index 8895f41f4ab28..ee0a12e412983 100644 --- a/docs/pages/faq.mdx +++ b/docs/pages/faq.mdx @@ -4,6 +4,10 @@ description: Frequently Asked Questions About Using Teleport h1: Teleport FAQ --- +This page includes answers to frequently asked questions about setting up, +managing, and using Teleport. If you are new to Teleport, read our [Getting +Started Guide](get-started.mdx). + ## Can I use Teleport in production today? Teleport has been deployed on server clusters with thousands of hosts at diff --git a/docs/pages/reference/agent-services/application-access.mdx b/docs/pages/reference/agent-services/application-access.mdx index 2b9e6dcadfc85..5058f42de5037 100644 --- a/docs/pages/reference/agent-services/application-access.mdx +++ b/docs/pages/reference/agent-services/application-access.mdx @@ -3,6 +3,10 @@ title: Application Access Reference Documentation description: Configuration and CLI reference documentation for Teleport application access. --- +This guide describes interfaces and options for interacting with the Teleport +Application Service, including the static configuration file for the `teleport` +binary, the dynamic `app` resource, and `tsh apps` commands. + ## Configuration (!docs/pages/includes/backup-warning.mdx!) diff --git a/docs/pages/reference/agent-services/database-access-reference/configuration.mdx b/docs/pages/reference/agent-services/database-access-reference/configuration.mdx index de74f27491bb3..6e7091b08f6fd 100644 --- a/docs/pages/reference/agent-services/database-access-reference/configuration.mdx +++ b/docs/pages/reference/agent-services/database-access-reference/configuration.mdx @@ -3,6 +3,9 @@ title: Database Access Configuration Reference description: Configuration reference for Teleport database access. --- +This guide explains configuration options for the Teleport Database Service, +which proxies user traffic between Teleport users and protected databases. + ## Database service configuration The following snippet shows full YAML configuration of a Database Service diff --git a/docs/pages/reference/agent-services/database-access-reference/labels.mdx b/docs/pages/reference/agent-services/database-access-reference/labels.mdx index e8f4fcdee0729..4702f4f1713e6 100644 --- a/docs/pages/reference/agent-services/database-access-reference/labels.mdx +++ b/docs/pages/reference/agent-services/database-access-reference/labels.mdx @@ -3,6 +3,9 @@ title: Database Labels Reference description: Database labels reference for Teleport database access. --- +Teleport assigns system-defined labels to protected databases. This guide +describes the system-defined labels and how Teleport uses them. + ## Origin All registered databases have a predefined `teleport.dev/origin` label with one diff --git a/docs/pages/reference/agent-services/desktop-access-reference/audit.mdx b/docs/pages/reference/agent-services/desktop-access-reference/audit.mdx index e4a7ee8a9fbd7..8da5f7f531d63 100644 --- a/docs/pages/reference/agent-services/desktop-access-reference/audit.mdx +++ b/docs/pages/reference/agent-services/desktop-access-reference/audit.mdx @@ -3,6 +3,12 @@ title: Desktop Access Audit Events Reference description: Audit events reference for Teleport desktop access. --- +This guide lists the structures and field names of audit events related to +connecting to remote desktops with Teleport. Use this guide to understand +desktop-related audit events and configure your log management solutions if you +are [exporting audit +events](../../../admin-guides/management/export-audit-events/export-audit-events.mdx). + ## windows.desktop.session.start (TDP00I/W) Emitted when a client successfully connects to a desktop or when a connection diff --git a/docs/pages/reference/agent-services/kubernetes-application-discovery.mdx b/docs/pages/reference/agent-services/kubernetes-application-discovery.mdx index 1aeaa726d9628..723a005739aaf 100644 --- a/docs/pages/reference/agent-services/kubernetes-application-discovery.mdx +++ b/docs/pages/reference/agent-services/kubernetes-application-discovery.mdx @@ -3,6 +3,11 @@ title: Kubernetes Application Discovery Reference description: This guide is a comprehensive reference of configuration options for automatically enrolling Kubernetes applications with Teleport. --- +Kubernetes Application Discovery involves the Teleport Discovery Service, +Teleport Application Service, and annotations on Kubernetes services. This guide +shows you how to configure each of these to manage Kubernetes Application +Discovery in your Kubernetes cluster. + ## Configuring Teleport agent Helm chart You can configure scope of services discovery by setting value `kubernetesDiscovery` of the chart. For more information diff --git a/docs/pages/reference/agent-services/okta.mdx b/docs/pages/reference/agent-services/okta.mdx index bf1b2315f0a0e..69ebd3bdf74e0 100644 --- a/docs/pages/reference/agent-services/okta.mdx +++ b/docs/pages/reference/agent-services/okta.mdx @@ -3,6 +3,10 @@ title: Okta Service Reference Documentation description: Configuration and CLI reference documentation for Teleport Okta service. --- +This guide describes interfaces and options for configuring the Teleport Okta +Service, including Okta import rules, Okta assignments, and `tctl` commands. It +also includes troubleshooting instructions. + ## Okta Import Rule resources Full YAML spec of Okta import rule resources managed by `tctl` resource commands: diff --git a/docs/pages/reference/architecture/api-architecture.mdx b/docs/pages/reference/architecture/api-architecture.mdx index c02c311a7d51e..0efa625a3f109 100644 --- a/docs/pages/reference/architecture/api-architecture.mdx +++ b/docs/pages/reference/architecture/api-architecture.mdx @@ -3,6 +3,12 @@ title: API Architecture description: Architectural overview of the Teleport gRPC API. --- +This guide describes the architecture of the Teleport gRPC API, which enables +clients like `tctl`, the Teleport Terraform provider, and the Teleport +Kubernetes operator to manage dynamic resources in your Teleport cluster. If you +are new to the Teleport gRPC API, read how to [Get +Started](../../admin-guides/api/getting-started.mdx). + ## Authentication The Auth API uses mTLS to authenticate a client-server connection. Therefore, the client must provide diff --git a/docs/pages/reference/architecture/authentication.mdx b/docs/pages/reference/architecture/authentication.mdx index 67787df9179a3..313cdbf9cfe14 100644 --- a/docs/pages/reference/architecture/authentication.mdx +++ b/docs/pages/reference/architecture/authentication.mdx @@ -4,14 +4,13 @@ description: This chapter explains how Teleport uses certificate authorities to h1: Teleport Authentication with Certificates --- -## Authentication - Teleport handles both authentication and authorization. - Authentication is about proving an identity of a user or a service. - Authorization is proving access rights to something. -This article covers authentication with short-lived certificates. +This guide explains how Teleport handles authentication with short-lived +certificates. ## Short-Lived Certificates diff --git a/docs/pages/reference/architecture/authorization.mdx b/docs/pages/reference/architecture/authorization.mdx index a432b7c8d108b..6fd5e012a9b63 100644 --- a/docs/pages/reference/architecture/authorization.mdx +++ b/docs/pages/reference/architecture/authorization.mdx @@ -4,14 +4,12 @@ description: This chapter explains how Teleport authorizes users and roles. h1: Teleport Authorization --- -## Authorization - Teleport handles both authentication and authorization. - Authentication is about proving an identity of a user or a service. - Authorization is proving access rights to something. -This article covers authorization of users and services with RBAC. +This article explains authorization of users and services with RBAC. ## Users and Roles diff --git a/docs/pages/reference/architecture/teleport-cloud-architecture.mdx b/docs/pages/reference/architecture/teleport-cloud-architecture.mdx index e11a7d4bb439f..bb6f63a574b6c 100644 --- a/docs/pages/reference/architecture/teleport-cloud-architecture.mdx +++ b/docs/pages/reference/architecture/teleport-cloud-architecture.mdx @@ -3,6 +3,14 @@ title: Teleport Enterprise Cloud Architecture description: Cloud security, availability, and networking details. --- +This guide describes architectural features of Teleport Enterprise (Cloud). In +general, Teleport Enterprise (Cloud) includes managed deployments of the +Teleport Auth Service and Teleport Proxy Service. Read on for information about +topics like High Availability, deployment regions, and data retention. + +If you are new to Teleport Enterprise (Cloud), read the [Getting Started +Guide](../../get-started.mdx). + ## Security We have designed the Teleport Enterprise Cloud environment to be secure. We work with independent diff --git a/docs/pages/reference/architecture/trustedclusters.mdx b/docs/pages/reference/architecture/trustedclusters.mdx index 5d659e3b76796..35bf8256cd30c 100644 --- a/docs/pages/reference/architecture/trustedclusters.mdx +++ b/docs/pages/reference/architecture/trustedclusters.mdx @@ -3,8 +3,6 @@ title: Trusted Clusters Architecture description: Deep dive into design of Teleport Trusted Clusters. --- -## Overview - Teleport can partition compute infrastructure into multiple clusters. A cluster is a group of Teleport connected resources. Each cluster manages a set of certificate authorities (CAs) for its users and resources. diff --git a/docs/pages/reference/cloud-faq.mdx b/docs/pages/reference/cloud-faq.mdx index 1a1d5e3ede050..a15a3828e6fbc 100644 --- a/docs/pages/reference/cloud-faq.mdx +++ b/docs/pages/reference/cloud-faq.mdx @@ -4,6 +4,10 @@ description: Teleport cloud frequently asked questions. tocDepth: 3 --- +This page provides answers to frequently asked questions about Teleport +Enterprise (Cloud). For a list of frequently asked questions about Teleport in +general, see [Frequently Asked Questions](../faq.mdx). + ## Billing and usage ### How does Cloud Billing work? diff --git a/docs/pages/reference/monitoring/tracing-service-configuration.mdx b/docs/pages/reference/monitoring/tracing-service-configuration.mdx index 58ad7c77b0294..9515b6882edca 100644 --- a/docs/pages/reference/monitoring/tracing-service-configuration.mdx +++ b/docs/pages/reference/monitoring/tracing-service-configuration.mdx @@ -3,9 +3,9 @@ title: Distributed Tracing Configuration Reference description: Configuration reference for Distributed Tracing. --- -## Tracing Service configuration - -`teleport.yaml` fields related to Distributed Tracing: +This guide lays out the configuration fields that are related to distributed +tracing in Teleport. You can find these fields in the Teleport configuration +file, which is `teleport.yaml` by default: ```yaml # Main service responsible for Distributed Tracing. @@ -13,4 +13,4 @@ description: Configuration reference for Distributed Tracing. # You must enable the Tracing Service once per teleport.yaml for all # agents that you wish to capture traces from, (!docs/pages/includes/diagnostics/tracing-config.yaml!) -``` \ No newline at end of file +``` diff --git a/docs/pages/reference/networking.mdx b/docs/pages/reference/networking.mdx index 888b4c3da586e..ad86dfde7667b 100644 --- a/docs/pages/reference/networking.mdx +++ b/docs/pages/reference/networking.mdx @@ -3,6 +3,14 @@ title: Networking description: This reference explains the networking requirements of a Teleport cluster, including its public address, ports, and support for HTTP CONNECT proxies. --- +A Teleport cluster is a distributed system that may comprise a number of +networks. On Teleport Enterprise (Cloud), for example, the Auth Service and +Proxy Service run in Teleport-managed infrastructure, while Teleport users +manage Agents and `tbot` instances. + +This reference guide describes the networking requirements of a Teleport +cluster. + ## Public address