Prepare five guides for Cloud users

Configuration reference - Add a tabbed warning box, which incorporates the existing warnings into a single Admonition (to avoid Admonition clutter) and add instructions for Cloud users. Backends Add a compatibility note for Cloud users. There is little else we can do at this point since it is not currently possible to adjust the visibility of an entire page of the docs site based on the scope selector. EC2 node labels guide - Add Tabs to the Prerequisites section so users don't see scope- irrelevant content. - Misc. clarity/style/grammar edits. Audit Logs guide - Prevent Cloud, Enterprise, or OSS users from seeing scope-irrelevant information by using Tabs. - Note that this change does not attempt to update the list of audit event types, since doing so would exceed the time I allotted for updating this guide. Docker setup guide - Remove the image.mdx partial, since it is only used once. - Create a partial for the Enterprise Docker image table. - Use Tabs to display different instructions for users of different Teleport editions.
gravitational · Mar 28, 2022 · 4f04087 · 4f04087
1 parent 8b00efe
commit 4f04087
Show file tree

Hide file tree

Showing 8 changed files with 335 additions and 110 deletions.
diff --git a/docs/pages/enterprise/getting-started.mdx b/docs/pages/enterprise/getting-started.mdx
@@ -359,18 +359,7 @@ We currently only offer Docker images for `x86_64` architectures.
 
 ### Pick your image
 
-This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are
-automatically rebuilt every night. These nightly images point to the latest version of Teleport Enterprise from the three most recent release branches.
-They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date.
-
-| Image name | Open Source or Enterprise? | Teleport version | Image automatically updated? | Image base |
-| - | - | - | - | - |
-| `(=teleport.latest_ent_docker_image=)` | Enterprise | The latest version of Teleport Enterprise (=version=) | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) |
-| `(=teleport.latest_ent_docker_image=)-fips` | Enterprise FIPS | The latest version of Teleport Enterprise (=version=) FIPS | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) |
-| `quay.io/gravitational/teleport-ent:(=teleport.version=)` | Enterprise | The version specified in the image's tag (i.e. (=teleport.version=)) | No | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) |
-| `quay.io/gravitational/teleport-ent:(=teleport.version=)-fips` | Enterprise FIPS | The version specified in the image's tag (i.e. (=teleport.version=)) | No | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) |
-
-For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently `(=teleport.latest_ent_docker_image=)`.
+(!docs/pages/includes/enterprise/docker-images.mdx!)
 
 ### Quickstart using docker-compose
 

diff --git a/docs/pages/includes/enterprise/docker-images.mdx b/docs/pages/includes/enterprise/docker-images.mdx
@@ -0,0 +1,14 @@
+This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are
+automatically rebuilt every night. 
+
+Nightly images point to the latest version of Teleport Enterprise from the three most recent release branches.
+They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date.
+
+| Image name | Open Source or Enterprise? | Teleport version | Image automatically updated? | Image base |
+| - | - | - | - | - |
+| `(=teleport.latest_ent_docker_image=)` | Enterprise | The latest version of Teleport Enterprise (=version=) | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) |
+| `(=teleport.latest_ent_docker_image=)-fips` | Enterprise FIPS | The latest version of Teleport Enterprise (=version=) FIPS | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) |
+| `quay.io/gravitational/teleport-ent:(=teleport.version=)` | Enterprise | The version specified in the image's tag (i.e. (=teleport.version=)) | No | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) |
+| `quay.io/gravitational/teleport-ent:(=teleport.version=)-fips` | Enterprise FIPS | The version specified in the image's tag (i.e. (=teleport.version=)) | No | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) |
+
+For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently `(=teleport.latest_ent_docker_image=)`.
diff --git a/docs/pages/includes/image.mdx b/docs/pages/includes/image.mdx
diff --git a/docs/pages/setup/guides/docker.mdx b/docs/pages/setup/guides/docker.mdx
@@ -1,60 +1,143 @@
 ---
-title: Getting started with Teleport using Docker
-description: How to get started with Teleport Open Source Edition using Docker locally.
+title: How to Run Teleport Using Docker
+description: How to run Teleport using Docker.
 h1: Run Teleport using Docker
 ---
 
-This section will cover:
+This guide will explain how to run a container using one of Teleport's Docker
+images and execute commands on that container via Teleport's `tsh` client.
 
-- Getting started with a local Teleport using Docker.
-- Using Teleport with Teleport's native client, `tsh`.
+<Notice scope={["cloud"]} type="tip">
 
-<Details scope={["cloud"]} title="Teleport Cloud" scopeOnly={true} opened={true}>
-Teleport Cloud includes managed instances of Teleport's Auth Service and Proxy Service. Since all of Teleport's services are run from the same binary, you can use our Docker image to run other services (e.g., the Database Service or App Service), or explore the Auth and Proxy Services locally.
-</Details>
+Since all of Teleport's services are run from the same binary, you can
+use our Docker image to run Node services (e.g., the Database Service or App
+Service) or explore the Auth and Proxy Services locally.
+
+</Notice>
 
 ## Prerequisites
 
-- Teleport v(=teleport.version=) Open Source or Enterprise.
-- Docker v(=docker.version=) or later.
+<Tabs>
+<TabItem scope={["oss"]} label="Open Source">
+
+- Docker v(=docker.version=) or later. We currently only offer Docker images for
+  `x86_64` architectures.
+
+```code
+$ docker version
+# Client: Docker Engine - Community
+# Version:           (=docker.version=)
+```
+
+- The `tsh` client tool, which ships with the `teleport` binary. Visit [Download Teleport](/teleport/download/) to download the open source edition.
+
+</TabItem>
+<TabItem scope={["cloud", "enterprise"]} label="Commercial">
+
+- Docker v(=docker.version=) or later. We currently only offer Docker images for
+  `x86_64` architectures.
 
 ```code
 $ docker version
 # Client: Docker Engine - Community
 # Version:           (=docker.version=)
 ```
 
+- The Enterprise edition of the `tsh` client tool, which ships with the `teleport` binary. Visit the [customer portal](https://dashboard.gravitational.com/web/login) to download Teleport.
+
+</TabItem>
+</Tabs>
 
 ## Step 1/4. Pick your image
 
-(!docs/pages/includes/image.mdx!)
+<Tabs>
+<TabItem scope={["oss"]} label="Open Source">
+We provide pre-built Docker images for every version of Teleport.
+
+These images are hosted on quay.io. All tags under `quay.io/gravitational/teleport` [are Teleport Open Source images](https://quay.io/repository/gravitational/teleport?tag=latest\&tab=tags).
+
+The table below gives an idea of how our image naming scheme works. We offer images that
+point to a static version of Teleport, as well as images that are automatically rebuilt
+every night. These nightly images point to the latest version of Teleport from the
+three most recent release branches. They are stable, and we recommend their use to
+keep your Teleport installation up to date.
+
+<table>
+ <thead>
+   <tr><td>Image name</td><td>Teleport version</td><td>Image automatically updated?</td><td>Image base</td></tr>
+ </thead>
+ <tbody>
+   <tr><td>`(=teleport.latest_oss_docker_image=)`</td><td>The latest version of Teleport Open Source (=version=)</td><td>Yes</td><td>[Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)</td></tr>
+   <tr><td>`quay.io/gravitational/teleport:(=teleport.version=)`</td><td>The version specified in the image's tag (i.e. (=teleport.version=))</td><td>No</td><td>[Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)</td></tr> 
+ </tbody>
+</table>
+
+For testing, we always recommend that you use the latest release version of Teleport, which is currently `(=teleport.latest_oss_docker_image=)`.
+</TabItem>
+<TabItem scope={["enterprise", "cloud"]} label="Commercial">
+We provide pre-built Docker images for every version of Teleport.
+
+(!docs/pages/includes/enterprise/docker-images.mdx!)
+
+</TabItem>
+</Tabs>
 
-## Step 2/4. Start teleport
+## Step 2/4. Start Teleport
 
-Create teleport configs and start the process with sample `docker run` commands:
+<Tabs>
+<TabItem scope={["oss"]} label="Open Source">
+
+Create Teleport configs and start the process with the following `docker run` commands:
 
 ```code
-# Create local config and data directories for teleport, which will be mounted into the container
+# Create local config and data directories for Teleport, which will be mounted
+# into the container.
 $ mkdir -p ~/teleport/config ~/teleport/data
-# Generate a sample teleport config and write it to the local config directory.
-# This container will write the config and immediately exit - this is expected.
+# Generate a sample Teleport config and write it to the local config directory.
+# This container will write the config and immediately exit--this is expected.
 $ docker run --hostname localhost --rm \
   --entrypoint=/bin/sh \
   -v ~/teleport/config:/etc/teleport \
-  (=teleport.latest_oss_docker_image=) -c "teleport configure > /etc/teleport/teleport.yaml"
-# Start teleport with mounted config and data directories, plus all ports
+  (=teleport.latest_oss_docker_image=) bash -c "teleport configure > /etc/teleport/teleport.yaml"
+# Start Teleport with mounted config and data directories, plus all ports
 $ docker run --hostname localhost --name teleport \
   -v ~/teleport/config:/etc/teleport \
   -v ~/teleport/data:/var/lib/teleport \
   -p 3023:3023 -p 3025:3025 -p 3080:3080 \
   (=teleport.latest_oss_docker_image=)
 ```
 
+</TabItem>
+<TabItem scope={["enterprise", "cloud"]} label="Commercial">
+
+Create Teleport configs and start the process with the following `docker run` commands:
+
+```code
+# Create local config and data directories for Teleport, which will be mounted
+# into the container.
+$ mkdir -p ~/teleport/config ~/teleport/data
+# Generate a sample Teleport config and write it to the local config directory.
+# This container will write the config and immediately exit--this is expected.
+$ docker run --hostname localhost --rm \
+  --entrypoint=/bin/sh \
+  -v ~/teleport/config:/etc/teleport \
+  (=teleport.latest_ent_docker_image=) bash -c "teleport configure > /etc/teleport/teleport.yaml"
+# Start Teleport with mounted config and data directories, plus all ports
+$ docker run --hostname localhost --name teleport \
+  -v ~/teleport/config:/etc/teleport \
+  -v ~/teleport/data:/var/lib/teleport \
+  -p 3023:3023 -p 3025:3025 -p 3080:3080 \
+  (=teleport.latest_ent_docker_image=)
+```
+
+</TabItem>
+</Tabs>
+
 ## Step 3/4. Creating a Teleport user
 
 To create a user inside your Teleport container, use `docker exec`.
 
-This example command will create a Teleport user called `testuser` which is allowed to log in as either operating system user `root` or `ubuntu`:
+This example command will create a Teleport user called `testuser` which is allowed to log in as either `root` or `ubuntu` on the host operating system:
 
 ```code
 $ docker exec teleport tctl users add testuser --roles=editor,access --logins=root,ubuntu,ec2-user
@@ -74,11 +157,9 @@ The Web UI will be available at the displayed URL.
 
 ## Step 4/4. tsh into your Teleport container
 
-Finish signing up and creating your user using the generated link created previously.
-
-[Download and install](https://goteleport.com/teleport/download) a copy of Teleport locally. Doing so will install the `tsh` tool so you can interact with Docker containers.
-
-Open a second terminal and issue the command:
+After you have finished creating your user, open a second terminal and issue the
+command, which will log in to your Teleport cluster via the Proxy Service at
+`localhost`.
 
 ```code
 $ tsh login --proxy=localhost --insecure --user=testuser
@@ -120,7 +201,7 @@ $ tsh ls
 # localhost 127.0.0.1:3022 env=example, hostname=localhost 
 ```
 
-To SSH into the local Node `localhost` (running in your Docker container) issue the following `tsh` command:
+To SSH into the local Node called `localhost`:
 
 ```code
 $ tsh ssh root@localhost

diff --git a/docs/pages/setup/guides/ec2-tags.mdx b/docs/pages/setup/guides/ec2-tags.mdx
@@ -1,19 +1,65 @@
 ---
-title: EC2 Tags as Teleport node labels
-description: How to setup Teleport node labels based on EC2 tags
-h1: Sync EC2 Tags and Teleport node labels
+title: EC2 Tags as Teleport Node Labels
+description: How to set up Teleport Node labels based on EC2 tags
+h1: Sync EC2 Tags and Teleport Node Labels
 ---
 
-This section will explain how to setup Teleport node labels based on EC2 tags.
+This guide will explain how to set up Teleport Node labels based on Amazon EC2 tags.
 
 ## Prerequisites
 
-- Teleport v(=teleport.version=) Open Source, Enterprise, or Cloud
-- An AWS EC2 instance running a Teleport node
+<Tabs>
+<TabItem scope={["oss"]} label="Open Source">
+
+- The Teleport Auth Service and Proxy Service version >= (=teleport.version=).
+
+  See [Getting Started](../../getting-started.mdx) for details on how to deploy
+  Teleport in your environment.
+
+- One Teleport Node running on an Amazon EC2 instance. See
+  [Adding Nodes](../admin/adding-nodes.mdx) for how to set up a Teleport Node.
+
+- The following software installed on your Teleport Node: `curl`, `python`, and
+  the `aws` CLI, which comes from the `awscli` Python package.
+
+</TabItem>
+<TabItem
+  scope={["enterprise"]} label="Enterprise">
+- The Teleport Auth Service and Proxy Service version >= (=teleport.version=).
+
+  See [Teleport Enterprise Quick Start](../../enterprise/getting-started.mdx)
+  for details on deploying these services.
+
+  To download Teleport Enterprise, visit the
+  [customer portal](https://dashboard.gravitational.com/web/login).
+
+- One Teleport Node running on an Amazon EC2 instance. See
+  [Adding Nodes](../admin/adding-nodes.mdx) for how to set up a Teleport Node.
+
+- The following software installed on your Teleport Node: `curl`, `python`, and
+  the `aws` CLI, which comes from the `awscli` Python package.
+
+</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.
+
+- One Teleport Node running on an Amazon EC2 instance. See
+  [Adding Nodes](../admin/adding-nodes.mdx) for how to set up a Teleport Node.
+
+- The following software installed on your Teleport Node: `curl`, `python`, and
+  the `aws` CLI, which comes from the `awscli` Python package.
+
+</TabItem>
+</Tabs>
 
 ## Step 1/3. Deploy the script
 
-You’ll need a script on your instance that can query the AWS API and get the values of your instance's tags for you. The Teleport node will then use these values to execute RBAC rules.
+You’ll need a script on your EC2 instance that can query the AWS API and get the
+values of your instance's tags for you. The Teleport Node will then use these
+values to execute RBAC rules.
 
 Here’s one script you can use:
 
@@ -45,13 +91,6 @@ Run the command below to make it executable:
 $ chmod +x /usr/local/bin/get-tag.sh
 ```
 
-<Admonition type="note">
-For the script to work, you’ll need `curl`, `python` and the `aws` command line tool installed.
-`aws` comes from the `awscli` Python package, so you can install it using `pip3 install awscli` or similar.
-
-If you don’t have `python`, `pip3` or `curl` installed, look for them via your OS’s package manager.
-</Admonition>
-
 ## Step 2/3. Set up an IAM role
 
 Grant your EC2 instance an IAM role that will allow it to query tag values for EC2 instances.
@@ -79,7 +118,7 @@ $ /usr/local/bin/get-tag.sh test
 tagValue
 ```
 
-## Step 3/3. Modify the Teleport node config file
+## Step 3/3. Modify the Teleport Node config file
 
 Modify the Teleport config file on your node (`/etc/teleport.yaml`) as follows:
 
@@ -125,6 +164,11 @@ spec:
     port_forwarding: true
 ```
 
-When assigned to Teleport users, this role will only allow them to log in to Teleport nodes which have the `aws_tag_test` label with the value of tagValue, effectively gating access to infrastructure based on the value of the EC2 test tag.
+When assigned to Teleport users, this role will only allow them to log in to
+Teleport Nodes which have the `aws_tag_test` label with the value of `tagValue`,
+effectively gating access to infrastructure based on the value of the EC2 `test`
+tag.
 
-By adding multiple commands to a Teleport node set to the values of different tags and then adding Teleport roles which reference them, you can build quite complex RBAC systems based off your EC2 tagging structure.
+By adding multiple commands to a Teleport Node, setting the values of different
+tags, then adding Teleport roles that reference these tags, you can build
+fine-grained RBAC systems based on your EC2 tagging structure.