* 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"
* Edit the Slack access request plugin guide
Fixes#14581
- Flesh out the intro a bit
- Fix the directory name used in the `mv` command in the installation
step. Also fix the name of the binary generated by the `make` command.
- Add a step to test the installation
- Edit the rbac.mdx and impersonations.mdx partials to provide more
context and restructure the instructions so users can follow them step
by step.
- Add context around other existing steps
- Add more comprehensive role mapping instructions. The guide included
an example role mapping, but did not spell out the general logic of
the role mapping bheavior, e.g., that the "*" key is required.
- Move the step re: inviting the bot to after the user configures role
mapping so they know which channels to invite the bot to.
- Add a section on creating roles to enable Access Requests so it is
eassier to follow this guide linearly. Otherwise, users will need to
do more work to match the configuration instructions with the
specifics of their RBAC setup.
- Capitalize "Access Request" in this and other guides, since we're
adding more emphasis on this as a product.
- Turn the "Audit Log" section into an Admonition and make the
instructions there more accurate.
- Add context to the "identity-export.mdx" partial. This is a pretty
confusing part of the Access Request setup process, so I added context
to explain why different identity file formats are used.
* Apply suggestions from code review
Co-authored-by: Nic Klaassen <nic@goteleport.com>
* Respond to PR review
Co-authored-by: Nic Klaassen <nic@goteleport.com>
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".
* Update error message returned when user is not allowed to sign db certs
* Update lib/auth/auth_with_roles.go
Co-authored-by: Nic Klaassen <nic@goteleport.com>
* Update docs
* Fix docs
* Update error for snowflake cert signing
* Update docs/pages/database-access/reference/cli.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/database-access/reference/cli.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Nic Klaassen <nic@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.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.
* 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
* Fix resource links
Fixes#12839
Some video links still refer to the outdated "/teleport/" path.
This change adds the videos these links refer to to the "img"
directory and updates the links.
Note that two of the three MDX files that are changed here do not
actually render the video. I've changed the links here anyway in
case someone uses these as a reference for the link format.
* Apply suggestions from code review
Co-authored-by: Ben Arent <ben@goteleport.com>
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
Co-authored-by: Ben Arent <ben@goteleport.com>
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
* Edit tctl instructions to clarify remote login
Closes#11464
- Ensure that all example tctl commands are accompanied either by
instructions to log in to the cluster or the tctl.mdx partial.
- Edit the guides in the Architecture section to remove notes that
tctl can only be used locally to the Auth Service.
- Edit the user-client-rereqs partial to mention tctl for all
editions, since you can log in to tctl remotely for all editions.
Not editing guides where:
- tctl is run via kubectl exec
- tctl is not mentioned in a code block, i.e., only in passing, and
a reader isn't expected to run the command on their own while
following the guide.
- The user is already expected to run tctl on the Auth Service. The
docker-compose Getting Started guide is an example of this.
* Respond to PR feedback
- Provide more context on authenticating with tctl in the CLI reference
- Update the link to more information re: tctl in the architecture
overview, and indicate that tctl users must authenticate.
- Minor tweaks.
* Respond to PR feedback
- Rephrase the authentication paragraph in the Architecture Overview.
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 Redis guides for Cloud users
See #10637
- Add tabbed instructions in the Prerequisites for users of
different scopes.
- Add instructions to make it clearer where things are running, since
the previous guides did not mention that you need to install and
run the Teleport Database Service on a separate host. This adds
a new section re: the Database Service that mirrors instructions
in other Database Access guides.
Note that this branch cherry-picks all docs/pages/includes changes
from #11668. Please add feedback on the partials to that branch,
and I will keep this branch rebased to that one.
* Address PR feedback
* Edit the Database Access GUI guide for Cloud users
See #10637
- Add a Prerequisites section with tabs for different scopes
- Use a ScopedBlock so the "Get connection information" section only
shows connection options that are relevant to a particular scope.
- Where the guide refers to a particular "tsh" command that doesn't
apply to all scopes, refer to the "Get connection information"
section instead.
- Light copy-edits for style, clarity, and grammar
* Respond to PR feedback
* 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
* Add Cloud instructions to five guides
See #10637
Database Access FAQ
- Add tabbed instructions where answers differ for Cloud/Self-Hosted
- Style/grammar tweaks
Dynamic Registration
- While this guide is edition agnostic, I have added the tctl.mdx
partial so Cloud users know to log in to Teleport before running
tctl commands.
Configuration reference
- The only part that required different instructions for Cloud users
was the reference configuration for the Proxy Service. I have
supplied the values hardcoded in Teleport Cloud.
CLI reference
- Add ScopedBlocks where examples mention proxy.example.com--use a
Cloud tenant address for Cloud readers.
- Light style/grammar edits
Architecture
- This guide is mostly edition agnostic. After the overview diagram,
I used a ScopedBlock to make it clear to Cloud users that the Proxy
Service uses the Teleport Cloud tenant address.
* Respond to PR feedback
Also remove mongo_public_addr from the Cloud proxy_service config,
since this was included incorrectly.
* Add notes about wildcard certificates
Guides to getting started with Teleport on various platforms
recommend creating a DNS record for *.teleport.com. It would help
prospective users to know why this is needed. This change adds
context for why Application Access requires a wildcard subdomain.
Fixes#5378
* Respond to PR feedback
- Move information into a partial
- Mention that you can create a DNS A record for each application-
specific subdomain
* Restore DNS-related cloud provider commands
Gabriel Corado