* Reorganize the config reference
Closes#11253
This change breaks up the config reference by moving each Teleport
service's configuration settings into a separate YAML snippet, and
organizing each YAML snippet into a `TabItem` within a `Tabs` with
`dropdownView` enabled. When Teleport Enterprise Cloud doesn't support a
service, this change adds a `Notice` with a message about Teleport
Enterprise Cloud in the relevant `TabItem`.
I thought this approach would be cleaner than alternatives:
- **Including an H2 for each service:** With this approach, the
configuration reference would be even longer than it is now. With the
approach I'm proposing, readers would navigate to "Reference
configurations", then choose a service from a dropdown menu: much less
scrolling for slightly more clicking.
- **Including another set of `TabItem`s for Teleport editions:** I
thought about adding a `Tabs` with a dropdown option for each Teleport
edition and a horizontal `TabItem` for each service, but this would
require horizontal scrolling and doesn't scale very well.
- **Including horizontal tabs for each Teleport edition**, with an inner
dropdown menu for each Teleport service: There is currently no way to
do this without multiple `Tabs` components, which gets messy quickly.
**Note** that this change does not attempt to copy-edit comments/example
values within the configuration snippets. The scope of this change is
limited only to reorganization.
* Respond to PR feedback
* Update docs/pages/includes/config-reference/instance-wide.yaml
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Respond to PR feedback
Use headings instead of `TabItem`s to split up sections of the config
reference.
---------
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* 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
* Remove Auth/Proxy instructions from DB guides
Closes#11538
A number of our Database Service guides instruct the user to install the
Auth Service and the Proxy Service. For users who have already set up
these services, these instructions add friction. For users who have
_not_ set up these services, Teleport has existing instructions that
users can follow instead.
This change edits our Database Access guides to require the user to have
a running Teleport cluster as a prerequisite, in line with how-to guides
in other sections of the docs.
Note that, while the issue this change closes is to add Auth/Proxy
Service setup instructions to _more_ places in the docs, this change
follows our style guide recommendation (#20024) to add steps to the
Prerequisites section if we have them documented elsewhere and they
don't directly pertain to the goal of a how-to guide.
* Respond to PR feedback
Change H3s to H2s
---------
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Require a new flag for enabling dynamic resources matching for "tsh db configure create"
* rename flag to --dynamic-resources-labels
* make naming more consistent
* Update security information in docs.
Update README.md with some updated security and trust information.
Additonally, update SECURITY.md to deprecate our email-based submission process
with our current process via HackerOne.
This change also removes the now-unused PGP public key document.
* Update README.md
Co-authored-by: Reed Loden <reed@goteleport.com>
* Update Teleport download link to current page.
---------
Co-authored-by: Reed Loden <reed@goteleport.com>
Closes#17092
The Database Access introduction lists the databases that Teleport
supports, but also includes a list of links to all of our Database
Access guides.
So we don't have to maintain two separate lists, I have removed the
first list of supported databases.
I have also edited the heading of the section that lists our
database-specific guides so it's clearer that they are about specific
databases.
* sort list of db guides alphabetically
* add Elastic guide
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
* additional edits from review
* add spaces to next steps include
This is so that additional ul items added to a guide using this partial will have consistent spacing
* remove instructions and add tip
Resolves #r995144908 and #r995566035
* fix Database Access config and add scopes
* Move note into relevant tab
* adjust example user mapping
* incorporate more feedback
* incorporate feedback from @tener
* Update docs/pages/database-access/guides/elastic.mdx
Co-authored-by: Krzysztof Skrzętnicki <krzysztof.skrzetnicki@goteleport.com>
* bypass linter rule
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
Co-authored-by: Krzysztof Skrzętnicki <krzysztof.skrzetnicki@goteleport.com>
* Add screenshots for azure IAM setup
* Update azure mysql postgres guide to explain discovery
* Update db service config yaml reference
* Update docs/pages/database-access/guides/azure-postgres-mysql.mdx
Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com>
* Fix typo in admonition type
* Redact IDs in azure screenshots
* Clarify that role assignment applies to either principal type
* Advise restarting db service after checking credentials
* optimize images
* Update docs/pages/database-access/guides/azure-postgres-mysql.mdx
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Update docs/pages/database-access/guides/azure-postgres-mysql.mdx
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Update docs/pages/database-access/guides/azure-postgres-mysql.mdx
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com>
Co-authored-by: alexfornuto <alex@fornuto.com>
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* 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.
Fixes#13688
Database Access guides instruct the user to log in to their cluster
and test their tctl connection before installing the Auth/Proxy, which
can cause confusion.
This change fixes this by:
- Editing start-auth-proxy.mdx to include tctl.mdx, and removing the
text telling all users to run tctl commands on their Auth Service
host.
- Removing tctl.mdx from the Prerequisites sections of DB Access
guides.
Fixes#10976
This change helps to remedy two issues with the documentation:
- Much of the documentation was written when Teleport's services
consisted of the Auth Service, Proxy Service, and Nodes/SSH Service.
There are some places in the docs where a reader can mistake the
Node Service to mean "any resource service."
- Users often associate the term "agent" with a daemon that must run on
every host in their infrastructure, and usage of this term can make
Teleport seem more resource intensive than it actually is.
This change corrects mentions of "Node" that stand in for "any service
that access resources in your infrastructure" to account for Teleport's
other resource services. It also replaces mentions of the term "agent"
with "instance," the name of a resource service, or simply "Teleport."
Also edits the "agentless" question in the FAQ to include more detailed
information about each of Teleport's resource services.
This change also does some light copy-editing to correct the
capitalization of service names. It doesn't aim to be comprehensive,
though, since the main purpose of this change is to fix potentially
misleading mentions of "Node" and "agents".
Finally, this change deletes the production.mdx guide, as there is
no way to access this guide due to redirects. This guide includes
some outdated usage of "Nodes".
Teleport now will try to extract MySQL server version from initial handshake package instead of sending `8.0.0-Teleport` every time. This string can be overridden by new configuration option `mysql.server_version`. On DB service start Teleport will also try to fetch the current version from MySQL/MariaDB instance. After that the server version will be updated on every successful connection to keep it up to date.
Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Edit Database Access guides for Cloud users
This edits Database Access guides that show you how to access
specific databases. These guides follow the same structure and use the
same partials, so it made sense to address them in a single commit.
See #10637
Edits made
- Some Prerequisites sections were either absent or required
"Teleport," which I've clarified with a scoped Tabs component to
indicate the appropriate client tools for each deployment type.
Since we instruct users on deploying the Auth/Proxy later in the
guide, I restricted this to client tools. Also flesh out the
Prerequisites a bit in general.
- Add ScopedBlocks for minor details that vary between scopes.
- Ensure that all commands that take place on the Database Service node
are described correctly as taking place on that node.
- Change the tctl-auth-sign.mdx partial. Since the start-auth-proxy.mdx
partial now instructs self-hosted users to run tctl commands on the
Auth Service host, we no longer need the Self-Hosted tab. As a result,
I have turned the Cloud tab into a ScopedBlock.
- Reorder self-hosted guide sections so users start the Auth/Proxy
before running "tctl auth sign". Otherwise, this command will not
work.
- Minor style/grammar tweaks
* Respond to PR feedback
Introduce Database Certificate Authority. New CA is used by Database Access to sign database certificates making them independent from Host CA.
Co-authored-by: Marek Smoliński <marek@goteleport.com>
start-auth-proxy.mdx is a partial used by a number of Database Access
guides. After PR #9556, the partial included garbled instructions for
setting up Teleport with Let's Encrypt. This change edits these
instructions for clarity.
* Add plugin setup instructions for cloud users
- Turn the identity file export and RBAC instructions into
includes, since these instructions are the same for each
plugin.
- Change the tab set re: an impersonation role to a detail box
scoped to cloud users.
- Add separate example config files for cloud and self-hosted
deployments of each plugin.
- Misc. changes for clarity
Fixes#8936
* Respond to PR feedback
Also make minor stylistic tweaks
* Respond to PR feedback with stylistic tweaks
* Standardize ACME instruction details
Our Getting Started guides often include instructions for
configuring Let's Encrypt and ACME before starting
Teleport, but not all of these instructions have the same
level of detail, and some are missing some context around
how Teleport uses ACME and why you need to open port 443 on
your Proxy Service host. This change adds an include that
spells out these instructions and invokes the include in the
appropriate guides.
The intention was to include as much relevant information within
the guides themselves to prevent the reader from having to
navigate to other pages.
Closes#6448
* Respond to PR feedback
- Substitute "proxy" for "node" where it was incorrectly used
- Some small stylistic fixes
- Clarify that "teleport configure" does not write the config
itself
Add Teleport Cloud instructions to 3 guides
This change addresses three guides mentioned in issue #5845.
- Update the start-auth-proxy partial to include Cloud
instructions
- Mention Teleport Cloud usage in three guides
- Add minor readability and style guide-related tweaks
* Respond to PR feedback
* Minor tweaks to remaining Database Access guides
- Mention Teleport Cloud
- Add small stylistic changes
