doctl: управление ресурсами DigitalOcean из командной строки

Коротко: doctl — это инструмент командной строки для работы с API DigitalOcean. Он переводит HTTP API в удобные команды. Подходит для автоматизации и скриптов.

Быстрая навигация

• Установка
• Создание токена доступа
• Подключение к аккаунту
• Тестирование конфигурации
• Работа с ресурсами DigitalOcean
• Несколько аккаунтов (контексты)
• Значения конфигурации по умолчанию
• Форматы вывода
• Когда doctl не подходит и альтернативы
• Чек-листы и playbook
• Заключение

Введение

DigitalOcean предоставляет REST API. doctl — официальный клиент, оборачивающий API в понятные команды. Вы получите скриптабельный интерфейс. Это экономит время при повторяющихся задачах и интеграции с CI/CD.

Определение: doctl — клиент командной строки (CLI) для DigitalOcean, который переводит API-запросы в команды терминала.

Важно: doctl не заменяет панель управления. Он дополняет её и подходит для автоматизации.

Установка

doctl доступен для Windows, macOS и Linux. Поддерживается несколько способов установки: через пакетные менеджеры, snap, Homebrew, скачивание релиза с GitHub и Docker-образ.

Рекомендация: используйте менеджер пакетов вашей ОС для автоматических обновлений.

Примеры установки:

• macOS (Homebrew):

brew install doctl

• Ubuntu/Debian (snap поддерживается):

sudo snap install doctl

• Скачать релиз с GitHub:

Скачайте архив с последним релизом и распакуйте в каталог с бинарниками.

• Docker (одноразовое использование):

DigitalOcean предоставляет официальные контейнеры на Docker Hub. Использование контейнера подходит для CI-пайплайнов или изолированных сред.

docker run --rm -it digitalocean/doctl:latest doctl version

Совет: проверяйте страницу релизов на GitHub, если нужна конкретная версия.

Создание персонального токена доступа

Для подключения doctl к аккаунту нужен персональный токен (Personal Access Token). Токен выдаёт права от имени пользователя, поэтому храните его в защищённом месте.

Шаги:

1. Войдите в панель DigitalOcean.
2. Нажмите ссылку API в боковой панели.
3. В разделе Personal access tokens выберите Generate New Token.
4. Укажите понятное имя токена.
5. Включите scope чтения и записи, если планируете управлять ресурсами.
6. Сохраните значение токена сразу: после закрытия окна токен нельзя будет просмотреть снова.

Важно: при утере токена удалите его и создайте новый. Никогда не храните токен в публичных репозиториях.

Подключение к аккаунту

Вернитесь в терминал и выполните команду аутентификации:

doctl auth init

Вас попросят ввести токен. Если валидация успешна, doctl сохранит учетные данные в конфигурации. Они будут использоваться автоматически при последующих командах.

Файл конфигурации по умолчанию хранится в:

~/.config/doctl

Если вы используете контейнер Docker, передайте токен через переменные окружения или монтируйте конфигурацию.

Проверка конфигурации

Проверьте доступ с помощью:

doctl account get

Ожидаемый результат — данные аккаунта, такие как Email и идентификатор. Если команда возвращает ошибку, проверьте токен и связи сети.

Работа с ресурсами DigitalOcean

doctl покрывает почти все API-эндпоинты. Ниже — наиболее используемые пространства команд и примеры.

Compute (Droplets и прочее)

• Основная команда:

doctl compute

• Работа с Droplet:

doctl compute droplet list

Создание Droplet (пример):

doctl compute droplet create --image ubuntu-20-04-x64 --size s-1vcpu-1gb --region lon1 my-droplet

Пояснение: --image указывает образ, --size — тип машины, --region — датацентр.

Базы данных

• Работа с базами в кластере:

doctl databases db list

Создание базы внутри кластера:

doctl databases db create  

Другие команды позволяют масштабировать кластеры и управлять пользователями.

Kubernetes

doctl kubernetes cluster list

Команды для управления узлами, версиями кластера и подключениями к реестру контейнеров.

Container Registry

doctl registry list

Управление реестрами, включение/отключение garbage collection, просмотр образов.

Общая навигация и документация в CLI

Запуск команды верхнего уровня без аргументов покажет подкоманды:

doctl compute

Это ускоряет изучение возможностей клиента.

Автодополнение

doctl поддерживает автодополнение в популярных оболочках. Для Bash добавьте в ~/.profile:

source <(doctl completion bash)

Замените bash на вашу оболочку (zsh, fish и т.д.). Подробности — в официальной документации doctl.

Несколько аккаунтов и контексты

doctl поддерживает контексты для работы с несколькими аккаунтами. Контекст — это именованный набор учётных данных и настроек.

Управление контекстами:

doctl auth init --context my-context

Вы можете переключаться между контекстами через флаг --context или переменную окружения DIGITALOCEAN_CONTEXT.

По умолчанию используется контекст default.

Значения конфигурации по умолчанию

Файл конфигурации обычно находится тут:

~/.config/doctl/config.yaml

Формат записи значения по умолчанию:

category.command.subcommand.flag: value

Пример — размер по умолчанию для создания Droplet:

compute.droplet.create.size: s-1vcpu-1gb

Любое значение из конфигурации можно переопределить флагом в командной строке.

Форматы вывода

По умолчанию doctl выводит удобные таблицы и списки. Для машинной обработки используйте JSON:

--output json

Выбор полей для таблицы выполняется через --format. Укажите список имён колонок, разделённых запятой, без пробелов.

Пример:

doctl compute droplet list --format ID,Name,PublicIPv4

Используйте JSON для интеграции с jq, Python или другими инструментами парсинга.

Когда doctl не подходит

• Если вам нужен графический интерфейс для ад-хок управления — используйте веб-панель.
• Для операций с Spaces (объектное хранилище S3-совместимое) удобнее S3-совместимый клиент (aws-cli, s3cmd). DigitalOcean рекомендует такие утилиты.
• При работе с нестандартными API-операциями или экспериментальными эндпоинтами используйте прямые HTTP-запросы к API.

Альтернативы и дополняющие инструменты

• Веб-панель DigitalOcean — для визуального управления.
• Прямые HTTP-запросы к API — для кастомных интеграций.
• Terraform — для декларативного управления инфраструктурой.
• Ansible — для конфигурации и оркестрации.
• Docker image doctl — для CI/CD.

Выбор зависит от цели: одноразовые задачи лучше выполнять через doctl, декларативные — через Terraform.

Ментальные модели и лучшие практики

• Идея «контекста» похожа на профили AWS CLI. Используйте отдельные контексты для продакшена и теста.
• Токены — это секреты. Относитесь к ним как к паролям.
• Сначала тестируйте команды в песочнице, затем автоматизируйте в CI с защитой секретов.
• Логи команд и состояния инфраструктуры храните отдельно (audit trail).

Чек-листы по ролям

Администратор:

• Создать персональные токены для сервиса CI.
• Настроить контексты для отделов.
• Зафиксировать правила ротации токенов.

Разработчик:

• Использовать локальный контекст для тестов.
• Привязать конфигурацию по умолчанию для быстрого старта.
• Подключить автодополнение shell.

SRE/Операции:

• Интегрировать doctl в CI/CD через официальный Docker image.
• Парсить вывод JSON для мониторинга.
• Настроить оповещения при изменениях критичных ресурсов.

Playbook: создать и подключить Droplet (шаги)

1. Подготовьте токен и убедитесь, что doctl account get возвращает данные.
2. Выберите регион и размер.
3. Выполните команду создания Droplet:

doctl compute droplet create --image ubuntu-20-04-x64 --size s-1vcpu-1gb --region lon1 my-droplet

4. Подождите, пока Droplet не получит IP. Можно следить через doctl compute droplet list.
5. Подключитесь по SSH, используя вывод команды или через DigitalOcean Console.
6. При необходимости создайте snapshot и добавьте запись в документацию.

Критерии приёмки:

• Droplet появился в списке.
• Assigned public IP доступен по ping/ssh (в зависимости от политики брандмауэра).
• Теги и метаданные установлены согласно шаблону.

Безопасность и рекомендации

• Храните токены в менеджерах секретов (Vault, AWS Secrets Manager, GitHub Secrets).
• Ограничивайте права токена минимумом необходимых scope.
• Периодически ротируйте токены и удаляйте неиспользуемые.
• Не публикуйте ~/.config/doctl в репозитории.

Конфиденциальность и соответствие

Doctl сам по себе не обрабатывает персональные данные, он лишь отправляет запросы в API DigitalOcean. Управление учетными данными и логированием должно соответствовать вашей политике безопасности и требованиям GDPR, если вы оперируете персональными данными.

Часто встречающиеся ошибки и как их исправить

• Ошибка аутентификации: проверьте токен и сетевой доступ.
• Права доступа: удостоверьтесь, что токен имеет нужные scope.
• Неправильный регион/образ: проверьте доступные варианты через doctl compute region list и doctl compute image list.

Заключение

doctl — надёжный инструмент для повседневного управления DigitalOcean. Он ускоряет рутинные операции и легко встраивается в автоматизацию. Для декларативного управления рекомендуется рассматривать Terraform параллельно. Для операций с Spaces используйте S3-совместимые утилиты.

Полезные ссылки: документация doctl на сайте DigitalOcean и репозиторий на GitHub.

Важно: регулярно обновляйте doctl и управляйте токенами по политике вашей организации.

Резюме

• doctl переводит API DigitalOcean в команды CLI.
• Используйте токены доступа и контексты для безопасной работы.
• Для автоматизации выбирайте JSON-вывод и интеграцию с CI.
• Для Spaces используйте S3-инструменты.