266 lines
8.2 KiB
Markdown
266 lines
8.2 KiB
Markdown
# @apiclient.xyz/hetznercloud
|
|
|
|
`@apiclient.xyz/hetznercloud` is an unofficial TypeScript client for the Hetzner Cloud API. It wraps the day-to-day infrastructure primitives this package currently supports - servers, volumes, and firewalls - behind small classes that keep the original Hetzner resource data available while giving you convenient methods for create, list, label-filter, and delete workflows.
|
|
|
|
## Issue Reporting and Security
|
|
|
|
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
|
|
|
|
## Why Use It?
|
|
|
|
- TypeScript-first ESM package for Hetzner Cloud automation.
|
|
- Simple `HetznerAccount` object that owns API token authentication.
|
|
- Resource classes for `HetznerServer`, `HetznerVolume`, and `HetznerFirewall`.
|
|
- Label-based lookup helpers for predictable automation runs.
|
|
- Typed request and response shapes generated from the Hetzner OpenAPI specification.
|
|
- Escape hatch via `account.request()` whenever you need an endpoint that does not yet have a higher-level class method.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
pnpm add @apiclient.xyz/hetznercloud
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```typescript
|
|
import {
|
|
HetznerAccount,
|
|
HetznerFirewall,
|
|
HetznerVolume,
|
|
} from '@apiclient.xyz/hetznercloud';
|
|
|
|
const account = new HetznerAccount('your-hetzner-api-token');
|
|
|
|
const server = await account.createServer({
|
|
name: 'demo-api-01',
|
|
type: 'cpx31',
|
|
location: 'nbg1',
|
|
labels: {
|
|
app: 'demo-api',
|
|
environment: 'staging',
|
|
},
|
|
userData: '#!/bin/bash\napt-get update',
|
|
});
|
|
|
|
const volume = await HetznerVolume.create(account, {
|
|
name: 'demo-api-data',
|
|
size: 25,
|
|
location: 'nbg1',
|
|
labels: {
|
|
app: 'demo-api',
|
|
environment: 'staging',
|
|
},
|
|
server,
|
|
});
|
|
|
|
const firewall = await HetznerFirewall.create(account, {
|
|
name: 'demo-api-web',
|
|
labels: {
|
|
app: 'demo-api',
|
|
environment: 'staging',
|
|
},
|
|
rules: [
|
|
{
|
|
direction: 'in',
|
|
protocol: 'tcp',
|
|
port: '443',
|
|
source_ips: ['0.0.0.0/0', '::/0'],
|
|
},
|
|
],
|
|
});
|
|
|
|
console.log(server.data);
|
|
console.log(volume.data);
|
|
console.log(firewall.data);
|
|
```
|
|
|
|
## Core Concepts
|
|
|
|
### Accounts
|
|
|
|
`HetznerAccount` stores your Hetzner Cloud API token and exposes the shared request layer used by all resource classes.
|
|
|
|
```typescript
|
|
import { HetznerAccount } from '@apiclient.xyz/hetznercloud';
|
|
|
|
const account = new HetznerAccount('your-hetzner-api-token');
|
|
```
|
|
|
|
Available account helpers:
|
|
|
|
- `account.getServers()` lists all servers visible to the token.
|
|
- `account.getServersByLabel(labels)` lists servers and returns exact label matches.
|
|
- `account.createServer(options)` creates a new server.
|
|
- `account.request(method, path, payload)` calls the Hetzner Cloud API directly.
|
|
|
|
The direct request helper returns an object shaped like this:
|
|
|
|
```typescript
|
|
const response = await account.request('GET', '/servers', {});
|
|
|
|
console.log(response.statusCode);
|
|
console.log(response.body);
|
|
```
|
|
|
|
The current implementation logs request metadata and response bodies to the console, which is useful during automation debugging and important to remember when running with sensitive payloads.
|
|
|
|
### Servers
|
|
|
|
Servers are represented by `HetznerServer`. The package can create, list, filter, and delete them.
|
|
|
|
```typescript
|
|
const server = await account.createServer({
|
|
name: 'worker-01',
|
|
type: 'cpx41',
|
|
location: 'fsn1',
|
|
labels: {
|
|
role: 'worker',
|
|
},
|
|
userData: '#!/bin/bash\necho ready',
|
|
});
|
|
|
|
const allServers = await account.getServers();
|
|
const workerServers = await account.getServersByLabel({ role: 'worker' });
|
|
|
|
await server.delete();
|
|
```
|
|
|
|
`createServer()` currently creates Ubuntu 22.04 servers, starts them immediately, and enables public IPv4 and IPv6 networking.
|
|
|
|
Supported server type names are:
|
|
|
|
```text
|
|
cx11, cx21, cx31, cx41, cx51,
|
|
ccx11, ccx21, ccx31, ccx41, ccx51,
|
|
ccx13, ccx23, ccx33, ccx43, ccx53, ccx63,
|
|
cpx11, cpx21, cpx31, cpx41, cpx51, cpx61, cpx70, cpx71, cpx90
|
|
```
|
|
|
|
Supported location names are:
|
|
|
|
```text
|
|
fsn1, nbg1, hel1, ash, hil
|
|
```
|
|
|
|
### Volumes
|
|
|
|
Volumes are represented by `HetznerVolume`. A volume is created for and attached to an existing `HetznerServer` instance.
|
|
|
|
```typescript
|
|
import { HetznerVolume } from '@apiclient.xyz/hetznercloud';
|
|
|
|
const volume = await HetznerVolume.create(account, {
|
|
name: 'worker-01-data',
|
|
size: 50,
|
|
location: 'fsn1',
|
|
labels: {
|
|
role: 'worker',
|
|
},
|
|
server,
|
|
});
|
|
|
|
const allVolumes = await HetznerVolume.getVolumes(account);
|
|
const workerVolumes = await HetznerVolume.getVolumesByLabel(account, { role: 'worker' });
|
|
|
|
await volume.delete();
|
|
```
|
|
|
|
`HetznerVolume.create()` currently formats new volumes as `xfs` and attaches them to `options.server.data.id`.
|
|
|
|
### Firewalls
|
|
|
|
Firewalls are represented by `HetznerFirewall`. The package can create firewalls with rules, list them, filter them by label, and delete them.
|
|
|
|
```typescript
|
|
import { HetznerFirewall } from '@apiclient.xyz/hetznercloud';
|
|
|
|
const firewall = await HetznerFirewall.create(account, {
|
|
name: 'web-ingress',
|
|
labels: {
|
|
app: 'frontend',
|
|
},
|
|
rules: [
|
|
{
|
|
direction: 'in',
|
|
protocol: 'tcp',
|
|
port: '80',
|
|
source_ips: ['0.0.0.0/0', '::/0'],
|
|
},
|
|
{
|
|
direction: 'in',
|
|
protocol: 'tcp',
|
|
port: '443',
|
|
source_ips: ['0.0.0.0/0', '::/0'],
|
|
},
|
|
],
|
|
});
|
|
|
|
const allFirewalls = await HetznerFirewall.getFirewalls(account);
|
|
const frontendFirewalls = await HetznerFirewall.getFirewallsByLabel(account, { app: 'frontend' });
|
|
|
|
await firewall.delete();
|
|
```
|
|
|
|
### Label Filtering
|
|
|
|
The label helpers perform exact matches for every key/value pair you pass in. This makes them practical for idempotent automation where labels are your resource ownership contract.
|
|
|
|
```typescript
|
|
const servers = await account.getServersByLabel({
|
|
app: 'demo-api',
|
|
environment: 'staging',
|
|
});
|
|
```
|
|
|
|
## Direct API Access
|
|
|
|
Use `account.request()` when you need access to an endpoint that is not wrapped yet. Pass the HTTP method, the API path below `/v1`, and a payload object.
|
|
|
|
```typescript
|
|
const locationsResponse = await account.request('GET', '/locations', {});
|
|
|
|
if (locationsResponse.statusCode >= 200 && locationsResponse.statusCode < 300) {
|
|
console.log(locationsResponse.body);
|
|
}
|
|
```
|
|
|
|
For non-`GET` and non-`DELETE` requests, the payload is sent as JSON.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm test
|
|
pnpm run build
|
|
```
|
|
|
|
Tests use `@git.zone/tstest`. Live Hetzner API tests look for `HETZNER_API_TOKEN`; without a usable token, the live API parts are skipped.
|
|
|
|
The OpenAPI types can be refreshed with:
|
|
|
|
```bash
|
|
pnpm run updateOpenapi
|
|
```
|
|
|
|
## License and Legal Information
|
|
|
|
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.
|
|
|
|
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
|
|
|
|
### Trademarks
|
|
|
|
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
|
|
|
|
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
|
|
|
|
### Company Information
|
|
|
|
Task Venture Capital GmbH
|
|
Registered at District Court Bremen HRB 35230 HB, Germany
|
|
|
|
For any legal inquiries or further information, please contact us via email at hello@task.vc.
|
|
|
|
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
|