update
This commit is contained in:
270
docs/apiclient.xyz/hetznercloud_readme.md
Normal file
270
docs/apiclient.xyz/hetznercloud_readme.md
Normal file
@ -0,0 +1,270 @@
|
||||
---
|
||||
title: "@apiclient.xyz/hetznercloud"
|
||||
---
|
||||
# @apiclient.xyz/hetznercloud
|
||||
An unofficial API client for the Hetzner Cloud API
|
||||
|
||||
## Install
|
||||
|
||||
You can install the `@apiclient.xyz/hetznercloud` package via npm:
|
||||
|
||||
```bash
|
||||
npm install @apiclient.xyz/hetznercloud
|
||||
```
|
||||
|
||||
Or using yarn:
|
||||
|
||||
```bash
|
||||
yarn add @apiclient.xyz/hetznercloud
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
The `@apiclient.xyz/hetznercloud` package provides a modern approach to interact with the Hetzner Cloud API. Below are some detailed examples demonstrating the usage of this package for different scenarios like managing accounts, servers, volumes, and firewalls.
|
||||
|
||||
### Initial Setup
|
||||
|
||||
To begin using the package, you need to import it and initialize your Hetzner account with an API token:
|
||||
|
||||
```typescript
|
||||
import { HetznerAccount, HetznerServer, Volume, HetznerFirewall } from '@apiclient.xyz/hetznercloud';
|
||||
|
||||
// Initialize Hetzner account
|
||||
const myHetznerAccount = new HetznerAccount('yourHetznerApiToken');
|
||||
```
|
||||
|
||||
### Managing Servers
|
||||
|
||||
#### Creating a Server
|
||||
|
||||
You can create a new server using the `createServer` method in the `HetznerAccount` class. Provide the necessary options such as name, type, location, labels, and optional user data:
|
||||
|
||||
```typescript
|
||||
const newServer = await myHetznerAccount.createServer({
|
||||
name: 'my-server',
|
||||
type: 'cpx31',
|
||||
location: 'nbg1',
|
||||
labels: {
|
||||
purpose: 'test'
|
||||
},
|
||||
userData: '#!/bin/bash\necho Hello from your new server!'
|
||||
});
|
||||
|
||||
console.log('New server details:', newServer.data);
|
||||
```
|
||||
|
||||
#### Listing Servers
|
||||
|
||||
To list all servers in your account, you can use the `getServers` method:
|
||||
|
||||
```typescript
|
||||
const servers = await myHetznerAccount.getServers();
|
||||
console.log('Current servers:', servers);
|
||||
```
|
||||
|
||||
#### Filtering Servers by Labels
|
||||
|
||||
You can filter servers based on specific labels:
|
||||
|
||||
```typescript
|
||||
const filteredServers = await myHetznerAccount.getServersByLabel({ purpose: 'test' });
|
||||
console.log('Filtered servers:', filteredServers);
|
||||
```
|
||||
|
||||
#### Deleting a Server
|
||||
|
||||
To delete a server, call the `delete` method on the server instance:
|
||||
|
||||
```typescript
|
||||
const serverToDelete = filteredServers[0]; // Example, choose the first filtered server
|
||||
await serverToDelete.delete();
|
||||
console.log('Server deleted successfully');
|
||||
```
|
||||
|
||||
### Managing Volumes
|
||||
|
||||
#### Creating a Volume
|
||||
|
||||
To create a new volume, use the `Volume.create` method, passing in the necessary options:
|
||||
|
||||
```typescript
|
||||
const newVolume = await Volume.create(myHetznerAccount, {
|
||||
name: 'my-volume',
|
||||
size: 10, // Size in GB
|
||||
location: 'nbg1',
|
||||
labels: {
|
||||
purpose: 'test-volume'
|
||||
},
|
||||
server: newServer // Attach the volume to a specific server (newServer in this case)
|
||||
});
|
||||
|
||||
console.log('New volume details:', newVolume.data);
|
||||
```
|
||||
|
||||
#### Listing Volumes
|
||||
|
||||
You can list all volumes in your account with the `getVolumes` method:
|
||||
|
||||
```typescript
|
||||
const volumes = await Volume.getVolumes(myHetznerAccount);
|
||||
console.log('Current volumes:', volumes);
|
||||
```
|
||||
|
||||
#### Filtering Volumes by Labels
|
||||
|
||||
To filter volumes based on specific labels:
|
||||
|
||||
```typescript
|
||||
const filteredVolumes = await Volume.getVolumesByLabel(myHetznerAccount, { purpose: 'test-volume' });
|
||||
console.log('Filtered volumes:', filteredVolumes);
|
||||
```
|
||||
|
||||
#### Deleting a Volume
|
||||
|
||||
To delete a volume, call the `delete` method on the volume instance:
|
||||
|
||||
```typescript
|
||||
const volumeToDelete = filteredVolumes[0]; // Example, choose the first filtered volume
|
||||
await volumeToDelete.delete();
|
||||
console.log('Volume deleted successfully');
|
||||
```
|
||||
|
||||
### Managing Firewalls
|
||||
|
||||
#### Creating a Firewall
|
||||
|
||||
To create a new firewall, use the `create` method in the `HetznerFirewall` class:
|
||||
|
||||
```typescript
|
||||
const newFirewall = await HetznerFirewall.create(myHetznerAccount, {
|
||||
name: 'my-firewall',
|
||||
labels: {
|
||||
purpose: 'test-firewall'
|
||||
},
|
||||
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']
|
||||
}
|
||||
]
|
||||
});
|
||||
|
||||
console.log('New firewall details:', newFirewall.data);
|
||||
```
|
||||
|
||||
#### Listing Firewalls
|
||||
|
||||
To list all firewalls in your account:
|
||||
|
||||
```typescript
|
||||
const firewalls = await HetznerFirewall.getFirewalls(myHetznerAccount);
|
||||
console.log('Current firewalls:', firewalls);
|
||||
```
|
||||
|
||||
#### Filtering Firewalls by Labels
|
||||
|
||||
To filter firewalls based on specific labels:
|
||||
|
||||
```typescript
|
||||
const filteredFirewalls = await HetznerFirewall.getFirewallsByLabel(myHetznerAccount, { purpose: 'test-firewall' });
|
||||
console.log('Filtered firewalls:', filteredFirewalls);
|
||||
```
|
||||
|
||||
#### Deleting a Firewall
|
||||
|
||||
To delete a firewall, call the `delete` method on the firewall instance:
|
||||
|
||||
```typescript
|
||||
const firewallToDelete = filteredFirewalls[0]; // Example, choose the first filtered firewall
|
||||
await firewallToDelete.delete();
|
||||
console.log('Firewall deleted successfully');
|
||||
```
|
||||
|
||||
### Example: Full Lifecycle Management
|
||||
|
||||
Here is a complete example that demonstrates the full lifecycle of creating, listing, filtering, and deleting servers, volumes, and firewalls:
|
||||
|
||||
```typescript
|
||||
import { HetznerAccount, HetznerServer, Volume, HetznerFirewall } from '@apiclient.xyz/hetznercloud';
|
||||
|
||||
// Initialize Hetzner account
|
||||
const myHetznerAccount = new HetznerAccount('yourHetznerApiToken');
|
||||
|
||||
// Step 1: Create a new server
|
||||
const newServer = await myHetznerAccount.createServer({
|
||||
name: 'my-server',
|
||||
type: 'cpx31',
|
||||
location: 'nbg1',
|
||||
labels: { purpose: 'test' },
|
||||
userData: '#!/bin/bash\necho Hello from your new server!'
|
||||
});
|
||||
console.log('New server created:', newServer.data);
|
||||
|
||||
// Step 2: Create a new volume and attach it to the server
|
||||
const newVolume = await Volume.create(myHetznerAccount, {
|
||||
name: 'my-volume',
|
||||
size: 10, // GB
|
||||
location: 'nbg1',
|
||||
labels: { purpose: 'test-volume' },
|
||||
server: newServer
|
||||
});
|
||||
console.log('New volume created:', newVolume.data);
|
||||
|
||||
// Step 3: Create a new firewall and attach rules to it
|
||||
const newFirewall = await HetznerFirewall.create(myHetznerAccount, {
|
||||
name: 'my-firewall',
|
||||
labels: { purpose: 'test-firewall' },
|
||||
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'] }
|
||||
]
|
||||
});
|
||||
console.log('New firewall created:', newFirewall.data);
|
||||
|
||||
// Step 4: List all servers, volumes, and firewalls
|
||||
const servers = await myHetznerAccount.getServers();
|
||||
console.log('All servers:', servers);
|
||||
|
||||
const volumes = await Volume.getVolumes(myHetznerAccount);
|
||||
console.log('All volumes:', volumes);
|
||||
|
||||
const firewalls = await HetznerFirewall.getFirewalls(myHetznerAccount);
|
||||
console.log('All firewalls:', firewalls);
|
||||
|
||||
// Step 5: Filter servers, volumes, and firewalls by labels
|
||||
const filteredServers = await myHetznerAccount.getServersByLabel({ purpose: 'test' });
|
||||
console.log('Filtered servers:', filteredServers);
|
||||
|
||||
const filteredVolumes = await Volume.getVolumesByLabel(myHetznerAccount, { purpose: 'test-volume' });
|
||||
console.log('Filtered volumes:', filteredVolumes);
|
||||
|
||||
const filteredFirewalls = await HetznerFirewall.getFirewallsByLabel(myHetznerAccount, { purpose: 'test-firewall' });
|
||||
console.log('Filtered firewalls:', filteredFirewalls);
|
||||
|
||||
// Step 6: Cleanup - Delete created resources
|
||||
for (const server of filteredServers) {
|
||||
await server.delete();
|
||||
console.log('Server deleted:', server.data);
|
||||
}
|
||||
|
||||
for (const volume of filteredVolumes) {
|
||||
await volume.delete();
|
||||
console.log('Volume deleted:', volume.data);
|
||||
}
|
||||
|
||||
for (const firewall of filteredFirewalls) {
|
||||
await firewall.delete();
|
||||
console.log('Firewall deleted:', firewall.data);
|
||||
}
|
||||
```
|
||||
|
||||
This comprehensive example demonstrates how you can manage your Hetzner resources using the `@apiclient.xyz/hetznercloud` package efficiently and effectively.
|
||||
undefined
|
||||
Reference in New Issue
Block a user