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

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

Введение

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

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

Предпосылки

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

Локальный компьютер с установленным doctl в соответствии с инструкциями проекта по установке и настройке.

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

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

Вызов команд

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

account для информации, связанной с аккаунтом
auth для аутентификации в DigitalOcean
вычисления для управления инфраструктурой

Чтобы увидеть обзор всех команд, вы можете вызвать сам doctl. Чтобы увидеть все доступные команды в одной из трех основных категорий, вы можете использовать doctl category, например doctl calculate. Чтобы получить руководство по использованию определенной команды, введите команду с флагом --help, как в дроплете вычислений doctl --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 calculate droplet get поддерживает шаблоны вывода, что позволяет настраивать формат вывода. Чтобы использовать эту функцию, укажите шаблон в формате Go с помощью флага --template.

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

doctl compute droplet get 12345678 --template "droplet_name: {{ .Name}}

Outputdroplet_name: ubuntu-1gb-nyc3-01

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

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

Чтобы получить список ресурсов, таких как Droplets, вы можете использовать команду 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 как необязательный параметр. 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

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

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

Например, следующая команда создает именованный тест 64-разрядной капли Debian 8 с 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:

Command	Notes
`doctl compute droplet list`	Your Droplets. Some commands also take the name; most require the numeric value from the ID column.
`doctl compute ssh-key list`	The SSH keys associated with your account. For Droplet creation, you can specify either the numeric ID or fingerprint.
`doctl compute region list`	Available regions. Use the string in the Slug column.
`doctl compute image list`	Available images, including snapshots, backups, and base distribution images. Use the string in the Slug column for creating new Droplets.
`doctl compute size list`	Available Droplet sizes. Use the string in the Slug column.
`doctl compute tag list`	Available Tags. Use the string in the Name column.

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

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

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

`doctl compute droplet` subcommand	Notes
`actions droplet_id`	Display a history of actions taken for a Droplet.
`backups droplet_id`	List backups for a Droplet.
`create name --size s-1vcpu-1gb --image image_slug --region nyc1`	Create a Droplet. Size, image and region are all mandatory.
`delete droplet_id_or_name`	Delete a Droplet by id or name.
`get droplet_id`	Get details for a particular Droplet.
`kernels droplet_id`	List kernels for a Droplet.
`list`	List your current Droplets.
`neighbors droplet_id`	List your Droplets running on the same physical hardware as a specific Droplet.
`snapshots droplet_id`	List snapshots for a Droplet.
`tag droplet_id/droplet_name`	Tag a Droplet.
`untag droplet_id/droplet_name`	Untag a Droplet.

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

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

`doctl compute droplet-action` subcommand	Notes
`get droplet_id --action-id action_id`	Get details about action on a Droplet.
`disable-backups droplet_id`	Disable backups for a Droplet.
`reboot droplet_id`	Reboot a Droplet.
`power-cycle droplet_id`	Turn a Droplet off and back on again.
`shutdown droplet_id`	Shut down a Droplet.
`power-off droplet_id`	Power off a Droplet. The Droplet must be powered on. It’s usually best to do this from the command line of the Droplet itself in order to prevent data loss.
`power-on droplet_id`	Power on a Droplet. The Droplet must be powered off.
`power-reset droplet_id`	Power reset Droplet.
`enable-ipv6 droplet_id`	Enable ipv6 for a Droplet.
`enable-private-networking droplet_id`	Enable private networking for a Droplet.
`upgrade droplet_id`	Upgrade a Droplet.
`restore droplet_id --image-id image_id`	Restore a Droplet to a specific backup image. The `image_id` must be a backup of the Droplet.
`resize droplet_id --size 2gb`	Resize a Droplet. The Droplet must be powered off. By default, disk is not resized, which allows Droplet to be downgraded. You can resize disk using the `--resize-disk` flag.
`rebuild droplet_id --image-id image_id`	Rebuild a Droplet from a specific image.
`rename droplet_id --droplet-name new_name`	Rename a Droplet to `new_name`.
`change-kernel droplet_id --kernel-id kernel_id`	Change a Droplet’s kernel to `kernel_id`.
`snapshot droplet_id --snapshot-name snapshot_name`	Take a snapshot of a Droplet, naming it `snapshot_name`.

Работа с SSH

Создание SSH-подключений

Чтобы подключиться к отдельному дроплету с помощью 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

Примечание. Переадресация команд SSH в настоящее время недоступна в Windows.

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

Flag	Description
`--ssh-user string`	User name to use for the SSH session.
`--ssh-port int`	The port for the SSH session.
`--ssh-key-path string`	Path to SSH key.
`--ssh-agent-forwarding`	Enable agent forwarding.

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

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

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

`doctl compute ssh-key` subcommand	Notes
`list`	List SSH keys associated with your account.
`get ssh_key_id_or_fingerprint`	Get info on a specific key, by numeric ID or key’s fingerprint.
`create new_key_name --public-key "public_key"`	Associate a public key with your account by specifying its contents.
`import new_key_name --public-key-file ~/.ssh/id_rsa.pub`	Associate a public key with your account by specifying a source file.
`delete ssh_key_id_or_fingerprint`	Delete a key from your account by numeric ID or fingerprint.
`update ssh_key_id_or_fingerprint --key-name new_key_name`	Change a key’s name by numeric ID or fingerprint.

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

Плавающий IP-адрес — это общедоступный статический IP-адрес, который может быть назначен одной из ваших капель. Подробное описание этой функции можно найти в разделе «Как использовать плавающие IP-адреса в DigitalOcean». Вы можете манипулировать плавающими IP-адресами с помощью doctl Compute Floating-IP.

`doctl compute floating-ip` subcommand	Notes
`list`	List all Floating IP addresses.
`get floating_ip_address`	Get the details for a Floating IP address.
`create --region nyc1`	Create a Floating IP in `nyc1` region.
`delete floating_ip_address`	Delete a floating IP address.

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

Команда doctl Compute Floating-IP-Action используется для назначения или отмены плавающего IP-адреса в дроплете.

`doctl compute floating-ip-action` subcommand	Notes
`assign floating_ip droplet_id`	Assign a Floating IP to the Droplet by its numeric ID.
`unassign floating_ip`	Unassign a Floating IP.
`get floating_ip action_id`	Get details about a Floating IP action by its numeric ID.

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

Команда doctl calculate domain используется для управления доменами. См. нашу серию «Введение в управление DNS» для общего обзора предмета.

`doctl compute domain` subcommand	Notes
`list`	List domains.
`create domain_name --ip-address droplet_ip_address`	Create a domain with default records for `droplet_ip_address`.
`get domain_name`	Get a domain record.
`delete domain_name`	Delete a domain.

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

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

`doctl compute domain records` subcommand	Notes
`list domain_name`	List records for given domain.
`create domain_name --record-type record_type`	Create an record for domain.
`delete domain_name record_id`	Delete record by numeric ID.
`update domain_name --record-id record_id`	Update record by numeric ID.

Работа с томами блочного хранилища

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

Команду doctl Compute Volume можно использовать для создания, удаления или получения информации о томах блочного хранилища DigitalOcean. Для получения дополнительной информации об этой функции прочитайте наше руководство «Как использовать блочное хранилище в DigitalOcean».

`doctl compute volume` subcommand	Notes
`list`	List volumes.
`create volume_name --region volume_region --size volume_size`	Create a volume. The name, region, and size are mandatory.
`get volume_ID`	Get volume by numeric ID.
`delete volume_ID`	Delete volume.
`snapshot volume_ID`	Snapshot volume.

Запуск действий с объемом

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

`doctl compute volume-action` subcommand	Notes
`attach volume_id droplet_id`	Attach a volume to a Droplet.
`detach volume_id droplet_id`	Detach a volume from a Droplet.
`resize volume_id --region volume_region --size new_size`	Resize a volume.

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

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

`doctl compute load-balancer` subcommand	Notes
`list`	List load balancers.
`create --name lb_name --region lb_region --tag-name tag_name --forwarding-rules forwarding_rule`	Create a Load Balancer. The name, region, a tag or list of Droplet IDs, and at least one forwarding rule are mandatory.
`update --name lb_name --region lb_region --tag-name tag_name --forwarding-rules forwarding_rule`	Create a Load Balancer. The name, region, a tag or list of Droplet IDs, and at least one forwarding rule are mandatory.
`get lb_ID`	Get a load balancer.
`delete lb_ID`	Delete a load balancer.
`add-droplets lb_ID --droplet-ids droplet_ID`	Add Droplets to a load balancer.
`remove-droplets lb_ID --droplet-ids droplet_ID`	Remove Droplets from a load balancer.
`add-forwarding-rules lb_ID --forwarding-rules forwarding_rule`	Add forwarding rules to a load balancer.
`remove-forwarding-rules lb_ID --forwarding-rules forwarding_rule`	Remove forwarding rules from a load balancer.

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

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

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

`doctl compute certificate` subcommand	Notes
`list`	List all Certificates.
`get certificate_id`	Get a Certificate by ID.
`create --name certificate_name --leaf-certificate-path leaf_certificate_path`	Create a Certificate. Name and Leaf Certificate Path are mandatory.
`delete certificate_id`	Delete a Certificate by ID.

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

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

`doctl compute snapshot` subcommand	Notes
`list`	List all Snapshots.
`get snapshot_ID`	Get a Snapshot.
`delete snapshot_ID`	Delete a Snapshot.

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

моментальный снимок дроплет-действия doctl droplet_ID создает мгновенный снимок из дроплета.
моментальный снимок вычислительного тома doctl идентификатор_тома создает моментальный снимок из тома.

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

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

`doctl compute image` subcommand	Notes
`list --public`	List all images.
`list-distribution --public`	List all available distribution images.
`list-application --public`	List all available One-Click Applications.
`list-user`	List all user-created images.
`get image_id`	Get an Image by ID.
`update image_id --name image_name`	Update Image’s name. Name is mandatory.
`delete image_id`	Delete an Image by ID.

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

Команда doctl Compute Image-Action позволяет передавать изображения и получать сведения о действиях, выполняемых над изображениями.

`doctl compute image-action` subcommand	Notes
`get image_id --action-id action_id`	Get an Action for Image by its ID. Action ID is mandatory.
`transfer image_id --region region`	Transfer an Image to the another region. Image ID and region are mandatory.

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

Команда doctl Compute Firewall позволяет создавать брандмауэры и управлять ими, в том числе создавать и поддерживать правила. Для получения дополнительной информации об администрировании брандмауэров с помощью doctl ознакомьтесь с учебным пособием Как защитить инфраструктуру веб-сервера с помощью облачных брандмауэров DigitalOcean с помощью Doctl.

`doctl compute firewall` command	Notes
`list`	List all Firewalls.
`list-by-droplet droplet_id`	List all Firewalls by Droplet’s numeric ID.
`create --name firewall_name --inbound-rules inbound_rules --outbound-rules outbound_rules`	Create a Firewall. The name and at least an inbound or outbound rule are mandatory.
`update firewall_id --name firewall_name --inbound-rules inbound_rules --outbound-rules outbound_rules`	Update a Firewall. The numeric ID, name and at least an inbound or outbound rule are mandatory.
`get firewall_id`	Get a Firewall by its numeric ID.
`delete firewall_id`	Delete a Firewall by numeric ID.
`add-droplets firewall_id --droplet-ids droplet_IDs`	Add Droplets by their numeric ID to the Firewall.
`remove-droplets firewall_id --droplet-ids droplet_IDs`	Remove Droplets from the Firewall by their numeric IDs.
`add-tags firewall_id --tag-names tags`	Add Tags to the Firewall.
`remove-tags firewall_id --tag-names tags`	Remove Tags from the Firewall.
`add-rules firewall_id --inbound-rules inbound_rules --outbound-rules outbound_rules`	Add inbound or outbound rules to the Firewall.
`remove-rules firewall_id --inbound-rules inbound_rules --outbound-rules outbound_rules`	Remove inbound or outbound rules to the Firewall.

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

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

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

`doctl compute tag` subcommand	Notes
`create tag_name`	Create a Tag.
`get tag_name`	Get a Tag by name.
`list`	List all Tags.
`delete tag_name`	Delete a Tag by name.

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

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

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

doctl compute action list

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

doctl compute droplet actions droplet_id

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

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

doctl account get

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

doctl account ratelimit

Заключение

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

Помимо изучения таких инструментов, как Ansible, для автоматизации задач системного уровня.