Skip to content

Latest commit

 

History

History
1404 lines (945 loc) · 64.4 KB

README.md

File metadata and controls

1404 lines (945 loc) · 64.4 KB
Raw

twc

Интерфейс командной строки для управления сервисами Timeweb Cloud и простой SDK 💫

См. также полный справочник по командам: Command Line Interface (CLI) Reference 📜

Руководство пользователя

Содержание:

  1. Установка
    1. pip (рекомендованный способ)
    2. pipx
    3. Архив .tar.gz
    4. zipapp
  2. Обновление
  3. Начало работы
  4. Представление информации
    1. Формат вывода
    2. Фильтрация списков, опция --filter
  5. Управление облачными серверами
    1. Создание сервера
    2. Установка ПО из Маркетплейса
    3. Переустановка сервера
    4. Просмотр списка серверов
    5. Получение информации о сервере
    6. Управление IP-адресами
    7. Управление дисками
    8. Резервное копирование
  6. Управление образами
    1. Основные действия с образами
    2. Создание образа существующей ВМ
    3. Загрузка собственного образа
  7. Управление базами данных
    1. Создание базы данных
    2. Изменение параметров базы данных
  8. Управление балансировщиками нагрузки
  9. Управление объектным хранилищем
    1. Базовые операции с бакетами
    2. Изменение настроек бакета
    3. Привязка доменных имён к бакету
    4. Получение конфигурации для S3-клиентов
  10. Управление кластерами Kubernetes
    1. Создание кластера
    2. Подключение к кластеру
    3. Управление нодами в кластере
  11. Управление DNS
    1. Добавление доменного имени
    2. Работа с поддоменами
    3. Просмотр информации о доменах
    4. Редактирование DNS
  12. Управление сетями (VPC)
    1. Создание приватной сети
    2. Команды для работы с сетью
  13. Управление Firewall
    1. Правила и группы правил
    2. Создание и применение правил
  14. Управление проектами
  15. Коrнфигурация
    1. Конфигурационный файл
    2. Переменные окружения
    3. Работа с несколькими аккаунтами
    4. Использование прокси
      1. HTTP/HTTPS-прокси
      2. SOCKS-прокси
  16. Автодополнение команд
  17. Использование twc в качестве SDK

Установка

pip (рекомендованный способ)

  1. Убедитесь, что на компьютер установены Python не ниже версии 3.7 и пакетный менеджер pip. См. инструкцию.
  2. Установите пакет twc-cli с помощью pip командой:
pip install twc-cli

В зависимости от установленных на компьютере версий Python вам может потребоваться использовать команду pip3 вместо pip.

pipx

  1. Убедитесь, что на компьютер установен Python не ниже версии 3.7 и пакетный менеджер pip. См. инструкцию.
  2. Установите пакетный менеджер pipx по инструкции.
  3. Установите пакет twc-cli:
pipx install twc-cli

Архив .tar.gz

  1. Убедитесь, что на компьютер установены Python не ниже версии 3.7 и пакетный менеджер pip. См. инструкцию.
  2. Скачайте пакет twc-cli в формате .tar.gz со страницы загрузок.
  3. Перейдите в терминале в директорию где расположен файл .tar.gz и установите его с помощью pip:
pip install ./twc_cli-2.1.1.tar.gz

zipapp

  1. Убедитесь, что на компьютер установен Python не ниже версии 3.7. См. инструкцию.
  2. Скачайте пакет в формате .pyz со страницы загрузок.
  3. а) Приложение в формате zipapp не требует установки, вы можете сразу запустить программу следующим образом:
python twc-cli-2.1.1.pyz --help
  1. б) Вы можете поместить файл в директорию из PATH, например так (на UNIX-подобных системах):
install -m755 twc-cli-2.1.1.pyz /usr/local/bin/twc

Обновление

Рекомендуем регулярно обновлять twc. Если вы установили twc с помощью pip, то команда для обновления будет выглядеть так:

pip install -U twc-cli

pipx:

pipx upgrade twc-cli

Обновление пакетов в форматах .tar.gz и .pyz нужно выполнять вручную по инструкции по установке.

Следующий однострочный скрипт позволит скачать актуальный zipapp-пакет с GitHub:

curl -sS -w %{redirect_url} https://github.com/timeweb-cloud/twc/releases/latest | cut -d / -f 8 | sed s/v// | xargs -I {} curl -sSLo twc_cli-{}.pyz https://github.com/timeweb-cloud/twc/releases/download/v{}/twc_cli-{}.pyz

Проверить наличие обновлений вручную вы можете на странице релизов в GitHub или в PyPI. Актуальный релиз помечен как Latest.

Начало работы

Прежде всего нужно получить токен доступа в панели управления Timeweb Cloud. Перейдите в раздел Токены API и выпустите новый токен с любым сроком действия.

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

twc config

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

twc содержит встроенную справку на английском языке. Через неё можно получить информацию обо всех доступных командах и опциях. Вызвать справку можно запустив twc опцией с --help:

twc --help

twc имеет множество субкоманд с различной степенью вложенности. Опция --help доступна на каждом уровне вложенности для всех субкоманд. Например так можно последовательно прочитать справку по командам для управления облачными серверами:

twc server --help
twc server create --help

В этом руководстве пользователя нет исчерпывающего описания всех доступных команд, субкоманд и их опций. Обращайтесь к встроенной справке twc или CLI Reference для информации. Далее описаны вероятные сценарии использования утилиты, способы конфигурации и некоторые полезные приёмы.

Представление информации

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

По умолчанию twc старается выводить данные на экран в человекочитаемом виде: таблицы, списки или отформатированный текст. Через опцию --output (-o) можно выбрать машиночитаемые форматы.

Формат Описание
default Отформатированный текст или таблица (по умолчанию)
raw Тело ответа в необработанном "сыром" виде
json JSON с сортировкой ключей
yaml YAML с сортировкой ключей

Некоторые объекты, возвращаемые от API из-за большого числа ключей удобней просматривать в YAML. Например, чтобы увидеть полную информацию об облачном сервере выполните команду:

twc server get  -o yaml 1235631

ID сервера можно получить запросив их список командой twc server list.

response_id: 80903661-f587-43ca-abfc-d610ac3bc50c
server:
  avatar_id: null
  boot_mode: std
  comment: ''
  configurator_id: 11
  cpu: 2
  cpu_frequency: '3.3'
  created_at: '2023-02-04T15:08:20.000Z'
  disks:
  - id: 8260143
    is_mounted: true
    is_system: true
    size: 30720
    status: done
    system_name: vda
    type: nvme
    used: 0
  - id: 8471677
    is_mounted: true
    is_system: false
    size: 40960
    status: done
    system_name: vdb
    type: nvme
    used: 0
  id: 1235631
  is_ddos_guard: false
  location: ru-1
  name: dev-1
  networks:
  - bandwidth: 200
    ips:
    - ip: x.x.x.x
      is_main: true
      ptr: example.tld
      type: ipv4
    type: public
  - ips:
    - ip: 172.16.16.51
      type: ipv4
    nat_mode: dnat_and_snat
    type: local
  os:
    id: 79
    name: ubuntu
    version: '22.04'
  preset_id: null
  ram: 2048
  software: null
  start_at: '2023-02-20T12:12:15.000Z'
  status: 'on'
  vnc_pass: soG7u7JA

Чтобы постоянно использовать определённый формат вывода задайте переменную окружения TWC_OUTPUT_FORMAT или параметр output_format в конфигурационном файле.

Фильтрация списков, опция --filter

Некоторые команды имеют опцию --filter (-f) для фильтрации коллекций (списков) по их ключам.

Обратите внимание, что --filter действует только на формат вывода по умолчанию и не влияет на вывод в других форматах (см. --output). Для фильтрации JSON используйте утилиту jq, а для фильтрации YAML — yq.

Рассмотрим фильтрацию на примере списка облачных серверов. Следующая команда выведет только серверы, которые имеют статус on, то есть включены:

twc server list -f status:on

Фильтровать можно одновременно по нескольким критериям перечислив пары ключ:значение через запятую. Эта команда покажет все включённые серверы в локации ru-1:

twc server list -f status:on,location:ru-1

Для фильтра по локациям также можно использовать алиас region.

При фильтрации полагайтесь на имена полей, которые содержатся в JSON/YAML, а не на имена столбцов в таблице.

Поддерживается поиск по вложенным ключам. Так, например, имя (name) и версия (version) операционной системы являются дочерними от ключа os. Для того, чтобы обратиться к дочернему ключу, нужно записать его через точку. Фильтр нечувствителен к регистру. Вот так можно посмотреть серверы, на которые установлена ОС Ubuntu 22.04:

twc server list -f os.name:ubuntu,os.version:22.04

Фильтр по вложенным ключам не будет работать с ключами, которые содержат списки. Для серверов это ключи networks и disks. Используйте JSON или YAML для сложных запросов.

Управление облачными серверами

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

В Timeweb Cloud серверы можно создавать на основе готовых пресетов или собрать свою конфигурацию через конфигуратор.

Для создания сервера как минимум нужно три обязательных параметра: имя, пресет или конфигуратор и образ.

Пресет (опция --preset-id) определяет основные параметры сервера, такие как RAM, объём системного диска, тип диска, количество vCPU и др. Получить список всех доступных пресетов можно следующей командой:

twc server list-presets

Обратите внимание, что пресет также определяет локацию (регион) создания сервера. Вот так можно посмотреть все доступные пресеты для локации ru-1 (Россия, Санкт-Петербург) с типом диска NVMe SSD:

twc server list-presets -f location:ru-1,disk_type:nvme

Другой обязательный параметр это образ (опция --image). Timeweb Cloud предлагает готовые к работе образы популярных операционных систем, получить их список можно командой:

twc server list-os-images

Можно использовать как числовой ID (os_id) образа, так и имя операционной системы в формате <name>-<version>-<codename>. codename добавляется только для образов ОС Windows, образы GNU/Linux можно однозначно идентифицировать и по шаблону <name>-<version>, например, debian-11. Ещё одно возможное значение это UUID пользовательского образа диска (доступно с версии v1.1.0).

Пример создания сервера на основе пресета с готовым образом ОС:

twc server create --name dev-1 --image ubuntu-22.04 --preset-id 2573 --ssh-key ~/.ssh/id_rsa.pub

Для создания сервера с произвольной конфигурацией необходимо указать как минимум объём RAM, объём диска и число vCPU:

twc server create --name dev-1 --image ubuntu-22.04 --cpu 2 --ram 2G --disk 50G --ssh-key ~/.ssh/id_rsa.pub --region ru-1

Значения --ram и --disk поддерживают запись в M, G и T.

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

Добавлено в версии v2.1.0 Опционально можно задать опцию --region для выбора локации.

Посмотрите встроенную справку по созданию серверов twc server create --help, чтобы изучить все доступные опции.

Установка ПО из Маркетплейса

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

Получите ID ПО командой list-software:

$ twc server list-software
ID	NAME                 	OS
2 	ISPmanager 6 Lite    	39, 73, 58, 57, 47, 61
17	LAMP                 	39, 47, 58, 79, 73, 67, 61
18	GitLab               	39, 47, 79
20	VestaCP              	39, 47, 58
21	ISPmanager 6 Business	39
23	Portainer            	47, 39, 58, 79, 61, 67
24	Ruby on Rails        	47, 79
25	Docker               	47, 61, 79
26	Redmine              	47, 61, 79
...
91	NextCloud            	79

В колонке OS перечислены ID (os_id) операционных систем для которых доступен софт. При создании сервера необходимо передать как ID софта, так и ID или имя соответствующей операционной системы.

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

twc server create --name my-nextcloud --preset-id 2451 --image ubuntu-22.04 --software-id 91

ubuntu-22.04 соотвествует os_id 79. Все соответствия можно найти по выводу команды twc server list-os-images.

Переустановка сервера

Предусмотрена возможность переустановки ОС сервера.

twc server reinstall --help

Переустановить ОС на сервере 1234567:

twc server reinstall 1234567

Будет установлена та же ОС или пользовательский образ, что были установлены ранее. Также можно установить другую операционную систему или образ. Например, AlmaLinux 9.0:

twc server reinstall --image almalinux-9.0 1234567

Возможно также установить доп. ПО, см. twc server list-software.

twc server reinstall --image ubuntu-22.04 --software-id 91 1234567

Здесь опцию --image можно опустить, twc автоматически подставит ID операционной системы, которая в текущий момент установлена на сервере. Если ОС совместима с указанным ПО, то операция завершится успешно, иначе сервер не будет изменён.

Warning
Обратите внимание, что при переустановке сервера с выбранным ПО будет также переустановлена ОС!

Просмотр списка серверов

Выполните следующую команду, чтобы увидеть список всех облачных серверов на вашем аккаунте:

twc server list

В некоторых случаях будет удобна опция --ids, которая вместо таблицы покажет список ID серверов.

См. также Фильтрация списков, опция --filter.

Получение информации о сервере

Команда get отобразит информацию о конкретном сервере:

twc server get 1234567

Будет напечатана стандартная таблица. Для полного вывода добавьте опцию -o yaml.

Отдельно доступен просмотр информации по сетям и подключённым дискам.

Информация о дисках:

twc server get --disks 1234567
twc server disk list 1234567  # идентичный результат

Информация о сетях:

twc server get --networks 1234567

Обратите внимание, что команда выше покажет информацию как о публичной, так и о приватной сети. Следующая команда покажет только публичную сеть:

twc server ip list 1234567

Опция --status позволит отобразить на экране лишь статус сервера без посторонней информации. Если статус не равен on twc завершит работу с кодом выхода 1. Это применимо в Shell-скриптах для автоматизации. Например, так можно выполнить команды при условии, что сервер включён:

if twc server get --status 1234567 >/dev/null 2>&1; then
    # команды
fi

Изменение параметров сервера

twc server resize --help

Вы можете изменить CPU, RAM и ширину сетевого канала в бо́льшую или меньшую сторону, диски только в бо́льшую. Возможен переход с конфигуратора на пресет и обратно.

Чтобы перейти на (другой) пресет выполните:

twc server resize --preset-id 1234 1234567

Где 1234567 это ID сервера.

Изменение отдельных параметров (CPU, RAM, диск) приводит к переходу на конфигуратор:

twc server resize --cpu 4 --ram 8G 1234567

Чтобы изменить пропускную способность сети:

twc server resize --bandwidth 300 1234567

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

Управление IP-адресами

Команда ip предоставляет интерфейс для работы с публичными IP-адресами.

twc server ip --help

Следующая команда добавит к серверу дополнительный IPv4-адрес:

twc server ip add --ipv4 1234567

Опцию --ipv4 можно опустить, по умолчанию применяется IPv4.

Задать PTR mail.example.org для IP-адреса 123.123.123.123:

twc server ip set --ptr mail.example.org 123.123.123.123

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

В управлении дисками доступен просмотр подключённых дисков, добавление/удаление дисков, а также настройка автоматических резервных копий диска.

twc server disk --help

Добавить дополнительный диск к серверу 1234567:

twc server disk add --size 50g 1234567

Резервное копирование

Команда backup реализует интерфейс для работы с резервными копиями дисков. Резервная копия представляет собой образ блочного устройства.

twc server backup --help

Добавлено в версии v2.0.0. Для того, чтобы включить регулярное резервное копирование основного диска для сервера 1234567 выполните:

twc server backup schedule --enable --keep 3 $(twc server disk list -o default 1234567 | awk '$4~/True/{print $1}')

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

Посмотреть текущие настройки автоматического копирования диска 7654321:

twc server backup schedule --status 7654321

Просмотр списка бэкапов по ID диска:

twc server backup list 7654321

Следующая команда покажет список бэкапов по всем дискам для сервера 1234567:

twc server disk list -o default 1234567 | awk 'NR>1{print $1}' | xargs -L 1 twc server backup list

Создать резервную копию диска 7654321:

twc server backup create 7654321

Восстановить резервную копию диска 7654321:

twc server backup restore 7654321 1234567

Здесь 1234567 это ID резервной копии.

Управление образами

Добавлено в версии v1.1.0.

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

twc image --help

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

Учитывайте, что образы имеют привязку к локациям — для создания ВМ в другой локации сперва необходимо загрузить образ в новю локацию. Пока сервис доступен только в ru-1 (Санкт-Петербург).

Создание образа существующей ВМ

twc image create --help

Сперва получите ID диска, образ которого нужно создать:

twc server disk list SERVER_ID

Следующая команда создаст образ диска 7654321 и напечатает на экран UUID образа.

twc image create 7654321

Можно одной командой сразу сделать образ системного диска сервера (1234567):

twc image create $(twc server disk list -o default 1234567 | awk '$4~/True/{print $1}')

Можно отслеживать прогресс создания образа командой:

watch echo Progress: $(twc image get uuid_образа -o json | jq .image.progress)%

watch будет каждые 2 секунды проверять прогресс. Нажмите Ctrl+C для выхода.

Загрузка собственного образа

Note
Предварительно необходимо специальным образом подготовить образ диска. См. инструкцию.

twc image upload --help

В twc пока реализована только загрузка образа по прямой HTTP-ссылке. Загрузите файл с расширением vmdk, vhd, vhdx, vdi, raw, img или qcow2 в любое хранилище, где можно получить прямую ссылку. Затем выполните команду вида:

twc image upload --name my-custom-image https://example.com/custom-image.qcow2

В ответ команда напечатает UUID образа.

Управление базами данных

Добавлено в версии v1.2.0.

twc db --help

Создание базы данных

twc db create --help

Просмотрите список доступных пресетов конфигурации баз данных. Пресеты различаются в зависимости от СУБД.

twc db list-presets

Вы можете отфильтровать пресеты по СУБД в поле type. Следующая команда покажет пресеты для MySQL:

twc db list-presets -f type:mysql

Создайте базу данных:

twc db create --name db-dev --type mysql8 --login app --preset-id 327

После нажатия Enter twc предложит ввести пароль для базы данных. Вместо интерактивного ввода вы можете использовать опцию --password и ввести пароль прямо в командной строке. Учтите, что печатать пароль в командной строке может быть небезопасно.

Команда создаст инстанс СУБД MySQL 8 db-dev с юзером app. Имя базы данных для подключения будет default_db. Смотрите параметры подключения в выводе команды:

twc db get -o yaml 123456

Где 123456 это ID инстанса СУБД.

Вы можете сразу при создании БД указать параметры СУБД, например:

twc db create --name db-dev --type mysql8 --login app --preset-id 327 --param max_connections=200 --param max_allowed_packet=64M

Изменение параметров базы данных

twc db set --help

С помощью этой команды вы можете изменять свойства инстанса и параметры СУБД. Например для БД ID 123456:

twc db set --param max_connections=200 123456

Изменить отображаемое имя инстанса СУБД (не изменяет имя базы данных):

twc db set --name db-dev-1 123456

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

twc balancer --help

TODO

Управление объектным хранилищем

Добавлено в версии v1.3.0

twc s3 --help

Команда storage или s3 позволяет управлять бакетами в объектном хранилище.

Note twc не реализует методы S3 API, поэтому для работы с объектами внутри бакетов используйте готовые S3-клиенты такие как s3cmd или rclone, cм. Получение конфигурации для S3-клиентов ниже.

Базовые операции с бакетами

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

Чтобы создать бакет сперва узнайте ID пресета, список пресетов можно получить командой:

twc s3 list-presets

Пресет можно не указывать, тогда будет выбран минимальный с 10 Гб диска.

Создать новый бакет:

twc s3 mb --preset-id 1234 имя-бакета

По умолчанию бакет будет приватный, вы можете задать опцию --type public, чтобы сделать его публичным.

Обратите внимание, что при создании бакетов через twc (и API Timeweb Cloud) к имени бакета будет добавлен уникальный для аккаунта префикс. Имя созданного бакета будет отображено сразу по выполнении команды. Префикс не добавляется при создании бакетов через S3-клиенты.

Просмотр списка бакетов:

twc s3 ls

В списке работает фильтрация.

Изменение настроек бакета

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

twc s3 set --type public имя-бакета

Изменить пресет бакета:

twc s3 set --preset-id 1234 имя-бакета

Привязка доменных имён к бакету

twc s3 subdomain --help

Справка по привязке доменов.

Успешно привязать домен можно если у него есть CNAME-запись s3.timeweb.com. Например:

twc s3 subdomain add my-bucket.example.com имя-бакета

Запросить SSL-сертификат Let's Encrypt для домена (будет продлеваться автоматически):

twc s3 subdomain gencert my-bucket.example.com

Получение конфигурации для S3-клиентов

twc s3 genconfig --help

Поддерживается генерация конфигов для утилит s3cmd и rclone.

Чтобы сгенерировать конфигурационный файл для s3cmd выполните:

twc s3 genconfig --client s3cmd

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

Если вы впервые настраивате s3cmd выполните (на Linux/Mac):

twc s3 genconfig --client s3cmd > ~/.s3cfg

Если вы уже пользовались s3cmd, то вероятно захотите сохранить конфигурацию в другой файл:

twc s3 genconfig --client s3cmd > ~/.s3cfg-twc

В таком случае для использования s3cmd добавляйте к командам опцию -c ~/.s3cfg-twc.

Если ваша командная оболочка не поддерживает операторы >, >> для перенаправления вывода, то вы можете воспользоваться опцией --save, чтобы сохранить конфигурацию в файл. Например (Windows cmd.exe):

twc s3 genconfig --client s3cmd --save %USERPROFILE%\.s3cfg

Note Осторожно: --save перезапишет файл, если он уже существует.

Для генерации конфига rclone выполните:

mkdir -p ~/.config/rclone
twc s3 genconfig --client rclone >> ~/.config/rclone/rclone.conf

Далее можно работать с объектами в бакете по схеме twc:

rclone ls twc:/

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

Добавлено в версии v2.3.0

twc cluster --help

Создание кластера

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

  • Версии Kubernetes: twc cluster list-k8s-versions
  • Доступные сетевые драйверы: twc cluster list-network-drivers
  • Пресеты конфигурации нод: twc cluster list-presets -f type:worker

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

twc cluster create --name myproj-dev \
    --k8s-version v1.22.17 \
    --network-driver canal \
    --ingress \
    --add-worker-group name=gr-1,preset=443,count=2 \
    --add-worker-group name=gr-2,preset=399,count=4

В самом простом случае необходимо указать только имя кластера:

twc cluster create --name myproj-dev

В таком случае будут применены параметры по умолчанию: cетевой драйвер canal, Ingress, одна группа воркер-нод, одна воркер-нода с минимальным пресетом (1Гб RAM, 1 CPU).

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

Для управления кластером используйте утилиту kubectl или любой другой клиент для Kubernetes (например, Lens)

Чтобы получить KubeConfig выполните команду:

twc cluster kubeconfig 123456 --save config.yaml

где 123456 ID кластера. ID можно посмотреть в выоде команды twc cluster list.

Теперь можно работать с кластером через kubectl:

kubectl --kubeconfig config.yaml get nodes

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

Увеличить число нод в группе 54321 на два:

twc cluster group scale-up 54321 2

Уменьшить число нод на два:

twc cluster group scale-down 54321 2

Добавить новую группу нод:

twc cluster group add --name group-2 --preset-id 443 --count 2

Значения для --preset-id можно получить командой twc cluster list-presets -f type:worker.

Управление DNS

Добавлено в версии v2.4.0

twc domain --help

Добавление доменного имени

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

twc domain add example.com

Note Команда выше всего-лишь добавит домен в систему. Для того, чтобы редактировать DNS обязательно нужно изменить NS-серверы домена на NS Timeweb Cloud.

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

Добавить поддомен subdomain:

twc domain subdomain add subdomain.example.com

Если ваш домен зарегистрирован на 2LD, то есть в зоне второго уровня (например, example.spb.ru), то для создания поддомена используйте опцию --2ld:

twc domain subdomain add subdomain.example.spb.ru --2ld

Поддомены четвёртого, пятого и т.д. уровней создаются аналогичным образом с указанием полного имени (FQDN). Для 2LD также всегда нужно добавлять опцию --2ld.

Просмотр информации о доменах

Вывести список доменов:

twc domain list

Опция -a (--all) позволит отобразить полный список включающий все поддомены.

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

twc domain info example.com

Редактирование DNS

Просмотреть список DNS-записей домена:

twc domain record list example.org

Опция -a (--all) позволит отобразить также записи со всех поддоменов. Заметьте, что у записей есть ID, он потребуется для редактирования существующих записей.

Добавить A-запись для домена example.com:

twc domain record add example.com --type A --value 127.128.129.130

Добавить MX-запись с приоритетом 10:

twc domain record add example.com --type MX --value mx.example.com --prio 10

Добавить SPF-запись:

twc domain record add example.com --type TXT --value 'v=spf1 ip4:127.128.129.130 ~all'

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

twc domain record update example.com 53162075 --type A --value 127.128.129.131

Здесь 53162075 это ID DNS-записи.

Добавить DMARC-запись:

twc domain record add _dmarc.example.com --type TXT --value 'v=DMARC1;p=quarantine;rua=mailto:postmaster@example.com'

Чтобы добавить/изменить записи на доменах третьего уровня (на 2LD) или их поддоменах указывайте опцию --2ld.

Управление сетями (VPC)

Добавлено в версии v2.4.0

twc vpc --help

или

twc network --help

Создание приватной сети

twc network create 10.0.10.0/24

Команда вернёт идентификатор сети. Этот ID нужно будет использовать при создании сервисов, чтобы добавить их в сеть.

Используйте опцию --region чтобы явно задать локацию, в которой будет создана сеть. По умолчанию — ru-1 (Санкт-Петербург).

Команды для работы с сетью

Показать список сетей:

twc network list

Показать список сервисов в сети:

twc network show network-0d48ed0787f84aa681c346a62342a0a1

Показать список сетевых портов:

twc network port list network-0d48ed0787f84aa681c346a62342a0a1

Смотрите другие команды в справке twc vpc --help.

Управление Firewall

Добавлено в версии v2.4.0

twc firewall --help

Правила и группы правил

Правила файрвола представляют собой записи с указанием CIDR (одного или нескольких IP-адресов), портов, протокола и направления трафика. Правила для удобства менеджмента объединяются в группы. Можно создать ограниченное количество групп и правил, см.Firewall.

Задача: запретить к серверу любой траафик кроме SSH и ICMP (пинг) для любых IP-адресов. Решение:

  • Создать группу правил
  • Добавить правило разрешающее трафик на 22-й порт TCP
  • Добавить правило разрешаюющее трафик ICMP
  • Слинковать (применить) группу правил на сервер

Созданную группу правил можно слинковать со многими другими серверами.

Создание и применение правил

Продолжая задачу из предыдущего пункта получаем следующее практическое решение. Создаём группу правил с нужными правилами:

twc firewall rule add -G --ingress --cidr 0.0.0.0/0 22/TCP ICMP

В ответ команда напечатает ID группы правил и ID каждого созданного правила. Здесь будет два правила для 22/TCP и ICMP соответственно.

Здесь использована опция -G (--make-group), которая создаёт новую группу и добавляет в неё все перечисленные правила. С помощью опции -g (--group) можно добавить правла в уже существующую группу. См. все опции в справке. Команда для редактирования правила работает аналогично twc firewall rule update --help.

Создать новую группу (без правил):

twc firewall group create --name 'basic_firewall'

Показать список групп правил:

twc firewall group list

Показать список правил в заданной группе:

twc firewall rule list a46c71de-36c2-46b9-9dff-a85761545c68

Здесь a46c71de-36c2-46b9-9dff-a85761545c68 это ID группы правил.

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

twc firewall link server 12345678 fe497e70-e3a9-43af-9da5-c9367ed1f991

Первый аргумент (server) задаёт тип сервиса, с которым будет произведено действие, за ним следует ID сервиса и ID группы правил файрвола. Чтобы удалить все правила вместо команды link используйте аналогичную команду unlink. Чтобы удалить одно конкретное правило используйте команду вида:

twc firewall rule remove fe497e70-e3a9-43af-9da5-c9367ed1f991

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

twc firewall show server 1234567

Список правил можно фильтровать. Например, так можно посмотреть все правила для TCP:

twc firewall show server 1234567 -f proto:tcp

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

Добавлено в версии v1.1.0.

twc project --help

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

Посомтреть список проектов:

twc project list

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

Субкомманда resource позволяет выпонлять операции над ресурсами (сервисами) проекта.

twc project resource --help

Можно вывести на экран список всех ресурсов проекта:

twc project resource list 12345

Здесь 12345 это ID преокта.

Изменено в версии v2.0.0. Переместить сервер 1234567 в проект 54321:

twc project resource move --server 1234567 54321

Конфигурация

Конфигурационный файл

Конфигурационный файл представляет из себя обычный текст в формате TOML в кодировке UTF-8. Его можно редактировать любым текстовым редактором.

twc сохраняет конфигурацию в домашней директории пользователя.

На операционных системах семейства Windows конфигурация сохраняется в скрытый файл .twcrc (не имеет расширения). Найти путь к домашнему каталогу можно через переменную среды USERPROFILE, обычно она имеет значение вида c:\Users\имя_пользователя. Файл также может называться .twcrc.toml (доступно с версии v2.0.0).

На операционных системах семейств Linux, Mac, BSD и других UNIX-подобных конфигурация сохраняется в HOME в файл .twcrc. Обычно /home/имя_пользователя/.twcrc.

Добавлено в версии v1.3.0. Выполните следующую команду чтобы посмотреть путь до конфигурационного файла:

twc config file

Поддерживаемые параметры:

Параметр Описание
token Токен доступа Timeweb Cloud. Параметр записывается автоматически при вызове twc config
output_format Соответствует опции --output (-o)
project_id ID проекта, куда будет добавлен ресурс после создания
region Локация по умолчанию для новых ресуерсов

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

Добавлено в версии v1.3.0. Вы можете без ручного редактирования файла задать параметры конфигурации командой twc config set.

По умолчанию будет задан параметр для профиля default, например:

twc config set output_format=yaml

Укажите конкретный профиль опцией --profile (-p), если их несколько:

twc config set -p dev output_format=yaml

Добавлено в версии v2.0.0. Удалить параметр из конфигурации можно командой twc config unset параметр.

Добавлено в версии v1.3.0. Если вам нужно обновить токен (например, после того как перевыпустили его) запустите twc config, введите имя профиля и новый токен.

Переменные окружения

twc поддерживает ряд переменных окружения (они же переменные среды), которые могут быть использованы для конфигурации во время выполнения. Прочитайте страницу о переменных окружения в Википедии.

Переменная Опция Описание
TWC_TOKEN Токен доступа
TWC_PROFILE --profile, -p Имя профиля
TWC_CONFIG_FILE --config, -c Путь до конфигурационного файла
TWC_DEBUG --verbose, -v Включить подробный лог
TWC_OUTPUT_FORMAT --output, -o Формат вывода (default, raw, json, yaml)
TWC_PROJECT --project-id ID проекта, куда будет добавлен ресурс после создания
TWC_LOG Параметры логирования через запятую, допустимые параметры: log_response
TWC_REGION --region Локация по умолчанию для новых ресуерсов

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

Ниже перечислены параметры конфигурации в порядке понижения приоритета:

  1. --profile, -p, --config, -c
  2. TWC_TOKEN
  3. TWC_PROFILE, TWC_CONFIG_FILE

Наличие конфигурационного файла при использовании переменной TWC_TOKEN необязательно.

Работа с несколькими аккаунтами

Вы можете работать с несколькими аккаунтами Timeweb Cloud используя один или несколько конфигурационных файлов.

В командной строке используйте опции --config (-с) и --profile (-p) для указания пути к конфигурационному файлу и имени профиля соответственно.

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

Так выглядит стандартный файл:

[default]
token = "здесь_ваш_токен"

В этом примере есть только один профиль — default. Он используется по умолчанию.

Чтобы добавить дополнительный профиль вы можете отредактировать конфигурационный файл вручную или вызвать команду twc config (доступно с версии v1.3.0). Интерактивный сеанс будет выглядеть так:

$ twc config
You already have TWC CLI configured, continue? [y/N]: y
Enter profile name [default]: dev
Enter API token for 'dev': eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtp...
Done! Configuration is saved in /home/user/.twcrc

Конфигурационный файл станет выглядеть так:

[default]
token = "токен_для_default"

[dev]
token = "токен_для_dev"

Теперь можно переключаться между профилями с помощью опции -p.

Показать список серверов для профиля default:

twc server list

Показать список серверов для профиля dev:

twc -p dev server list

Вы можете использовать переменные окружения вместо опций -p и -c. Это может быть полезно при автоматизации через Shell-скрипты. См. раздел Переменные окружения ниже.

Использование прокси

twc использует популярную библиотеку Python Requests для выполнения HTTP-запросов.

В requests уже реализована поддержка переменных окружения HTTP_PROXY, HTTPS_PROXY, ALL_PROXY и NO_PROXY. Подробнее об их применении можно прочитать в документации Requests.

HTTP/HTTPS-прокси

Экспортируйте в оболочку переменные окружения. Замените адрес прокси на актуальный.

Linux/Mac:

export HTTP_PROXY=http://10.10.1.10:3128
export HTTPS_PROXY=http://10.10.1.10:1080

Windows:

set HTTP_PROXY=http://10.10.1.10:3128
set HTTPS_PROXY=http://10.10.1.10:1080

SOCKS-прокси

Для работы c SOCKS-прокси необходимо установить дополнительную библиотеку Python — PySocks. Ею поддерживаются протоколы HTTP, SOCKS4 и SOCKS5.

Linux/Mac:

export ALL_PROXY=socks5://localhost:1080

Windows:

set ALL_PROXY=socks5://localhost:1080

Если вы хотите отправлять через прокси также и DNS-запросы, то замените схему socks5 на socks5h:

export ALL_PROXY=socks5h://localhost:1080

Автодополнение команд

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

Установить скрипт автодополнения:

twc --install-completion

twc автоматически распознает командную оболочку, поддерживаются: Bash, Zsh, Fish, PowerShell.

Использование twc в качестве SDK

В twc реализован почти полнофункциональный клиент API Timeweb Cloud.

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

  • работа с токенами доступа;
  • управление ограничениями доступа к аккаунту;
  • методы для выделенных серверов;
  • работа с доменами за исключением редактирования DNS.

Установите пакет twc-cli в систему или в виртуальное окружение. Импортируйте в свой код класс TimewebCloud из модуля twc.api.client. В простейшем случае вам нужно создать объект этого класса передав в его конструктор строку с токеном. После этого можно обращаться к методам класса. Все методы возвращают объект requests.Response.

Пример кода для получения списка облачных серверов:

import os
import json

from twc import TimewebCloud


client = TimewebCloud(os.getenv("TIMEWEB_CLOUD_TOKEN"))
print(json.dumps(client.get_servers().json(), ensure_ascii=False, indent=2))

Есть собственные исключения в модуле twc.api.exceptions. В конструктор класса TimewebCloud можно передать функцию-декоратор, которая обернёт метод _request(). Все исключения унаследованы от TimewebCloudException.

Пример обработки ошибок через декоратор:

import os
import sys
import textwrap

from twc import TimewebCloud
from twc.api import TimewebCloudException, UnauthorizedError


def handle_errors(func):
    def wrapper(self, *args, **kwargs):
        try:
            return func(self, *args, **kwargs)
        except UnauthorizedError as err:
            sys.exit(f"Error: {err}")
        except TimewebCloudException as err:
            sys.exit(
                textwrap.dedent(
                    f"""
                    Status code: {err.status_code}
                    Error code: {err.error_code}
                    Message: {err.message}
                    Response ID: {err.response_id}
                    """
                ).strip()
            )
    return wrapper

client = TimewebCloud(
    os.getenv("TIMEWEB_CLOUD_TOKEN"),
    request_decorator=handle_errors,
)

ssh_keys = client.get_ssh_keys().json()

См. расширенный пример в модуле twc.apiwrap.

Методы задокументированы в коде в докстрингах, а также на https://timeweb.cloud/api-docs.