Include inlining the partial:
docs/pages/includes/machine-id/recover-circle-ci-claims.mdx
This is because it's only used by two pages and, as a partial, violates
the rule in which each Var with a given name must be used multiple
times on a single page. Since this Vale rule uses the `raw` scope, it is
not possible to ignore it with an MDX comment.
See gravitational/docs-website#91
Docusaurus uses semantic HTML tags instead of a custom Details
component. Replace instances of our Details component with the
`<details>` and `<summary>` tags so we do not need to perform a
conversion when building the docs website.
Closesgravitational/docs-website#70
`Tabs` components that use a dropdown menu do not render on the
Docusaurus site. Since there are not many of these in the docs content,
it makes sense to change them to standard `Tabs` components instead of
porting the legacy `Tabs` behavior to the new Docusaurus site.
- Change long picker partials to use a standard `Tabs` component instead
of a dropdown menu. While this is not ideal, it standardizes the
`Tabs` component in the docs to only use attributes that the docs
engine can process. All `TabItems` render as expected.
- Remove an unused partial that uses two-dimensional `Tabs`
(`docs/pages/includes/install-linux-self-hosted.mdx`).
- In some guides, collapse two-dimensional `Tabs` components to only
require one dimension.
- In `install-linux-enterprise.mdx`, use the one-line installation
script to simplify the instructions and avoid using `Tabs` entirely.
See gravitational/docs-website#95
The docs engine currently unwraps them, meaning that they are no-op
components. Remove these so we can delete the Figure-unwrapping code.
Use Docusaurus syntax for admonitions so the docs engine does not need
to replace these. This is one step toward removing the
`remark-update-tags` plugin. See: gravitational/docs-website#94
Relevant commands are included below to make reproducing this work
easier.
1. Replace all `Notice` tags with `Admonition` tags.
2. Add `type="info"` if an Admonition is missing a type.
To find instances:
```
find docs/pages -name "*.mdx" -exec awk '
BEGIN{a=0}
a==0 && /<Admonition/{ a = 1 }
a==1 && /type/{t = 1}
a==1 && />/{ a = 0; if(t == 0) print FILENAME ":" FNR }' {} \;
```
3. Replace `type="notice"` with `type="note"`.
To find instances:
```
find docs/pages -name "*.mdx" -exec awk '
BEGIN{a=0}
a==0 && /<Admonition/{ a = 1 }
a==1 && /type="notice"/{t = 1}
a==1 && />/{ a = 0; if(t == 1) print FILENAME ":" FNR }' {} \;
```
* Remove v13 mentions in the docs
Our policy is to remove mentions of the version prior to the most recent
deprecated version.
This change includes mentions of v13 in Helm chart values file comments.
* Clarify distroless images in Helm values
Responds to hugoShaka feedback.
Closes#47068
The TTL shown in a `tctl auth sign` command does not correspond to the
description of the TTL. Fix the description while making the TTL an
integer divisible by 24.
One edge case is the `structure.architecture-h2` warning in
`docs/pages/includes/database-access/rds-proxy.mdx`. This is technically
correct, since the "How it works" section is before the "Prerequisites"
section. We can determine whether this is a bug to fix in a separate
change.
* Docs: add discovery_group to teleport.yaml/discovery_service examples
When the discovery_group is not configured, teleport will log a warning
message saying that it is recommended.
Some configuration examples do not include it, so when users use that
example to implement their own variation, it will output a warning
message.
After seeing that warning users might wonder if there's anything wrong
with their `teleport.yaml`.
Instead, we add a discovery_group to all examples so that users don't
get that message.
* explain discovery group
* use partial instead
Docusaurus [sidebar
generation](https://docusaurus.io/docs/next/sidebar/autogenerated)
expects category index pages to have one of three file path conventions:
- `section/index.mdx`
- `section/README.mdx`
- `section/section.mdx`
This change standardizes category index paths on the third convention so
Docusaurus sidebar generation succeeds. We can then add checks to the
current docs site to prevent additional menu pages from violating this
convention.
This change also adds redirects to the new category index pages, and
updates internal links to pages that were moved.
Note that this change does not move all relevant menu pages. We still
need to reorganize the `reference/terraform-provider` section. Since
this section is automatically generated, we need another approach to
restructuring it.
Closes#38931
Remove "Static" and "Dynamic" configuration branching. Use the dynamic
approach unless the guide already shows readers how to use the static
approach elsewhere, e.g., using `teleport db configure create`.
For example, in the AWS OpenSearch guide, creating a Teleport
configuration is required for the guide anyway, so this change uses only
the static approach.
Ignore edge cases where the branching has some qualities that are unique
to a specific guide:
- `application-access/cloud-apis/google-cloud.mdx`: includes branching
on authentication preference type.
- `application-access/guides/connecting-apps.mdx` because it explains
syntax differences between the static and dynamic approaches.
- `enroll-aws-databases/aws-cross-account.mdx`: branches using three
tabs, so editing requires another approach than the one this change
applies.
This change edits only how-to guides, not conceptual guides, since the
goal of a how-to guide is to get the user to an end state as quickly as
possible.
* docs: use code instead of shell
* docs: revert generated file
* docs: update shell styling for generated file
---------
Co-authored-by: Steven Martin <stevenmartin@Stevens-MBP.fios-router.home>
* A handful of smaller fixes.
* Oracle Exadata guide.
* Apply suggestions from code review
Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com>
* Apply suggestions from code review
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
* Reorganise, update doc.
* Update docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/oracle-exadata.mdx
Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com>
* Update docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/oracle-exadata.mdx
Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com>
* A few minor corrections and clarifications.
* Move to 'managed databases' from 'self-hosted'.
* Update index page.
* include intro for non-self-hosted dbs
* extend cspell.json with extra random words
* Fix lint warnings which are treated as errors.
---------
Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com>
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
* docs: update desktop access getting started
* docs: restore diff for section
* docs: remove variables from diff sections
---------
Co-authored-by: Steven Martin <stevenmartin@Stevens-MBP.fios-router.home>
* delete the bootstrap docs partial file
* for redshift-serverless guide specifically:
- the user role's trust policy does not need to include ec2
- fix the title to use Amazon instead of AWS
- rename the IAM role to better indicate its purpose
- clarify which database service we are referring to
Provide a less overwhelming documentation experience for users by
condensing sidebar sections into five, organized loosely around
different audiences of the documentation:
- **Get Started:** new Teleport users, as well as users of all levels
who want to quickly look up key, frequently changing information, such
as the changelog and upcoming release information.
- **Admin Guides:** intermediate users completing a specific task. This
includes all how-to guides in the docs except those in "Get Started"
and "Enroll Resources".
- **Enroll Resources:** Admin Guides, but for our extensive library of
how-to guides for protecting infrastructure resources with Teleport.
- **References:** Advanced users looking for comprehensive reference
information and architecture guides. This includes all reference
guides in the docs.
- **User Guides:** Guides for end users looking to access resources.
Related changes:
- **Move Helm reference partials**. Use the `docs/pages/includes`
directory so we can generate the sidebar from `docs/pages/reference`.
- **Move the Architecture sidebar section** into "References", and move
architecture guides across the documentation into "Architecture".
- **Remove "Documentation Overview"** as this is out of date. Now, top-level
sidebar sections are more self explanatory.
- **Remove "Choose an Edition"**, since we want to elevate Teleport
Enterprise (Cloud), making Teleport Enterprise (Self-Hosted) available
for certain use cases.
- **Add an infrastructure as code section** to Admin Guides.
* DocumentDB guide
* update diagrams and add screenshots
* fix img link
* review comments
* address comments from Paul
* add docdb and sasl to spelling
* move the discovery/database service permissions into partials
* replace the dynamic IAM permissions setup with simple permissions
* add a reference section for the discovery service
* remove details wrappers from IAM role trust setup partial
The number of sections on the left sidebar makes the documentation
difficult to navigate. This change reduces the number of sidebar
sections by creating an "Enroll Resources" section from sidebar sections
related to protecting infrastructure resources with Teleport.
This change configures the sidebar for the Enroll Resources section to
be automatically generated. Since the generator expects each
subdirectory of a section to have a corresponding table of contents
page, this change also adds missing table of contents pages.
In some cases, we can repurpose an existing section introduction page
for a section's table of contents page. In other cases, the introduction
spends too much time on providing context to make for a useful table of
contents, so this change adds a separate table of contents page. Table
of contents pages use the `(!toc!)` syntax to list links automatically
based on the file system.
This change also adds redirects based on mentions of Teleport docs URLs
in the Web UI source, and removes all other redirects to avoid exceeding
the maximum number of routes in Vercel.
* add discovery tip partial in database guides
* Update docs/pages/includes/database-access/auto-discovery-tip.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Break up /database-access/guides/
Closes#17641
Organize the guides to enrolling databases in specific cloud providers
(or self-hosted databases) into separate subsections of the "Database
Actions" section, organized by cloud provider (or self-hosted).
We can later add general information to the index page of each
subsection about how Teleport database access works for each cloud
provider. The remaining guides in the "Guides" subsection have to do
with database-agnostic functionality of the Teleport Database Service.
This change also adds a redirect for each page it moves.
* Respond to greedy52 feedback
- In the "Database Access" intro page, move the self-hosted section
first in the list of links to database-specific guides so it's less
easy to miss.
- Change "AWS" to "Amazon" in product names.
* Fix linter issues
* Remove redirects added by the DB guide reorg
This prevents us from running into Vercel route limit issues, since the
number of redirects is large.
* Add own-CA instructions to self-hosted DB guides
Closes#14728
In guides where we show how to configure Teleport to protect a
self-hosted database that uses mTLS to communicate with the Database
Service, show how to configure the Database Service to trust a custom
CA.
This includes the following self-hosted database guides:
- Postgres
- Vitess
- MySQL
- Elasticsearch
- ClickHouse
- Standalone Redis
- Standalone MongoDB
- Cassandra/Scylla
- Oracle
This change does not touch guides that:
- Already include instructions to configure the Database Service to
trust a custom CA via the `ca_cert_file` config field, e.g., the
CockroachDB and Redis cluster guides.
- Use a different authentication mechanism, e.g., the SQL Server PKINIT
guide.
* Respond to feedback
- Change `db-client` to `db_client` in commands beside `tctl auth
export`. (greedy52)
- Use consistent Proxy Service example addresses in the Clickhouse
guide. (Tener)
- Fix wording around the function of a CA. (GavinFrazar)
- Clarify remote `tctl` permissions in partials. (GavinFrazar)
- Clarify the need for `Db` impersonation privileges. (GavinFrazar)
* Update docs/pages/includes/database-access/self-hosted-introduction.mdx
Co-authored-by: Gavin Frazar <gavin.frazar@goteleport.com>
* Respond to greedy52 feedback
- Edit `tctl-auth-sign-3-files.mdx` to instruct the user to append the
database client CA to your database's existing cert file.
- Use Tabs for tctl-auth-sign-3-files.mdx
---------
Co-authored-by: Gavin Frazar <gavin.frazar@goteleport.com>
* [docs] Update DB access AWS IAM reference page
* add other aws databases
* reword and fix a few spots
* remove please and add the for service
* address review coments
* fix spelling
* fix link
* Add architectural information to database guides
Closes#21540
Rather than attempt to describe the entirety of the database access
architecture in the `/docs/database-access/architecture/` guide, this
change:
- Edits the architecture guide to clarify that authentication between
the Teleport Database Service and each proxied database depends on the
database.
- Adds a "How it works" H2 before the "Prerequisites" H2 of each how-to
guide for accessing a specific database, describing the architecture
of the setup shown in the guide.
* Respond to greedy52 feedback
- Correct the DynamoDB and OpenSearch architecture descriptions.
- Correct the AWS Redis architecture description by moving a description
from later in the page. Also adds Redis ACL to the prerequisites.
- Edit the Azure Cache for Redis and Azure MySQL and PostgreSQL guides
to say "Microsoft Entra ID" in the architecture section. This change
does not attempt to correct "Azure AD" elsewhere in the guides, as
this entails fixing UI instructions that are outside the scope of the
PR.
* Remove auto-discovery from specific DB guides
Closes#22942
Help users enroll specific databases with Teleport while directing them
auto-discovery instructions if they want to go that route.
- Revert #30913 for guides to enrolling specific databases. For guides
that always included auto-discovery instructions, add instructions to
enroll databases at specific URLs.
- Add a note in the introduction sections of AWS guides that it is
possible to enroll AWS databases with auto-discovery, linking to the
relevant guide.
* Respond to greedy52 feedback
- Remove auto-discovery notes where they are incorrect.
- Remove unneeded `id` flags.
- Use `teleport db configure create` for Redshift Serverless, removing
unneeded config fields. Also add the `aws-bootstrap.mdx` partial to
the Redshift Serverless guide, making it more consistent with other
guides that include `teleport db configure bootstrap` instructions.
- Minor spelling/grammar tweaks.
- Fix example description outputs.
- Use URI/protocol flags in `rds-proxy.mdx` instructions.
- Restore `opensearch` to `database-config.yaml`.
* Respond to greedy52 feedback
- Add the `--name` parameter to `db configure create`
- Edit `tsh db ls` output in the RDS guide
* Fix linter issues
Marco Dinis