[ZT] Create tunnel using Terraform (#21780)

* create tunnel using Terraform

* fix components

* move tunnel token steps to partial

* configure virtual networks

* no longer need to input tunnel_secret in v5

* Apply suggestions from code review

Co-authored-by: marciocloudflare <[email protected]>

---------

Co-authored-by: marciocloudflare <[email protected]>

Author: ranbel

src/content/docs/cloudflare-one/connections/connect-networks/configure-tunnels/remote-tunnel-permissions.mdx

@@ -9,7 +9,7 @@ import { TabItem, Tabs, Render } from "~/components";
 
 A remotely-managed tunnel only requires the tunnel token to run. Anyone with access to the token will be able to run the tunnel.
 
-## View the tunnel token
+## Get the tunnel token
 
 To get the token for a remotely-managed tunnel:
 
@@ -35,6 +35,13 @@ Make a `GET` request to the [Cloudflare Tunnel token](/api/resources/zero_trust/
 ```
 
 </TabItem>
+
+<TabItem label="Terraform (v5)">
+
+<Render file="terraform/get-tunnel-token" product="cloudflare-one" />
+
+</TabItem>
+
 </Tabs>
 
 ## Rotate a token without service disruption

src/content/docs/cloudflare-one/connections/connect-networks/deployment-guides/ansible.mdx

@@ -90,16 +90,11 @@ The following configuration will modify settings in your Cloudflare account.
 
 
 		```tf
-		# Generates a 32-byte secret for the tunnel.
-		resource "random_bytes" "tunnel_secret" {
-			byte_length = 32
-		}
 
 		# Creates a new remotely-managed tunnel for the GCP VM.
 		resource "cloudflare_zero_trust_tunnel_cloudflared" "gcp_tunnel" {
 			account_id    = var.cloudflare_account_id
 			name          = "Ansible GCP tunnel"
-			tunnel_secret = random_bytes.tunnel_secret.base64
 		}
 
 		# Reads the token used to run the tunnel on the server.

src/content/docs/cloudflare-one/connections/connect-networks/deployment-guides/terraform.mdx

@@ -133,16 +133,11 @@ The following configuration will modify settings in your Cloudflare account.
 		<TabItem label="Terraform (v5)">
 
 		```tf
-		# Generates a 32-byte secret for the tunnel.
-		resource "random_bytes" "tunnel_secret" {
-			byte_length = 32
-		}
 
 		# Creates a new remotely-managed tunnel for the GCP VM.
 		resource "cloudflare_zero_trust_tunnel_cloudflared" "gcp_tunnel" {
 			account_id    = var.cloudflare_account_id
 			name          = "Terraform GCP tunnel"
-			tunnel_secret = random_bytes.tunnel_secret.base64
 		}
 
 		# Reads the token used to run the tunnel on the server.

src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel-api.mdx

@@ -5,7 +5,7 @@ sidebar:
   order: 2
 ---
 
-import { Tabs, TabItem } from "~/components";
+import { Render } from "~/components";
 
 Follow this guide to set up a Cloudflare Tunnel using the API.
 
@@ -142,49 +142,7 @@ To configure Zero Trust policies and connect as a user, refer to [Connect privat
 
 Install `cloudflared` on your server and run the tunnel using the `token` value obtained in [2. Create a tunnel](#2-create-a-tunnel). You can also get the tunnel token using the [Cloudflare Tunnel token](/api/resources/zero_trust/subresources/tunnels/subresources/cloudflared/subresources/token/methods/get/) endpoint.
 
-<Tabs> <TabItem label="Linux">
-
-1.  [Download and install](https://pkg.cloudflare.com/index.html) `cloudflared`.
-
-2.  Run the following command:
-
-        ```sh
-        sudo cloudflared service install <tunnel-token>
-        ```
-
-</TabItem> <TabItem label="Windows">
-
-1.  [Download and install](/cloudflare-one/connections/connect-networks/downloads/#windows) `cloudflared`.
-
-2.  Open Command Prompt as administrator.
-
-3.  Run the following command:
-
-        ```txt
-        cloudflared.exe service install <tunnel-token>
-        ```
-
-</TabItem> <TabItem label="macOS">
-
-1.  [Download and install](/cloudflare-one/connections/connect-networks/downloads/#macos) `cloudflared`.
-
-2.  Run the following command:
-
-        ```sh
-        sudo cloudflared service install <tunnel-token>
-        ```
-
-</TabItem> <TabItem label="Docker">
-
-1.  Open a terminal window.
-
-2.  Run the following command:
-
-        	```sh
-        	docker run cloudflare/cloudflared:latest tunnel --no-autoupdate run --token <tunnel-token>
-        	```
-
-</TabItem>  </Tabs>
+<Render file="tunnel/install-and-run-tunnel" product="cloudflare-one" />
 
 ## 5. Verify tunnel status
 

src/content/docs/cloudflare-one/connections/connect-networks/private-net/cloudflared/tunnel-virtual-networks.mdx

@@ -46,7 +46,7 @@ Here are a few scenarios where virtual networks may prove useful:
 The following example demonstrates how to add two overlapping IP routes to Cloudflare (`10.128.0.1/32` staging and `10.128.0.1/32` production).
 
 <Tabs>
-   <TabItem label="Dashboard">
+  <TabItem label="Dashboard">
       To route overlapping IPs over virtual networks:
 
       1. First, create two unique virtual networks:
@@ -67,10 +67,71 @@ The following example demonstrates how to add two overlapping IP routes to Cloud
 
       We now have two overlapping IP addresses routed over `staging-vnet` and `production-vnet` respectively. You can use the Cloudflare WARP client to [switch between virtual networks](#connect-to-a-virtual-network).
 
-   </TabItem>
+  </TabItem>
 
-   <TabItem label="cli">
-      To route overlapping IPs over virtual networks:
+	<TabItem label="Terraform (v5)">
+	To route overlapping IPs over virtual networks:
+		1. Add the following permission to your [`cloudflare_api_token`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_token):
+			- `Cloudflare Tunnel Write`
+
+		2. Create two unique virtual networks:
+			```tf
+			resource "cloudflare_zero_trust_tunnel_cloudflared_virtual_network" "staging_vnet" {
+				account_id = var.cloudflare_account_id
+				name       = "staging-vnet"
+				comment    = "Staging virtual network"
+				is_default = false
+			}
+
+			resource "cloudflare_zero_trust_tunnel_cloudflared_virtual_network" "production_vnet" {
+				account_id = var.cloudflare_account_id
+				name       = "production-vnet"
+				comment    = "Production virtual network"
+				is_default = false
+			}
+			```
+
+		3. Create a Cloudflare Tunnel for each private network:
+			```tf
+			resource "cloudflare_zero_trust_tunnel_cloudflared" "staging_tunnel" {
+				account_id = var.cloudflare_account_id
+				name       = "Staging tunnel"
+				config_src = "cloudflare"
+			}
+
+			resource "cloudflare_zero_trust_tunnel_cloudflared" "production_tunnel" {
+				account_id = var.cloudflare_account_id
+				name       = "Production tunnel"
+				config_src = "cloudflare"
+			}
+			```
+
+		4. Route `10.128.0.1/32` through `Staging tunnel` and assign it to `staging-vnet`. Route `10.128.0.1/32` through `Production tunnel` and assign it to `production-vnet`.
+
+				```tf
+				resource "cloudflare_zero_trust_tunnel_cloudflared_route" "staging_tunnel_route" {
+					account_id         = var.cloudflare_account_id
+					tunnel_id          = cloudflare_zero_trust_tunnel_cloudflared.staging_tunnel.id
+					network            = "10.128.0.1/32"
+					comment            = "Staging tunnel route"
+					virtual_network_id = cloudflare_zero_trust_tunnel_cloudflared_virtual_network.staging_vnet.id
+				}
+
+				resource "cloudflare_zero_trust_tunnel_cloudflared_route" "production_tunnel_route" {
+					account_id         = var.cloudflare_account_id
+					tunnel_id          = cloudflare_zero_trust_tunnel_cloudflared.production_tunnel.id
+					network            = "10.128.0.1/32"
+					comment            = "Production tunnel route"
+					virtual_network_id = cloudflare_zero_trust_tunnel_cloudflared_virtual_network.production_vnet.id
+				}
+				```
+		5. [Get the token](/cloudflare-one/connections/connect-networks/configure-tunnels/remote-tunnel-permissions/#get-the-tunnel-token) for each tunnel.
+
+		6. Using the tunnel tokens, run `Staging tunnel` in your staging environment and run `Production tunnel` in your production environment. Refer to [Install and run the tunnel](/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel-api/#4-install-and-run-the-tunnel).
+  </TabItem>
+
+  <TabItem label="Locally-managed tunnels">
+      To route overlapping IPs over virtual networks for [locally-managed tunnels](/cloudflare-one/connections/connect-networks/do-more-with-tunnels/local-management/):
 
       1. Create a tunnel for each private network:
 
@@ -113,10 +174,9 @@ The following example demonstrates how to add two overlapping IP routes to Cloud
          cloudflared tunnel vnet list
          ```
 
-    	{/* Commenting out notes within tabs for now
     	:::note[Default virtual network]
     	All accounts come pre-configured with a virtual network named `default`. You can choose a new default by typing `cloudflared tunnel vnet update --default <virtual-network-name>`.
-    	::: */}
+    	:::
 
 4.  Configure your tunnels with the IP/CIDR range of your private networks, and assign the tunnels to their respective virtual networks.
 
@@ -162,7 +222,7 @@ The following example demonstrates how to add two overlapping IP routes to Cloud
 ## Delete a virtual network
 
 <Tabs>
-   <TabItem label="Dashboard">
+  <TabItem label="Dashboard">
       To delete a virtual network:
 
       1. In [Zero Trust](https://one.dash.cloudflare.com/), go to **Networks** > **Tunnels** and ensure that no IP routes are assigned to the virtual network you are trying to delete. If your virtual network is in use, delete the route or reassign it to a different virtual network.
@@ -175,10 +235,10 @@ The following example demonstrates how to add two overlapping IP routes to Cloud
 
       You can optionally delete the tunnel associated with your virtual network.
 
-   </TabItem>
+  </TabItem>
 
-   <TabItem label="cli">
-      To delete a virtual network:
+  <TabItem label="Locally-managed tunnels">
+      To delete a virtual network for [locally-managed tunnels](/cloudflare-one/connections/connect-networks/do-more-with-tunnels/local-management/):
 
       1. Delete all IP routes in the virtual network. For example,
 
@@ -200,7 +260,7 @@ The following example demonstrates how to add two overlapping IP routes to Cloud
 
       You can verify that the virtual network was successfully deleted by typing `cloudflared tunnel vnet list`.
 
-   </TabItem>
+  </TabItem>
 </Tabs>
 
 ## Connect to a virtual network

src/content/docs/learning-paths/replace-vpn/connect-private-network/cloudflared.mdx

@@ -6,20 +6,61 @@ sidebar:
 
 ---
 
-import { Render } from "~/components"
+import { Render, Tabs, TabItem } from "~/components"
 
 Cloudflare Tunnel is an outbound-only daemon service that can run on nearly any host machine and proxies local traffic once validated from the Cloudflare network. User traffic initiated from the WARP endpoint client onramps to Cloudflare, passes down your Cloudflare Tunnel connections, and terminates automatically in your local network. Traffic reaching your internal applications or services will carry the local source IP address of the host machine running the `cloudflared` daemon.
 
 ## Create a tunnel
 
 To connect your private network:
 
+<Tabs syncKey="dashPlusAPI">
+
+<TabItem label="Dashboard">
+
 <Render file="tunnel/create-tunnel" product="cloudflare-one" />
 
 9. In the **Private Networks** tab, enter the CIDR of your private network (for example, `10.0.0.0/8`).
 
 10. Select **Save tunnel**.
 
+</TabItem>
+<TabItem label="Terraform (v5)">
+
+1. Add the following permission to your [`cloudflare_api_token`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_token):
+	- `Cloudflare Tunnel Write`
+
+2. Create a tunnel using the [`cloudflare_zero_trust_tunnel_cloudflare`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_tunnel_cloudflared) resource.
+
+		```tf
+		resource "cloudflare_zero_trust_tunnel_cloudflared" "example_tunnel" {
+			account_id = var.cloudflare_account_id
+			name       = "Example tunnel"
+			config_src = "cloudflare"
+		}
+		```
+
+3. Route the CIDR of your private network through the tunnel using the [`cloudflare_zero_trust_tunnel_cloudflared_route`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_tunnel_cloudflared_route) resource:
+
+		```tf
+		resource "cloudflare_zero_trust_tunnel_cloudflared_route" "example_tunnel_route" {
+			account_id         = var.cloudflare_account_id
+			tunnel_id          = cloudflare_zero_trust_tunnel_cloudflared.example_tunnel.id
+			network            = "10.0.0.0/8"
+			comment            = "Example tunnel route"
+		}
+		```
+
+4. Get the [token](/cloudflare-one/connections/connect-networks/configure-tunnels/remote-tunnel-permissions/) used to run the tunnel:
+		<Render file="terraform/get-tunnel-token" product="cloudflare-one" />
+
+5. Install `cloudflared` on a host machine in your private network and run the tunnel:
+
+		<Render file="tunnel/install-and-run-tunnel" product="cloudflare-one" />
+
+</TabItem>
+</Tabs>
+
 All internal applications and services in this IP range are now connected to Cloudflare.
 
 :::note

src/content/partials/cloudflare-one/terraform/get-tunnel-token.mdx

@@ -0,0 +1,50 @@
+---
+{}
+
+---
+
+import { Details } from "~/components"
+
+	```tf
+	data "cloudflare_zero_trust_tunnel_cloudflared_token" "tunnel_token" {
+		account_id = var.cloudflare_account_id
+		tunnel_id = cloudflare_zero_trust_tunnel_cloudflared.example_tunnel.id
+	}
+	```
+
+	If your host machine is not managed in Terraform or you want to install the tunnel manually, you can output the token value to the CLI.
+<Details header="Example: Output to CLI" open = {false}>
+	1. Output the tunnel token to the Terraform state file:
+		```tf
+		output "tunnel_token" {
+			value       = data.cloudflare_zero_trust_tunnel_cloudflared_token.tunnel_token.token
+			sensitive   = true
+		}
+		```
+2. Apply the configuration:
+		```sh
+		terraform apply
+		```
+3. Read the tunnel token:
+		```sh
+		terraform output -raw tunnel_token
+		```
+		```sh output
+		eyJhIj...
+		```
+
+</Details>
+
+	Alternatively, pass `data.cloudflare_zero_trust_tunnel_cloudflared_token.tunnel_token.token` directly into your host's Terraform configuration or store the token in your secret management tool.
+
+<Details header="Example: Store in HashiCorp Vault" open = {false}>
+		```tf
+		resource "vault_generic_secret" "tunnel_token" {
+			path         = "kv/cloudflare/tunnel_token"
+
+			data_json = jsonencode({
+				"TUNNEL_TOKEN" = data.cloudflare_zero_trust_tunnel_cloudflared_token.tunnel_token.token
+			})
+		}
+		```
+</Details>

src/content/partials/cloudflare-one/terraform/providers-v5.mdx

@@ -12,9 +12,6 @@ terraform {
 		google = {
 			source = "hashicorp/google"
 		}
-		random = {
-			source = "hashicorp/random"
-		}
 	}
 	required_version = ">= 1.2"
 }