Client VPN

WireGuard into a network: reach a private database from your laptop.

What it is

A WireGuard gateway into one of your networks, so a person — or a CI job — can reach what is private on purpose: a managed database, a cache, an app's machines. Nothing is made public for it. Each peer reaches only the resources it was granted, and a revoked peer stops working within about 20 seconds. Find it under Client VPN in the console.

It is opt-in. No gateway exists until someone creates one, and a gateway is a small machine billed by the hour.

Concepts

Term Meaning
Gateway One WireGuard machine in one network — the only thing in it with a public port (UDP 51820). One gateway per network.
Peer One person's (or machine's) key on the gateway: a name, a WireGuard public key, a tunnel address and what it may reach.
Target What a peer may reach, written type:id: vpc:<id> (the whole network), database:ewdb-…, cache:ewc-…, app:<id> (the app's machines) or instance:i-….
Key pair Made on your own computer — in the browser, by the CLI, or with wg genkey. Deutsche Cloud receives the public key only; the private key exists only in the .conf file you download.
Tunnel range 100.96.0.0/24. The gateway is 100.96.0.1; peers get the next free address. Carrier-grade NAT space, so it never collides with one of your networks or the one you are on.
Expiry A peer stops working after 30 days unless another expiry is chosen (at most 365).
Activity The gateway's event stream: provisioning, every peer created and revoked, and every connection with where it came from.

How to

Create a gateway

Client VPN → Create gateway, choose the network (the default one is where apps, databases and caches run) and confirm the monthly price shown on the button. Or:

dcloud vpn endpoints node-types        # the price; the default machine is marked
dcloud vpn endpoints create            # the default VPC; --vpc-id for another
POST /vpn/api/endpoints
{}

The gateway is creating until its machine has started WireGuard and reported its public key, usually within two minutes; then it is available.

Make the gateway highly available

Choose Two gateways, automatic failover under Availability, or pass { "highlyAvailable": true }. You get:

  • Two gateway machines in different zones (de1a and de1b; on different hosts of one zone when the size is out of stock in the other), both running the same WireGuard key and the same peers.
  • One address. The endpoint's public address is a floating IP that the active gateway holds. Peer files name it, and they never change.
  • Automatic failover. Each gateway checks in every 15 seconds. When the active one has missed two check-ins, the standby takes over the floating IP. Connected clients reconnect on their own: WireGuard starts a new handshake within seconds, against the same key at the same address. Expect up to about 45 seconds without access while that happens. Connections that were open through the old gateway (an SSH or database session) break and have to be opened again: the standby forwards from its own address in the network.
  • Automatic replacement. A standby that has not checked in for 5 minutes (after a failover, that is the gateway that failed) is deleted and replaced by a new machine with the same name, address and key, so the endpoint is back to two gateways without anyone acting. The address does not move back: the replacement becomes the new standby.
  • The gateway page shows both gateways, which one is active, when each last checked in, and the last failover. Each failover and replacement is recorded in Activity.

Unlike a single gateway, which makes its own key, the key of a highly available pair is made by Deutsche Cloud and filed in Secrets (VPN_<ID>_GATEWAY_KEY): both machines must run the same one, and a rebuilt gateway can run it again, so your peer files keep working. Both machines are billed. A gateway keeps the availability it was created with.

Give a developer access to an app

The usual way in. On the app's page, VPN access:

  1. If the app's network has no gateway, Create gateway — the button names the monthly price, and nothing exists until it is pressed. It is available within about a minute.
  2. Create access opens the peer dialog with what the app uses already ticked: its bound databases and caches. Its own machines are offered, unticked. Name the peer, adjust, Create peer, and download the .conf.

Who has access below lists the active peers that reach anything of the app's. From a terminal, the same in one step:

dcloud vpn apps access <app-id>                                # its VPC, gateway, and targets
dcloud vpn peers connect --app <app-id> --name alice-laptop    # bound databases and caches
dcloud vpn peers connect --app <app-id> --name alice-laptop --machines   # …and its machines

--app finds the gateway of the app's network; if there is none it says what one costs and prints the dcloud vpn endpoints create --vpc-id … to create it. Add --target type:id for anything else. Each target still needs vpn:CreateClientVpnPeer on it, and the app needs deploy:DescribeApp.

Add a peer in the console

On the gateway's page, Add peer: give it a name, tick what it may reach, choose an expiry and Create peer. The browser makes the key pair and sends only the public key. The finished .conf is shown once — Download .conf, or scan the QR code with the WireGuard phone app. Close the dialog and the private key is gone; for a new one, revoke the peer and add another.

Add a peer with the CLI

dcloud vpn endpoints targets ewvpn-0123456789ab          # what can be granted, with addresses
dcloud vpn peers connect ewvpn-0123456789ab \
  --name alice-laptop \
  --target database:ewdb-payments \
  --out alice-laptop.conf

connect makes the key pair on your computer, creates the peer, and writes the .conf with the private key filled in (mode 0600). Bring the tunnel up with the WireGuard app (Import tunnel from file) or:

sudo wg-quick up ./alice-laptop.conf
sudo wg-quick down ./alice-laptop.conf

To bring your own key instead, send its public half: wg genkey | tee key | wg pubkey, then dcloud vpn peers create <gateway> --name … --public-key … --targets '[{"type":"database","id":"ewdb-…"}]', and put the private key into the returned config where it says <your private key>.

Look into your app's database with a GUI client

The app's database is private: only machines in its network reach it. With a peer granted that database:

  1. Find the database. Databases → your database → Connection shows its private name, ewdb-….private.db.apps.<root domain>, its master user and the secret that holds the password (PG_<NAME>_PASSWORD in Secrets). dcloud vpn endpoints targets <gateway> lists the same name.
  2. Create the peer granted database:<id> (above) and bring the tunnel up.
  3. Download the CA bundle so the client can verify the certificate: Databases → Connection → Download CA, or dcloud rds ca-bundle download --out dcloud-ca.pem.
  4. Connect with the private name — the same name the app uses. The platform's public nameservers answer it with the private address, so no DNS setting is needed; the tunnel carries the traffic.
    • psql: psql "host=ewdb-….private.db.apps.<root> port=5432 dbname=postgres user=<master user> sslmode=verify-full sslrootcert=dcloud-ca.pem"
    • TablePlus / DBeaver / pgAdmin / DataGrip: host = the private name, port 5432, user and password as above, SSL mode verify-full (or "Require"/"Verify identity") with the CA file as the root certificate.
  5. Disconnect when done, and revoke the peer when nobody needs it.

The database sees the gateway's network address, not yours — who connected, from where and when is on the gateway's Activity and in the peer list.

Revoke a peer

The gateway page, Revoke on the peer, or dcloud vpn peers revoke ewpeer-…. The gateway polls every 15 seconds and drops it on the next sync — measured on dev at 16 s from the revoke to the gateway applying it, 19 s until the tunnel stopped passing traffic. The peer stays listed as revoked.

Delete the gateway

The gateway page, Delete gateway, or dcloud vpn endpoints delete ewvpn-…. Every peer stops on the next sync, the machine and its firewall are removed, and billing stops.

Permissions

Action Allows
vpn:DescribeClientVpnEndpoints Listing gateways, their price, their activity and what could be granted.
vpn:CreateClientVpnEndpoint Creating a gateway.
vpn:DeleteClientVpnEndpoint Deleting a gateway.
vpn:DescribeClientVpnConnections Listing peers with their last handshake and traffic.
vpn:CreateClientVpnPeer Creating a peer. Checked on the gateway and on every target, under the target's own RN.
vpn:RevokeClientVpnPeer Revoking a peer.

So "Alice may open a tunnel to the payments database, and nothing else" is:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "vpn:CreateClientVpnPeer",
      "Resource": [
        "rn:ews:de1:<org id>:vpn:endpoint/ewvpn-0123456789ab",
        "rn:ews:de1:<org id>:rds:db/ewdb-payments"
      ]
    }
  ]
}

Run outside Germany (Helsinki, fi1)

Gateways are in Germany (de1) unless your organization decides otherwise. After an administrator turns on Allow EU locations outside Germany (Settings → Data location), choose region fi1 in the create form, or send "regionId": "fi1" (CLI --region fi1). The gateway machine(s) and the public address are in Helsinki, Finland, and it forwards into a network in fi1. A highly available pair is on two hosts in the one Helsinki zone. Without the setting the create answers 403.

Reference

Gateway

Item Value
Machine performance-1 unless another node type is given
Public ports UDP 51820 (WireGuard). Nothing else.
Key Generated on the gateway at first boot; never leaves it.
Peer list Fetched from the console every 15 seconds; a change applies within one sync.
Enforcement nftables on the gateway: each peer may reach only its granted addresses; everything else is dropped.
NAT Peer traffic leaves the gateway from its network address, so no database or cache firewall has to change.
Client config AllowedIPs is the network range (what your computer routes into the tunnel); the gateway decides what is reachable.

Statuses

Status Meaning
creating The machine is being built, or has not reported its key yet.
available WireGuard is up; peers can be added.
deleting Every peer is dropped and the machine is being removed.
failed Provisioning failed; the reason is on the gateway page and in Activity.

Billing

One gateway-hour per hour the machine exists, at the machine's price (vpn.<node type>.hour); a highly available gateway is two machines, so two gateway-hours. The floating IP is not billed. Traffic is not billed separately.

What is not supported

  • More than one gateway endpoint per network (a highly available one has two machines behind one endpoint).
  • Turning high availability on or off for an existing gateway: create a new one.
  • Replacing a failed gateway machine automatically: after a failover the endpoint runs on one machine until the failed one is back (a reboot brings it back as the standby).
  • IPv6 inside the tunnel.
  • Peer-to-peer traffic between two peers.
  • Changing a peer's targets: revoke it and create another.
  • Re-downloading a .conf with its private key — Deutsche Cloud never had it.

Troubleshooting

Symptom Cause Fix
"Not in this gateway's network, or has no private address" The target is in another network, or has no private address yet. Grant something in the gateway's network; dcloud vpn endpoints targets lists what can be granted.
Forbidden creating a peer No vpn:CreateClientVpnPeer on one of the targets. Ask for the permission on that resource, or grant fewer targets.
Handshake but no connection The address is not one the peer was granted. Check the peer's targets; a database's private name must be used, not its public one.
No handshake at all UDP 51820 is blocked on your network, or the peer was revoked. Try another network; check the peer's state.
Certificate does not match Connecting by address instead of the private name. Use ewdb-….private.db.apps.<root>.
Did this page help you?