* Edit forScopes configurations and edit guides
Closes#26500
This change requires merging gravitational/docs#326 to add a Team scope
to the docs.
This updates pages within the docs so that:
- Each page's `forScopes` configuration is accurate, especially with
regard to support for Teleport Team.
- All scoped components match the `forScopes` configuration for each
page. For this, I used the linter introduced by
gravitational/docs#327.
* Respond to alexfornuto feedback
* Promote IAC docs for agents and dynamic resources
Closes#27382Closes#25418Closes#25442
Two aspects of setting up a Teleport cluster are omnipresent in the docs
but never get dedicated treatment:
- Running agents
- Applying dynamic resources
As a result, it is difficult to include discussions about those topics
that are separate from a specific workflow or how-to guide. One glaring
absence has been prominent guidance on using infrastructure-as-code
tools to achieve these tasks.
This change improves the visibility of Teleport's support for
infrastructure-as-code tools by:
- Creating top-level docs sections for running agents and applying
dynamic resources
- Making IAC instructions prominent within these sections
The intention is for readers to become familiar with different methods
of applying dynamic resources and running agents, including how to do
this with IAC, so they can apply this knowledge when reading other parts
of the docs.
As a result, in the docs sidebar, the "Dynamic Resources" section comes
before the section on RBAC, and the "Teleport Agents" section comes
before the sections related to individual Teleport services
("Application Access", "Server Access", etc.).
The new section on dynamic resources also gives us a place to put other
guides to using the Terraform provider and Kubernetes Operator, e.g., if
we add guides to using these tools with popular GitOps platforms.
Likewise, the section on agents gives us a place to put other agent-wide
information, e.g., how to enable an additional Teleport service on an
instance that is already running.
To allow for these changes, I have also made the following, more
tangentially related sidebar changes:
- **Renamed sidebar sections to be noun phrases instead of verb
phrases:** Currently, one half of the sidebar is made of imperative
phrases like "Manage Access" and "Manage your Cluster". This doesn't
really work for the sections on agents and dynamic resources, so I
have renamed these sections for consistency.
- **Moved the "Manage your Cluster" and "Deploy a Cluster" sections**: I
have arranged the sidebar so more basic topics (i.e., those that new
users and experienced users alike will need to be familiar with) are
on the top and more advanced ones are on the bottom.
The other sections that are currently in the first half of the sidebar
are topics that all Teleport users will need to get familiar with,
while day two operations and self-hosted production deployments are
more advanced topics.
- **Edited the landing page:** I have edited the landing page of the
docs to reflect the new sidebar organization. This also makes the page
shorter, simpler, and more opinionated. It spells out a high-level
sequence for setting up Teleport, then provides a list of advanced
topics for further reading.
Links correspond to sidebar sections--as before, I wanted to describe
the topic of each sidebar section so users would know this information
without having to navigate away from the landing page.
* Move the "Dynamic Configuration" section
Make this a subsection of "Manage your Cluster" since it's not
self-evidently clear as a top-level docs section. Users will probably
need an introduction via the "Manage your Cluster" section intro page.
This also reverts some of the more drastic sidebar changes introduced by
the previous commit.
Responds to xinding33 feedback.
* Make IAC learning tracks prominent/hard to avoid
Closes#27751
Responds to xinding33 feedback
The motivation is to be more opinionated about the course that users
take through the docs. We currently recommend two tracks for
self-service users, i.e., the users expected to make use of the landing
page:
- Setting up a toy self-hosted Teleport cluster
- Setting up a Teleport Team/Enterprise Cloud cluster that can
eventually become production ready
By moving the "Get Started" guide to the landing page, we direct users
immediately on to the first track. This change then gives new users a
way to enter the second track from the docs landing page with a
prominent link to the Teleport Team docs.
This change also edits The landing page to direct users who have
completed the getting started experience to instructions for setting up
a pool of agents on Terraform, helping to make infrastructure-as-code a
first-class citizen of the docs.
This change also removes the menu of links that used to confront users
on the landing page. Since all sidebar sections include introduction
pages, users interested in the content of a sidebar section can visit
the section. By removing links, we make it clearer for users how to
proceed through the docs.
* Fix linter errors
* Incorporate Trivy recommendations
* Respond to alexfornuto feedback
* Restore list of dynamic resources to the reference
* Fix linter warnings
* Remove the ".sh" extension from userdata script
The Terraform module that reads this file does not need the extension,
which was causing trouble for our shellcheck linter.
* Use teleport.example.com as the example proxy
* Add the core Jamf guide steps
* Add sync schedule optional section
* Add the multiple sources optional section
* Add the auto-enrollment guide
* Add the Jamf service reference config
* Add words to cspell.json and sort it
* Use `--config` instead of `-c`
* Apply Alex's suggestions
* Add preview admonition to auto-enrollment.mdx
* Add scopes for auto-enrollment guide
* Add scopes for jamf-integration guide
* Remove "and restart" from Auth update instructions
* Auth restart instructions
* s/Jamf service/The Teleport Jamf service/
* Use an inline code block for external links
* s/the following/the following keys/
* Use inline code block for key names
* Use inline code block for key names
* Use inline code block for key names
* Use inline code block for key names
* Mention "local workstation" after we transition from Jamf to Teleport
* Mention Jamf service host when switching context
* Use `(=presets.tokens.second=)`
* Use `(=presets.ca_pin=)`
* Mention logs example explicitly
* Add a missing comma
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Address Alex's comments
* Reflow text
* Remove redudant tsh prereqs sentence
* Add a registered device to auto-enrollment prereqs
* Use headers instead of bold
* Use a narrower image for jamf-setup-2.png
---------
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
Closes#14788
The description of the `disablesse` S3 backend setting implies that this
setting disables server-side encryption, when it actually stops the Auth
Service from enabling SSE on a per-operation basis.
Also clarify the relationship between `disablesse` and `sse_kms_key`.
* Add reviewer and requester roles.
Reviewer and requester roles have been added to allow for easy defaults for
reviewing and requesting applications and user groups for the Okta service.
* Update comments, add in requester/reviewer references all over docs.
* Update constants.go
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
* Better names in resource-requests.mdx, no options for reviewer/requester presets.
* Add dbreviewer to cspell.json.
* Update init_test.go to handle the new number of presets.
* Remove access review/request role creation from resource-requests.mdx.
* Improve wording.
* Only add reviewer/requester/group access if in enterprise.
* Docs updates.
* Remove errant scoped block.
* Tune access controls getting started.
* Prevent customer roles from being overwritten by new defaults.
* Apply suggestions from code review
Co-authored-by: Nic Klaassen <nic@goteleport.com>
* Doc updates, function name updates, bootstrap label behavior changes.
* Adjust TeleportManagedLabel comment to sound less dire.
* Remove unnecessary references to reviewer/requester in the docs.
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Docs tweaks, removal of unnecessary login setting.
* Use internal resource type as discussed offline.
* Update api/types/constants.go
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
---------
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
Co-authored-by: Nic Klaassen <nic@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
* docs: provide information on local user locks from login attemps
* Update docs/pages/reference/authentication.mdx
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* header update
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* user variable use
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* verbiage change
* fix file reference
* Change to blocked instead of locked
* Correct words
---------
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Closes#25170
Since we want to keep docs on configuring Teleport's backends within the
Backend Reference, add a Notice to this reference in the DynamoDB
section.
Closes#13571
The instructions for the `cert-format` flag of `tsh` commands are a bit
vague in the CLI reference. While #19041 already fixes the `oldssh` flag
value, it's still unclear how `tsh` uses this flag. This change adds
more information. While #13571 indicates that `cert-format` is not a
true global flag, it is still a flag of the `tsh` command (not a
subcommand), so it makes sense to retain it within the "Global flags"
table.
* Refresh port descriptions
Closes#22839
Clarify that agents do not need to have ports open to the public
internet. Also update the networking guide's use of Teleport terms,
e.g., replacing "Node" as appropriate, and separate Auth Service ports
from Proxy Service ports in the "Self-Hosted" tab since production
deployments may run these services separately.
* Respond to strideynet feedback
* Respond to strideynet feedback
* Simplify Application Service paragraph
* Add docs for shell completion
* Address Zac's comments
* Apply suggestions from Alex
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Do not mention bash_profile
* update cspell
* Remove 'After that'
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
---------
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
GCS does not implement the S3 multipart API, so we emulate it
by uploading parts and manually "completing" the upload.
The delete permissions is required in order to assemble the
individual parts.
remove the comment saying Teleport won't start without the Firestore backend existing. This is wrong and contradicted by the first bullet point below the example
Closes#12575
Edit the CLI reference to indicate that `tsh ls` can support multiple
label argument values, resolving a longstanding TODO.
Co-authored-by: Steven Martin <steven@goteleport.com>
* [docs] Include File Transfers in moderated sessions docs
* Fix typo
* Add note in tsh scp reference
* Update docs/pages/access-controls/guides/moderated-sessions.mdx
Co-authored-by: Steven Martin <steven@goteleport.com>
* Add screenshot
* Update docs/pages/access-controls/guides/moderated-sessions.mdx
Co-authored-by: Steven Martin <steven@goteleport.com>
* Update moderated-sessions.mdx
---------
Co-authored-by: Steven Martin <steven@goteleport.com>
* Fix Helm chart Join token secret creation
Since #20763 was merged, we lost the ability of the chart reusing the
externally created secrets for join token.
This PR changes the logic and allows to control the secret creation
using the `joinTokenSecret.create` boolean and the secret name with
`joinTokenSecret.name`.
Fixes#20763
* Add changelog
* Clarify Auth Service backend permissions
Closes#22482
This change clarifies descriptions of:
- IAM permissions that the Auth Service requires in order to manage S3
buckets and DynamoDB tables
- When the Auth Service needs to create an S3 bucket/DynamoDB table
Specific edits:
- Add tabs to the partials we use to describe S3 and DynamoDB IAM
policies. One tab item is for cases where the Auth Service creates a
bucket/table, and another tab item is for when you have a pre-existing
bucket/table.
- Remove an extraneous H3 in the Backends Reference re: the required
DynamoDB policy. This H3 includes a very permissive policy, while
another H3 in the same page includes a policy with more reasonable
permissions. The more permissive H3 must have been left in the page by
mistake.
- Clarify permissions in the HA guide.
* Respond to webvictim feedback
* Respond to alexfornuto feedback
* Respond to webvictim feedback
Add a comment above the function that creates a DynamoDB table to change
the docs if the schema changes.
* Respond to alexfornuto feedback
* Make --reason required for `tctl alert ack`
The backend requires a reason, so by having it optional in the CLI
it just means we have to make a network request in order to get
an error.
Also update the docs to indicate that this is not optional.
* tctl: show acknowledged alerts when the -v flag is provided
* Add a --format flag for tctl alerts ls
This makes it easier to programatically operate on the alerts.
* Okta documentation.
Okta documentation has been added for the Okta service. This aims to explain
the Okta service and give simple examples.
* Typo fixes, comment fixes, naming fixes.
* Reorganization of Okta docs, fixing typos, adding in images and tuning wording.
* Use an architecture image for now until mermaid support can be reenabled.
* Correct spellings.
* Update docs/pages/application-access/okta/guide.mdx
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
* Correct architecture diagram.
* Linting fixes.
---------
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
* docs: document the updater
This commit adds the updater documentation covering:
- its architecture
- how to setup a self-hosted version server for on-prem users
- how to enroll an agent into automatic updates
- the `cluster_maintenance_config` resource reference
The PR currently restricts the automatic update scope to enterprise and
cloud. Technically oss users could benefit from it but we don't have an
oss package yet. Hopefully this should happen post 13.0 release.
* add new page to section index and sort
* Apply suggestions from code review
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* docs feedback pt.1
* docs feedback pt.2
* fix tabs and edit innards
* Apply suggestions from code review
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* docs feedback pt.3
* docs feedback pt.4
* Apply suggestions from code review
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
* docs feedback pt.5
* mark as preview
---------
Co-authored-by: alexfornuto <alex.fornuto@goteleport.com>
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
Machine ID is often a better option than `tctl auth sign` when
Teleport certificates are required for automation purposes.
This commit mentions Machine ID as an option in several areas
where we currently recommend the tctl approach.
In the future, we should update some of these guides (or make new
ones) to list Machine ID as the primary approach, but that's a larger
change and I wanted to get something out that can highlight Machine ID
as an option right away.
This change makes the experience of getting started with Teleport more
opinionated and more precisely molded around our intended audience. The
assumption is that people who want to go through our getting started
experience are skilled technologists who:
- Are curious about how Teleport works and want to tinker with a toy
cluster
- Need to set up a production cluster in order to protect their
infrastructure, in which case a toy cluster is less important than a
way to get started with the real thing
Promote the "Linux Server" guide
--------------------------------
Make the "Linux Server" guide the definitive introduction to OSS
Teleport by removing other "Try out Teleport" guides and moving this one
to the "Home" section. We want to remove the need for users to decide
which getting started guide to try, and this guide is the only one that
lets users spin up a fully fledged demo cluster besides the Digital
Ocean guide.
To let users know about the DigitalOcean 1-Click droplet, this change
links to our DigitalOcean 1-Click app from within the Linux Server
guide. It also advises users who don't meet the Linux Server guide
prerequisites to sign up for a Teleport Enterprise Cloud free trial.
This change also removes the Docker guide and redirects Docker-related
traffic to the Installation page, since the Docker guide is more of a
Getting Started guide than an integration guide, and our Installation
page already includes Docker setup information.
Edit the Linux Server getting started guide
-------------------------------------------
- Remove Application Service instructions, since it can turn off users
who, for example, don't use Python or don't want to run the
Application Service (plus we already mention it at the end of the
guide for users who do want to run this service).
- Update installation instructions to use our one-liner.
- Make this guide more explicitly focused on the Open Source edition,
removing Enterprise instructions. Users who want to tinker with
Teleport will not be interested in the Enterprise edition.
- Add session recording instructions. Most of the content of the Linux
Server guide has to do with setting up Teleport, rather than seeing
Teleport features, so I wanted to adjust this balance a bit.
- Remove the permission warning. It takes up around 1/4 of the screen
height when viewing the page, and we expect our intended audience to
know this information already.
Change the Enterprise information architecture
----------------------------------------------
- Remove the Enterprise "Getting Started" guide: This guide shows you
how to deploy a demo Teleport Enterprise cluster, which is sort of a
contradiction in terms. Enterprise users expect a production-grade
cluster, which is not what you get in this guide.
- In the Enterprise Introduction page, include instructions to read the
Deployment Guides, which show how to set up a mature HA deployment,
plus a recommendation to use Teleport Enterprise Cloud unless you need
the Enterprise-specific features explained in this guide.
* Change Helm reference `--set` formatting
Closes#9686
Since the `--set` flag examples aren't commands, this change removes the
shell prompts and changes code fence labels from `code` to `text`.
* Remove --set examples from Helm references
Keep the values.yaml examples. Used the following script to generate the
change:
files="$(find docs/pages/reference/helm-reference -name "*.mdx")";
for i in $(echo "$files"); do
tmp=$(awk 'BEGIN{yaml=""}
/<Tabs>/{t=1}
t==1 && /```yaml/{y=1; yaml="`values.yaml` example:\n\n"}
y==1{yaml = (yaml "\n" $0)}
y==1 && /```$/{y=0; print yaml; yaml=""}
t==1 && /<\/Tabs/{t=0; next}
t==0{print $0 }' $i)
echo "$tmp" > $i;
done
* Add docs subsection about joining services
Closes#21851
Also see #21305
Restructure the "Adding Nodes" guide to make joining Teleport processes
via the Proxy Service the default approach. Make it easier for users to
put these instructions in the context of our other joining methods by
creating a separate docs subsection for our joining guides.
This change also updates the previous "Adding Nodes" guide based on
testing.
This also renames "Node" to "Teleport process" and clarifies the
distinction between running a Teleport process and running services on
the process.
* Respond to zmb3 feedback
* Respond to alexfornuto feedback
* Improve the "Join Token" guide descriptionA
Makes this guide consistent with
df3e36e49e
* Move the Kubernetes guide
* Fix spelling
* Linter fixes
* Default headless to --mlock=best_effort to reduce errors to a debug
log.
* Add error for non-linux operating systems using headless.
* Add a better mlock error message and add corresponding troubleshooting
docs.
In gravitational/docs#238, we will add a linter that lints for incorrect
usage of Teleport terms. This change fixes linter violations to
anticipate this new linter.
Changes include:
- Ensuring that Teleport service names are capitalized
- No longer using the "[Resource] Access" terminology. Instead, talk
about adding resources, using Teleport services, etc.
* Support spellchecking in docs content
In gravitational/docs#261, we will add a script that checks the spelling
of each version of the docs. This change edits one version of the docs
content to support this, including:
- A cspell configuration file
- A new step in the GitHub Actions in the "Lint (Docs)" workflow that
runs the spellcheck script we will add in `gravitational/docs`
- Fix mispellings so this passes the lint job. The mispellings are in a
file that we generated automatically, but there are few enough of
them, and we haven't merged the auto-generation script yet, that I
think it makes sense to fix them in the generated file for now.
* Respond to PR feedback
- Remove misspellings from the ignore list
- Sort the ignore list (and format it via prettier)
* Use the new yarn spellcheck command
* Spelling fixes
* spell fixes and add words to cspell.json
---------
Co-authored-by: Steven Martin <steven@goteleport.com>
Paul Gottschling