* Add more info re: AWS credentials to the docs
Closes#2781
- Add a partial for how to provide credentials to Teleport's AWS client.
Since this includes adding environment variables to the file used by
our systemd service, I also created a partial re: how to configure
Teleport's systemd service and added these two partials to the
relevant guides.
- Removed `Admonition`s that link to the docs re: AWS credentials in
favor of the partial above. (The partial links to the Go SDK for AWS
docs for situations where users have a specific use case.)
- Remove mentions of the AWS credential-related config settings from the
Backends reference. The example config snippets don't actually include
the `access_key` and `secret_key` settings, so these are left over
from an earlier version of the guide. While you can still add these
settings to a config file, I thought it would make sense to leave them
undocumented since using an EC2 instance, environment variables, etc.
is the recommended approach.
- Split the S3/DynamoDB sections of the Backends reference into
subsections so the extra authentication info fits a bit better.
* Respond to PR feedback
* Add new partials to the RDS Proxy guide
* docs: remove references to old Teleport versions
With the release of Teleport 12, the oldest supported version of
Teleport will be Teleport 10. This commit removes some references
to Teleport 7 and Teleport 8. The docs for those versions are no
longer available on goteleport.com, so it's safe to assume that
readers are on a more recent version.
* Update docs/pages/management/guides/joining-nodes-aws-ec2.mdx
---------
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Correct redirect syntax
Redirects are evaluated in order left-to-right so cloning err from out (`2>&1`) before redirecting stdout (`> /dev/null`) has the effect of sending stderr to fd 1 and stdout to the redirected file.
* Do not expand here document text
Avoids need to escape quotes and variable references in pasted script.
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
* add version compatibility callout to Cloud section
* consolidate partial usage in various guides
* remove partial consolidated into
* Apply suggestions from code review
* Reorganize early-stage docs sections
Closes#18127
Currently, there are two sections of the docs related to the earliest
stages of setting up Teleport, "Try out Teleport" and "Deploy a
Cluster". While the organization of our top-level docs sections attempts
to correspond to the stages a user goes through when setting up
Teleport, these combine some tasks that should probably be separated:
- **Choosing an edition and deploying a production cluster**: While the
"Deploy a Cluster" section includes our deployment guides as well as
our edition guides, user will likely commit to setting up Teleport
Cloud, Open Source, or Enterprise before they plan a full HA
production deployment.
- **Deploying a production cluster and deploying a small-scale Teleport
cluster:** While the "Deploy a Cluster" section includes the Linux
Server and Digital Ocean 1-Click guides, these two guides are more for
small-scale deployments than full production clusters.
This change improves the early-stage docs experience for new Teleport
users by:
Splitting the "Deploy a Cluster" section
----------------------------------------
The "Deploy a Cluster" section includes subsections related to choosing
a Teleport edition as well as subsections related to deploying a
production cluster. The problem with this approach is that it leaves no
room for adding introductory guides to help users with these two
purposes.
By splitting the "Deploy a Cluster" section into two top-level sections,
one related to choosing an edition and the other to dpeloying to
production, we can add introductory pages that put the subsections of
these sections in context.
_This change accompanies the work on #16751 to write a general guide to
HA Teleport deployments, since the new guide will have a prominent
place in the reorganized "Deploy a Cluster" section._
Adding introductory pages
-------------------------
Sections related to getting started with Teleport, "Try out Teleport"
and "Deploy a Cluster", were missing introductory pages. This change
adds them, and also adds one to the new "Choose an Edition" section.
Moving the Linux Server and Digital Ocean guides
------------------------------------------------
Move these to "Try out Teleport". The Digital Ocean guide didn't fit
with the rest of the deployment guides, since it's not about
architecting an HA deployment.
This is also a better home for the "Linux Server" guide, so this change
moves that as well.
Removing the "getting-started.mdx" page
---------------------------------------
This page is not reachable via the navigation menu.
* Respond to PR feedback
* Respond to PR feedback
Also minor text tweaks
* Re-add the section about EC2 instances including the AmazonSSMManagedInstanceCore
* spacing cleanup
* make the linter happy
Co-authored-by: alexfornuto <alex.fornuto@goteleport.com>
* markdown linting and spacing
* update ec2 discovery for bootstrapping
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* re-add invite token step
* remove sid
* document keys to adjust in example config
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/server-access/guides/ec2-discovery.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* add reference to docs on IAM tokens
* Apply suggestions from code review
Co-authored-by: Alex McGrath <alex.mcgrath@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* additional copy edits
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Alex McGrath <alex.mcgrath@goteleport.com>
Closes#14692
PR #10987 repurposed the Ansible Server Access guide to be a Machine ID
guide. Since users still found use in the original Server Access guide,
this change restores that guide.
Note that this change does not attempt to edit the Ansible Server Access
guide, and simply restores it to the state it was in before #10987. The
Machine ID Ansible guide is left untouched.
* Organize docs guide sections chronologically
This change aims to make docs navigation easier by organizing some docs
sections according to the sequence of steps a user would take to set up
Teleport.
The current docs organization uses a variety of categories and schemes
to organize the docs. For example, there is a "Home" section that
includes the Changelog, Installation page, and Getting Started guides; a
"Setup" section that includes references and admin guides; and
edition-specific sections (Enterprise, Cloud). For a user who is setting
up Teleport--or who has already done some setup work and wants more
advanced instructions--it's difficult to know where in the docs to find
the right information.
This change organizes our how-to guides into the following categories
that describe the process of setting up Teleport:
- Try out Teleport
- Deploy a Cluster (including choosing an edition)
- Configure Access (including SSO, RBAC, and Access Requests)
- Manage your Cluster (admin guides, operations, etc.)
- Use Teleport (this section already exists)
I moved the Reference section after this chronology, since users can
access the reference guides anywhere in the setup process.
As part of the change, I have also moved the content from the
"Enterprise" and "Cloud" sections into "Deploy a Cluster", since this
content has to do with how to deploy a specific edition of Teleport.
Note that this change does _not_ attempt to reorganize our
protocol-specific sections. While adding resources is part of the
Teleport setup process, we have a lot of content in our
protocol-specific sections, and moving it all into a single section
related to adding resources to a cluster would (a) exceed the maximum
depth for subsections in the nav bar and (b) cause more confusion than
it alleviates.
* Respond to PR feedback
- Create a "Compliance Frameworks" section of "Configure Access" with
the FedRAMP and SOC 2 guides
- Rename "Use Teleport" to "Connect your Client"
- Move the database GUI client guide into "Connect your Client"
* Add redirects
* Fix linter issues
This change replaces all `Tile`s in the docs with lists of links. This
achieves two things:
- Helps us move toward a more text-focused look and feel for the docs.
See gravitational/docs#93.
- Makes it easier to reorganize the docs. Currently, there's no linting
for internal links in `Tile` hrefs (See gravitational/docs#100).
I used this script to edit each docs page, invoking the script for all
MDX files in docs/pages:
```
gawk '
BEGIN{inopentag=0; indesc=0; desc=""; title=""; href="";}
/<\/?TileSet>/{next;}
/<Tile/ {
inopentag=1;
}
inopentag==1 && /title=/{
title=gensub(/.*title="([^"]+)".*/, "\\1", "g", $0);
}
inopentag==1 && /href=/{
href=gensub(/.*href="([^"]+)".*/, "\\1", "g", $0);
}
inopentag==1 && />/ {
inopentag=0;
indesc=1;
next;
}
indesc==1 && !/<\/Tile/{
gsub(/(\n|\t|\s{2,})/," ",$0);
desc=desc ($0);
next;
}
/<\/Tile/{
print "- [" title "](" href "):" desc;
indesc=0;
desc="";
title="";
href="";
next;
}
inopentag==0 && indesc==0{ print $0 }
' $1 > "$1.tmp";
cat "$1.tmp" > "$1";
rm "$1.tmp";
```
I then cleaned up each file changed by the script and fixed any
incorrect URLs.
If we are following the example, we should be grepping for the user created directly above this command to see if it was deleted.
Co-authored-by: Gavin Frazar <gavinfrazar@gmail.com>
Our architecture section was written almost 5 years ago
and was completely obsolete.
I refactored all of it to be up to date, added Kuberentes
and other resource type references, replaced and created new diagrams.
* Add context to "tsh ls" in docs
Fixes#7051
- Create a partial for how the Teleport Auth Service filters Nodes
based on user roles/logins in response to queries.
- Add the partial to provide context for example commands that include
"tsh ls".
- Make our existing text on Teleport's authorization checks clearer
by enumerating the checks in the order they are executed in
services.RoleSet.CheckAccess.
Note that this does not change guides that instruct the user to create
a new user and role, since a user following these guides will see the
correct "tsh ls" output.
* Respond to PR feedback
* Ensure tctl commands include login instructions
See #10192
Add the tctl.mdx partial or a "tsh login" command in some pages that
include example tctl commands. Note that this change does not address
SSO guides, which will be handled separately.
Where a guide requires a complete restructuring to provide full context,
"docs/pages/application-access/guides/connecting-apps.mdx", I've added
"tsh login" instruction above the first tctl command.
* Respond to PR feedback
* Make the OpenSSH guide more usable
See #11841
- Add a Prerequisites section and divide the instructions into steps via
H2 headings.
- Use ScopedBlocks to add instructions for Cloud users.
- Fill in missing instructions (e.g., adding host_cert permissions for
Cloud users and editing the file permission of the host key/cert)
- Since all supported versions of Teleport now include "tsh config,"
remove the manual OpenSSH configuration option. This makes the guide
much simpler to follow.
- Add a Details box explaining "tsh config" The original OpenSSH guide
included some technical details about the proxy subsystem, but
without enough context to understand the configuration generated by
tsh config. I've moved the technical details into a Details box, and
expanded them, so readers interested in how the local SSH config they
generate via "tsh config" works.
- Indicate that you need to specify the SSH port when connecting to an
OpenSSH host via configuration generated by tsh config.
* Respond to PR feedback
Alex Fornuto