Reorganize the API and Architecture sections (#42589)

Incorporate the API and Architecture sections into new docs structure.

Move API guides into Admin Guides, except for the API architecture page,
which belongs in Reference. This change adds an Architecture section to
Reference for the API architcture guide and other architecture guides.

This change also merges the API intro page and TOC page, as the intro
page doesn't add much beyond the TOC.

Finally, this change moves all guides in the Architecture sidebar
section into `reference/architecture`.

docs/config.json

@@ -79,6 +79,16 @@
         }
       ]
     },
+    {
+    	"title": "Admin Guides",
+    	"icon": "wrench",
+    	"entries": [
+	    {
+	    	"title": "All Topics",
+	    	"slug": "/admin-guides/"
+	    }
+	]
+    },
     {
       "icon": "success",
       "title": "Choose an Edition",
@@ -1687,37 +1697,6 @@
         }
       ]
     },
-    {
-      "icon": "list",
-      "title": "API",
-      "entries": [
-        {
-          "title": "Introduction",
-          "slug": "/api/introduction/"
-        },
-        {
-          "title": "Getting Started",
-          "slug": "/api/getting-started/"
-        },
-        {
-          "title": "Architecture",
-          "slug": "/api/architecture/"
-        },
-        {
-          "title": "How to Build an Access Request Plugin",
-          "slug": "/api/access-plugin/",
-          "forScopes": ["enterprise", "cloud"]
-        },
-        {
-          "title": "Automatically Register Teleport Agents",
-          "slug": "/api/automatically-register-agents/"
-        },
-        {
-          "title": "Automatically Generate Roles",
-          "slug": "/api/rbac/"
-        }
-      ]
-    },
     {
       "icon": "book",
       "title": "Reference",
@@ -1857,55 +1836,11 @@
               "slug": "/reference/helm-reference/teleport-plugin-slack/"
             }
           ]
-        }
-      ]
-    },
-    {
-      "icon": "integrations",
-      "title": "Architecture",
-      "entries": [
-        {
-          "title": "Introduction",
-          "slug": "/architecture/introduction/"
-        },
-        {
-          "title": "Authentication",
-          "slug": "/architecture/authentication/"
-        },
-        {
-          "title": "Authorization",
-          "slug": "/architecture/authorization/"
-        },
-        {
-          "title": "Teleport Proxy",
-          "slug": "/architecture/proxy/"
-        },
-        {
-          "title": "Trusted Clusters",
-          "slug": "/architecture/trustedclusters/"
         },
 	{
-	  "title": "Teleport Agents",
-	  "slug": "/architecture/agents/"
-	},
-        {
-          "title": "Session Recording",
-          "slug": "/architecture/session-recording/"
-        },
-        {
-          "title": "TLS Routing",
-          "slug": "/architecture/tls-routing/"
-        },
-        {
-          "title": "Proxy Peering",
-          "slug": "/architecture/proxy-peering/",
-          "forScopes": ["enterprise"]
-        },
-        {
-          "title": "Agent Update Management",
-          "slug": "/architecture/agent-update-management/",
-          "forScopes": ["enterprise", "cloud"]
-        }
+	    "title": "All Topics",
+	    "slug": "/reference/"
+	}
       ]
     }
   ],
@@ -2003,11 +1938,6 @@
     }
   },
   "redirects": [
-    {
-      "source": "/architecture/users/",
-      "destination": "/architecture/authorization/",
-      "permanent": true
-    },
     {
       "source": "/enterprise/ssh_sso/",
       "destination": "/access-controls/sso/",
@@ -2038,11 +1968,6 @@
       "destination": "/",
       "permanent": true
     },
-    {
-      "source": "/api-reference/",
-      "destination": "/api/getting-started/",
-      "permanent": true
-    },
     {
       "source": "/server-access/guides/tsh/",
       "destination": "/connect-your-client/tsh/",
@@ -2708,21 +2633,11 @@
       "destination": "/connect-your-client/introduction/",
       "permanent": true
     },
-    {
-      "source": "/api/",
-      "destination": "/api/introduction/",
-      "permanent": true
-    },
     {
       "source": "/preview/",
       "destination": "/upcoming-releases/",
       "permanent": true
     },
-    {
-      "source": "/architecture/",
-      "destination": "/architecture/introduction/",
-      "permanent": true
-    },
     {
       "source": "/management/guides/joining-nodes-aws-ec2/",
       "destination": "/agents/join-services-to-your-cluster/aws-ec2/",

docs/pages/admin-guides.mdx

@@ -0,0 +1,15 @@
+---
+title: "Teleport Admin Guides"
+description: "Step-by-step guides to performing common Teleport tasks"
+---
+
+{/*TOPICS*/}
+
+## Teleport API Introduction
+
+Introduction to the Teleport gRPC API. ([more info](admin-guides/api.mdx))
+
+- [API Getting Started Guide](admin-guides/api/getting-started.mdx): Get started working with the Teleport API programmatically using Go.
+- [Automatically Register Resources with Teleport](admin-guides/api/automatically-register-agents.mdx): Learn how to use the Teleport API to start agents automatically when you add resources to your infrastructure.
+- [Generate Teleport Roles from an External RBAC System](admin-guides/api/rbac.mdx): Use Teleport's API to automatically generate Teleport roles based on third-party RBAC policies
+- [How to Build an Access Request Plugin](admin-guides/api/access-plugin.mdx): Manage Access Requests using custom workflows with the Teleport API

docs/pages/api/introduction.mdx → docs/pages/admin-guides/api.mdx

@@ -7,8 +7,6 @@ layout: tocless-doc
 The Teleport Auth Service provides a gRPC API for remotely interacting with your
 cluster. In this section, we will show you how to use Teleport's API. 
 
-## Go client
-
 Teleport has a public [Go
 client](https://pkg.go.dev/github.com/gravitational/teleport/api/client) to
 programatically interact with the API. [tsh and tctl](../reference/cli.mdx) use
@@ -23,24 +21,14 @@ Here is what you can do with the Go Client:
    and provisioning tokens.
  - Dynamically configure Teleport.
 
-## Get started
-
-Create an API client in 3 minutes with the [Getting Started
-Guide](./getting-started.mdx).
-
-## Learn how to use Teleport's API libraries
-
 The following guides provide tours of API libraries that are relevant when
 setting up an API client to automate some aspect of setting up Teleport. Read
 these guides to set up a minimal working example and plan your own use of
 Teleport's API client libraries:
 
-- [Automatically Register Teleport Agents](./automatically-register-agents.mdx):
-  Write a Teleport API client to reconcile the resources in your Teleport
-  cluster with an external service discovery API.
-- [Automatically generate Teleport roles](./rbac.mdx) from an external RBAC
-  system, making it easier to get started with Teleport-based RBAC and keep your
-  Teleport roles up to date.
-- [Write an Access Request Plugin](./access-plugin.mdx): Follow this guide for a
-  minimal working example of a plugin that you can use to manage Access Requests
-  through your organization's unique communication workflows.
+{/*TOPICS*/}
+
+- [API Getting Started Guide](api/getting-started.mdx): Get started working with the Teleport API programmatically using Go.
+- [Automatically Register Resources with Teleport](api/automatically-register-agents.mdx): Learn how to use the Teleport API to start agents automatically when you add resources to your infrastructure.
+- [Generate Teleport Roles from an External RBAC System](api/rbac.mdx): Use Teleport's API to automatically generate Teleport roles based on third-party RBAC policies
+- [How to Build an Access Request Plugin](api/access-plugin.mdx): Manage Access Requests using custom workflows with the Teleport API

docs/pages/reference.mdx

@@ -36,6 +36,22 @@ Comprehensive lists of configuration values in Teleport's Helm charts ([more inf
 - [teleport-plugin-pagerduty Chart Reference](reference/helm-reference/teleport-plugin-pagerduty.mdx): Values that can be set using the teleport-plugin-pagerduty Helm chart
 - [teleport-plugin-slack Chart Reference](reference/helm-reference/teleport-plugin-slack.mdx): Values that can be set using the teleport-plugin-slack Helm chart
 
+## Teleport Architecture Guides
+
+Guides to the inner workings of components within a Teleport cluster. ([more info](reference/architecture.mdx))
+
+- [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.
+- [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 Architecture Guides](reference/architecture/introduction.mdx): Get detailed information about how Teleport works
+- [Teleport Authentication](reference/architecture/authentication.mdx): This chapter explains how Teleport uses certificate authorities to authenticate users and services.
+- [Teleport Authorization](reference/architecture/authorization.mdx): This chapter explains how Teleport authorizes users and roles.
+- [Teleport Proxy Service](reference/architecture/proxy.mdx): Architecture of Teleport's identity-aware proxy service
+- [Teleport SSH Nodes](reference/architecture/nodes.mdx): This chapter explains the concept of a Teleport Node and how Teleport manages SSH.
+- [Teleport Session Recording](reference/architecture/session-recording.mdx): An overview of Teleport's session recording and its configuration
+- [Trusted Clusters Architecture](reference/architecture/trustedclusters.mdx): Deep dive into design of Teleport Trusted Clusters.
+
 ## Teleport CLI Reference Guides
 
 Comprehensive lists of commands, arguments, and flags for Teleport CLI tools. ([more info](reference/cli.mdx))

docs/pages/architecture.mdx → docs/pages/reference/architecture.mdx

@@ -5,6 +5,7 @@ description: Guides to the inner workings of components within a Teleport cluste
 
 {/*TOPICS*/}
 
+- [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.
 - [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

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/database-access,docs/pages/access-controls,docs/pages/desktop-access,docs/pages/kubernetes-access,docs/pages/connect-your-client,docs/pages/agents,docs/pages/auto-discovery,docs/pages/architecture,docs/pages/api,docs/pages/choose-an-edition,docs/pages/server-access,docs/pages/deploy-a-cluster,docs/pages/machine-id,docs/pages/reference,docs/pages/application-access",
+    "all-topics": "node docs/gen-topic-pages/index.js --in docs/pages/admin-guides,docs/pages/database-access,docs/pages/access-controls,docs/pages/desktop-access,docs/pages/kubernetes-access,docs/pages/connect-your-client,docs/pages/agents,docs/pages/auto-discovery,docs/pages/choose-an-edition,docs/pages/server-access,docs/pages/deploy-a-cluster,docs/pages/machine-id,docs/pages/reference,docs/pages/application-access",
     "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",