* 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>
The `tsh appps` family of commands is aliased to `tsh apps`, so both
invocations work correctly. The command itself is defined as `tsh apps`,
so this is what appears in the help message.
Update references to `tsh app` to recommend `tsh apps` instead so that
there isn't confusion when browsing `tsh help` and looking for a missing
`app` subcommand.
Fixes#21367
* Document Google Cloud CLI access
Closes#17584
- Add a guide to configuring and using Google Cloud CLI access via the
Teleport Application Service.
- Since we now have three guides to setting up secure access to cloud
APIs, create a new subsection of the "Application Access" docs section
related to cloud provider APIs.
* Respond to PR feedback
- Capitalize "JSON Web Tokens"
- Edit the AWS guide's nav bar entry
- Fix garbled section in the App Access intro page
- Improve the service account name we use in the how-to guide
- Clarify the way the App Service uses a service account
- Add new env vars to the `tsh proxy` command output
- Other small changes in response to suggestions/comments
* Edit instructions for starting the VM
Add instructions to launch a new VM with a service account attached.
This addresses feedback on the PR.
* Use more precise terminology for service accounts
This addresses feedback on the PR
* Add information about `tsh gsutil`
This adds to both the Google Cloud API access how-to guide and the CLI
reference.
* Respond to PR feedback
* use nobr tags
* fix multiline command
---------
Co-authored-by: alexfornuto <alex.fornuto@goteleport.com>
* 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>
* Add x-teleport-api-error to reserved headers
* Update app tests for rewritten headers
* Add test case for x-teleport-api-error
* Fix test for XForwardedSsl since it was effectively untested before
* Refactor leaf test to parse the response from dumper app
* Update docs reference reserved headers
* 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
* Document Azure CLI access
Closes#17583
- Create a guide to Azure CLI access
- Update references to reflect changes to roles, commands, and the file
config
* Respond to alexfornuto feedback
* Add a section to the guide on `tsh proxy azure`
* Respond to smaller feedback items from Tener
* Switch the order of role approaches
Responds to one item of feedback from Tener.
* Respond to zmb3 feedback
* Document new behavior
- Wildcards in `deny` rules
- The `tsh proxy az` alias
* Add SSO instructions for defining a role
* Update env var values
* optimize images
Co-authored-by: alexfornuto <alex.fornuto@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 slug for self signed certs
* Add self-signed certs guide
* Move tls cert setup into an include snippet
* Update tsh section on self signed certs
* Fix indentation
* Remove extra slash before heading
* Update docs/config.json
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/management/admin.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/includes/tls-certificate-setup.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/management/admin/self-signed-certs.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/management/admin/self-signed-certs.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/management/admin/self-signed-certs.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/management/admin/self-signed-certs.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Fix formatting of github suggestion commit
* Change link title to avoid abbreviation
* Update intro to explain the purpose of the guide and why anyone would want it
* Make 'proxy' and 'certs' consistent throughout the guide:
certs -> certificates
proxy -> Proxy Service
* Move motivation for guide out of warning and into intro
* Simplify the warning notice
* Change headings
* Capitalize helm and simplify label
* Update Helm info to include inline instructions
* Simplify systemd label
* Update systemd tab
* Update slug certs -> certificates
* Fix include snippet yaml example
* Change prereqs to omit cloud tab and instruct user to check for self-signed certs config
* Update docs/pages/management/admin/self-signed-certs.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/management/admin/self-signed-certs.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/management/admin/self-signed-certs.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/management/admin/self-signed-certs.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Get specific about problem caused by insecure TLS
* Remove 'how to setup tls certs' section in favor of a link at the bottom
* Add examples for tsh and tctl, and clean up tctl wording
* Remove link to systemd guide
* Add more detail to systemd instructions
* Change wording around instructions for teleport
* Rearrange links
* Remove reference to deleted acme.mdx
* Remove v2 config reference to auth_servers
* Remove list syntax for proxy_server
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* transport: Rewrite headers, including JWTs, for websockets.
Applications can otherwise 401 on websocket requests, as they do not
present any authentication headers.
docs: Fix the reserved JWT header name.
Signed-off-by: Roman Tkachenko <roman@goteleport.com>
* Add test for JWT header in websocket apps
Signed-off-by: Roman Tkachenko <roman@goteleport.com>
Co-authored-by: Alex Vandiver <alex@chmrr.net>
* 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 Machine ID Kubernetes guide and partial Apps guide
* Small wording tweaks to the k8s guide
* Rename menu titles to match convention
* Fix inaccurate CA cert recommendation on the API access guide
* Tidy up the Kubernetes guide
* Finish up first pass on Apps guide
* Remove empty admonition
* Address review feedback
* Fix doctest lints
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Address a batch of review comments
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Address further review comments
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@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.
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".
* 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
* 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.
* 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
* Mention Cloud compatibility in three guides
Server Access getting started:
- Remove the instructions to install and set up the Auth
Service, and add references to main Getting Started guides
and Cloud signup page.
- Add a prerequisite to have deployed the Auth Service and
Proxy Service.
EC2 joining guide: make it explicit that the Cloud is not
compatible with this. Also make small style tweaks.
App Access getting started page:
- The guide assumes that you are running the Auth Service,
Proxy Service, and App Service via the same binary, which
does not work for Cloud users.
* Respond to PR feedback
- Add newlines after headings
- Use teleport app start instead of teleport start --roles=app
- Fix incorrect Ubuntu version number
- Add a Details box explaining tctl usage for Cloud
- Correctly capitalize "Node"
* 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 Cloud compatibility notes to guides
Add Details boxes to some guides that do not mention Teleport
Cloud, indicating how each guide relates to Teleport Cloud users.
* Respond to PR feedback
Removes Details boxes unless necessary to warn users of
incompatibility with Teleport Cloud.
Also makes minor stylistic tweaks.
Russell Jones