Что получится
Джоба GitLab CI, которая получает список машин проекта через h3, строит инвентарь Ansible и выполняет плейбук по SSH ключом CI. Ключ CI записан только на те машины, где ему выдан доступ, и отзывается одной кнопкой.
Что понадобится
- Одна или несколько машин на Linux с публичным IP и включённым «Управление ключами через агента» — например, из сценария «Сайт на облачном сервере».
- Проект в GitLab с CI/CD и правом на переменные.
- Ansible 2.14+ и
jqлокально — чтобы проверить плейбук до CI.
-
Шаг 1. Сгенерируйте ключ для CI и добавьте его в профиль ответственного
SSH-ключи на платформе принадлежат людям. Ключ CI добавляет в свой профиль ответственный за автоматизацию — тогда в журнале доступа видно, чей это ключ, а при уходе человека из проекта ключ теряет доступ вместе с ним.
Консоль
- Значок ключа «API и SSH ключи» внизу левой панели → Добавить ключ → Добавить SSH-ключ.
- Имя ключа
gitlab-ci, в поле Ключ — строка изci_ed25519.pub. Нажмите Добавить.
CLI
Терминалh3 config set user_id <ваш ID пользователя> h3 ssh create --name gitlab-ci --key-file ./ci_ed25519.pubНа вашем компьютереssh-keygen -t ed25519 -N '' -C 'gitlab-ci' -f ./ci_ed25519 cat ./ci_ed25519.pubПроверка
Ключ
gitlab-ciпоявился на вкладке SSH-ключи. Приватный файлci_ed25519пока лежит у вас — после следующего шага его место только в переменной CI. -
Шаг 2. Выдайте ключу CI доступ «выбранные» на нужные машины
Режим «выбранные ключи» записывает в машину только ключ
gitlab-ci, а не все ваши ключи. Выдавайте доступ только к тем машинам, которые настраивает пайплайн.Консоль
- Инстансы → машина → секция «Доступ по SSH». Если вы уже в списке «Участники с доступом» — нажмите Изменить у своей строки, иначе Выдать доступ и выберите себя в поле Участники проекта.
- Выключите «Синхронизировать ключи пользователя» и в поле Ключи отметьте
gitlab-ci(и, если нужно, свой рабочий ключ). Нажмите Сохранить.
CLI
Терминал# для каждой машины, которую настраивает CI h3 vm ssh-access grant <vm-id> <ваш ID> --mode selected --key-ids <ID ключа gitlab-ci>,<ID рабочего ключа>Проверка
Статус «Применено» (ключи доезжают примерно за 2 минуты). С вашего компьютера вход ключом CI работает:
Терминалssh -i ./ci_ed25519 -o IdentitiesOnly=yes user@<IP машины> hostnameЕсли не получилось
- Один грант на человека: если в списке ключей оставить только
gitlab-ci, ваш рабочий ключ с машины уйдёт. Отметьте оба.
-
Шаг 3. Соберите инвентарь из API
h3 apiподписывает запрос API-ключом и возвращает список машин проекта: имя, статус, публичный адресendpointи внутреннийnet_config.internal_ip. Из негоjqсобирает инвентарь в формате INI. Группы Ansible берём из префикса имени машины:web-1попадёт в группуweb.inventory.sh#!/usr/bin/env bash # Инвентарь Ansible из API h3llo.cloud: работающие машины с публичным IP. set -euo pipefail h3 api GET /api/vms/v1 --with-project | jq -r ' [ .[] | select(.status == "RUNNING" and (.endpoint // "") != "") ] | group_by(.name | sub("-[0-9]+$"; "")) | .[] | "[" + (.[0].name | sub("-[0-9]+$"; "")) + "]", (.[] | "\(.name) ansible_host=\(.endpoint) ansible_user=user"), ""'Проверка локальноexport H3_KEY_ID=<ID API-ключа> H3_SECRET_KEY=<секрет> H3_PROJECT_ID=<ID проекта> chmod +x inventory.sh && ./inventory.sh > hosts.ini && cat hosts.ini ANSIBLE_HOST_KEY_CHECKING=False ansible all -i hosts.ini --private-key ./ci_ed25519 -m pingПроверка
hosts.iniсодержит группы по префиксам имён,ansible … -m pingотвечает"ping": "pong"для каждой машины, где ключу CI выдан доступ. Машины без доступа ответятPermission denied (publickey)— так и должно быть.Если не получилось
- Пустой вывод — у машин нет публичного IP или они остановлены. Для машин в частной сети за бастионом используйте
net_config.internal_ipи добавьте в инвентарьansible_ssh_common_args='-o ProxyJump=user@<IP бастиона>'. 401от API — не заданыH3_KEY_ID/H3_SECRET_KEY, ключ выключен или истёк.
- Пустой вывод — у машин нет публичного IP или они остановлены. Для машин в частной сети за бастионом используйте
-
Шаг 4. Положите секреты в переменные GitLab CI
Для CI создайте отдельный API-ключ: тогда его можно отозвать, не трогая ключи людей. Ключ ограничьте одним проектом и сроком.
Консоль
- API-ключи → Добавить ключ → Добавить API-ключ: Имя ключа
gitlab-ci, Проекты — этот проект, Срок действия — «90 дней». Нажмите Создать API ключ и скопируйте секрет. - В GitLab: Settings → CI/CD → Variables. Добавьте
H3_KEY_ID,H3_SECRET_KEY(Masked, Protected),H3_PROJECT_IDи переменную типа FileSSH_PRIVATE_KEYс содержимымci_ed25519. - Удалите локальную копию приватного ключа:
shred -u ./ci_ed25519.
- API-ключи → Добавить ключ → Добавить API-ключ: Имя ключа
-
Шаг 5. Запустите плейбук из пайплайна
.gitlab-ci.ymlconfigure: image: python:3.12-slim rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH before_script: - apt-get update && apt-get install -y --no-install-recommends curl jq openssh-client ca-certificates - pip install --no-cache-dir ansible-core - curl -fsSL https://h3llo.cloud/cli/install.sh | sh - chmod 600 "$SSH_PRIVATE_KEY" script: - ./inventory.sh > hosts.ini - cat hosts.ini - ansible-playbook -i hosts.ini --private-key "$SSH_PRIVATE_KEY" site.yml variables: ANSIBLE_HOST_KEY_CHECKING: "False"site.yml- hosts: all become: true tasks: - name: Пакеты обновлены ansible.builtin.apt: update_cache: true upgrade: safeПроверка
Пайплайн на ветке по умолчанию проходит, в логе —
hosts.iniиPLAY RECAPсfailed=0. В карточке машины, «Журнал доступа», видно, когда выдавался доступ ключу CI.Если не получилось
h3: command not found— установщик положил бинарник не вPATHобраза; добавьтеexport PATH=$HOME/.local/bin:$PATHвbefore_script, если он ставит в домашний каталог.ANSIBLE_HOST_KEY_CHECKING: Falseудобно для начала. Для прода соберитеknown_hostsзаранее (ssh-keyscanпо адресам из инвентаря) и храните его в репозитории.
Проверка результата
Создайте новую машину с префиксом web- и выдайте ключу CI доступ — при следующем запуске она сама попадёт в группу web и получит плейбук, без правок инвентаря.
./inventory.sh | grep -A5 '^\[web\]' Как удалить ресурсы
- В карточке каждой машины → «Доступ по SSH» → Изменить у своей строки → снимите ключ
gitlab-ci→ Сохранить. Или удалите ключ целиком: SSH-ключи →gitlab-ci→ Удалить — «ключ удалён из профиля» появится в журнале доступа, а из машин он уйдёт сам. - API-ключи →
gitlab-ci→ меню «…» → Удалить → Подтвердить. - В GitLab удалите переменные
H3_KEY_ID,H3_SECRET_KEY,SSH_PRIVATE_KEY.
Типичные ошибки
Почему не положить в CI свой личный ключ?
Его придётся менять во всех пайплайнах, когда вы смените ноутбук, а отзыв ключа CI отрежет и вас. Отдельный ключ `gitlab-ci` отзывается независимо, и в журнале видно, что заходил именно он.
Можно ли выдать ключу CI доступ ко всем машинам проекта сразу?
Доступ выдаётся по машине: в консоли, `h3 vm ssh-access grant` в цикле по `h3 vm list -o json | jq -r '.[].id'` или ресурсом `h3_vm_ssh_access` в Terraform.
Плейбук сам добавил ключ в authorized_keys, а он пропал
При включённом управлении ключами агент перезаписывает `/home/user/.ssh/authorized_keys`. Ключи вне платформы кладите в `~/.ssh/authorized_keys2`.
Связанные продукты и материалы
- Сценарий · 45 минСайт на облачном сервере: публичный IP, домен и HTTPS
- Сценарий · 35 минИнфраструктура как код: сервер в Terraform и state в S3
- Сценарий · 40 минПриложение в Managed Kubernetes из своего реестра образов
- Сценарий · 35 минManaged PostgreSQL для приложения: пользователь, pgvector и восстановление на момент времени
- ПродуктСерверы
- ПродуктБезопасность
Попробовать в h3llo.cloud
Новым пользователям — 4 000 ₽ на 30 дней на любые сервисы: бонуса хватит, чтобы попробовать этот сценарий целиком. Бонус начисляется после подтверждения телефона и привязки карты.