Hetzner · Cloud

hcloud CLI: установка, контексты и команды для Hetzner Cloud

Обновлено

hcloud — официальная консольная утилита Hetzner Cloud. Всё, что делается мышкой в Hetzner Console, через неё делается одной командой: создать сервер, сделать снимок, включить Rescue System, открыть порт в файрволе, поменять DNS-запись. Утилита удобна и для скриптов: вывод в JSON, фильтры по меткам, коды возврата. На ноябрь 2026 года актуальна версия 1.70.2 (выпущена 23 октября 2026 года, релизы на GitHub). Ниже — установка, настройка нескольких проектов и шпаргалка по командам, которые нужны чаще всего.

Установка

Способы установки описаны в официальной инструкции.

Linux, готовый бинарный файл:

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
rm hcloud-linux-amd64.tar.gz
hcloud version

Для серверов и компьютеров на ARM замените amd64 на arm64. На странице релизов есть также пакеты .deb и .rpm (Hetzner помечает их как экспериментальные) — они ставят автодополнение и man-страницы.

macOS и Linux через Homebrew: brew install hcloud.

Windows: winget install HetznerCloud.CLI или Scoop. Эти пакеты, по словам Hetzner, поддерживает не сама компания.

Из исходников: go install github.com/hetznercloud/cli/cmd/hcloud@latest (версия в такой сборке не прописывается).

Установка вручную не обновляется сама: раз в несколько месяцев проверяйте hcloud version и ставьте свежий релиз. Новые возможности API (например, управление DNS-зонами и Storage Box) появляются только в новых версиях.

Токен и контексты

Утилита работает с API от имени токена. Токен создаётся в Hetzner Console: откройте проект, раздел Security → API tokens. Права Read подходят для просмотра и инвентаризации, Read & Write — для изменений. Один токен действует только на один проект.

Чтобы не передавать токен в каждой команде, создайте контекст — именованную пару «проект + токен»:

hcloud context create prod          # запросит токен
hcloud context create staging
hcloud context list
hcloud context use prod
hcloud context active

Контексты хранятся в ~/.config/hcloud/cli.toml (в Windows — %APPDATA%\hcloud\cli.toml); файл содержит токены, не публикуйте его и не копируйте на чужие машины. В CI удобнее переменная окружения: HCLOUD_TOKEN имеет приоритет над контекстом, а hcloud context create --token-from-env имя сохранит токен из окружения без вопроса. Для разовой команды в другом проекте используйте глобальный флаг --context staging.

Автодополнение для bash: source <(hcloud completion bash) (добавьте строку в ~/.bashrc); есть варианты для zsh, fish и PowerShell.

Как читать вывод: колонки, JSON, метки

Команды list выводят таблицу. Колонки и их порядок задаются флагом -o columns=…, заголовок убирается -o noheader, сортировка — -s:

hcloud server list -o columns=id,name,status,type,location,ipv4,private_net
hcloud server list -o noheader -o columns=name,ipv4
hcloud server list -s created:desc
hcloud server list --status running

Для скриптов используйте JSON и jq:

hcloud server list -o json | jq -r '.[] | "\(.name)\t\(.public_net.ipv4.ip)"'
hcloud server describe web-1 -o json | jq '.server_type.name, .datacenter.location.name'

Метки (labels) — главный способ группировать ресурсы. По ним фильтруют списки (-l) и применяют файрволы:

hcloud server add-label web-1 role=web env=prod
hcloud server list -l role=web
hcloud server list -l 'env in (prod,stage)'
hcloud server remove-label web-1 env

Серверы: создание и повседневные операции

Сначала посмотрите, из чего выбирать:

hcloud location list
hcloud server-type list -o columns=name,cores,memory,disk,deprecated
hcloud image list -t system -a x86
hcloud ssh-key list

Загрузите ключ и создайте сервер:

hcloud ssh-key create --name laptop --public-key-from-file ~/.ssh/id_ed25519.pub

hcloud server create \
  --name web-1 \
  --type cx23 \
  --image ubuntu-24.04 \
  --location fsn1 \
  --ssh-key laptop \
  --firewall web \
  --label role=web \
  --user-data-from-file cloud-init.yaml

Флаги --ssh-key, --firewall, --network и --volume можно указывать несколько раз. Без --ssh-key Hetzner отправит пароль root на почту — лучше так не делать. Как настроить новый сервер после создания, описано в статье Первый сервер в Hetzner Cloud.

Частые операции:

hcloud server ssh web-1                       # SSH по публичному IPv4 (по умолчанию root, порт 22)
hcloud server ssh -u deploy web-1 uptime      # выполнить команду на сервере
hcloud server shutdown web-1 --wait           # корректное выключение через ACPI
hcloud server poweron web-1
hcloud server reboot web-1
hcloud server reset web-1                     # жёсткий сброс, если система зависла
hcloud server change-type web-1 cx33          # смена типа (сервер должен быть выключен)
hcloud server change-type --keep-disk web-1 cx33   # без увеличения диска: тип можно будет уменьшить
hcloud server enable-protection web-1 delete rebuild

Смена типа без --keep-disk увеличивает диск, и вернуться на тип с меньшим диском уже нельзя. Это частая причина невозможности «откатить» тариф.

Снимки, резервные копии и Rescue

hcloud server create-image --type snapshot --description "before-upgrade" web-1
hcloud image list -t snapshot
hcloud server rebuild --image ID_СНИМКА web-1      # вернуть сервер к снимку (данные на диске будут заменены)
hcloud server enable-backup web-1                   # автоматические копии (платная опция)

hcloud server enable-rescue web-1 --ssh-key laptop  # Rescue System с вашим ключом
hcloud server reboot web-1                          # загрузка в Rescue
hcloud server disable-rescue web-1

Снимок делается и на включённом сервере, но для согласованности баз данных лучше остановить сервисы или выключить сервер. Снимки и резервные копии хранятся только в Hetzner и не скачиваются: для переноса к другому провайдеру нужны собственные бэкапы (например, в Storage Box). В Rescue System работают те же приёмы, что и на выделенных серверах — см. Спасательная система Hetzner.

Файрволы

hcloud firewall create --name web
hcloud firewall add-rule web --direction in --protocol tcp --port 22 --source-ips 203.0.113.10/32
hcloud firewall add-rule web --direction in --protocol tcp --port 443 --source-ips 0.0.0.0/0 --source-ips ::/0
hcloud firewall apply-to-resource web --type label_selector --label-selector role=web
hcloud firewall describe web
hcloud firewall delete-rule web --direction in --protocol tcp --port 22 --source-ips 203.0.113.10/32
hcloud firewall replace-rules web --rules-file rules.json    # заменить все правила разом

Как Cloud Firewall сочетается с ufw на сервере и почему Docker обходит ufw — в статье Hetzner Cloud Firewall или ufw.

Сети, тома и IP-адреса

# приватная сеть
hcloud network create --name main --ip-range 10.0.0.0/16
hcloud network add-subnet main --type cloud --network-zone eu-central --ip-range 10.0.1.0/24
hcloud server attach-to-network web-1 --network main --ip 10.0.1.10

# том (Volume)
hcloud volume create --name data --size 50 --server web-1 --format ext4 --automount
hcloud volume resize data --size 100        # затем расширьте файловую систему: resize2fs
hcloud volume detach data

# адреса
hcloud primary-ip list
hcloud floating-ip create --type ipv4 --home-location fsn1 --name vip
hcloud floating-ip assign vip web-1
hcloud server set-rdns web-1 --ip IP_СЕРВЕРА --hostname web-1.example.ru

Primary IP, созданный отдельно или с выключенным автоудалением, остаётся в проекте и оплачивается после удаления сервера — проверяйте hcloud primary-ip list.

DNS-зоны

DNS-зоны Hetzner управляются через ту же утилиту (команды hcloud zone):

hcloud zone list
hcloud zone rrset list example.ru
hcloud zone set-records --record 203.0.113.20 example.ru www A      # заменить записи www A
hcloud zone add-records --record 203.0.113.21 example.ru www A      # добавить ещё одну
hcloud zone rrset change-ttl --ttl 300 example.ru www A
hcloud zone export-zonefile example.ru > example.ru.zone            # выгрузка в формате BIND
hcloud zone import-zonefile example.ru --zonefile example.ru.zone   # загрузка (заменяет все записи)

Экспорт зоны — первое, что стоит сделать перед любым переездом: файл содержит все записи, включая MX и TXT.

Инвентаризация и контроль расходов

Команда hcloud all list выводит все ресурсы проекта, а с флагом --paid — только платные. Это быстрый способ найти забытый снимок, том или IP-адрес:

hcloud all list --paid
hcloud all list -o json > inventory-$(date +%F).json

Если нужного действия нет среди команд, hcloud api выполняет произвольный запрос к API с токеном текущего контекста:

hcloud api /servers -v label_selector=role=web
hcloud api /pricing

Примеры скриптов

Ежедневный снимок всех серверов с меткой backup=daily (например, из cron на управляющей машине):

#!/usr/bin/env bash
set -euo pipefail
for s in $(hcloud server list -l backup=daily -o noheader -o columns=name); do
  hcloud server create-image --type snapshot \
    --label auto=daily --description "auto-$(date +%F)" "$s"
done

Удаление автоматических снимков старше 14 дней:

#!/usr/bin/env bash
set -euo pipefail
cutoff=$(date -d '14 days ago' +%s)
hcloud image list -t snapshot -l auto=daily -o json |
  jq -r --argjson c "$cutoff" '.[] | select((.created | sub("\\+00:00$"; "Z") | fromdateiso8601) < $c) | .id' |
  while read -r id; do hcloud image delete "$id"; done

Перед запуском удаления выполните скрипт без последней команды и посмотрите, какие ID попадают под условие. Снимки оплачиваются по объёму, так что автоматическая очистка заметно экономит.

hcloud, Terraform или консоль

  • Консоль — для разовых действий и знакомства с продуктом.
  • hcloud — для операций и скриптов: снимки, Rescue, смена типа, инвентаризация, быстрые правки DNS.
  • Terraform — когда инфраструктура должна быть описана кодом и воспроизводиться (Terraform и Hetzner Cloud). hcloud при этом остаётся полезен для просмотра и разовых действий, но не меняйте им ресурсы, которыми управляет Terraform, иначе следующий plan покажет расхождения.

Для выделенных серверов из Robot hcloud не подходит: у них отдельный API — см. справку API Hetzner: Robot Webservice и Cloud API.

Частые вопросы

Как переключаться между проектами Hetzner Cloud в hcloud?

Создайте по контексту на проект командой hcloud context create и переключайтесь через hcloud context use. Для одной команды в другом проекте добавьте глобальный флаг --context.

Где hcloud хранит токен?

В файле ~/.config/hcloud/cli.toml, в Windows — %APPDATA%\hcloud\cli.toml. Если задана переменная окружения HCLOUD_TOKEN, используется она. Файл с токенами не публикуйте и не храните в репозиториях.

Почему не получается уменьшить тип сервера?

При смене типа без флага --keep-disk диск увеличивается, а тип с меньшим диском выбрать уже нельзя. Используйте --keep-disk, если планируете возвращаться на меньший тариф.

Можно ли через hcloud скачать снимок сервера?

Нет. Снимки и резервные копии Hetzner Cloud хранятся только внутри Hetzner и не выгружаются. Для переноса данных используйте собственные бэкапы, rsync и дампы баз.

Как найти ресурсы, за которые продолжаются списания?

Выполните hcloud all list --paid в каждом проекте: команда покажет серверы, тома, снимки, IP-адреса и другие платные ресурсы.