Extract tabbed Prerequisites into a partial (#11961)

Backports #11710 While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
gravitational · Apr 15, 2022 · 760c6ea · 760c6ea
1 parent 16f8651
commit 760c6ea
Show file tree

Hide file tree

Showing 24 changed files with 153 additions and 504 deletions.
diff --git a/docs/pages/access-controls/getting-started.mdx b/docs/pages/access-controls/getting-started.mdx
@@ -13,8 +13,7 @@ with creating your own role.
 
 ## Prerequisites
 
-- Installed [Teleport](../getting-started.mdx) or [Teleport Cloud](../cloud/introduction.mdx) >= (=teleport.version=)
-- [Tctl admin tool](https://goteleport.com/teleport/download) >= (=teleport.version=)
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
 
 (!docs/pages/includes/permission-warning.mdx!)
 

diff --git a/docs/pages/access-controls/guides/dual-authz.mdx b/docs/pages/access-controls/guides/dual-authz.mdx
@@ -13,23 +13,59 @@ Here are the most common scenarios:
 Let's set up Teleport's access requests to require approval of
 two team members for a privileged role `dbadmin`.
 
-<Admonition
+<Notice
   type="warning"
-  title="Version Warning"
 >
   This guide requires a commercial edition of Teleport. The open source
-  edition of Teleport only supports [Github](../../setup/admin/github-sso.mdx) as
+  edition of Teleport only supports [GitHub](../../setup/admin/github-sso.mdx) as
   an SSO provider.
-</Admonition>
+</Notice>
 
 <Admonition title="Note" type="tip">
   The steps below describe how to use Teleport with Mattermost. You can also [integrate with many other providers](../../enterprise/workflow/index.mdx).
 </Admonition>
 
 ## Prerequisites
 
-- Installed [Teleport Enterprise](../../enterprise/introduction.mdx) or [Teleport Cloud](../../cloud/introduction.mdx) >= (=teleport.version=)
-- [Tctl enterprise admin tool](https://goteleport.com/teleport/download) >= (=teleport.version=)
+<Tabs>
+<TabItem
+  scope={["enterprise"]} label="Enterprise">
+
+- A running Teleport cluster. For details on how to set this up, see our Enterprise
+  [Getting Started](/docs/enterprise/getting-started) guide.
+
+- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=),
+  which you can download by visiting the
+  [customer portal](https://dashboard.gravitational.com/web/login).
+
+  ```code
+  $ tctl version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  
+  $ tsh version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  ```
+
+</TabItem>
+<TabItem scope={["cloud"]}
+  label="Teleport Cloud">
+
+- A Teleport Cloud account. If you do not have one, visit the
+  [sign up page](https://goteleport.com/signup/) to begin your free trial.
+
+- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=).
+  To download these tools, visit the [Downloads](/docs/cloud/downloads) page.
+
+  ```code
+  $ tctl version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  
+  $ tsh version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  ```
+
+</TabItem>
+</Tabs>
 - Mattermost installed.
 
 <Admonition

diff --git a/docs/pages/access-controls/guides/impersonation.mdx b/docs/pages/access-controls/guides/impersonation.mdx
@@ -15,8 +15,7 @@ non-interactive CI/CD user Jenkins and a security scanner.
 
 ## Prerequisites
 
-- Installed [Teleport](../getting-started.mdx) or [Teleport Cloud](../../cloud/introduction.mdx) >= (=teleport.version=)
-- [Tctl admin tool](https://goteleport.com/teleport/download) >= (=teleport.version=)
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
 
 (!docs/pages/includes/tctl.mdx!)
 

diff --git a/docs/pages/access-controls/guides/locking.mdx b/docs/pages/access-controls/guides/locking.mdx
@@ -36,8 +36,7 @@ A lock can target the following objects or attributes:
 
 ## Prerequisites
 
-- Installed [Teleport](../getting-started.mdx) >= (=teleport.version=) or [Teleport Cloud](../../cloud/introduction.mdx)
-- [Tctl admin tool](https://goteleport.com/teleport/download) >= (=teleport.version=)
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
 
 (!docs/pages/includes/tctl.mdx!)
 

diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx
@@ -30,13 +30,16 @@ Teleport certificates.
 
 ## Prerequisites
 
-- Installed [Teleport](../getting-started.mdx) or [Teleport Cloud](../../cloud/introduction.mdx) >= (=teleport.version=)
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
 - [WebAuthn configured](webauthn.mdx) on this cluster
 - Second factor hardware device, such as YubiKey or SoloKey
 - A Web browser with [WebAuthn support](
   https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) (if using
   SSH from the Teleport Web UI)
 
+(!docs/pages/includes/tctl.mdx!)
+
 <Admonition type="note" title="Per-session MFA with FIPS">
 Teleport FIPS builds disable local users. To configure WebAuthn in order to use
 per-session MFA with FIPS builds, provide the following in your `teleport.yaml`:

diff --git a/docs/pages/access-controls/guides/role-templates.mdx b/docs/pages/access-controls/guides/role-templates.mdx
@@ -19,8 +19,7 @@ Let's explore how Teleport's role templates provide a way to describe these and
 
 ## Prerequisites
 
-- Installed [Teleport](../getting-started.mdx) or [Teleport Cloud](../../cloud/introduction.mdx) >= (=teleport.version=)
-- [Tctl admin tool](https://goteleport.com/teleport/download) >= (=teleport.version=)
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
 
 (!docs/pages/includes/tctl.mdx!)
 

diff --git a/docs/pages/access-controls/guides/u2f.mdx b/docs/pages/access-controls/guides/u2f.mdx
@@ -18,10 +18,13 @@ into individual SSH nodes or Kubernetes clusters (`tsh ssh` and `kubectl`).
 
 ## Prerequisites
 
-- Installed [Teleport](../getting-started.mdx) or [Teleport Cloud](../../cloud/introduction.mdx) >= (=teleport.version=)
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
 - U2F hardware device, such as Yubikey or Solokey
 - Web browser that [supports U2F](https://caniuse.com/u2f)
 
+(!docs/pages/includes/tctl.mdx!)
+
 ## Enable U2F support
 
 By default U2F is disabled. To enable U2F support, edit the Teleport

diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx
@@ -16,10 +16,8 @@ and Web UI), as well as biometric authenticators like Touch ID and Windows Hello
 
 ## Prerequisites
 
-- Installed [Teleport](../getting-started.mdx) or [Teleport Cloud](
-  ../../cloud/introduction.mdx) >= (=teleport.version=)
-- [Tctl admin tool](https://goteleport.com/teleport/download) >=
-  (=teleport.version=).
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
 - WebAuthn hardware device, such as YubiKey or SoloKey
 - A Web browser with [WebAuthn support](
   https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/)

diff --git a/docs/pages/includes/edition-prereqs-tabs.mdx b/docs/pages/includes/edition-prereqs-tabs.mdx
@@ -0,0 +1,53 @@
+{/* 
+TODO: Since we can't control the directory level of the page that uses this
+partial, and it is currently not possible to include absolute paths to MDX 
+files in partials, this partial uses relative URL paths instead.
+*/}
+<Tabs>
+<TabItem scope={["oss"]} label="Open Source">
+
+- A running Teleport cluster. For details on how to set this up, see one of our
+  [Getting Started](/docs/getting-started) guides. 
+
+- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=).
+
+  ```code
+  $ tctl version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
+
+  $ tsh version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  ```
+
+  See [Installation](/docs/installation) for details.
+
+</TabItem>
+<TabItem
+  scope={["enterprise"]} label="Enterprise">
+
+- A running Teleport cluster. For details on how to set this up, see our Enterprise
+  [Getting Started](/docs/enterprise/getting-started) guide.
+
+- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=),
+  which you can download by visiting the
+  [customer portal](https://dashboard.gravitational.com/web/login).
+
+  ```code
+  $ tctl version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  
+  $ tsh version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  ```
+
+</TabItem>
+<TabItem scope={["cloud"]}
+  label="Teleport Cloud">
+
+- A Teleport Cloud account. If you do not have one, visit the
+  [sign up page](https://goteleport.com/signup/) to begin your free trial.
+- The `tctl` admin tool and `tsh` client tool. To download these tools, visit
+  the [Downloads](https://goteleport.com/download/) page.
+
+</TabItem>
+</Tabs>
diff --git a/docs/pages/kubernetes-access/getting-started/agent.mdx b/docs/pages/kubernetes-access/getting-started/agent.mdx
@@ -5,70 +5,10 @@ description: Connecting a Kubernetes cluster to Teleport
 
 ## Prerequisites
 
-<Tabs>
-<TabItem scope={["oss"]} label="Open Source">
-
-- A running Teleport cluster. For details on how to set this up, see one of our
-  [Getting Started](../../getting-started.mdx) guides. 
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
 
 - The `jq` tool to process `JSON` output. This is available via common package managers.
 
-- The `tctl` admin tool version >= (=teleport.version=).
-
-  ```code
-  $ tctl version
-  # Teleport v(=teleport.version=) go(=teleport.golang=)
-  ```
-
-  See [Installation](../../installation.mdx) for details.
-
-  (!docs/pages/includes/tctl.mdx!)
-
-</TabItem>
-<TabItem
-  scope={["enterprise"]} label="Enterprise">
-
-- A running Teleport cluster. For details on how to set this up, see one of our
-  [Getting Started](../../getting-started.mdx) guides.
-
-- The `jq` tool to process `JSON` output. This is available via common package managers.
-
-- The `tctl` admin tool version >= (=teleport.version=), which you can download
-  by visiting the
-  [customer portal](https://dashboard.gravitational.com/web/login).
-
-  ```code
-  $ tctl version
-  # Teleport Enterprise v(=teleport.version=) go(=teleport.golang=)
-  ```
-
-  (!docs/pages/includes/tctl.mdx!)
-
-</TabItem>
-<TabItem scope={["cloud"]}
-  label="Teleport Cloud">
-
-- A Teleport Cloud account. If you do not have one, visit the
-  [sign up page](https://goteleport.com/signup/) to begin your free trial.
-
-- The `jq` tool to process `JSON` output. This is available via common package
-  managers.
-
-- The `tctl` admin tool version >= (=teleport.version=).
-
-  ```code
-  $ tctl version
-  # Teleport v(=teleport.version=) go(=teleport.golang=)
-  ```
-
-  See [Installation](../../installation.mdx) for details.
-
-  (!docs/pages/includes/tctl.mdx!)
-
-</TabItem>
-</Tabs>
-
-
 (!docs/pages/includes/kubernetes-access/helm-k8s.mdx!)
 
 (!docs/pages/includes/tctl.mdx!)

diff --git a/docs/pages/kubernetes-access/guides/multiple-clusters.mdx b/docs/pages/kubernetes-access/guides/multiple-clusters.mdx
@@ -7,73 +7,21 @@ This guide will show you how to use Teleport as an access plane for multiple Kub
 
 ## Prerequisites
 
-<Tabs>
-<TabItem scope={["oss"]} label="Open Source">
-
-- A Teleport cluster running on Kubernetes, version >=
-  v(=kubernetes.major_version=).(=kubernetes.minor_version=).0. We will assume
-  that you have followed the
-  [Kubernetes with SSO](../getting-started/cluster.mdx) guide
-- The `jq` tool to process `JSON` output. This is available via common package managers
-- An additional Kubernetes cluster version >=
-  v(=kubernetes.major_version=).(=kubernetes.minor_version=).0
-- Helm >= (=helm.version=)
-
-(!docs/pages/includes/helm.mdx!)
-
-
-</TabItem>
-<TabItem
-  scope={["enterprise"]} label="Enterprise">
-
-- A Teleport cluster running on Kubernetes, version >=
-  v(=kubernetes.major_version=).(=kubernetes.minor_version=).0. We will assume
-  that you have followed the
-  [Kubernetes with SSO](../getting-started/cluster.mdx) guide
-- The `jq` tool to process `JSON` output. This is available via common package managers
-- An additional Kubernetes cluster version >=
-  v(=kubernetes.major_version=).(=kubernetes.minor_version=).0
-- Helm >= (=helm.version=)
-
-(!docs/pages/includes/helm.mdx!)
-
-
-</TabItem>
-<TabItem scope={["cloud"]}
-  label="Teleport Cloud">
-
-- A Teleport Cloud account. If you do not have one, visit the
-  [sign up page](https://goteleport.com/signup/) to begin your free trial
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
 
 - The Teleport Kubernetes Service running in a Kubernetes cluster, version >=
   v(=kubernetes.major_version=).(=kubernetes.minor_version=).0. We will assume
   that you have already followed
   [Connect a Kubernetes Cluster to Teleport](../getting-started/agent.mdx)
-
 - The `jq` tool to process `JSON` output. This is available via common package
   managers
-
-- The `tctl` admin tool version >= (=teleport.version=).
-
-  ```code
-  $ tctl version
-  # Teleport v(=teleport.version=) go(=teleport.golang=)
-  ```
-
-  See [Installation](../../installation.mdx) for details.
-
-  (!docs/pages/includes/tctl.mdx!)
-
 - An additional Kubernetes cluster version >=
   v(=kubernetes.major_version=).(=kubernetes.minor_version=).0
-
 - Helm >= (=helm.version=)
 
 (!docs/pages/includes/helm.mdx!)
 
-
-</TabItem>
-</Tabs>
+(!docs/pages/includes/tctl.mdx!)
 
 ## Connecting clusters