From 891adcf9fa6f566766571d614ede43a5ea997fcf Mon Sep 17 00:00:00 2001 From: Ranbel Sun Date: Wed, 19 Feb 2025 14:40:38 -0500 Subject: [PATCH 1/2] api tunnel tutorial --- .../get-started/create-local-tunnel.mdx | 2 +- .../get-started/create-remote-tunnel-api.mdx | 260 ++++++++++++++++++ .../get-started/create-remote-tunnel.mdx | 2 - .../connect-networks/get-started/index.mdx | 2 +- .../tunnel/add-public-hostname.mdx | 3 + 5 files changed, 265 insertions(+), 4 deletions(-) create mode 100644 src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel-api.mdx diff --git a/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel.mdx b/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel.mdx index 4932292c38fb69a..d5215fd8e1f511e 100644 --- a/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel.mdx +++ b/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel.mdx @@ -2,7 +2,7 @@ title: Create a locally-managed tunnel (CLI) pcx_content_type: how-to sidebar: - order: 2 + order: 3 --- import { Render, TabItem, Tabs } from "~/components"; diff --git a/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel-api.mdx b/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel-api.mdx new file mode 100644 index 000000000000000..d17354a00f4f974 --- /dev/null +++ b/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel-api.mdx @@ -0,0 +1,260 @@ +--- +title: Create a remotely-managed tunnel (API) +pcx_content_type: how-to +sidebar: + order: 2 +--- + +import { Tabs, TabItem } from "~/components"; + +Follow this guide to set up a Cloudflare Tunnel using the API. + +## 1. Create an API token + +[Create an API token](/fundamentals/api/get-started/create-token/) with the following permissions: + +| Type | Item | Permission | +| ------- | ---------------- | ---------- | +| Account | Cloudflare Tunnel | Edit | +| Zone | DNS | Edit | + +## 2. Create a tunnel + +Make a `POST` request to the [Cloudflare Tunnel](/api/resources/zero_trust/subresources/access/subresources/applications/methods/create/) endpoint: + +```sh +curl 'https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel' \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ +--data '{ + "name": "api-tunnel", + "config_src": "cloudflare" +}' +``` + +```sh output +{ + "success": true, + "errors": [], + "messages": [], + "result": { + "id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa", + "account_tag": "699d98642c564d2e855e9661899b7252", + "created_at": "2025-02-18T22:41:43.534395Z", + "deleted_at": null, + "name": "example-tunnel", + "connections": [], + "conns_active_at": null, + "conns_inactive_at": "2025-02-18T22:41:43.534395Z", + "tun_type": "cfd_tunnel", + "metadata": {}, + "status": "inactive", + "remote_config": true, + "credentials_file": { + "AccountTag": "699d98642c564d2e855e9661899b7252", + "TunnelID": "c1744f8b-faa1-48a4-9e5c-02ac921467fa", + "TunnelName": "api-tunnel", + "TunnelSecret": "bTSquyUGwLQjYJn8cI8S1h6M6wUc2ajIeT7JotlxI7TqNqdKFhuQwX3O8irSnb==" + }, + "token": "eyJhIjoiNWFiNGU5Z..." + } +} +``` + +Copy the `id` and `token` values shown in the output. You will need these values to configure and run the tunnel. + +The next steps depend on whether you want to [connect an application](#3a-connect-an-application) or [connect a network](#3b-connect-a-network). + +## 3a. Connect an application + +Before you connect an application through your tunnel, you must: + +- [Add a website to Cloudflare](/fundamentals/setup/manage-domains/add-site/). +- [Change your domain nameservers to Cloudflare](/dns/zone-setups/full-setup/setup/). + +Follow these steps to connect an application through your tunnel. If you are looking to connect a network, skip to the [Connect a network section](#3b-connect-a-network). + +1. Make a [`PUT` request](/api/resources/zero_trust/subresources/tunnels/subresources/cloudflared/subresources/configurations/methods/update/) to route your local service URL to a public hostname. For example, + + ```sh + curl --request PUT \ + 'https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel/c1744f8b-faa1-48a4-9e5c-02ac921467fa/configurations' \ + --header 'Content-Type: application/json' \ + --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ + --data '{ + "config": { + "ingress": [ + { + "hostname": "app.example.com", + "service": "http://localhost:8001", + "originRequest": {} + }, + { + "service": "http_status:404" + } + ] + } + }' + ``` + + :::note + If you add a multi-level subdomain (more than one level of subdomain), you must [order an Advanced Certificate for the hostname](/cloudflare-one/faq/troubleshooting/#i-see-this-site-cant-provide-a-secure-connection). + ::: + + Your ingress rules must include a catch-all rule at the end. In this example, `cloudflared` will respond with a 404 status code when the request does not match any of the previous hostnames. + +2. [Create a DNS record](/api/resources/dns/subresources/records/methods/create/) for your application: + ```sh + curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records \ + --header 'Content-Type: application/json' \ + --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ + --data '{ + "type": "CNAME", + "proxied": true, + "name": "app.example.com", + "content": "c1744f8b-faa1-48a4-9e5c-02ac921467fa.cfargotunnel.com" + }' + ``` + + This DNS record allows Cloudflare to proxy `app.example.com` traffic to your Cloudflare Tunnel (`.cfargotunnel.com`). + +This application will be publicly available on the Internet once you [run the tunnel](#4-install-and-run-the-tunnel). To allow or block specific users, [create an Access application](/cloudflare-one/applications/configure-apps/self-hosted-public-app/). + +## 3b. Connect a network + +To connect a private network through your tunnel, [add a tunnel route](/api/resources/zero_trust/subresources/networks/subresources/routes/methods/create/): + +```sh +curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/teamnet/routes \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ +--data '{ + "network": "172.16.0.0/16", + "tunnel_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa", + "comment": "Example private network route" +}' +``` + +To configure Zero Trust policies and connect as a user, refer to [Connect private networks](/cloudflare-one/connections/connect-networks/private-net/cloudflared/). + +## 4. Install and run the tunnel + +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. + + + +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 + ``` + + + +1. [Download and install](/cloudflare-one/connections/connect-networks/downloads/#macos) `cloudflared`. + +2. Run the following command: + + ```sh + sudo cloudflared service install + ``` + + + +1. [Download and install](https://pkg.cloudflare.com/index.html) `cloudflared`. + +2. Run the following command: + + ```sh + sudo cloudflared service install + ``` + + + +1. Open a terminal window. + +2. Run the following command: + + ```sh + docker run cloudflare/cloudflared:latest tunnel --no-autoupdate run --token + ``` + + +## 5. Verify tunnel status + +To check if the tunnel is serving traffic: + +```sh +curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel/c1744f8b-faa1-48a4-9e5c-02ac921467fa \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" +``` + +```sh output +{ + "success": true, + "errors": [], + "messages": [], + "result": { + "id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa", + "account_tag": "699d98642c564d2e855e9661899b7252", + "created_at": "2025-02-18T22:41:43.534395Z", + "deleted_at": null, + "name": "example-tunnel", + "connections": [ + { + "colo_name": "bos01", + "uuid": "2xz99mfm-a59e-4924-gyh9-z9vafaw6k0i2", + "id": "2xz99mfm-a59e-4924-gyh9-z9vafaw6k0i2", + "is_pending_reconnect": false, + "origin_ip": "10.1.0.137", + "opened_at": "2025-02-19T19:11:12.101642Z", + "client_id": "4xh4eb3f-cz0j-2aso-hu6i-36207018771a", + "client_version": "2025.2.0" + }, + { + "colo_name": "phl01", + "uuid": "axe2socu-2fb5-3akx-b860-898zyes3cs9q", + "id": "axe2socu-2fb5-3akx-b860-898zyes3cs9q", + "is_pending_reconnect": false, + "origin_ip": "10.1.0.137", + "opened_at": "2025-02-19T19:11:12.006297Z", + "client_id": "4xh4eb3f-cz0j-2aso-hu6i-36207018771a", + "client_version": "2025.2.0" + }, + { + "colo_name": "phl01", + "uuid": "9b5y0wm9-ca7f-ibq6-8ff4-sm53xekfyym1", + "id": "9b5y0wm9-ca7f-ibq6-8ff4-sm53xekfyym1", + "is_pending_reconnect": false, + "origin_ip": "10.1.0.137", + "opened_at": "2025-02-19T19:11:12.004721Z", + "client_id": "4xh4eb3f-cz0j-2aso-hu6i-36207018771a", + "client_version": "2025.2.0" + }, + { + "colo_name": "bos01", + "uuid": "g6cdeiz1-80f5-3akx-b18b-3y0ggktoxwkd", + "id": "g6cdeiz1-80f5-3akx-b18b-3y0ggktoxwkd", + "is_pending_reconnect": false, + "origin_ip": "10.1.0.137", + "opened_at": "2025-02-19T19:11:12.110765Z", + "client_id": "4xh4eb3f-cz0j-2aso-hu6i-36207018771a", + "client_version": "2025.2.0" + } + ], + "conns_active_at": "2025-02-19T19:11:12.004721Z", + "conns_inactive_at": null, + "tun_type": "cfd_tunnel", + "metadata": {}, + "status": "healthy", + "remote_config": true + } +} +``` + +A healthy tunnel will have four connections to Cloudflare's network. diff --git a/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel.mdx b/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel.mdx index e3f91cbe5ff87ae..85e6aa769292dcf 100644 --- a/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel.mdx +++ b/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel.mdx @@ -26,8 +26,6 @@ Follow these steps to connect an application through your tunnel. If you are loo -If you add a multi-level subdomain (more than one level of subdomain), you must [order an Advanced Certificate for the hostname](/cloudflare-one/faq/troubleshooting/#i-see-this-site-cant-provide-a-secure-connection). - The application is now publicly available on the Internet. To allow or block specific users, [create an Access application](/cloudflare-one/applications/configure-apps/self-hosted-public-app/). ## 2b. Connect a network diff --git a/src/content/docs/cloudflare-one/connections/connect-networks/get-started/index.mdx b/src/content/docs/cloudflare-one/connections/connect-networks/get-started/index.mdx index 99594af411ebac0..da86c48e554a91c 100644 --- a/src/content/docs/cloudflare-one/connections/connect-networks/get-started/index.mdx +++ b/src/content/docs/cloudflare-one/connections/connect-networks/get-started/index.mdx @@ -13,6 +13,6 @@ import { DirectoryListing, GlossaryTooltip } from "~/components" To create and manage tunnels, you will need to install and authenticate cloudflared on your origin server. `cloudflared` is what connects your server to Cloudflare's global network. -You have the option of creating a tunnel [via the dashboard](/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel/) or [via the command line](/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel/). We recommend getting started with the dashboard, since it will allow you to manage the tunnel from any machine. +You have the option of creating a tunnel using the dashboard, API, or command line. We recommend getting started with the dashboard or API, since it will allow you to manage the tunnel from any machine. diff --git a/src/content/partials/cloudflare-one/tunnel/add-public-hostname.mdx b/src/content/partials/cloudflare-one/tunnel/add-public-hostname.mdx index a06546576bf4e31..96ca8b295041638 100644 --- a/src/content/partials/cloudflare-one/tunnel/add-public-hostname.mdx +++ b/src/content/partials/cloudflare-one/tunnel/add-public-hostname.mdx @@ -6,6 +6,9 @@ 1. In the **Public Hostnames** tab, select **Add a public hostname**. 2. Enter a subdomain and select a **Domain** from the dropdown menu. Specify any subdomain or path information. + :::note + If you add a multi-level subdomain (more than one level of subdomain), you must [order an Advanced Certificate for the hostname](/cloudflare-one/faq/troubleshooting/#i-see-this-site-cant-provide-a-secure-connection). + ::: 3. Specify a service, for example `https://localhost:8000`. From eb1e6e3869071f994176257cddcc1362cce24038 Mon Sep 17 00:00:00 2001 From: Ranbel Sun Date: Fri, 28 Feb 2025 14:57:16 -0500 Subject: [PATCH 2/2] update title --- .../connect-networks/get-started/create-remote-tunnel-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel-api.mdx b/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel-api.mdx index d17354a00f4f974..89c5937fd325c92 100644 --- a/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel-api.mdx +++ b/src/content/docs/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel-api.mdx @@ -1,5 +1,5 @@ --- -title: Create a remotely-managed tunnel (API) +title: Create a tunnel (API) pcx_content_type: how-to sidebar: order: 2