* 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
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
See #11383
Help ensure that no visitor to the Teleport docs site sees content that
is irrelevant to their scope (e.g., Cloud, Open Source, or Enterprise) by
hiding scope-irrelevant content from the navigation menu and menu
pages.
For pages that aren't step-by-step guides and are meant to convey
general information about a Teleport edition, show these pages in all
scopes so users who are curious about another scope can get the
information they need.
This PR focuses on the Server Access section.
It also includes links to all Server Access guides in the intro page,
since only the PAM guide was included before.
If a user installs an agent version that is greater than the control
plane version, the agent will not be able to contact the control plane
(e.g., it will call a gRPC method that the control plane doesn't
recognize). The current partial for installing Teleport on a Linux host
includes only instructions for installing the latest version. Since
Teleport Cloud is behind the latest version, I have added a partial for
installing a Cloud-compatible agent and included it for Cloud users
in guides that require installing a Teleport agent.
* Edit two guides for Cloud users
PAM guide
- Minor style/clarity/grammar edits
- Use a ScopedBlock to hide Cloud-irrelevant information in the MOTD
section
- The organization of the original guide was a bit scrambled, so I
attempted to reorganize it into a form that made more sense.
Tsh guide
- Use ScopedBlocks to provide scope-relevant information.
- Mention Machine ID in the "### SSH certificates for automation"
section.
- Misc grammar/clarity/style edits
* Respond to PR feedback
* Add Teleport Cloud instructions to two guides
See #10634
Restricted Sessions for SSH
While this already includes a compatibility note, I wanted to ensure
that users would only see information relevant to the scope they had
selected. Changes made:
- Added a tabbed Prerequisites section
- Removed instructions to install the Auth/Proxy that implicitly
applied to all scopes
- Misc style/grammar/clarity edits
BPF Session Recording
- Add scoped tabs
- Merge steps 2 and 3, which both involved examining the audit log to
verify that Enhanced Session Recording is enabled
- Misc style/grammar/clarity tweaks
* Respond to PR feedback
- Fix style
- Flesh out the Node setup section
- Add Details about file-based event logs
* Respond to PR feedback
Restore the introductory section with minor copy-edits.
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.
Paul Gottschling