Skip to content

[Hyperdrive] Improving Hyperdrive <> Tunnel tutorial to use steps and details components #24126

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 1, 2025
Merged

[Hyperdrive] Improving Hyperdrive <> Tunnel tutorial to use steps and details components #24126

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
544890f
Improving page to use steps and details components
Oxyjun Aug 1, 2025
7daff8c
Removing toggling on default to make both options more visible
Oxyjun Aug 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 19 additions & 11 deletions src/content/docs/hyperdrive/configuration/connect-to-private-database.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ sidebar:
text: Beta
---

import { TabItem, Tabs, Render } from "~/components";
import { TabItem, Tabs, Render, Steps, Details } from "~/components";

Hyperdrive can securely connect to your private databases using [Cloudflare Tunnel](/cloudflare-one/connections/connect-networks/) and [Cloudflare Access](/cloudflare-one/policies/access/).

Expand Down Expand Up @@ -48,11 +48,13 @@ First, create a [Cloudflare Tunnel](/cloudflare-one/connections/connect-networks

Your tunnel must be configured to use a public hostname so that Hyperdrive can route requests to it. If you don't have a hostname on Cloudflare yet, you will need to [register a new hostname](/registrar/get-started/register-domain/) or [add a zone](/dns/zone-setups/) to Cloudflare to proceed.

<Steps>
1. In the **Public Hostnames** tab, choose a **Domain** and specify any subdomain or path information. This will be used in your Hyperdrive configuration to route to this tunnel.

2. In the **Service** section, specify **Type** `TCP` and the URL and configured port of your database, such as `localhost:5432` or `my-database-host.database-provider.com:5432`. This address will be used by the tunnel to route requests to your database.

3. Select **Save tunnel**.
</Steps>

:::note
If you are setting up the tunnel through the CLI instead ([locally-managed tunnel](/cloudflare-one/connections/connect-networks/do-more-with-tunnels/local-management/)), you will have to complete these steps manually. Follow the Cloudflare Zero Trust documentation to [add a public hostname to your tunnel](/cloudflare-one/connections/connect-networks/routing-to-tunnel/dns/) and [configure the public hostname to route to the address of your database](/cloudflare-one/connections/connect-networks/do-more-with-tunnels/local-management/configuration-file/).
Expand All @@ -64,26 +66,29 @@ To restrict access to the Cloudflare Tunnel to Hyperdrive, a [Cloudflare Access

The Cloudflare dashboard can automatically create and configure the underlying [Cloudflare Access application](/cloudflare-one/applications/), [Service Auth token](/cloudflare-one/policies/access/#service-auth), and [Policy](/cloudflare-one/policies/) on your behalf. Alternatively, you can manually create the Access application and configure the Policies.

<Tabs> <TabItem label="Automatic creation">
<Details header="Automatic creation" open={true}>
Copy link
Contributor

@marciocloudflare marciocloudflare Aug 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a note: when I was looking at the page I almost missed the manual section bc this one was auto open

Copy link
Contributor Author

@Oxyjun Oxyjun Aug 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll keep the default off in that case


### 2.1 Create a Hyperdrive configuration in the Cloudflare dashboard
### 2.1. (Automatic) Create a Hyperdrive configuration in the Cloudflare dashboard

Create a Hyperdrive configuration in the Cloudflare dashboard to automatically configure Hyperdrive to connect to your Cloudflare Tunnel.

<Steps>
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive), navigate to **Storage & Databases > Hyperdrive** and click **Create configuration**.
2. Select **Private database**.
3. In the **Networking details** section, select the tunnel you are connecting to.
4. In the **Networking details** section, select the hostname associated to the tunnel. If there is no hostname for your database, return to step [1.2. Connect your database using a public hostname](/hyperdrive/configuration/connect-to-private-database/#12-connect-your-database-using-a-public-hostname).
5. In the **Access Service Authentication Token** section, select **Create new (automatic)**.
6. In the **Access Application** section, select **Create new (automatic)**.
7. In the **Database connection details** section, enter the database **name**, **user**, and **password**.
</Steps>
</Details>

</TabItem>
<TabItem label="Manual creation">
### 2.1 Create a service token
<Details header="Manual creation" open={false}>
### 2.1. (Manual) Create a service token

The service token will be used to restrict requests to the tunnel, and is needed for the next step.

<Steps>
1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Access** > **Service auth** > **Service Tokens**.

2. Select **Create Service Token**.
Expand All @@ -99,11 +104,13 @@ The service token will be used to restrict requests to the tunnel, and is needed
:::caution
This is the only time Cloudflare Access will display the Client Secret. If you lose the Client Secret, you must regenerate the service token.
:::
</Steps>

### 2.2 Create an Access application to secure the tunnel
### 2.2. (Manual) Create an Access application to secure the tunnel

[Cloudflare Access](/cloudflare-one/policies/access/) will be used to verify that requests to the tunnel originate from Hyperdrive using the service token created above.

<Steps>
1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Access** > **Applications**.

2. Select **Add an application**.
Expand Down Expand Up @@ -137,8 +144,9 @@ The service token will be used to restrict requests to the tunnel, and is needed
16. Select **Next**.

17. Save the application.
</Steps>

### 2.3 Create a Hyperdrive configuration
### 2.3. (Manual) Create a Hyperdrive configuration

To create a Hyperdrive configuration for your private database, you'll need to specify the Access application and Cloudflare Tunnel information upon creation.

Expand Down Expand Up @@ -180,17 +188,17 @@ In addition, it will also set the Access Client ID and the Access Client Secret
When creating the Hyperdrive configuration for the private database, you must enter the `access-client-id` and the `access-client-id`, and omit the `port`. Hyperdrive will route database messages to the public hostname of the tunnel, and the tunnel will rely on its service configuration (as configured in [1.2. Connect your database using a public hostname](#12-connect-your-database-using-a-public-hostname)) to route requests to the database within your private network.
:::

</TabItem> </Tabs>
</Details>

## 3. Query your Hyperdrive configuration from a Worker (optional)

To test your Hyperdrive configuration to the database using Cloudflare Tunnel and Access, use the Hyperdrive configuration ID in your Worker and deploy it.

### Create a Hyperdrive binding
### 3.1. Create a Hyperdrive binding

<Render file="create-hyperdrive-binding" product="hyperdrive" />

### Query your database
### 3.2. Query your database

Validate that you can connect to your database from Workers and make queries.

Expand Down
4 changes: 4 additions & 0 deletions src/content/partials/cloudflare-one/tunnel/create-tunnel.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

---

import { Steps } from "~/components";

<Steps>
1. Log in to [Zero Trust](https://one.dash.cloudflare.com) and go to **Networks** > **Tunnels**.

2. Select **Create a tunnel**.
Expand All @@ -20,3 +23,4 @@
![Connector appearing in the UI after cloudflared has run](~/assets/images/cloudflare-one/connections/connect-apps/connector.png)

8. Select **Next**.
</Steps>