TOC

Как использовать Doctl, официальный клиент командной строки DigitalOcean

Более ранняя версия этого руководства была написанаBrennen Bearnes.

Вступление

Веб-панель управления DigitalOcean обеспечивает интерфейс «укажи и нажми» для управления каплями. Тем не менее, вы можете предпочесть инструмент командной строки, если у вас есть много Droplets для управления, вам нужно администрировать Droplets из терминала без графического рабочего стола или у вас есть задачи, которые выиграют от интерфейса с поддержкой сценариев.

doctl - официальный клиент командной строки DigitalOcean. Он используетthe DigitalOcean API для обеспечения доступа к большинству функций учетной записи и Droplet.

Предпосылки

Чтобы следовать этому уроку, вам понадобится:

Это руководство предназначено для справки по большинству операцийdoctl. Поскольку командыdoctl тесно связаны с API, также может быть полезно прочитатьAPI documentation иHow To Use the DigitalOcean API v2.

Общее использованиеdoctl

Вызов Команды

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

  • account для информации, связанной с аккаунтом

  • auth для аутентификации в DigitalOcean

  • compute для управления инфраструктурой

Чтобы увидеть обзор всех команд, вы можете вызватьdoctl отдельно. Чтобы увидеть все доступные команды в одной из трех основных категорий, вы можете использоватьdoctl category, напримерdoctl compute. Чтобы получить руководство по использованию конкретной команды, введите команду с флагом--help, напримерdoctl compute droplet --help.

Получение данных в формате JSON

В средах сценариев или при работе в командной строке с инструментами обработки данных часто бывает полезно получить машиночитаемый вывод команды.

По умолчаниюdoctl форматирует свой вывод в виде столбцов удобочитаемого текста, но может создавать подробный вывод JSON с помощью параметра--output json. 

doctl compute droplet get droplet_id --output json
Sample Output{
  "id": droplet_id,
  "name": "droplet_name",
  "memory": 1024,
  "vcpus": 1,
  "disk": 30,
  "region": {
    "slug": "nyc3",
    "name": "New York 3",
    "sizes": [
...

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

форматирование

Часто бывает полезно получить только набор полей из вывода. Для этого вы можете использовать флаг--format, который берет список полей по имени. Например, если вы хотите получить только идентификатор, имя и IP-адрес ваших капель, вы можете использовать следующую команду: 

doctl compute droplet list --format "ID,Name,PublicIPv4"
Sample outputID          Name       Public IPv4
50513569    doctl-1    67.205.152.65
50513570    test       67.205.148.128
50513571    node-1     67.205.131.88

Шаблоны

Командаdoctl compute droplet get поддерживает создание шаблонов вывода, что позволяет настраивать формат вывода. Чтобы использовать эту функцию, укажитеthe Go-formatted template с помощью флага--template.

Например, если вы хотите получить имя капли в форматеdroplet_name: droplet_name, вы должны использовать следующую командуget: 

doctl compute droplet get 12345678 --template "droplet_name: {{ .Name}}
Outputdroplet_name: ubuntu-1gb-nyc3-01

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

Список ресурсов

Чтобы получить список ресурсов, таких как капли, вы можете использовать командуlist без параметров. 

doctl compute droplet list
Sample output for list commandID          Name       Public IPv4       Private IPv4    Public IPv6    Memory    VCPUs    Disk    Region    Image                 Status    Tags
50513569    test-1     67.205.152.65                                    512       1        20      nyc1      Ubuntu 16.04.2 x64    active
50513571    test-2      67.205.131.88                                    512       1        20      nyc1      Ubuntu 16.04.2 x64    active
50513570    site       67.205.148.128                                   512       1        20      nyc1      Ubuntu 16.04.2 x64    active

Командаlist поддерживает glob как необязательный параметр. Глобус представляет собой шаблон с подстановочными знаками, который можно использовать для фильтрации определенных ресурсов по имени. Например, чтобы получить список капель, имена которых начинаются сtest, вы можете использовать следующую команду: 

doctl compute droplet list 'test*'
Sample output for list command with 'doctl-' as globID          Name       Public IPv4       Private IPv4    Public IPv6    Memory    VCPUs    Disk    Region    Image                 Status    Tags
50513569    test-1     67.205.152.65                                    512       1        20      nyc1      Ubuntu 16.04.2 x64    active
50513571    test-2      67.205.131.88                                    512       1        20      nyc1      Ubuntu 16.04.2 x64    active

Создание ресурсов

Создание ресурса требует более длинных команд с более подробными параметрами. Чтобы создать каплю, вам нужно указать изображение, которое вы хотите использовать, область центра данных и тип капли, который вы хотите использовать, используя связанный слаг. СмотритеNew Size Slugs for Droplet Plan Changes
, чтобы найти пул, который вы хотите использовать. Alternatively, run the doctl compute size list command.

Например, следующая команда создает 64-разрядную каплю Debian 8 с именемtest с 1 ГБ памяти, одним процессором, ключом SSH и включенным резервным копированием. 

doctl compute droplet create test --size s-1vcpu-1gb    --image debian-8-x64 --region nyc1 --ssh-keys 4d:23:e6:e4:8c:17:d2:cf:89:47:36:b5:c7:33:40:4e --enable-backups

Вы увидите этот вывод: 

Sample Droplet creation outputID              Name    Public IPv4     Memory  VCPUs   Disk    Region  Image           Status
11450164        test                    1024    1       30      nyc1    Debian 8.3 x64  new

Для удаления ресурса требуется идентификатор ресурса в качестве аргумента или имя ресурса в случае, если идентификатор не существует для данного ресурса (например, теги). Чтобы подтвердить свои намерения, вам необходимо подтвердить все действия по удалению, ответив на вопрос подтверждения с помощьюy илиyes. 

doctl compute droplet delete 123456
OutputWarning: Are you sure you want to delete droplet(s) (y/N) ?

Отсутствие ответа или предоставление ответа, отличного отy илиyes, отменит действие без удаления ресурса. Вы можете заставитьdoctl принять утвердительный ответ без явного его предоставления, используя флаг--f (--force): 

doctl compute droplet delete -f 123456

Поиск уникальных идентификаторов для ресурсов

Для команды создания капли требуется ряд идентификаторов, таких какnyc1 для региона NYC1,debian-8-x64 для образа Debian и отпечаток ключа SSH, например4d:23:e6:e4:8c:17:d2:cf:89:47:36:b5:c7:33:40:4e.

Ряд ресурсов, таких как капли и изображения, идентифицируются по значению (часто числовому), уникальному в базе данных DigitalOcean.

Вы можете получить необходимые уникальные идентификаторы для большинства команд из API:

команда Заметки

doctl compute droplet list

Ваши капли. Некоторые команды также принимают имя; большинству требуется числовое значение из столбцаID.

doctl compute ssh-key list

Ключи SSH, связанные с вашей учетной записью. Для создания капли вы можете указатьnumeric ID илиfingerprint.

doctl compute region list

Доступные регионы. Используйте строку в столбцеSlug.

doctl compute image list

Доступные образы, включая снимки состояния, резервные копии и образы базового распространения. Используйте строку в столбцеSlug для создания новых капель.

doctl compute size list

Доступные размеры капель. Используйте строку в столбцеSlug.

doctl compute tag list

Доступные теги. Используйте строку в столбцеName.

Работа с каплями

Создание, удаление и проверка капель

Командаdoctl compute droplet позволяет создавать, удалять и проверять капли. Опять же, для большинства команд для работы с отдельными каплями требуется уникальный идентификатор капли, который можно найти в выходных данныхdoctl droplet list.

Подкомандаdoctl compute droplet Заметки

actions droplet_id

Отображение истории действий, предпринятых для капли.

backups droplet_id

Список резервных копий для капли.

create name --size s-1vcpu-1gb --image image_slug --region nyc1

Создайте каплю. Размер, изображение и регион являются обязательными.

delete droplet_id_or_name

Удалить каплю по идентификатору или имени.

get droplet_id

Получите подробную информацию о конкретной капле.

kernels droplet_id

Список ядер для капли.

list

Составьте список ваших текущих капель.

neighbors droplet_id

Составьте список ваших капель, работающих на том же физическом оборудовании, что и конкретная капля.

snapshots droplet_id

Список снимков для капли.

tag droplet_id/droplet_name

Отметьте каплю.

untag droplet_id/droplet_name

Снимите теги с капли.

Инициирование действий капли

Командаdoctl compute droplet-action позволяет запускать различные действия для капли, включая действия по управлению питанием и переключение функций, таких как резервное копирование и частные сети.

Подкомандаdoctl compute droplet-action Заметки

get droplet_id --action-id action_id

Получите подробные сведения о действии над каплей.

disable-backups droplet_id

Отключить резервное копирование для капли.

reboot droplet_id

Перезагрузите каплю.

power-cycle droplet_id

Выключите каплю и снова включите.

shutdown droplet_id

Выключите каплю.

power-off droplet_id

Выключите каплю. Капля должна быть включена. Обычно лучше делать это из командной строки самой капли, чтобы предотвратить потерю данных.

power-on droplet_id

Включите каплю. Капля должна быть выключена.

power-reset droplet_id

Сброс питания Droplet.

enable-ipv6 droplet_id

Включите ipv6 для капли.

enable-private-networking droplet_id

Включитеprivate networking для капли.

upgrade droplet_id

Обновите каплю.

restore droplet_id --image-id image_id

Восстановить каплю в конкретный резервный образ. image_id должен быть резервной копией капли.

resize droplet_id --size 2gb

Измените размер капли. Капля должна быть выключена. По умолчанию размер диска не изменяется, что позволяет понизить версию Droplet. Вы можете изменить размер диска с помощью флага--resize-disk.

rebuild droplet_id --image-id image_id

Восстановите каплю из определенного изображения.

rename droplet_id --droplet-name new_name

Переименуйте каплю вnew_name.

change-kernel droplet_id --kernel-id kernel_id

Измените ядро ​​капли наkernel_id.

snapshot droplet_id --snapshot-name snapshot_name

Сделайте снимок капли, назвав ееsnapshot_name.

Работа с SSH

Создание SSH-соединений

Чтобы подключиться к отдельному Droplet с SSH, обычно необходимо знать либо его IP-адрес, либо полное доменное имя. Вместо этого вы можете использоватьdoctl для подключения к капле по ее имени, числовому идентификатору или частному IP: 

doctl compute ssh droplet_name
doctl compute ssh droplet_id
doctl compute ssh --ssh-private-ip droplet_private_ip

Кроме того, вы можете предоставить команду для выполнения после установления SSH-соединения с помощью флага--ssh-command. Это запустит команду, вывод которой будет напечатан на вашем локальном терминале, а затем сессия SSH закроется. 

doctl compute ssh --ssh-command command

[.note] #Note: перенаправление команд SSH в настоящее время недоступно в Windows.
#

Имя пользователя SSH по умолчанию -root (core для CoreOS), а порт по умолчанию -22. Вы можете использовать флаги для установки значений не по умолчанию и включения других функций:

Flag Описание

--ssh-user string

Имя пользователя для использования в сеансе SSH.

--ssh-port int

Порт для сеанса SSH.

--ssh-key-path string

Путь к SSH-ключу.

--ssh-agent-forwarding

Включить пересылку агента.

Вы также можете изменить значения конфигурации по умолчанию в файле конфигурации. The project’s README file имеет более подробную информацию о том, как это сделать.

Использование ключей SSH

Вы можете управлять открытыми ключами SSH, связанными с вашей учетной записью, с помощью командыdoctl compute ssh-key. Большинство команд, которые ссылаются на ключи SSH, принимают числовой идентификатор ключа или его отпечаток.

Подкомандаdoctl compute ssh-key Заметки

list

Перечислите SSH-ключи, связанные с вашей учетной записью.

get ssh_key_id_or_fingerprint

Получите информацию о конкретном ключе по числовому идентификатору или отпечатку пальца ключа.

create new_key_name --public-key "public_key"

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

import new_key_name --public-key-file ~/.ssh/id_rsa.pub

Свяжите открытый ключ с вашей учетной записью, указав исходный файл.

delete ssh_key_id_or_fingerprint

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

update ssh_key_id_or_fingerprint --key-name new_key_name

Измените имя ключа по числовому идентификатору или отпечатку пальца.

Работа с плавающими IP

Плавающий IP-адрес - это общедоступный статический IP-адрес, который можно назначить одной из ваших капель. Подробное описание функции см. ВHow To Use Floating IPs on DigitalOcean. Вы можете управлять плавающими IP-адресами с помощьюdoctl compute floating-ip.

Подкомандаdoctl compute floating-ip Заметки

list

Перечислить все плавающие IP-адреса.

get floating_ip_address

Получите подробную информацию о плавающем IP-адресе.

create --region nyc1

Создайте плавающий IP-адрес в регионеnyc1.

delete floating_ip_address

Удалите плавающий IP-адрес.

Назначение плавающих IP-адресов для капель

Командаdoctl compute floating-ip-action используется для назначения или отмены назначения плавающего IP-адреса для капли.

Подкомандаdoctl compute floating-ip-action Заметки

assign floating_ip droplet_id

Назначьте капле плавающий IP-адрес по ее числовому идентификатору.

unassign floating_ip

Отменить назначение плавающего IP-адреса.

get floating_ip action_id

Получите подробную информацию о действии с плавающим IP-адресом по его числовому идентификатору.

Работа с доменами

Командаdoctl compute domain используется для управления доменами. Смотрите нашIntroduction to Managing DNS series для широкого обзора предмета.

Подкомандаdoctl compute domain Заметки

list

Список доменов.

create domain_name --ip-address droplet_ip_address

Создайте домен с записями по умолчанию дляdroplet_ip_address.

get domain_name

Получите запись домена.

delete domain_name

Удалить домен.

Управление доменными записями

Командуdoctl compute domain records можно использовать для создания, удаления, обновления или получения информации о записях DNS домена.

Подкомандаdoctl compute domain records Заметки

list domain_name

Список записей для данного домена.

create domain_name --record-type record_type

Создайте запись для домена.

delete domain_name record_id

Удалить запись по числовому идентификатору.

update domain_name --record-id record_id

Обновить запись по числовому идентификатору.

Работа с блочными томами хранения

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

Командуdoctl compute volume можно использовать для создания, удаления или получения информации о томах блочного хранилища DigitalOcean. Для получения дополнительной информации об этой функции прочитайте наше руководство поHow To Use Block Storage on DigitalOcean.

Подкомандаdoctl compute volume Заметки

list

Список томов.

create volume_name --region volume_region --size volume_size

Создать том. Имя, регион и размер являются обязательными.

get volume_ID

Получите объем по числовому идентификатору.

delete volume_ID

Удалить том.

snapshot volume_ID

Объем снимка.

Инициирование объемных действий

Командаdoctl compute volume-action позволяет запускать действия для тома, включая присоединение томов к каплям и отсоединение томов от них.

Подкомандаdoctl compute volume-action Заметки

attach volume_id droplet_id

Прикрепите объем к капле.

detach volume_id droplet_id

Отделите том от капли.

resize volume_id --region volume_region --size new_size

Измените размер тома.

Работа с балансировщиками нагрузки

Командуdoctl compute load-balancer можно использовать для создания, удаления или получения информации о балансировщиках нагрузки DigitalOcean. Для получения дополнительной информации об этой функции прочтите нашIntroduction to DigitalOcean Load Balancers.

Подкомандаdoctl compute load-balancer Заметки

list

Перечислить балансировщики нагрузки.

create --name lb_name --region lb_region --tag-name tag_name --forwarding-rules forwarding_rule

Создайте балансировщик нагрузки. Имя, регион, тег или список идентификаторов капель и хотя бы одно правило пересылки являются обязательными.

update --name lb_name --region lb_region --tag-name tag_name --forwarding-rules forwarding_rule

Создайте балансировщик нагрузки. Имя, регион, тег или список идентификаторов капель и хотя бы одно правило пересылки являются обязательными.

get lb_ID

Получите балансировщик нагрузки.

delete lb_ID

Удалите балансировщик нагрузки.

add-droplets lb_ID --droplet-ids droplet_ID

Добавьте капли в балансировщик нагрузки.

remove-droplets lb_ID --droplet-ids droplet_ID

Удалите капли из балансировщика нагрузки.

add-forwarding-rules lb_ID --forwarding-rules forwarding_rule

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

remove-forwarding-rules lb_ID --forwarding-rules forwarding_rule

Удалите правила пересылки из балансировщика нагрузки.

При использовании в качестве аргумента дляdoctl правила пересылки должны быть выражены следующим образом:entry_protocol:protocol,entry_port:port,target_protocol:protocol,target_port:port.

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

Подкомандаdoctl compute certificate позволяет загружать сертификаты SSL, закрытые ключи и цепочки сертификатов и управлять ими.

Подкомандаdoctl compute certificate Заметки

list

Перечислить все сертификаты.

get certificate_id

Получите сертификат по ID.

create --name certificate_name --leaf-certificate-path leaf_certificate_path

Создайте сертификат. Имя и путь к листу сертификата являются обязательными.

delete certificate_id

Удалить сертификат по идентификатору.

Работа со снимками

Командуdoctl compute snapshot можно использовать для перечисления, удаления или получения информации о снимках капель и томов.

Подкомандаdoctl compute snapshot Заметки

list

Список всех снимков.

get snapshot_ID

Сделайте снимок.

delete snapshot_ID

Удалить снимок.

Чтобы создать новый снимок, вам нужно использовать соответствующую команду в дереве команд соответствующего ресурса. Например:

  • doctl compute droplet-action snapshot droplet_ID создает снимок из капли.

  • doctl compute volume snapshot volume_ID создает снимок тома.

Работа с изображениями

Командаdoctl compute image позволяет управлять всеми образами, включая образы распространения, образы приложений и созданные пользователем образы, такие как резервные копии и моментальные снимки. Мы рекомендуем использовать командуsnapshot для управления моментальными снимками, поскольку она предоставляет более подробную информацию, имеет функцию удаления и поддерживает моментальные снимки блочного хранилища.

Подкомандаdoctl compute image Заметки

list --public

Список всех изображений.

list-distribution --public

Список всех доступных образов дистрибутива.

list-application --public

Перечислить все доступныеOne-Click Applications.

list-user

Список всех изображений, созданных пользователями.

get image_id

Получите изображение по идентификатору.

update image_id --name image_name

Обновите имя изображения. Имя обязательно.

delete image_id

Удалить изображение по идентификатору.

Вызов действия с изображениями

Командаdoctl compute image-action позволяет передавать изображения и получать подробную информацию о действиях, выполняемых с изображениями.

Подкомандаdoctl compute image-action Заметки

get image_id --action-id action_id

Получите действие для изображения по его идентификатору. ID действия является обязательным.

transfer image_id --region region

Перенести изображение в другой регион. ID изображения и регион являются обязательными.

Работа с брандмауэрами

Командаdoctl compute firewall позволяет создавать брандмауэры и управлять ими, в том числе создавать и поддерживать правила. Для получения дополнительной информации об администрировании брандмауэров с помощьюdoctl ознакомьтесь с руководством поHow To Secure Web Server Infrastructure With DigitalOcean Cloud Firewalls Using Doctl.

doctl compute firewall команда Заметки

list

Список всех брандмауэров.

list-by-droplet droplet_id

Список всех брандмауэров по числовому идентификатору Droplet.

create --name firewall_name --inbound-rules inbound_rules --outbound-rules outbound_rules

Создайте брандмауэр. Имя и как минимум правило для входящего или исходящего трафика являются обязательными.

update firewall_id --name firewall_name --inbound-rules inbound_rules --outbound-rules outbound_rules

Обновите брандмауэр. Числовой идентификатор, имя и как минимум правило для входящего или исходящего трафика являются обязательными.

get firewall_id

Получите брандмауэр по его числовому идентификатору.

delete firewall_id

Удалите брандмауэр по числовому идентификатору.

add-droplets firewall_id --droplet-ids droplet_IDs

Добавьте капли в брандмауэр по их числовому идентификатору.

remove-droplets firewall_id --droplet-ids droplet_IDs

Удалите капли из брандмауэра по их числовым идентификаторам.

add-tags firewall_id --tag-names tags

Добавьте теги в брандмауэр.

remove-tags firewall_id --tag-names tags

Удалите теги из брандмауэра.

add-rules firewall_id --inbound-rules inbound_rules --outbound-rules outbound_rules

Добавьте правила для входящего или исходящего трафика в брандмауэр.

remove-rules firewall_id --inbound-rules inbound_rules --outbound-rules outbound_rules

Удалите входящие или исходящие правила в брандмауэре.

При использовании в качестве аргумента дляdoctl входящие или исходящие правила должны быть выражены следующим образом:protocol:protocol,ports:ports,droplet_id:droplet-id.

Работа с тегами

Теги используются для применения пользовательских меток к ресурсам, что позволяет легко их фильтровать. Вы можете узнать больше о тегах вthe How To Tag DigitalOcean Droplets tutorial.

Подкомандаdoctl compute tag Заметки

create tag_name

Создайте тег.

get tag_name

Получите тег по имени.

list

Перечислить все теги.

delete tag_name

Удалить тег по имени.

Работа с вашей учетной записью

Чтение истории действий для вашей учетной записи

Система DigitalOcean регистрирует историю действий, выполненных с вашими Droplets, плавающими IP-адресами и другими ресурсами. Вы можете получить доступ к этим данным с помощью командыdoctl compute action: 

doctl compute action list

Вы можете увидеть действия для определенной капли, например, так: 

doctl compute droplet actions droplet_id

Получение информации о вашей учетной записи

Вы можете найти основные сведения о вашей учетной записи, такие как настроенный адрес электронной почты и лимит Droplet: 

doctl account get

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

doctl account ratelimit

Заключение

Утилитаdoctl - полезный инструмент для управления каплями и другими ресурсами из командной строки. Это может значительно уменьшить количество ручного взаимодействия с веб-интерфейсами, необходимого для повседневной разработки и административных задач.

Помимо изученияthe underlying API, вы можете изучитьlibraries which wrap the API for popular programming languages иtools such as Ansible для автоматизации задач системного уровня.

Related