Consolidate Reference docs section contents (#59082)

Backports #58248

* Consolidate Reference docs section contents

Closes #56206

Reduce the number of first-level children in the Reference section of
the docs from 23 to 9, not counting the index page available at
`/docs/reference/`. This makes the Reference section easier to navigate,
since a user can more readily form a mental model of the content
available in the section with fewer items and a more thematic
organization.

- Add a section for deployment references, consolidating reference
  guides for configuring and architecting a Teleport deployment.
- Move the Predicate Language and User Types references into the Access
  Controls section of References.
- Add a section for API reference guides, consolidating the Terraform,
  MWI Terraform, and Operator sections.
- Move Cloud FAQ to Quick Links. This places the guide next to the main
  FAQ in the sidebar to make it more discoverable, since the guide is
  currently rather hidden. This also helps pave the way to merge the two
  FAQs in the future.

* Add an MWI reference section

The MWI Terraform module reference does not belong with reference guides
for API clients. Add a section to the reference guide for Machine &
Workload Identity.

* Rename "API" to "Infrastructure as Code"

Teleport users expect tctl, Operator, and Terraform Provider docs to be
in an Infrastructure as Code reference section, rather than the more
vague "API" section.

Responds to **ravicious** feedback.

Author: ptgott

CHANGELOG.md

@@ -745,3 +745,4 @@ or `alpn-ping` as upgrade types was left as a fallback until v17.
 
 Teleport v18 removes the legacy upgrade mode entirely including the use of the
 `TELEPORT_TLS_ROUTING_CONN_UPGRADE_MODE` environment variable.
+

docs/config.json

@@ -1118,8 +1118,8 @@
     "hte"
   ],
   "ignorePaths": [
-    "**/reference/terraform-provider/**",
-    "**/reference/operator-resources/**",
+    "**/reference/infrastructure-as-code/terraform-provider/**",
+    "**/reference/infrastructure-as-code/operator-resources/**",
     "**/includes/reference/code-blocks-no-cspell/**"
   ]
 }

docs/cspell.json

@@ -9,7 +9,7 @@ tags:
 
 This page provides answers to frequently asked questions about Teleport
 Enterprise (Cloud). For a list of frequently asked questions about Teleport in
-general, see [Frequently Asked Questions](../faq.mdx).
+general, see [Frequently Asked Questions](faq.mdx).
 
 ## Billing and usage
 
@@ -29,7 +29,7 @@ If you plan to use S3 and DynamoDB as storage backends, we can provide data for
 
 ### How long will Teleport Enterprise Cloud retain my data?
 
-See our documentation on [data retention](architecture/teleport-cloud-architecture.mdx).
+See our documentation on [data retention](reference/architecture/teleport-cloud-architecture.mdx).
 
 ### Is an independent security audit available?
 
@@ -51,18 +51,18 @@ for customer data including session recordings and user records.
 
 ### Can I get a list of IP addresses that my infrastructure will need to allow connections to?
 
-See the [Public IP Address Allowlist](../ips.mdx) for the list of IP addresses used for inbound connections to Teleport Enterprise Cloud.
+See the [Public IP Address Allowlist](ips.mdx) for the list of IP addresses used for inbound connections to Teleport Enterprise Cloud.
 
 ### Can I configure a list of IP addresses which are allowed to connect to Teleport Enterprise Cloud?
 
 We do not have plans to offer support for inbound connection IP allowlists.
 
-We believe mTLS with strong user and [device identity](../identity-governance/device-trust/guide.mdx) provides the best available
+We believe mTLS with strong user and [device identity](identity-governance/device-trust/guide.mdx) provides the best available
 security for client authentication.
 
 For customers that require IP-based control for compliance purposes, we do
 support IP Pinning. For more information see `pin_source_ip` in our [Teleport
-Access Controls Reference](access-controls/roles.mdx).
+Access Controls Reference](reference/access-controls/roles.mdx).
 
 ### Are internal connections encrypted / authenticated?
 
@@ -74,7 +74,7 @@ S3, are established using encryption provided by AWS, both at rest and in transi
 
 You can connect servers, Kubernetes clusters, databases, desktops, and
 applications using [reverse
-tunnels](../enroll-resources/agents/agents.mdx).
+tunnels](enroll-resources/agents/agents.mdx).
 
 There is no need to open any ports on your infrastructure for inbound traffic.
 
@@ -88,7 +88,7 @@ If you plan on connecting more than 10,000 nodes or agents, please contact your
 ### Are dynamic node tokens available?
 
 After [connecting](#how-can-i-access-the-tctl-admin-tool) `tctl` to Teleport Enterprise Cloud, users can generate
-[dynamic tokens](../enroll-resources/agents/join-token.mdx):
+[dynamic tokens](enroll-resources/agents/join-token.mdx):
 
 ```code
 $ tctl nodes add --ttl=5m --roles=node,proxy --token=$(uuid)
@@ -98,7 +98,7 @@ $ tctl nodes add --ttl=5m --roles=node,proxy --token=$(uuid)
 
 ### How can I access the `tctl` admin tool?
 
-Find the appropriate download at [Installation](../installation/installation.mdx).
+Find the appropriate download at [Installation](installation/installation.mdx).
 
 After downloading the tools, first log in to your cluster using `tsh`, then use `tctl` remotely:
 
@@ -120,11 +120,11 @@ $ tctl tokens add --type=node
 
 ### Is there a way to forward Teleport Enterprise Cloud audit events to my company's internal Security Information and Event Management (SIEM)?
 
-Yes. We recommend Teleport's [event handler plugin](../zero-trust-access/export-audit-events/fluentd.mdx) to export Teleport Enterprise Cloud audit events.
+Yes. We recommend Teleport's [event handler plugin](zero-trust-access/export-audit-events/fluentd.mdx) to export Teleport Enterprise Cloud audit events.
 
 ### Is it possible to store audit logs and session recordings in my own S3 bucket?
 
-Yes, you can configure [External Audit Storage](../zero-trust-access/management/external-audit-storage.mdx).
+Yes, you can configure [External Audit Storage](zero-trust-access/management/external-audit-storage.mdx).
 
 ### Is it possible to enable proxy recording mode?
 
@@ -141,12 +141,12 @@ The ability to download recordings for offline viewing will be available in a fu
 If you have Teleport Agents connected to a Teleport Enterprise Cloud cluster
 that are more than one major version behind, you might experience compatibility
 issues unless your Teleport Agents are enrolled in automatic updates. See the [Upgrading
-Overview](../upgrading/overview.mdx) for more information.
+Overview](upgrading/overview.mdx) for more information.
 
 To get version information for your Teleport Agents, see [How can I find version information on
 connected agents?](#how-can-i-find-version-information-on-connected-agents).
 
-If you want more details about cluster updates, see [Cloud Cluster Updates](../upgrading/cloud-cluster-updates.mdx).
+If you want more details about cluster updates, see [Cloud Cluster Updates](upgrading/cloud-cluster-updates.mdx).
 
 For more information about automatic updates and compatibility issues, contact
 [Teleport support](https://goteleport.com/support/).
@@ -165,7 +165,7 @@ connected agents?](#how-can-i-find-version-information-on-connected-agents) for
 
 ### Are updates times configurable for Teleport Enterprise Cloud?
 
-Yes, see [Cloud Cluster Updates](../upgrading/cloud-cluster-updates.mdx#maintenance-windows) for further instruction.
+Yes, see [Cloud Cluster Updates](upgrading/cloud-cluster-updates.mdx#maintenance-windows) for further instruction.
 
 ### When are agents automatically updated?
 
@@ -177,7 +177,7 @@ update the software when new versions are found.
 If you enroll in automatic agent updates, Teleport Agents are automatically
 updated after your Teleport cluster is updated during your scheduled maintenance
 period. For more information, read the [Automatic Agent
-Updates](../upgrading/agent-managed-updates.mdx) guide.
+Updates](upgrading/agent-managed-updates.mdx) guide.
 
 ### How can I find version information on connected agents?
 
@@ -239,7 +239,7 @@ than through a port allocated to that service.
 In this case, you can see that TLS routing is enabled, and that the Proxy
 Service's public web address (`ssh.public_addr`) is `example.teleport.sh:443`.
 
-Read more in our [TLS Routing](architecture/tls-routing.mdx) guide.
+Read more in our [TLS Routing](reference/architecture/tls-routing.mdx) guide.
 
 ### How does Teleport manage web certificates? Can I upload my own?
 
@@ -250,7 +250,7 @@ certificate or use a custom domain name.
 ### Where does Teleport Enterprise Cloud run?
 
 Teleport Cloud runs on Amazon Web Services (AWS). We run proxies in a variety
-of regions all over the world, and allow customers to [select the region](architecture/teleport-cloud-architecture.mdx) where the data is stored.
+of regions all over the world, and allow customers to [select the region](reference/architecture/teleport-cloud-architecture.mdx) where the data is stored.
 
 ### Are you using AWS-managed encryption keys, or CMKs via KMS?
 
@@ -260,7 +260,7 @@ We use AWS-managed keys. Currently there is no option to provide your own key.
 
 It's a Teleport-managed S3 bucket with AWS-managed keys by default.
 
-Configuring [External Audit Storage](../zero-trust-access/management/external-audit-storage.mdx) will allow
+Configuring [External Audit Storage](zero-trust-access/management/external-audit-storage.mdx) will allow
 you to use your own S3 bucket.
 
 ### Is IPv6 Supported for connections to Teleport Enterprise Cloud?
@@ -315,7 +315,7 @@ When you sign up for a Teleport Enterprise (Cloud) account and set up your first
 user within the account, the Teleport Web UI displays a set of recovery codes:
 
 ![Web UI view showing Teleport recovery
-codes](../../img/cloud/recovery-codes.png)
+codes](../img/cloud/recovery-codes.png)
 
 Save the recovery codes into a safe location, such as your organization's
 password manager. You can use these codes to reset your account if you lose

docs/pages/reference/cloud-faq.mdx renamed to docs/pages/cloud-faq.mdx

@@ -1136,7 +1136,7 @@ proxy_templates:
 In the configuration above, `query` accepts an predicate expression.  This has
 priority over search but will be ignored if a host is provided.  See the
 [predicate language
-documentation](../reference/predicate-language.mdx#resource-filtering) for
+documentation](../reference/access-controls/predicate-language.mdx#resource-filtering) for
 predicate expression examples.
 
 `tsh -J {{proxy}} ssh` and `tsh -J {{proxy}} proxy ssh` will attempt to match the

docs/pages/connect-your-client/tsh.mdx

@@ -194,7 +194,7 @@ A **configuration resource** is a document stored on the **Teleport Auth
 Service** backend that specifies settings for your **Teleport cluster**.
 Examples include **roles**, **local users**, and **authentication connectors**
 
-Read more in our [resource reference](./reference/resources.mdx).
+Read more in our [resource reference](reference/infrastructure-as-code/resources.mdx).
 
 ### Role
 

docs/pages/core-concepts.mdx

@@ -253,9 +253,9 @@ While this guide shows you how to create a token using `tctl`, you can also
 manage tokens using the Teleport Terraform provider or Kubernetes operator. See
 the following documentation for information on the token resource:
 - [Terraform
-  provider](../../reference/terraform-provider/resources/provision_token.mdx)
+  provider](../../reference/infrastructure-as-code/terraform-provider/resources/provision_token.mdx)
 - [Kubernetes
-  operator](../../reference/operator-resources/resources-teleport-dev-provisiontokens.mdx)
+  operator](../../reference/infrastructure-as-code/operator-resources/resources-teleport-dev-provisiontokens.mdx)
 
 You can set up a system to automate the process of assigning join tokens to
 agents, ensuring that all Teleport services you run have the correct join

docs/pages/enroll-resources/agents/add-service-to-agent.mdx

@@ -151,7 +151,7 @@ Here's how it works in detail:
 
 For more information about Discovery Service configuration, refer to
 [one of the guides above](#supported-clouds) or the
-[Discovery Service Config File Reference](../../../reference/config.mdx).
+[Discovery Service Config File Reference](../../../reference/deployment/config.mdx).
 
 ## How the Database Service works
 

docs/pages/enroll-resources/auto-discovery/databases/databases.mdx

@@ -314,4 +314,4 @@ logs can be found on the targeted VM at
 - Read [Joining Nodes via Azure Managed Identity](../../agents/azure.mdx)
   for more information on Azure tokens.
 - Full documentation on Azure discovery configuration can be found through the [
-  config file reference documentation](../../../reference/config.mdx).
+  config file reference documentation](../../../reference/deployment/config.mdx).

docs/pages/enroll-resources/auto-discovery/servers/azure-discovery.mdx

@@ -304,4 +304,4 @@ for details on alternate methods.
 - Read [Joining Services via GCP](../../agents/gcp.mdx)
   for more information on GCP tokens.
 - Full documentation on GCP discovery configuration can be found through the [
-  config file reference documentation](../../../reference/config.mdx).
+  config file reference documentation](../../../reference/deployment/config.mdx).