1. Главная
  2. Хаб
  3. Сценарии
  4. Ротация API-ключа без простоя: второй ключ, переключение, отзыв старого

Сценарий 31

Ротация API-ключа без простоя: второй ключ, переключение, отзыв старого

API-ключ живёт не дольше года, и менять его стоит раньше, чем он истечёт посреди ночного деплоя. Показываем порядок, при котором ни один пайплайн не упадёт: новый ключ рядом со старым, переключение, проверка по дате использования, выключение и удаление старого.

15 минНовичок5 шагов Безопасность, Terraform обновлено

Содержание
  1. 01Посмотрите, где и до какого числа живёт старый ключ
  2. 02Создайте новый ключ рядом со старым
  3. 03Переключите все потребители на новый ключ
  4. 04Выключите старый ключ и подождите
  5. 05Удалите старый ключ и запланируйте следующую ротацию
  6. Проверка результата
  7. Как удалить ресурсы
  8. Типичные ошибки

Что получится

Terraform, CI и скрипты работают на новом ключе, старый удалён, а в календаре стоит напоминание о следующей ротации за пару недель до срока.

Что понадобится

  • Ключ, который используется в CI, Terraform или скриптах, и доступ к местам, где хранится его секрет (переменные CI, менеджер секретов).
  • CLI h3 или Terraform для проверки нового ключа.
  1. Шаг 1. Посмотрите, где и до какого числа живёт старый ключ

    Консоль

    1. Значок ключа «API и SSH ключи» внизу левой панели → вкладка API-ключи.
    2. У каждого ключа видны «Добавлен», «Использован», «Истекает» и состояние «Включен». Запишите имя, проекты и дату «Истекает» ключа, который меняете.

    Проверка

    Вы знаете все места, где лежит секрет: переменные CI, ~/.h3/config.yaml, переменные окружения Terraform H3_KEY_ID/H3_SECRET_KEY. Если сомневаетесь, дата «Использован» после переключения покажет, что старым ключом ещё кто-то пользуется.

    Если не получилось

    • Ключа без срока не бывает: срок можно продлить кнопкой Обновить, но не дальше года от сегодняшнего дня и не убрать совсем. Продление — не ротация: секрет остаётся прежним.
  2. Шаг 2. Создайте новый ключ рядом со старым

    Оба ключа работают одновременно, поэтому переключение не требует окна. Проекты у нового ключа — те же, что у старого.

    Консоль

    1. Добавить ключ → Добавить API-ключ. Имя ключа — с датой, например ci-2026-11, Проекты — как у старого, Срок действия — «90 дней» или «Год».
    2. Нажмите Создать API ключ и скопируйте секрет из окна «Ключ создан»: «Сохраните секретный ключ. Он больше не будет отображаться».
    3. ID нового ключа — в списке, строка «ID:» с кнопкой копирования.

    Проверка

    Новый ключ отвечает:

    Терминал
    H3_KEY_ID=<новый ID> H3_SECRET_KEY=<новый секрет> H3_PROJECT_ID=<ID проекта> h3 vm list

    Если не получилось

    • key not found or disabled сразу после создания — проверьте, что ID и секрет от одного ключа. «Публичных» и «приватных» частей у API-ключа нет: это ID и секрет h3_….
  3. Шаг 3. Переключите все потребители на новый ключ

    Консоль

    1. GitLab: Settings → CI/CD → Variables → замените значения H3_KEY_ID и H3_SECRET_KEY (Masked, Protected).
    2. GitHub Actions: Settings → Secrets and variables → Actions → обновите оба секрета.

    CLI

    Терминал
    # локальный конфиг CLI
    h3 config set key_id <новый ID>
    h3 config set secret_key <новый секрет>
    h3 config show

    Terraform

    Terraform
    # провайдер читает ключ из окружения — в .tf ничего менять не нужно
    export H3_KEY_ID="<новый ID>"
    export H3_SECRET_KEY="<новый секрет>"
    terraform plan

    Проверка

    Пайплайны прошли, terraform plan отработал без ошибок подписи. В консоли у нового ключа появилась строка «Использован …».

  4. Шаг 4. Выключите старый ключ и подождите

    Выключение обратимо, удаление — нет. Выключите старый ключ и дайте поработать всем расписаниям хотя бы сутки: если что-то ещё на нём, оно упадёт с 401, и ключ можно включить обратно за секунду.

    Консоль

    1. У старого ключа: меню «…» → Обновить → переключатель в положение «Выключен» → Обновить API ключ.

    Проверка

    В списке у старого ключа состояние «Выключен», дата «Использован» больше не меняется. Ночные задания прошли на новом ключе.

    Если не получилось

    • Что-то упало с 401 и key not found or disabled — это место ещё на старом ключе. Включите его обратно, поменяйте секрет там и повторите.
  5. Шаг 5. Удалите старый ключ и запланируйте следующую ротацию

    Консоль

    1. У старого ключа: меню «…» → Удалить → в окне «Пожалуйста, подтвердите своё действие» нажмите Подтвердить. Ключ перестаёт работать сразу, действие необратимо.
    2. Поставьте в календарь напоминание за две недели до даты «Истекает» нового ключа.

    Проверка

    В списке остался один ключ для этой задачи — ci-2026-11, включённый, с датой «Использован» за сегодня.

Проверка результата

Запустите пайплайн вручную и проверьте любым клиентом, что работает новый ключ, а старый отклоняется:

Терминал
H3_KEY_ID=<старый ID> H3_SECRET_KEY=<старый секрет> H3_PROJECT_ID=<ID проекта> h3 vm list   # 401
h3 vm list                                                                                     # новый ключ из конфига

Как удалить ресурсы

Сценарий не создаёт платных ресурсов. Если ротацию отменили, удалите неиспользуемый новый ключ: API-ключи → меню «…» → Удалить → Подтвердить.

Типичные ошибки

Секрет старого ключа утёк — тоже ждать сутки?

Нет. При утечке сразу выключите или удалите ключ, затем создайте новый и разложите его по потребителям. Простой в этом случае дешевле, чем чужой доступ к проекту.

Можно ли посмотреть секрет существующего ключа?

Нет, он показывается один раз при создании. Потеряли — создайте новый ключ по этому сценарию.

Как часто менять ключи?

По умолчанию новый ключ живёт 90 дней, максимум — год. Ключ для CI удобно менять раз в квартал, вместе с другими секретами пайплайна.

Один ключ на всё или по ключу на систему?

По ключу на систему: Terraform, CI, отчёты, внешняя панель. Тогда ротация и отзыв затрагивают одну систему, а по дате «Использован» видно, какой ключ живой.

Связанные продукты и материалы

Попробовать в h3llo.cloud

Новым пользователям — 4 000 ₽ на 30 дней на любые сервисы: бонуса хватит, чтобы попробовать этот сценарий целиком. Бонус начисляется после подтверждения телефона и привязки карты.