doctl — командная строка DigitalOcean

Быстрые ссылки

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

Введение

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

Определения (по одной строке):

• doctl — официальный CLI-клиент для DigitalOcean.
• Droplet — виртуальная машина (эквивалент инстанса).
• Context (контекст) — именованная конфигурация учётных данных doctl.
• Registry — реестр контейнеров DigitalOcean.

Установка

doctl доступен на Windows, macOS и Linux. Выберите метод установки, который лучше всего вписывается в ваш рабочий процесс.

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

macOS

• Homebrew (рекомендуется):

brew install doctl

• Также можно скачать релиз с GitHub и распаковать бинарник вручную.

Windows

• winget:

winget install digitalocean.doctl

• Chocolatey:

choco install doctl

• Для скриптов в PowerShell удобно использовать скачивание напрямую и добавление пути в PATH.

Linux

• Дистрибутивы часто имеют doctl в репозиториях. Примеры:

Debian/Ubuntu:

sudo apt install doctl

CentOS/RHEL (EPEL или репозиторий):

sudo yum install doctl

• Snap (если поддерживается):

sudo snap install doctl --classic

• Скачивание последнего релиза с GitHub и распаковка в /usr/local/bin также работает.

Docker

DigitalOcean предоставляет официальный контейнер на Docker Hub. Это удобно для одноразовых задач или CI:

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

Для взаимодействия с локальными файлами конфигурации примонтируйте томы.

Обновления и версии

Используйте пакетный менеджер для упрощённого обновления. Проверьте текущую версию:

doctl version

Создание токена доступа

Чтобы подключить doctl к аккаунту, нужен персональный токен доступа (Personal Access Token). Токен хранит права доступа и действует как ваш ключ к API.

Шаги:

1. Войдите в панель управления DigitalOcean.
2. Нажмите ссылку «API» в нижней части боковой панели.
3. В разделе «Personal access tokens» нажмите «Generate New Token».
4. Дайте токену понятное имя (например, CI/CD, laptop, automation) и установите нужные права: обычно read и write.
5. Сохраните значение токена в безопасном месте — после закрытия окна восстановить токен нельзя.

Советы по безопасности:

• Не храните токены в публичных репозиториях.
• Для CI используйте секреты системы CI (GitHub Actions Secrets, GitLab CI variables и т. п.).
• Регулярно ревизируйте и отзывайте неиспользуемые токены.

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

После создания токена вернитесь в терминал и выполните:

doctl auth init

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

~/.config/doctl

Пример содержимого каталога конфигурации:

• config.yaml — основные настройки и контексты
• tokens.yaml — зашифрованные/хранящиеся токены или ссылки на менеджер секретов (в зависимости от платформы)

Важно: убедитесь, что права доступа к файлам конфигурации ограничены (600). На Unix-системах:

chmod 600 ~/.config/doctl/config.yaml

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

Проверьте, что doctl может получить информацию об аккаунте:

doctl account get

Если команда возвращает данные аккаунта — конфигурация корректна.

Типичные проблемы и их решения:

• “Unauthorized” — проверьте правильность токена и права доступа.
• Ошибки сетевого подключения — проверьте прокси, VPN или firewall.

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

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

Важно: для полного списка subcommand-ов используйте вызов без аргументов.

doctl compute

Droplets (Виртуальные машины)

• Список Droplets:

doctl compute droplet list

• Создание базового Droplet (пример Ubuntu):

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

• Примеры дополнительных опций: ssh-keys, backups, user-data, tags.

Базы данных

• Список баз:

doctl databases db list --cluster-id 

• Создание базы:

doctl databases db create  mydatabase

• Масштабирование кластера делается через соответствующие субкоманды в пространстве databases.

Kubernetes

• Получение списка кластеров:

doctl kubernetes cluster list

• Получение kubeconfig для работы с kubectl:

doctl kubernetes cluster kubeconfig save 

Container Registry

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

doctl registry list

• Запуск ручной сборки/очистки и управление GC:

doctl registry garbage-collection run --registry 

Универсальные советы

• Чтобы узнать доступные подкоманды, вызовите команду без аргументов:

doctl compute

• Используйте автодополнение для ускорения работы в оболочке:

source <(doctl completion bash)

Добавьте эту строку в ~/.profile или ~/.bashrc. Замените bash на вашу оболочку (zsh, fish).

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

doctl поддерживает именованные контексты — полезно, если вы управляете несколькими аккаунтами или окружениями.

• Создание контекста:

doctl auth init --context my-context

• Переключение контекстов можно делать через флаг:

doctl compute droplet list --context my-context

или через переменную окружения:

export DIGITALOCEAN_CONTEXT=my-context

Контексты хранятся в config.yaml; при отсутствии контекста используется default.

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

Файл конфигурации обычно находится в ~/.config/doctl/config.yaml. В нём можно задать значения по умолчанию для флагов.

Пример задания значения по умолчанию для размера создаваемых Droplets:

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

Такие настройки удобны для стандартизации команд и снижения числа ошибок.

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

• Значения по умолчанию присутствуют в config.yaml и документированы.
• Разработчики и операторы знают, как их переопределить через CLI флаги.

Форматы вывода и использование в скриптах

По умолчанию doctl отображает человеко-читаемые таблицы. Для автоматизации чаще используют JSON.

• Вывод в JSON:

doctl compute droplet list --output json

• Фильтрация полей в табличном выводе:

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

• Пример конвейера с jq для извлечения IP-адресов:

doctl compute droplet list --output json | jq -r '.[].networks.v4[] | select(.type=="public") | .ip_address'

Советы для скриптов:

• Обрабатывайте коды возврата команд.
• Логируйте stdout/stderr.
• Не включайте токены в логи.

Автоматизация и интеграция с CI/CD

• Храните токены в секретном хранилище CI (GitHub Secrets, GitLab CI Variables).
• В Docker-образе подключайте doctl и монтируйте конфигурацию как секрет.
• Используйте контексты для разделения окружений (prod, staging, dev).

Безопасность и соответствие

Важно: токены дают полный доступ в зависимости от scope. Следуйте принципу наименьших прав.

Рекомендации по защите:

• Используйте разные токены для автоматизации и личных задач.
• Ревью разрешений и отозвание неиспользуемых токенов.
• Ограничивайте доступ к конфигам (chmod 600).
• В CI используйте short-lived tokens или rotate токены регулярно.

Приватность / GDPR:

• doctl работает с ресурсами, содержащими данные пользователей. При автоматизации учитывайте требования GDPR: минимизируйте экспорт персональных данных и логирование.

Когда doctl может не подойти

Контраргументы / ограничения:

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

Альтернативы:

• Прямой вызов DigitalOcean API (curl, httpie).
• Terraform (declarative infra-as-code).
• Ansible (операторская автоматизация).

Практическая методология внедрения (мини-методология)

1. Установите doctl и создайте сервисный токен с минимальными правами.
2. Настройте контекст для CI и контекст для локальной работы.
3. Создайте шаблон config.yaml с корпоративными дефолтами.
4. Автоматизируйте повторяющиеся операции и включите шаги проверки в CI (doctl account get, doctl compute droplet list).
5. Документируйте команды и поддерживайте их в репозитории.

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

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

• Установил doctl локально.
• Создал персональный токен для локальной работы.
• Настроил автодополнение в оболочке.
• Знает, как получить IP Droplet через –output json.

SRE / Оператор:

• Имеется сервисный токен для CI с минимальными правами.
• Настроены контексты prod/staging/dev.
• Создан config.yaml с корпоративными дефолтами.
• Настроено логирование и ревью токенов.

Security / Compliance:

• Политика ротации токенов и ревокации утверждена.
• Доступ к конфигурации ограничен и задокументирован.
• CI использует секретное хранилище, а не переменные в явном виде.

SOP: Быстрое создание Droplet для теста (шаблон)

1. Выберите контекст: export DIGITALOCEAN_CONTEXT=staging
2. Создайте Droplet с тегом для автоматической очистки:

doctl compute droplet create ci-test-01 --image ubuntu-22-04-x64 --size s-1vcpu-1gb --region nyc3 --tag-names ci-temp --wait

3. Выполните базовую проверку: ping, ssh (если ключи настроены).
4. Удалите Droplet после теста:

doctl compute droplet delete ci-test-01 --force

Отладка и типичные ошибки

• “could not read config” — проверьте права и корректность YAML.
• «connection refused» — проверьте интернет и доступ к API.digitalocean.com.
• Неправильный токен — создайте новый токен и повторите auth init.

Решение: когда использовать doctl, а когда — нет (ментальные модели)

• Нужна быстрая ад-хок операция или скрипт — doctl.
• Нужна декларативная инфраструктура, отслеживаемая в VCS — Terraform.
• Нужна массовая миграция объектов Spaces — используйте S3-совместимые инструменты.

Диаграмма принятия решения

flowchart TD
  A[Нужна ли декларативность?] -->|Да| B[Terraform]
  A -->|Нет| C[doctl или API]
  C --> D{Работаете в CI?}
  D -->|Да| E[Используйте doctl с секретным хранилищем]
  D -->|Нет| F[doctl локально]
  E --> G[Добавьте шаги проверки и ротацию токенов]
  F --> H[Настройте автодополнение и контексты]

Заключение

doctl упрощает управление ресурсами DigitalOcean и идеально подходит для скриптов, CI/CD и быстрых операций. Он поддерживает большинство API-операций и позволяет стандартизировать рабочие процессы через конфигурации и контексты.

Важно: для Spaces используйте S3-совместимые инструменты. Для декларативной инфраструктуры рассматривайте Terraform.

Ресурсы для дальнейшего чтения:

• Официальная документация doctl на сайте DigitalOcean
• Репозиторий doctl на GitHub (открытый исходный код)

Важно: храните токены в секрете и регулярно ревьюйте их. Документируйте конфигурации и автоматизируйте ротацию в CI.

Краткое резюме — что делать дальше:

1. Установите doctl через пакетный менеджер.
2. Создайте сервисный токен и выполните doctl auth init.
3. Настройте контексты и значения по умолчанию в config.yaml.
4. Автоматизируйте проверки и включите ротацию токенов.