hetzner-deploy

Hetzner Cloud CLI スキル

hcloud CLI を使用して Hetzner Cloud 上のインフラストラクチャをプロビジョニングおよび管理するためのスキルです。以下の判断ツリーで適切なコマンドグループを見つけてから、詳細なリファレンスを読み込んでください。

Hetzner Cloud の料金、サーバータイプ、ロケーション、API の動作に関する情報は古くなっている可能性があります。具体的な数値、利用可能なタイプ、設定オプションを示す場合は、事前学習済みの知識よりも情報の取得を優先してください。このスキルに付属するリファレンスファイルは、公式 CLI ドキュメントから抜粋した出発点です。

認証

CLI は API トークンを使用して認証します。HCLOUD_TOKEN 環境変数を設定するか、名前付きコンテキストを作成してください。

# Stateless (CI, scripting, agent use)
export HCLOUD_TOKEN="your-api-token"

# Named context (interactive use)
hcloud context create my-project

トークンは、プロジェクトの Security > API Tokens にある https://console.hetzner.cloud で生成できます。

インストール

# macOS / Linux (Homebrew)
brew install hcloud

# Linux (binary)
curl -sSLO https://github.com/hetznercloud/cli/releases/latest/download/hcloud-linux-amd64.tar.gz
sudo tar -C /usr/local/bin --no-same-owner -xzf hcloud-linux-amd64.tar.gz hcloud

# Docker
docker run --rm -e HCLOUD_TOKEN="$HCLOUD_TOKEN" hetznercloud/cli:latest <command>

クイック判断ツリー

「コンピューティングが必要」

Need a server?
├─ Create a new server → hcloud server create --name <n> --type <t> --image <img>
├─ With cloud-init user data → add --user-data-from-file <path>
├─ With firewall + network → add --firewall <fw> --network <net>
├─ List available types → hcloud server-type list
├─ List available images → hcloud image list
├─ SSH into server → hcloud server ssh <name>
├─ Create snapshot → hcloud server create-image --type snapshot <name>
├─ Rescue mode → hcloud server enable-rescue <name>
└─ Delete server → hcloud server delete <name>

「ネットワーキングが必要」

Need networking?
├─ Private network (VPC) → hcloud network create --name <n> --ip-range <cidr>
│  ├─ Add subnet → hcloud network add-subnet --network <n> --type cloud --network-zone <z> --ip-range <cidr>
│  └─ Attach server → hcloud server attach-to-network --network <n> --server <s>
├─ Firewall → hcloud firewall create --name <n> --rules-file <json>
│  ├─ Apply to server → hcloud firewall apply-to-resource --firewall <n> --type server --server <s>
│  └─ Replace rules → hcloud firewall replace-rules --rules-file <json> <name>
├─ Load balancer → hcloud load-balancer create --name <n> --type <t> --location <loc>
│  ├─ Add target → hcloud load-balancer add-target --server <s> <lb>
│  └─ Add service → hcloud load-balancer add-service --protocol <p> --listen-port <port> <lb>
├─ Floating IP → hcloud floating-ip create --type ipv4 --home-location <loc>
│  └─ Assign → hcloud floating-ip assign <ip> --server <s>
└─ Primary IP → hcloud primary-ip create --name <n> --type ipv4 --datacenter <dc>

「ストレージが必要」

Need storage?
├─ Block volume → hcloud volume create --name <n> --size <gb> --server <s> --automount --format ext4
│  ├─ Resize → hcloud volume resize --size <gb> <name>
│  └─ Detach → hcloud volume detach <name>
└─ Storage Box (managed NFS/CIFS/SCP) → hcloud storage-box create --name <n> --type <t> --location <loc>
   ├─ Subaccounts → hcloud storage-box subaccount create <box>
   └─ Snapshots → hcloud storage-box snapshot create <box>

「DNS が必要」

Need DNS?
├─ Create zone → hcloud zone create --name <domain>
├─ Add records → hcloud zone add-records --zone <z> --type A --name <n> --value <ip>
├─ Set full record set → hcloud zone set-records --zone <z> --type A --name <n> --value <ip1> --value <ip2>
├─ Import zone file → hcloud zone import-zonefile --zone <z> <file>
├─ Export zone file → hcloud zone export-zonefile <zone>
└─ Manage individual RRSets → hcloud zone rrset list <zone>

「情報が必要」

Need reference data?
├─ Server types + pricing → hcloud server-type list / describe <type>
├─ Locations → hcloud location list / describe <loc>
├─ Datacenters → hcloud datacenter list / describe <dc>
├─ Available images → hcloud image list
├─ ISO images → hcloud iso list
├─ Load balancer types → hcloud load-balancer-type list
└─ Storage box types → hcloud storage-box-type list

「CLI の設定が必要」

Need CLI config?
├─ Create context → hcloud context create <name>
├─ Switch context → hcloud context use <name>
├─ Set default SSH key → hcloud config set default-ssh-keys <key>
├─ View config → hcloud config list
└─ Shell completion → hcloud completion bash/zsh/fish

一般的なワークフロー

サーバーのクイックデプロイ

# Upload SSH key, create server, connect
hcloud ssh-key create --name deploy-key --public-key-from-file ~/.ssh/id_ed25519.pub
hcloud server create --name web-1 --type cpx21 --image ubuntu-24.04 --ssh-key deploy-key --location fsn1
hcloud server ssh web-1

ネットワークとファイアウォールを含むフルスタック

# Network
hcloud network create --name prod-net --ip-range 10.0.0.0/16
hcloud network add-subnet --network prod-net --type cloud --network-zone eu-central --ip-range 10.0.1.0/24

# Firewall (allow SSH + HTTP/S)
cat > rules.json << 'EOF'
[
  {"direction":"in","protocol":"tcp","port":"22","source_ips":["0.0.0.0/0","::/0"]},
  {"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"]}
]
EOF
hcloud firewall create --name web-fw --rules-file rules.json

# Server with network + firewall
hcloud server create --name app-1 --type cpx21 --image ubuntu-24.04 \
  --ssh-key deploy-key --network prod-net --firewall web-fw --location fsn1

# Load balancer
hcloud load-balancer create --name web-lb --type lb11 --location fsn1
hcloud load-balancer attach-to-network --network prod-net web-lb
hcloud load-balancer add-target --server app-1 web-lb
hcloud load-balancer add-service --protocol tcp --listen-port 80 --destination-port 80 web-lb

出力形式

すべての describe、list、create コマンドは、スクリプトやエージェントで使用するための構造化出力に対応しています。

hcloud server list --output json          # JSON array
hcloud server describe my-srv --output yaml  # YAML
hcloud server describe my-srv --output format='{{.ServerType.Cores}}'  # Go template
hcloud server list --output columns=id,name,status  # Custom table columns

リソース一覧

コンピューティング

リソース	リファレンス
サーバー	references/server/
サーバータイプ	references/info/

ネットワーキング

リソース	リファレンス
ネットワーク（VPC）	references/network/
ファイアウォール	references/firewall/
ロードバランサー	references/load-balancer/
フローティング IP	references/floating-ip/
プライマリ IP	references/primary-ip/

ストレージ

リソース	リファレンス
ボリューム	references/volume/
Storage Box	references/storage-box/

DNS

リソース	リファレンス
ゾーンとレコード	references/dns/

セキュリティとアクセス

リソース	リファレンス
SSH キー	references/ssh-key/
証明書	references/certificate/
イメージ	references/image/
プレースメントグループ	references/placement-group/

リファレンスデータ

リソース	リファレンス
サーバータイプ、LB タイプ、Storage Box タイプ、データセンター、ロケーション、ISO	references/info/

CLI の設定

リソース	リファレンス
設定、コンテキスト、補完	references/config/
すべてのリソース	references/all/
Raw API 呼び出し	references/api/

はじめに

リソース	リファレンス
セットアップ、サーバーチュートリアル、出力オプション、設定	references/getting-started/