netbird-docs/src/pages/manage/networks/use-cases/by-scenario/cloud-to-on-premise.mdx

import { Note } from '@/components/mdx'

# Cloud to On-Premise Access (VPN-to-Site)

This guide shows how to connect cloud workloads to on-premise databases and services using the Networks feature.

## What You'll Achieve

After following this guide, your cloud applications will be able to securely access on-premise databases, APIs, and services without exposing them to the public internet.

```
Cloud VM ────► NetBird Tunnel ────► Routing Peer ────► Database Server
(peer)                               (on-prem)         (no NetBird)
```

## Prerequisites

- A [NetBird cloud account](https://app.netbird.io/) or [self-hosted instance](/selfhosted/selfhosted-quickstart)
- Access to deploy VMs or containers in your cloud environment
- Network configuration permissions in your cloud VPC

## Step 1: Find Your On-Premise Subnet

Before configuring NetBird, identify your data center network's subnet.

**On your routing peer device, run:**

```bash
# Linux
ip route | grep -E "^[0-9]"
```

Look for your local subnet, typically something like `10.100.0.0/24`.

## Step 2: Create a Network for On-Premise Resources

1. Go to **Networks** in the NetBird dashboard
2. Click **Add Network**
3. Name it "On-Premise Data Center" and click **Save**

<p>
    <img src="/docs-static/img/manage/networks/use-cases/by-scenario/cloud-to-on-prem/add-network-on-prem-datacenter.png" alt="Add network" className="imagewrapper"/>
</p>

## Step 3: Add Your Database as a Resource

1. In your new network, click **Add Resource**
2. Enter a name like "Database Servers"
3. Enter your database subnet or specific IP (e.g., `10.100.0.0/24` or `10.100.0.50/32`)
4. Create a group called `on-prem-databases` for the destination
5. Click **Add Resource**

<p>
    <img src="/docs-static/img/manage/networks/use-cases/by-scenario/cloud-to-on-prem/add-resource-database-servers.png" alt="Add resource" className="imagewrapper"/>
</p>

<Note>
For more granular access, add specific database IPs instead of the entire subnet. For example, add `10.100.0.50/32` to only allow access to your production database.
</Note>

## Step 4: Create an Access Policy

1. After adding your resource, click **Create Policy**
2. Set **Source** to "`cloud-workloads`" (you'll create this group in the next step)
3. Set **Destination** to `on-prem-databases`
4. Set **Protocol** to TCP
5. Set **Ports** to the database ports (e.g., `5432` for PostgreSQL, `3306` for MySQL)
6. Name it "Cloud to Database Access" and click **Add Policy**

<p>
    <img src="/docs-static/img/manage/networks/use-cases/by-scenario/cloud-to-on-prem/add-policy-on-prem-databases.png" alt="Add policy" className="imagewrapper"/>
</p>

## Step 5: Set Up the Routing Peer On-Premise

The routing peer forwards traffic from NetBird to your data center network. Install NetBird on a server that can reach the database:

1. In the NetBird dashboard, go to **Setup Keys**
2. Create a new setup key (one-time use recommended). Add `on-prem-databases` to **Auto-assigned groups** and click **Create Setup Key**.

<p>
    <img src="/docs-static/img/manage/networks/use-cases/by-scenario/cloud-to-on-prem/create-new-setup-key-on-prem-db.png" alt="Create setup key" className="imagewrapper"/>
</p>

<Note>
You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**.
</Note>

3. On your on-premise server, run:

```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_SETUP_KEY
```

4. In the Networks view, click **Add Routing Peer** on your On-Premise Data Center network
5. Select your new peer and click **Add Routing Peer**

## Step 6: Deploy NetBird on `cloud-workloads`

Create a setup key for your cloud workloads:

1. In the NetBird dashboard, go to **Setup Keys**
2. Create a new setup key. Add "`cloud-workloads`" to **Auto-assigned groups** and click **Create Setup Key**.

**For VMs:**

```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_CLOUD_SETUP_KEY
```

**For containers (Docker Compose):**

```yaml
services:
  netbird:
    image: netbirdio/netbird:latest
    network_mode: host
    cap_add:
      - NET_ADMIN
    environment:
      - NB_SETUP_KEY=YOUR_SETUP_KEY
    volumes:
      - netbird-config:/etc/netbird
    restart: unless-stopped

volumes:
  netbird-config:
```

**For Kubernetes:**

Use the [NetBird Kubernetes Operator](/manage/integrations/kubernetes) for production deployments.

## Step 7: Verify Cloud Workload Group Assignment

After deploying NetBird on your cloud workloads:

1. Go to **Peers** in the NetBird dashboard
2. Verify your cloud workloads appear and are assigned to the "`cloud-workloads`" group
3. If using a setup key with auto-assigned groups, this happens automatically

## Step 8: Configure Your Application

Update your application's database connection to use the on-premise IP:

```python
# Example: Python with PostgreSQL
conn = psycopg2.connect(
    host="10.100.0.50",  # On-premise database IP
    dbname="production",
    user="app_user",
    password="secure_password"
)
```

Your cloud application can now securely access the on-premise database.

## Cloud-Specific Considerations

### AWS

- Use VPC endpoints where possible for AWS services
- Security groups must allow traffic from the NetBird routing peer
- Consider using an Auto Scaling group for the routing peer with a static ENI

### GCP

- Firewall rules must allow traffic from the routing peer's internal IP
- Use instance groups for high availability
- Enable IP forwarding on the routing peer instance

### Azure

- Network security groups must allow traffic from the routing peer
- Consider using a Virtual Machine Scale Set for HA
- Enable IP forwarding on the routing peer NIC

## Best Practices

### Security

- Use dedicated setup keys per environment (e.g., `dev-workloads`, `staging-workloads`, `prod-workloads`)
- Restrict access policies to specific ports and protocols
- Enable [activity logging](/manage/activity) for compliance

### High Availability

- Deploy multiple routing peers and configure failover
- Monitor routing peer health with your existing tools
- Use cloud-native load balancing where appropriate

### Performance

- Place routing peers close to the resources they serve
- Use direct peering where possible (NetBird will automatically optimize paths)
- Monitor latency and throughput between environments

## Troubleshooting

**Cloud workload can't reach on-premise:**
1. Verify the routing peer is online: `netbird status`
2. Check the routing peer can reach the target: `ping 10.100.0.50`
3. Verify access policies are configured correctly

**High latency:**
1. Check routing peer placement and network connectivity
2. Verify traffic is using direct peer-to-peer connections (not relays)
3. Review cloud network configuration for bottlenecks

## Next Steps

- **Need Multi-Cloud Site-to-Site?** If you need to connect cloud VPCs across providers, see [Site-to-Site: Cloud](/manage/network-routes/use-cases/by-scenario/site-to-site-cloud)
- **Advanced configuration:** See [Advanced Configuration](/manage/network-routes/use-cases/by-configuration/advanced-configuration) for masquerade options and detailed access control