* 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
An issue with `gravitational/docs` caused the docs linter to stop
catching issues for a period of time. Now that we have addressed the
linter issue, this change addresses warnings/errors flagged by the
linter.
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* 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
* Add port number to cloud address examples for proxy server
* fix port example
* Include 443 port in cloud proxy examples
* use 443 instead of 3080 for cloud examples
* Add a glossary of Teleport terms
Closes#16121Closes#13363
- Create a Core Concepts page based on the Architecture Overview page.
The Overview page is an outline of core concepts, so I thought it
would make a good starting point for the glossary.
- Add the Core Concepts page to the Home section to make it more
prominent for users who are visiting the docs homepage. This should
give it more traffic than leaving it in the Architecture section.
- Move definitions out of the "Definitions" table. Since this table
repeats content from the body sections and comes after them, it makes
sense to condense all content into brief body sections.
- Alphabetize sections
- Bold the first instance of each keyword within a given section. Not
adding links since these are all to the same page. It might get a bit
confusing to click a link and not see a change in view, since the
target section would already be on the page.
- Remove the intro paragraph of the old Overview page, since it's not
strictly related to core concepts.
* Respond to PR feedback and add further edits
- Group definitions into H3-level sections organized into H2s, improving
readability by presenting the more central components first.
- Group "Machine ID" with "Teleport Services" to simplify the glossary.
- Call instances of a Teleport Service an "agent". This is consistent
with our source and informal language about Teleport. This also
removes the "Node" terminology, which is prone to misuse (does it mean
"a Service instance"? An "SSH Service instance"? Both are present in
the docs) and easily confused with the lowercase "node" (i.e., a
host).
- For simplicity, remove the term "Teleport Process" and simply explain
that multiple Teleport Services can run via the same binary.
- Add a section on Teleport's editions, including the terms "Community
Edition", "Enterprise", and "Enterprise Cloud".
- Remove the mention of Teleport Discover, which isn't documented yet.
- Minor wording/readability changes.
* Respond to PR feedback
* Respond to zmb3 feedback
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.
Closes#16985
Fixes the grammar issue referenced above and corrects other minor copy
and clarity issues.
Co-authored-by: Steven Martin <steven@goteleport.com>
* 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>
* Remove spaces between scoped blocks
This enables faster regex searching for single scoped blocks, without alternate content for other scopes
* replace single scoped block with details component
By doing this, something remains visible even when the user hasn't selected the Enterprise scope. That way if they forgot to, they still have something visible to expand and get the information they need.
* make single scoped Details blocks scopeOnly=false
That way readers will still know there is content that doesn't apply to the current scope, in case they forgot to select the correct one
* 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
* Add RBAC instructions for DB tctl auth sign
Fixes#13768
Add a `Details` box to the `tctl auth sign` entry in the Database Access
CLI reference explaining how to set up your user's Teleport roles in
order to enable running `tctl auth sign` for database-specific
certificate formats.
* Update docs/pages/database-access/reference/cli.mdx
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
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.
Reorganize our Access Request guides
Fixes#13696
Most guides to Access Requests are currently not listed on the sidebar,
and the guides that are listed are available for Cloud as well as
Enterprise. This change makes it easier to find our Access Requests
guides by moving them to the Access Controls section and listing all
guides on the sidebar. It adds the "Access Requests" and "Access Request
Plugins" subsections to "Access Controls".
Since the Access Controls section includes one subsection, called
"Guides", this change also renames that subsection--and adds a
descriptive intro paragraph to the section's menu page--in order to
accommodate the Access Requests and Access Request Plugins subsections.
Move some guides into "Access Requests"
Paul Gottschling