Reorganize Machine ID guides (#42797)

This change moves most Machine ID guides into Admin Guides. Some guides
belong in the References section:

- Architecture
- FAQ
- The "Reference" subsection of Machine ID.

This change also renames the Machine ID Access Guides section. This is a
workaround to get this subsection to appear after the deployment guide
section in the table of contents.

docs/pages/admin-guides.mdx

@@ -31,6 +31,7 @@ Guides for enrolling servers, databases, and other infrastructure resources with
 
 - [AWS OIDC Integration](admin-guides/protect-resources/awsoidc-integration.mdx): How to connect your AWS account with Teleport and provide access to AWS resources.
 - [Automatically Enroll Infrastructure Resources (section)](admin-guides/protect-resources/auto-discovery.mdx): Learn how to use the Teleport Discovery Service, which automatically enrolls resources by query APIs
+- [Machine ID (section)](admin-guides/protect-resources/machine-id.mdx): Provide service accounts and automated systems with secure access to resources in your infrastructure.
 - [Protect Applications with Teleport (section)](admin-guides/protect-resources/application-access.mdx): How to enroll applications with your Teleport cluster for secure access
 - [Protect Databases with Teleport (section)](admin-guides/protect-resources/database-access.mdx): How to enrolls databases in your Teleport cluster.
 - [Protect Linux Servers with Teleport (section)](admin-guides/protect-resources/server-access.mdx): How to enroll Linux servers in your Teleport cluster to enable secure SSH access.

docs/pages/admin-guides/protect-resources.mdx

@@ -27,6 +27,18 @@ Learn how to use the Teleport Discovery Service, which automatically enrolls res
 - [Enroll Kubernetes Services as Teleport Applications (section)](protect-resources/auto-discovery/kubernetes-applications.mdx): Teleport can automatically detect applications running in your Kubernetes clusters and register them with Teleport for secure access.
 - [Server Auto-Discovery (section)](protect-resources/auto-discovery/servers.mdx): You can set up the Teleport Discovery Service to automatically enroll servers in your infrastructure.
 
+## Machine ID
+
+Provide service accounts and automated systems with secure access to resources in your infrastructure. ([more info](protect-resources/machine-id.mdx))
+
+- [Machine ID Deployment Guides (section)](protect-resources/machine-id/deployment.mdx): Guides to running Machine ID on various systems and CI/CD platforms.
+- [Machine ID Getting Started Guide](protect-resources/machine-id/getting-started.mdx): Getting started with Teleport Machine ID
+- [Machine ID Introduction](protect-resources/machine-id/introduction.mdx): Teleport Machine ID introduction, demo and resources.
+- [Machine ID Manifesto](protect-resources/machine-id/manifesto.mdx): A manifesto for Machine Identity
+- [Machine ID Troubleshooting Guide](protect-resources/machine-id/troubleshooting.mdx): Troubleshooting common issues with Machine ID
+- [Use Machine ID to Access your Infrastructure (section)](protect-resources/machine-id/access-guides.mdx): How to use Machine ID to enable secure access to Teleport resources.
+- [Workload Identity (section)](protect-resources/machine-id/workload-identity.mdx): Guides to Teleport Workload Identity, which issues flexible, short-lived identities to secure workload-to-workload communications.
+
 ## Protect Applications with Teleport
 
 How to enroll applications with your Teleport cluster for secure access ([more info](protect-resources/application-access.mdx))

docs/pages/machine-id.mdx → docs/pages/admin-guides/protect-resources/machine-id.mdx

@@ -5,25 +5,11 @@ description: Provide service accounts and automated systems with secure access t
 
 {/*TOPICS*/}
 
-- [Machine ID Architecture](machine-id/architecture.mdx): How Teleport Machine ID works.
-- [Machine ID FAQ](machine-id/faq.mdx): Frequently asked questions about Teleport Machine ID
 - [Machine ID Getting Started Guide](machine-id/getting-started.mdx): Getting started with Teleport Machine ID
 - [Machine ID Introduction](machine-id/introduction.mdx): Teleport Machine ID introduction, demo and resources.
 - [Machine ID Manifesto](machine-id/manifesto.mdx): A manifesto for Machine Identity
 - [Machine ID Troubleshooting Guide](machine-id/troubleshooting.mdx): Troubleshooting common issues with Machine ID
 
-## Access your Infrastructure with Machine ID
-
-How to use Machine ID to enable secure access to Teleport resources. ([more info](machine-id/access-guides.mdx))
-
-- [Machine ID with Ansible](machine-id/access-guides/ansible.mdx): How to use Machine ID with Ansible
-- [Machine ID with Application Access](machine-id/access-guides/applications.mdx): How to use Machine ID to access applications
-- [Machine ID with Database Access](machine-id/access-guides/databases.mdx): How to use Machine ID to access database servers
-- [Machine ID with Kubernetes Access](machine-id/access-guides/kubernetes.mdx): How to use Machine ID to access Kubernetes clusters
-- [Machine ID with Server Access](machine-id/access-guides/ssh.mdx): How to use Machine ID to access servers via SSH
-- [Machine ID with tctl](machine-id/access-guides/tctl.mdx): How to use Machine ID with tctl to manage your Teleport configuration
-- [Machine ID with the Teleport Terraform Provider](machine-id/access-guides/terraform.mdx): How to use Machine ID with the Teleport Terraform provider to manage your Teleport configuration as IaC
-
 ## Machine ID Deployment Guides
 
 Guides to running Machine ID on various systems and CI/CD platforms. ([more info](machine-id/deployment.mdx))
@@ -41,17 +27,17 @@ Guides to running Machine ID on various systems and CI/CD platforms. ([more info
 - [Deploying Machine ID on Spacelift](machine-id/deployment/spacelift.mdx): How to install and configure Machine ID on Spacelift
 - [Machine ID Deployment Overview](machine-id/deployment/overview.mdx): Explains how to deploy Machine ID on your platform and join it to your Teleport cluster.
 
-## Machine ID Reference
+## Use Machine ID to Access your Infrastructure
 
-Configuration and CLI reference for Teleport Machine ID. ([more info](machine-id/reference.mdx))
+How to use Machine ID to enable secure access to Teleport resources. ([more info](machine-id/access-guides.mdx))
 
-- [Diagnostics Service](machine-id/reference/diagnostics-service.mdx): Reference information for the `tbot` diagnostics service.
-- [GitHub Actions](machine-id/reference/github-actions.mdx): Reference for GitHub Actions joining
-- [GitLab CI](machine-id/reference/gitlab.mdx): Reference for GitLab joining
-- [Machine ID Configuration Reference](machine-id/reference/configuration.mdx): Configuration reference for Teleport Machine ID.
-- [Machine ID v14 Upgrade Guide](machine-id/reference/v14-upgrade-guide.mdx): Upgrade instructions for Machine ID in Teleport 14.0
-- [Machine ID v16 Upgrade Guide](machine-id/reference/v16-upgrade-guide.mdx): Upgrade instructions for Machine ID in Teleport 16.0
-- [Telemetry](machine-id/reference/telemetry.mdx): An explanation of the telemetry collected by Machine ID
+- [Machine ID with Ansible](machine-id/access-guides/ansible.mdx): How to use Machine ID with Ansible
+- [Machine ID with Application Access](machine-id/access-guides/applications.mdx): How to use Machine ID to access applications
+- [Machine ID with Database Access](machine-id/access-guides/databases.mdx): How to use Machine ID to access database servers
+- [Machine ID with Kubernetes Access](machine-id/access-guides/kubernetes.mdx): How to use Machine ID to access Kubernetes clusters
+- [Machine ID with Server Access](machine-id/access-guides/ssh.mdx): How to use Machine ID to access servers via SSH
+- [Machine ID with tctl](machine-id/access-guides/tctl.mdx): How to use Machine ID with tctl to manage your Teleport configuration
+- [Machine ID with the Teleport Terraform Provider](machine-id/access-guides/terraform.mdx): How to use Machine ID with the Teleport Terraform provider to manage your Teleport configuration as IaC
 
 ## Workload Identity
 

docs/pages/machine-id/access-guides.mdx → docs/pages/admin-guides/protect-resources/machine-id/access-guides.mdx

@@ -1,5 +1,5 @@
 ---
-title: Access your Infrastructure with Machine ID
+title: Use Machine ID to Access your Infrastructure
 description: How to use Machine ID to enable secure access to Teleport resources.
 layout: tocless-doc
 ---

docs/pages/reference.mdx

@@ -11,9 +11,22 @@ Contains guides to frequently asked questions for various Teleport features and
 
 - [Database Access FAQ](reference/faq/database-access.mdx): Frequently asked questions about Teleport database access.
 - [Kubernetes Access FAQ](reference/faq/kubernetes-access.mdx): Frequently asked questions about Teleport Kubernetes Access
+- [Machine ID FAQ](reference/faq/machine-id.mdx): Frequently asked questions about Teleport Machine ID
 - [Teleport Enterprise Cloud FAQ](reference/faq/cloud-hosting.mdx): Teleport cloud frequently asked questions.
 - [Teleport FAQ](reference/faq/faq.mdx): Frequently Asked Questions About Using Teleport
 
+## Machine ID Reference
+
+Configuration and CLI reference for Teleport Machine ID. ([more info](reference/machine-id.mdx))
+
+- [Diagnostics Service](reference/machine-id/diagnostics-service.mdx): Reference information for the `tbot` diagnostics service.
+- [GitHub Actions](reference/machine-id/github-actions.mdx): Reference for GitHub Actions joining
+- [GitLab CI](reference/machine-id/gitlab.mdx): Reference for GitLab joining
+- [Machine ID Configuration Reference](reference/machine-id/configuration.mdx): Configuration reference for Teleport Machine ID.
+- [Machine ID v14 Upgrade Guide](reference/machine-id/v14-upgrade-guide.mdx): Upgrade instructions for Machine ID in Teleport 14.0
+- [Machine ID v16 Upgrade Guide](reference/machine-id/v16-upgrade-guide.mdx): Upgrade instructions for Machine ID in Teleport 16.0
+- [Telemetry](reference/machine-id/telemetry.mdx): An explanation of the telemetry collected by Machine ID
+
 ## Operational Reference Guides
 
 References for concepts and tools available for operating Teleport. ([more info](reference/operations.mdx))
@@ -45,6 +58,7 @@ Guides to the inner workings of components within a Teleport cluster. ([more inf
 
 - [API Architecture](reference/architecture/architecture.mdx): Architectural overview of the Teleport gRPC API.
 - [Agent Update Management](reference/architecture/agent-update-management.mdx): This chapter explains how Teleport agent automatic update is working.
+- [Machine ID Architecture](reference/architecture/machine-id.mdx): How Teleport Machine ID works.
 - [Proxy Peering](reference/architecture/proxy-peering.mdx): How Teleport implements more efficient networking with Proxy Peering.
 - [TLS Routing](reference/architecture/tls-routing.mdx): How Teleport implements a single-port setup with TLS routing
 - [Teleport Agent Architecture](reference/architecture/agents.mdx): Describes the architecture that enables Teleport to securely proxy client traffic to infrastructure resources.

docs/pages/reference/architecture.mdx

@@ -7,6 +7,7 @@ description: Guides to the inner workings of components within a Teleport cluste
 
 - [API Architecture](architecture/architecture.mdx): Architectural overview of the Teleport gRPC API.
 - [Agent Update Management](architecture/agent-update-management.mdx): This chapter explains how Teleport agent automatic update is working.
+- [Machine ID Architecture](architecture/machine-id.mdx): How Teleport Machine ID works.
 - [Proxy Peering](architecture/proxy-peering.mdx): How Teleport implements more efficient networking with Proxy Peering.
 - [TLS Routing](architecture/tls-routing.mdx): How Teleport implements a single-port setup with TLS routing
 - [Teleport Agent Architecture](architecture/agents.mdx): Describes the architecture that enables Teleport to securely proxy client traffic to infrastructure resources.

docs/pages/reference/faq.mdx

@@ -7,5 +7,6 @@ description: Contains guides to frequently asked questions for various Teleport
 
 - [Database Access FAQ](faq/database-access.mdx): Frequently asked questions about Teleport database access.
 - [Kubernetes Access FAQ](faq/kubernetes-access.mdx): Frequently asked questions about Teleport Kubernetes Access
+- [Machine ID FAQ](faq/machine-id.mdx): Frequently asked questions about Teleport Machine ID
 - [Teleport Enterprise Cloud FAQ](faq/cloud-hosting.mdx): Teleport cloud frequently asked questions.
 - [Teleport FAQ](faq/faq.mdx): Frequently Asked Questions About Using Teleport

docs/pages/reference/machine-id.mdx

@@ -0,0 +1,14 @@
+---
+title: Machine ID Reference
+description: Configuration and CLI reference for Teleport Machine ID.
+---
+
+{/*TOPICS*/}
+
+- [Diagnostics Service](machine-id/diagnostics-service.mdx): Reference information for the `tbot` diagnostics service.
+- [GitHub Actions](machine-id/github-actions.mdx): Reference for GitHub Actions joining
+- [GitLab CI](machine-id/gitlab.mdx): Reference for GitLab joining
+- [Machine ID Configuration Reference](machine-id/configuration.mdx): Configuration reference for Teleport Machine ID.
+- [Machine ID v14 Upgrade Guide](machine-id/v14-upgrade-guide.mdx): Upgrade instructions for Machine ID in Teleport 14.0
+- [Machine ID v16 Upgrade Guide](machine-id/v16-upgrade-guide.mdx): Upgrade instructions for Machine ID in Teleport 16.0
+- [Telemetry](machine-id/telemetry.mdx): An explanation of the telemetry collected by Machine ID

package.json

@@ -2,7 +2,7 @@
   "name": "teleport-ui",
   "version": "1.0.0",
   "scripts": {
-    "all-topics": "node docs/gen-topic-pages/index.js --in docs/pages/admin-guides,docs/pages/access-controls,docs/pages/connect-your-client,docs/pages/machine-id,docs/pages/reference",
+    "all-topics": "node docs/gen-topic-pages/index.js --in docs/pages/admin-guides,docs/pages/access-controls,docs/pages/connect-your-client,docs/pages/reference",
     "build-ui": "yarn build-ui-oss && yarn build-ui-e",
     "build-ui-oss": "yarn workspace @gravitational/teleport build",
     "build-ui-e": "yarn workspace @gravitational/teleport.e build",