src-connect: move explainer to architecture page (#1578)

Author: bobheadxi

docs/admin/architecture.mdx

@@ -144,7 +144,7 @@ flowchart LR
 
     cloudflare["<b>Sourcegraph DNS (Cloudflare)</b><br/>WAF, Rate-limiting, VPN-only firewall (optional)"]
 
-    subgraph gcp_project["GCP Project - Dedicated per customer"]
+    subgraph gcp_project["GCP project - Dedicated per customer"]
         gcp_lb["<b>GCP Load Balancer</b><br/>SSL termination"]
         nat["Cloud NAT Gateway"]
         subgraph gke["GKE"]
@@ -171,6 +171,8 @@ flowchart LR
     gke --> nat
 ```
 
+For customers connecting to private resources in on-prem data centers, also refer to the [Sourcegraph Connect agent for Sourcegraph Cloud](#sourcegraph-connect-agent-for-sourcegraph-cloud) section.
+
 <Callout type="note">
 	Learn more in the [Sourcegraph Cloud docs](/cloud).
 </Callout>
@@ -403,6 +405,56 @@ Enterprise Portal also handles Sourcegraph licensing and metering. Sourcegraph w
 	docs](/admin/enterprise-portal).
 </Callout>
 
+### Sourcegraph Connect agent for Sourcegraph Cloud
+
+Sourcegraph Cloud supports connecting to private code hosts and artifact registries in the customer's network by deploying the Sourcegraph Connect tunnel agent in the customer's network.
+
+Sourcegraph Connect consists of three components:
+
+- **Connect tunnel clients:** Forward proxy clients for the Sourcegraph Cloud instance's containers to reach the customer's private code hosts and artifact registries, through the tunnel server.
+    - Clients are managed by Sourcegraph, and deployed in the customer's Sourcegraph Cloud instance's VPC.
+- **Connect tunnel servers:** The broker between agents and clients, it authenticates agents and clients, enforces ACLs, sets up mTLS, and proxies encrypted traffic between agents and clients.
+    - Tunnels are managed by Sourcegraph, and deployed in the customer's Sourcegraph Cloud instance's VPC.
+    - mTLS certificates are rotated every 6 hours by default.
+- **Connect agents:** Deployed by the customer inside their network, agents proxy and encrypt traffic between the customer's private resources and the Sourcegraph Cloud tunnel clients.
+    - The agent has its own identity, and using credentials provided to the customer during deployment, the agent authenticates and establishes a secure connection with the tunnel server. Only agents are allowed to establish secure connections with the tunnel server, and the server only accepts a connection if the agent's identity is approved.
+    - Agents can only communicate with permitted code hosts and artifact registries.
+    - The handshake between agents and tunnel servers occurs over a mTLS-encrypted connection using TCP/HTTP2 (gRPC) on port 50050.
+
+```mermaid
+flowchart LR
+    subgraph gcp["Dedicated&nbsp;Sourcegraph&nbsp;Cloud&nbsp;GCP&nbsp;project"]
+        subgraph frontend_pod["sourcegraph-frontend pod"]
+            frontend["frontend"]
+            tunnel_client_1["Connect tunnel client"]
+            frontend -->|"HTTPS"| tunnel_client_1
+        end
+
+        subgraph gitserver_pod["gitserver pod"]
+            gitserver["gitserver"]
+            tunnel_client_2["Connect tunnel client"]
+            gitserver -->|"HTTPS"| tunnel_client_2
+        end
+
+        tunnel_server["Connect tunnel server"]
+        tunnel_client_1 -->|"mTLS"| tunnel_server
+        tunnel_client_2 -->|"mTLS"| tunnel_server
+    end
+
+    subgraph customer["Customer Private Network"]
+        tunnel_agent["Connect agent"]
+        code_host["private code host"]
+        tunnel_agent -->|"HTTPS"| code_host
+    end
+
+    tunnel_server -->|"mTLS"| tunnel_agent
+```
+
+<Callout type="note">
+	Learn more in the [Sourcegraph Connect agent
+	docs](/cloud/private-connectivity-sourcegraph-connect).
+</Callout>
+
 ### Observability
 
 Observability encapsulates the monitoring and debugging of Sourcegraph deployments. Sourcegraph is designed and ships several observability tools and out-of-the-box capabilities to enable visibility into the health and state of a Sourcegraph deployment.
@@ -428,3 +480,18 @@ Debugging includes [tracing](/self-hosted/observability/tracing) and [logging](/
 <Callout type="note">
 	Learn more in the [Observability docs](/self-hosted/observability).
 </Callout>
+
+## Glossary
+
+### Standard ports
+
+Unless otherwise mentioned:
+
+- HTTPS: 443
+- SSH: 22
+- HTTP: 80
+
+### Data encryption
+
+- Where TLS is used, at minimum, TLS 1.2 (TLS 1.3 also supported) is required.
+- All data is encrypted in transit and at rest.

docs/cloud/private-connectivity-sourcegraph-connect.mdx

@@ -1,4 +1,4 @@
-# Private Resources in On-Prem Data Centers via Sourcegraph Connect Agent
+# Private resources in on-prem data centers via the Sourcegraph Connect agent
 
 <Callout type="note">
 	This feature is in the Experimental stage. [Contact
@@ -9,35 +9,7 @@ As part of the [Enterprise tier](https://sourcegraph.com/pricing), Sourcegraph C
 
 ## How it works
 
-Sourcegraph Connect consists of three components:
-
-### Tunnel Clients
-
-Forward proxy clients for the Sourcegraph Cloud instance's containers to reach the customer's private code hosts and artifact registries, through the tunnel server.
-
-Managed by Sourcegraph, and deployed in the customer's Sourcegraph Cloud instance's VPC.
-
-### Tunnel Server
-
-The broker between agents and clients, it authenticates agents and clients, enforces ACLs, sets up mTLS, and proxies encrypted traffic between agents and clients.
-
-Managed by Sourcegraph, and deployed in the customer's Sourcegraph Cloud instance's VPC.
-
-### Tunnel Agents
-
-Deployed by the customer inside their network, agents proxy and encrypt traffic between the customer's private resources and the Sourcegraph Cloud tunnel clients.
-
-The agent has its own identity, and using credentials provided to the customer during deployment, the agent authenticates and establishes a secure connection with the tunnel server. Only agents are allowed to establish secure connections with the tunnel server, and the server only accepts a connection if the agent's identity is approved.
-
-Agents can only communicate with permitted code hosts and artifact registries.
-
-<iframe
-	src="https://link.excalidraw.com/readonly/453uvY8infI8wskSecGJ"
-	width="100%"
-	height="100%"
-	style={{border: 'none'}}
-/>
-[Diagram link](https://link.excalidraw.com/readonly/453uvY8infI8wskSecGJ)
+A technical overview is available in [the architecture diagrams page](/admin/architecture#sourcegraph-connect-agent-for-sourcegraph-cloud).
 
 ## Steps
 
@@ -47,22 +19,22 @@ The customer reaches out to their account manager to request this feature be ena
 
 The account manager collects the required information from the customer, including but not limited to:
 
--   The DNS names of the needed private resources (e.g. `gitlab.internal.company.net`, `artifactory.internal.company.net`)
--   The ports of the private resources (e.g. `443`, `80`, `22`)
--   The type of TLS certificates used by the private resources (e.g. self-signed, internal PKI, or issued by a public CA)
+- The DNS names of the needed private resources (e.g. `gitlab.internal.company.net`, `artifactory.internal.company.net`)
+- The ports of the private resources (e.g. `443`, `80`, `22`)
+- The type of TLS certificates used by the private resources (e.g. self-signed, internal PKI, or issued by a public CA)
 
 Sourcegraph provides:
 
--   The instructions, config file, and credentials to run the agent
--   The tunnel server's static public IPs and ports
+- The instructions, config file, and credentials to run the agent
+- The tunnel server's static public IPs and ports
 
 ### Create the connection
 
 The customer installs the agent in their private network, following the instructions provided. At a high level:
 
--   Configure internet egress to the provided tunnel server's static public IPs and ports
--   Configure intranet egress to the needed private resources
--   Deploy the tunnel agent via Docker container or binary, with the provided config file and credentials
+- Configure internet egress to the provided tunnel server's static public IPs and ports
+- Configure intranet egress to the needed private resources
+- Deploy the tunnel agent via Docker container or binary, with the provided config file and credentials
 
 ### Configure the code host connection
 
@@ -126,9 +98,9 @@ The tunnel agent is designed and built with a minimal footprint and attack surfa
 
 You can:
 
--   Deploy the agent on a hardened container platform
--   Store the agent credential and config content in a secrets management system and mount these secrets to the container
--   Forward the agent's logs to your log management system
+- Deploy the agent on a hardened container platform
+- Store the agent credential and config content in a secrets management system and mount these secrets to the container
+- Forward the agent's logs to your log management system
 
 ### How can I inspect the agent's traffic, and audit the data the agent is accessing in my environment?