hetzner

Hetzner Cloud インフラストラクチャ

重大：シークレットと .env

• 稼働中の .env ファイルや認証情報を、スキルフォルダー内に決して保存しないでください。
• .env.template ファイルは、スキル内の assets/ にのみ配置してください。
• 稼働中のシークレットは ~/.admin/.env に保存し、そこから参照してください。

ステータス：本番環境対応済み | 依存関係：hcloud CLI、SSH キーペア

---

ナビゲーション

• 運用、トラブルシューティング、設定、コストの概要：references/OPERATIONS.md

---

ステップ 0：必要な情報を収集する（必須）

停止してください。デプロイコマンドを実行する前に、ユーザーからすべてのパラメーターを収集してください。

このチェックリストをコピーし、各項目を確認してください：

Required Parameters:
- [ ] SERVER_NAME          - Unique name for this server
- [ ] HETZNER_LOCATION     - Location (nbg1, fsn1, hel1, ash, hil)
- [ ] HETZNER_SERVER_TYPE  - Server type (see profiles below)
- [ ] SSH_KEY_NAME         - Name of SSH key in Hetzner
- [ ] SSH_KEY_PATH         - Path to local SSH private key (default: ~/.ssh/id_rsa)

Architecture Choice:
- [ ] ARM64 (CAX*) or x86 (CX*)?
      ARM64 → Only available in EU (nbg1, fsn1, hel1)
      x86   → Available in EU and US (ash, hil)

Deployment Purpose (determines recommended profile):
- [ ] Purpose: coolify / kasm / both / custom
      coolify → CAX11 ARM (~$4/mo) or CX22 x86 (~$5/mo)
      kasm    → CAX21 ARM (~$8/mo) or CX32 x86 (~$10/mo)
      both    → CAX31 ARM (~$16/mo) or CX42 x86 (~$20/mo)

目的別の推奨プロファイル：

目的	ARM（EU のみ）	x86（EU＋US）	vCPU	RAM	月額
coolify	CAX11	CX22	2	4GB	約 $4～5
kasm	CAX21	CX32	4	8GB	約 $8～10
両方	CAX31	CX42	8	16GB	約 $16～20

すべてのパラメーターが確認されるまで、前提条件に進まないでください。

---

前提条件

このスキルを使用する前に、次の項目を確認してください：

1. Hetzner Cloud CLI がインストールされている

hcloud version

インストールされていない場合は、次のコマンドでインストールしてください：

# macOS
brew install hcloud

# Linux (download binary)
curl -sL https://github.com/hetznercloud/cli/releases/latest/download/hcloud-linux-amd64.tar.gz | tar xz
sudo mv hcloud /usr/local/bin/

# Or via package manager (Arch)
pacman -S hcloud

2. Hetzner アカウントと API トークン

Hetzner アカウントをお持ちでない場合：

こちらから登録してください：https://hetzner.cloud/?ref=o3LvvIQgI5gs

開示事項：これは紹介リンクです。€20 分のクラウドクレジットを受け取れます。また、スキルの作成者にも少額のクレジットが付与されます。このリンクの使用は、これらのスキルの開発支援につながります。

API トークンの取得先：https://console.hetzner.cloud/ → Project → Security → API Tokens

Read & Write トークンを作成してください。

3. hcloud CLI の設定

hcloud context list

空の場合は、次のいずれかの方法で設定してください：

方法 A：非対話型（自動化に推奨）：

# Write directly to hcloud config file
mkdir -p ~/.config/hcloud
cat > ~/.config/hcloud/cli.toml << EOF
active_context = "myproject"

[[contexts]]
name = "myproject"
token = "$HETZNER_API_TOKEN"
EOF
chmod 600 ~/.config/hcloud/cli.toml

方法 B：環境変数（一時的、設定は保存されません）：

# Set for current session only - hcloud commands will work but context won't persist
export HCLOUD_TOKEN="$HETZNER_API_TOKEN"
hcloud server list  # Works without context

方法 C：対話型（手動設定）：

hcloud context create myproject
# Enter your API token when prompted

注：自動化には方法 A を推奨します。hcloud context create では対話型の入力が必要で、パイプで渡すことができないためです。

4. SSH キーペア

ls ~/.ssh/id_rsa.pub

ない場合は、次のコマンドで生成してください：

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N ""

5. Hetzner にアップロード済みの SSH キー

hcloud ssh-key list

空の場合は、次のコマンドでアップロードしてください：

hcloud ssh-key create --name my-key --public-key-from-file ~/.ssh/id_rsa.pub

6. 認証のテスト

hcloud server-type list

失敗した場合：トークンが無効または期限切れの可能性があります。新しいトークンを作成してください。

---

サーバープロファイル

プロファイル	サーバータイプ	vCPU	RAM	ストレージ	月額費用
coolify	CAX11（ARM）	2	4GB	40GB	約 $4
kasm	CAX21（ARM）	4	8GB	80GB	約 $8
both	CAX31（ARM）	8	16GB	160GB	約 $16

x86 の代替構成

プロファイル	サーバータイプ	vCPU	RAM	ストレージ	月額費用
coolify	CX22	2	4GB	40GB	約 $5
kasm	CX32	4	8GB	80GB	約 $10
both	CX42	8	16GB	160GB	約 $20

価格とパフォーマンスに優れているため、ARM（CAX）を推奨します。

---

デプロイ手順

ステップ 1：環境変数を設定する

export HETZNER_LOCATION="nbg1"           # nbg1, fsn1, hel1, ash, hil
export HETZNER_SERVER_TYPE="cax21"       # See profiles above
export HETZNER_IMAGE="ubuntu-22.04"
export SERVER_NAME="my-server"
export SSH_KEY_NAME="my-key"

⚠️ ARM サーバーのロケーション互換性： ARM サーバー（CAX11、CAX21、CAX31、CAX41）は、ヨーロッパのロケーションでのみ利用できます。

ロケーション	ARM（CAX）	x86（CX/CPX）
nbg1（ニュルンベルク）	✅ はい	✅ はい
fsn1（ファルケンシュタイン）	✅ はい	✅ はい
hel1（ヘルシンキ）	✅ はい	✅ はい
ash（アシュバーン、米国）	❌ いいえ	✅ はい
hil（ヒルズボロ、米国）	❌ いいえ	✅ はい

米国でのホスティングが必要な場合は、x86 サーバータイプ（CX22、CX32、CPX21 など）を使用してください。

ロケーションの選択肢

コード	ロケーション	地域	ARM の利用可否
nbg1	ニュルンベルク	ドイツ	✅ はい
fsn1	ファルケンシュタイン	ドイツ	✅ はい
hel1	ヘルシンキ	フィンランド	✅ はい
ash	アシュバーン	米国（バージニア州）	❌ いいえ
hil	ヒルズボロ	米国（オレゴン州）	❌ いいえ

ステップ 2：ファイアウォールを作成する

# Create firewall rules
hcloud firewall create --name my-firewall

# Allow SSH
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 22 --source-ips 0.0.0.0/0 --source-ips ::/0

# Allow HTTP/HTTPS
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 80 --source-ips 0.0.0.0/0 --source-ips ::/0
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 443 --source-ips 0.0.0.0/0 --source-ips ::/0

# Allow Coolify ports (if deploying Coolify)
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 8000 --source-ips 0.0.0.0/0 --source-ips ::/0
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 6001-6002 --source-ips 0.0.0.0/0 --source-ips ::/0

# Allow KASM ports (if deploying KASM)
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 8443 --source-ips 0.0.0.0/0 --source-ips ::/0
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 3389 --source-ips 0.0.0.0/0 --source-ips ::/0
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 3000-4000 --source-ips 0.0.0.0/0 --source-ips ::/0

ステップ 3：サーバーを検証して作成する

まず、ARM とロケーションの互換性を検証します：

# Check if trying to use ARM server in US location
if [[ "$HETZNER_SERVER_TYPE" == cax* ]] && [[ "$HETZNER_LOCATION" == ash* || "$HETZNER_LOCATION" == hil* ]]; then
  echo "ERROR: ARM servers (CAX) are not available in US locations ($HETZNER_LOCATION)"
  echo ""
  echo "Options:"
  echo "  1. Switch to European location: nbg1, fsn1, or hel1"
  echo "  2. Switch to x86 server type: cx22, cx32, cpx21, cpx31"
  echo ""
  echo "Recommended fix:"
  echo "  export HETZNER_LOCATION=nbg1    # Switch to Europe"
  echo "  # OR"
  echo "  export HETZNER_SERVER_TYPE=cx22  # Switch to x86"
  exit 1
fi
echo "Server type $HETZNER_SERVER_TYPE is compatible with location $HETZNER_LOCATION"

サーバーを作成します：

hcloud server create \
  --name "$SERVER_NAME" \
  --type "$HETZNER_SERVER_TYPE" \
  --image "$HETZNER_IMAGE" \
  --location "$HETZNER_LOCATION" \
  --ssh-key "$SSH_KEY_NAME" \
  --firewall my-firewall

ステップ 4：サーバーの IP アドレスを取得する

SERVER_IP=$(hcloud server ip "$SERVER_NAME")
echo "SERVER_IP=$SERVER_IP"

ステップ 5：サーバーの準備が整うまで待機する

# Wait for SSH to be available (typically 30-60 seconds)
echo "Waiting for server to be ready..."
until ssh -o ConnectTimeout=5 -o StrictHostKeyChecking=no root@$SERVER_IP "echo connected" 2>/dev/null; do
  sleep 5
done
echo "Server is ready!"

ステップ 6：接続を確認する

ssh root@$SERVER_IP "uname -a && free -h && df -h /"

ステップ 7：後続のスキル向けに出力する

# Determine architecture for downstream skills (cloudflare-tunnel needs this)
if [[ "$HETZNER_SERVER_TYPE" == cax* ]]; then
  SERVER_ARCH="arm64"
else
  SERVER_ARCH="amd64"
fi

# Save to .env.local for downstream skills
echo "SERVER_IP=$SERVER_IP" >> .env.local
echo "SSH_USER=root" >> .env.local
echo "SSH_KEY_PATH=~/.ssh/id_rsa" >> .env.local
echo "SERVER_ARCH=$SERVER_ARCH" >> .env.local
echo "COOLIFY_SERVER_IP=$SERVER_IP" >> .env.local
echo "KASM_SERVER_IP=$SERVER_IP" >> .env.local

echo ""
echo "Server deployed successfully!"
echo "  IP: $SERVER_IP"
echo "  Arch: $SERVER_ARCH"
echo "  SSH: ssh root@$SERVER_IP"

---

デプロイを確認する

ssh root@$SERVER_IP "echo 'Hetzner server connected successfully'"

---

クリーンアップ

警告：この操作は破壊的で、元に戻せません。

# Delete server
hcloud server delete "$SERVER_NAME"

# Delete firewall
hcloud firewall delete my-firewall

# Optionally delete SSH key
# hcloud ssh-key delete my-key

---

運用

トラブルシューティング、ベストプラクティス、構成変数、コストのスナップショットについては、references/OPERATIONS.md を参照してください。

---

ロギングの統合

インフラストラクチャの操作を行う際は、中央システムに記録します：

# After provisioning
log_admin "SUCCESS" "operation" "Provisioned Hetzner server" "id=$SERVER_ID provider=Hetzner"

# After destroying
log_admin "SUCCESS" "operation" "Deleted Hetzner server" "id=$SERVER_ID"

# On error
log_admin "ERROR" "operation" "Hetzner deployment failed" "error=$ERROR_MSG"

ロギングの詳細については、admin スキルの references/logging.md を参照してください。

---

参考資料

• Hetzner Cloud コンソール
• hcloud CLI ドキュメント
• サーバーの種類と料金
• API ドキュメント