Skip to content

Hetzner Cloud

The Hetzner provider lets you manage Hetzner Cloud infrastructure from cdkx. It uses the Hetzner Cloud API and is available as a separate package.

Installation

npm install @cdk-x/hetzner

Authentication

The provider reads your API token from the HCLOUD_TOKEN environment variable. Generate a token in the Hetzner Cloud Console under Project → Security → API Tokens.

export HCLOUD_TOKEN=your-api-token
cdkx deploy

Keep your token secret

Never commit HCLOUD_TOKEN to source control. Use environment variables, a secrets manager, or a .env file excluded from git.

Supported resources

Construct Type string Description
HtzNetwork Hetzner::Networking::Network Private network (VPC-like)
HtzSubnet Hetzner::Networking::Subnet Subnet within a network
HtzRoute Hetzner::Networking::Route Static route added to a network
HtzServer Hetzner::Compute::Server Virtual machine
HtzPlacementGroup Hetzner::Compute::PlacementGroup Controls physical server placement for high availability
HtzSshKey Hetzner::Security::SshKey SSH public key for server access
HtzCertificate Hetzner::Security::Certificate TLS certificate (uploaded or Let's Encrypt managed)
HtzVolume Hetzner::Storage::Volume Persistent block storage volume
HtzVolumeAttachment Hetzner::Storage::VolumeAttachment Attaches a volume to a server
HtzFloatingIp Hetzner::Networking::FloatingIp Static public IP independent of servers
HtzFloatingIpAssignment Hetzner::Networking::FloatingIpAssignment Assigns a floating IP to a server
HtzPrimaryIp Hetzner::Networking::PrimaryIp Pre-allocatable static public IP bound to a location
HtzLoadBalancer Hetzner::Compute::LoadBalancer Distributes traffic across backend targets
HtzLoadBalancerService Hetzner::Compute::LoadBalancerService Listener port and health check on a load balancer
HtzLoadBalancerTarget Hetzner::Compute::LoadBalancerTarget Backend server, label selector, or IP registered to a load balancer

Quick example

src/main.ts
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import { App, Stack } from '@cdk-x/core';
import {
  HtzNetwork,
  HtzSubnet,
  HtzServer,
  ServerType,
  NetworkZone,
} from '@cdk-x/hetzner';

const app = new App();
const stack = new Stack(app, 'MyStack');

const network = new HtzNetwork(stack, 'Network', { // (1)!
  name: 'my-network',
  ipRange: '10.0.0.0/8',
});

const subnet = new HtzSubnet(stack, 'Subnet', { // (2)!
  networkId: network.attrNetworkId,
  type: 'cloud',
  networkZone: NetworkZone.EU_CENTRAL,
  ipRange: '10.0.1.0/24',
});

new HtzServer(stack, 'Server', { // (3)!
  name: 'web-1',
  serverType: ServerType.CX22,
  image: 'ubuntu-24.04',
  networks: [subnet.networkId],
});

app.synth();
  1. Creates a private network — the foundation for all private networking.
  2. Carves out a /24 subnet. References the network's ID via a token — deployed after the network.
  3. A cx22 server booted with Ubuntu 24.04.

See also