twc-cli 2.4.1__py3-none-any.whl → 2.6.0__py3-none-any.whl

CHANGELOG.md

@@ -2,6 +2,52 @@
 
 В этом файле описаны все значимые изменения в Timeweb Cloud CLI. В выпусках мы придерживается правил [семантического версионирования](https://semver.org/lang/ru/).
 
+# Версия 2.6.0 (2024.08.14)
+
+## Добавлено
+
+- В команды и API-клиент для управления облачным файрволом добавлена поддержка протоколов TCP6, UDP6, ICMP6 и настройка стандартной политики (DROP или ACCEPT).
+- Добавлены новые команды: `twc firewall group get`, `twc firewall group dump` и `twc firewall group restore`.
+
+## Изменено
+
+- Улучшена валидация параметров и подстановка значений по умолчанию в командах `twc firewall`.
+- Команда `twc firewall rule remove` теперь может принимать список UUID правил через пробел.
+- В команде `twc firewall show` аргумент `all` стал необязательным.
+- Зависимость `typer` заменена на `typer-slim`.
+
+## Исправлено
+
+- Исправлено определение ендпоинта объектного хранилища при вызове команды `twc storage genconfig`.
+
+# Версия 2.5.0 (2024.07.24)
+
+## Добавлено
+
+- Добавлена поддержка зон доступности. Добавлен параметр конифгурации `availability_zone` (`TWC_AVAILABILITY_ZONE`).
+- Добавлены новые опции для команды `twc server create`: `--availability-zone`, `--user-data`, `--public-ip`, `--no-public-ip`, `--private-ip`.
+- Добавлена новая команда `twc ip` вместо устаревшей `twc server ip`. Поскольку IP-адреса сейчас являются отдельными ресурсами, управление ими вынесено из `twc server`.
+
+## Изменено
+
+- Минимальная поддерживаемая версия интерпретатора Python повышена до 3.8.
+- Обновлены версии зависимостей.
+- Обновлены команды и методы API-клиента для работы VPC.
+- Удалён параметр `log_response` принимаемый как значение переменной окружения `TWC_LOG`, теперь тело ответа API логируется всегда.
+- Команда `twc server ip` объявлена устаревшей (deprecated) и будет уделена в следующем мажорном релизе. Вместо неё используйте команду `twc ip`.
+- Другие мелкие обновления CLI без нарушения обратной совместимости.
+
+## Исправлено
+
+- Исправлен метод удаления кластеров Kubernetes во встроенном API-клиенте.
+- Исправлена ошибка разбора JSON при получении объекта сервера без IP.
+
+# Версия 2.4.1 (2023.08.30)
+
+## Исправлено
+
+- Исправлена ошибка парсинга доменного имени в команде `twc domain record add`.
+
 # Версия 2.4.0 (2023.08.21)
 
 ## Добавлено

twc/__main__.py

@@ -20,6 +20,7 @@ from .commands import (
     domain,
     vpc,
     firewall,
+    floating_ip,
 )
 from .commands.common import version_callback, version_option, verbose_option
 
@@ -44,6 +45,7 @@ cli.add_typer(
 cli.add_typer(domain, name="domain", aliases=["domains", "d"])
 cli.add_typer(vpc, name="vpc", aliases=["vpcs", "network", "networks"])
 cli.add_typer(firewall, name="firewall", aliases=["fw"])
+cli.add_typer(floating_ip, name="ip", aliases=["ips"])
 
 
 @cli.command("version")

twc/__version__.py

@@ -12,5 +12,5 @@
 import sys
 
 
-__version__ = "2.4.1"
+__version__ = "2.6.0"
 __pyversion__ = sys.version.replace("\n", "")

twc/api/base.py

@@ -29,7 +29,6 @@ class TimewebCloudBase:
         user_agent: Optional[str] = USER_AGENT,
         timeout: Optional[int] = TIMEOUT,
         hide_token: Optional[bool] = True,
-        log_response_body: Optional[bool] = False,
         request_decorator: Optional[Callable] = None,
     ):
         self.api_token = api_token
@@ -44,7 +43,6 @@ class TimewebCloudBase:
         self.headers["Authorization"] = f"Bearer {self.api_token}"
         self.log = logging.getLogger("api_client")
         self.hide_token = hide_token
-        self.log_response_body = log_response_body
 
         if headers:
             self.headers.update(headers)
@@ -66,10 +64,10 @@ class TimewebCloudBase:
 
     def _log_request(self, response: requests.Response) -> None:
         """Log HTTP requests."""
-        if self.log_response_body:
-            res_body = response.text or "<NO_BODY>"
-        else:
-            res_body = "<NOT_LOGGED>"
+        res_body = response.text or "<NO_BODY>"
+        req_body = response.request.body or "<NO_BODY>"
+        if isinstance(req_body, (bytes, bytearray)):
+            req_body = req_body.decode()
 
         self.log.debug(
             textwrap.dedent(
@@ -89,7 +87,7 @@ class TimewebCloudBase:
                 req_headers=self._format_headers(
                     self._secure_log(response.request.headers)
                 ),
-                req_body=response.request.body or "<NO_BODY>",
+                req_body=req_body,
                 res=response,
                 res_headers=self._format_headers(response.headers),
                 res_body=res_body,
@@ -136,7 +134,6 @@ class TimewebCloudBase:
             response.raise_for_status()
             self._log_request(response)
         except requests.HTTPError as e:
-            self.log_response_body = True  # Always log response body on errors
             self._log_request(response)
 
             # API issue: Bad response: 401 Unauthorized response haven't body

twc/api/client.py

@@ -18,6 +18,7 @@ from .types import (
     BackupInterval,
     IPVersion,
     ServiceRegion,
+    ServiceAvailabilityZone,
     ResourceType,
     DBMS,
     MySQLAuthPlugin,
@@ -25,6 +26,7 @@ from .types import (
     LoadBalancerAlgo,
     FirewallProto,
     FirewallDirection,
+    FirewallPolicy,
 )
 
 
@@ -70,9 +72,10 @@ class TimewebCloud(TimewebCloudBase):
         avatar_id: Optional[str] = None,
         software_id: Optional[int] = None,
         ssh_keys_ids: Optional[List[int]] = None,
-        is_local_network: Optional[bool] = None,
+        is_local_network: Optional[bool] = None,  # deprecated
         is_ddos_guard: bool = False,
         network: Optional[dict] = None,
+        availability_zone: Optional[ServiceAvailabilityZone] = None,
     ):
         """Create new Cloud Server. Note:
 
@@ -105,6 +108,11 @@ class TimewebCloud(TimewebCloudBase):
             **({"preset_id": preset_id} if preset_id else {}),
             **({"os_id": os_id} if os_id else {}),
             **({"image_id": image_id} if image_id else {}),
+            **(
+                {"availability_zone": str(availability_zone)}
+                if availability_zone
+                else {}
+            ),
         }
 
         return self._request("POST", f"{self.api_url}/servers", json=payload)
@@ -697,7 +705,7 @@ class TimewebCloud(TimewebCloudBase):
         )
 
     # -----------------------------------------------------------------------
-    # Databases
+    # Managed databases
 
     def get_databases(self, limit: int = 100, offset: int = 0):
         """Get databases list."""
@@ -1343,7 +1351,7 @@ class TimewebCloud(TimewebCloudBase):
     def delete_k8s_node(self, cluster_id: int, node_id: int):
         """Delete node from cluster."""
         return self._request(
-            "GET",
+            "DELETE",
             f"{self.api_url}/k8s/clusters/{cluster_id}/nodes/{node_id}",
         )
 
@@ -1483,6 +1491,7 @@ class TimewebCloud(TimewebCloudBase):
         name: str,
         subnet: IPv4Network,
         location: ServiceRegion,
+        availability_zone: Optional[ServiceAvailabilityZone] = None,
         description: Optional[str] = None,
     ):
         """Create new virtual private network."""
@@ -1490,6 +1499,11 @@ class TimewebCloud(TimewebCloudBase):
             "name": name,
             "subnet_v4": subnet,
             "location": location,
+            **(
+                {"availability_zone": str(availability_zone)}
+                if availability_zone
+                else {}
+            ),
             **({"description": description} if description else {}),
         }
         return self._request("POST", f"{self.api_url_v2}/vpcs", json=payload)
@@ -1536,14 +1550,20 @@ class TimewebCloud(TimewebCloudBase):
         )
 
     def create_firewall_group(
-        self, name: str, description: Optional[str] = None
+        self,
+        name: str,
+        description: Optional[str] = None,
+        policy: Optional[FirewallPolicy] = FirewallPolicy.DROP,
     ):
         payload = {
             "name": name,
             **({"description": description} if description else {}),
         }
         return self._request(
-            "POST", f"{self.api_url}/firewall/groups", json=payload
+            "POST",
+            f"{self.api_url}/firewall/groups",
+            json=payload,
+            params={"policy": policy},
         )
 
     def get_firewall_group(self, group_id: UUID):
@@ -1623,16 +1643,16 @@ class TimewebCloud(TimewebCloudBase):
         self,
         group_id: UUID,
         direction: FirewallDirection,
-        proto: FirewallProto,
+        protocol: FirewallProto,
         cidr: Union[IPv4Network, IPv6Network],
         port: Optional[str] = None,
         description: Optional[str] = None,
     ):
         payload = {
             **({"description": description} if description else {}),
-            **({} if proto == FirewallProto.ICMP.value else {"port": port}),
+            **({} if protocol == FirewallProto.ICMP.value else {"port": port}),
             "direction": direction,
-            "protocol": proto,
+            "protocol": protocol,
             "cidr": cidr,
         }
         return self._request(
@@ -1657,16 +1677,16 @@ class TimewebCloud(TimewebCloudBase):
         group_id: UUID,
         rule_id: UUID,
         direction: FirewallDirection,
-        proto: FirewallProto,
+        protocol: FirewallProto,
         cidr: Union[IPv4Network, IPv6Network],
         port: Optional[str] = None,
         description: Optional[str] = None,
     ):
         payload = {
             **({"description": description} if description else {}),
-            **({} if proto == FirewallProto.ICMP.value else {"port": port}),
+            **({} if protocol == FirewallProto.ICMP.value else {"port": port}),
             "direction": direction,
-            "protocol": proto,
+            "protocol": protocol,
             "cidr": cidr,
         }
         return self._request(
@@ -1690,3 +1710,67 @@ class TimewebCloud(TimewebCloudBase):
             f"{self.api_url}/firewall/service/{resource_type}/{resource_id}",
             params=params,
         )
+
+    # -----------------------------------------------------------------------
+    # Floating IPs
+
+    def get_floating_ips(self):
+        return self._request("GET", f"{self.api_url_v1}/floating-ips")
+
+    def get_floating_ip(self, floating_ip_id: str):
+        return self._request(
+            "GET", f"{self.api_url_v1}/floating-ips/{floating_ip_id}"
+        )
+
+    def create_floating_ip(
+        self,
+        availability_zone: ServiceAvailabilityZone,
+        ddos_protection: bool = False,
+    ):
+        payload = {
+            "is_ddos_guard": ddos_protection,
+            "availability_zone": str(availability_zone),
+        }
+        return self._request(
+            "POST", f"{self.api_url_v1}/floating-ips", json=payload
+        )
+
+    def update_floating_ip(
+        self,
+        floating_ip_id: str,
+        comment: Optional[str] = None,
+        ptr: Optional[str] = None,
+    ):
+        payload = {}
+        if comment:
+            payload["comment"] = comment
+        if ptr:
+            payload["ptr"] = ptr
+        return self._request(
+            "PATCH",
+            f"{self.api_url_v1}/floating-ips/{floating_ip_id}",
+            json=payload,
+        )
+
+    def delete_floating_ip(self, floating_ip_id: str):
+        return self._request(
+            "DELETE", f"{self.api_url_v1}/floating-ips/{floating_ip_id}"
+        )
+
+    def attach_floating_ip(
+        self,
+        floating_ip_id: str,
+        resource_type: ResourceType,
+        resource_id: str,
+    ):
+        payload = {"resource_type": resource_type, "resource_id": resource_id}
+        return self._request(
+            "POST",
+            f"{self.api_url_v1}/floating-ips/{floating_ip_id}/bind",
+            json=payload,
+        )
+
+    def detach_floating_ip(self, floating_ip_id: str):
+        return self._request(
+            "POST", f"{self.api_url_v1}/floating-ips/{floating_ip_id}/unbind"
+        )

twc/api/types.py

@@ -1,6 +1,6 @@
 """Custom data types for Timeweb Cloud API entities."""
 
-from typing import NamedTuple
+from typing import TypedDict, List, Optional
 from enum import Enum
 
 
@@ -9,10 +9,59 @@ class ServiceRegion(str, Enum):
 
     RU_1 = "ru-1"
     RU_2 = "ru-2"
-    PL_1 = "pl-1"
+    RU_3 = "ru-3"
     KZ_1 = "kz-1"
+    PL_1 = "pl-1"
     NL_1 = "nl-1"
 
+    @classmethod
+    def get_zones(cls, region: str) -> List[str]:
+        # pylint: disable=too-many-return-statements
+        if region == cls.RU_1:
+            return ["spb-1", "spb-2", "spb-3", "spb-4"]
+        if region == cls.RU_2:
+            return ["nsk-1"]
+        if region == cls.RU_3:
+            return ["msk-1"]
+        if region == cls.KZ_1:
+            return ["ala-1"]
+        if region == cls.PL_1:
+            return ["gdn-1"]
+        if region == cls.NL_1:
+            return ["ams-1"]
+        return []
+
+
+class ServiceAvailabilityZone(str, Enum):
+    """Availability zones."""
+
+    SPB_1 = "spb-1"
+    SPB_2 = "spb-2"
+    SPB_3 = "spb-3"
+    SPB_4 = "spb-4"
+    MSK_1 = "msk-1"
+    NSK_1 = "nsk-1"
+    ALA_1 = "ala-1"
+    GDN_1 = "gdn-1"
+    AMS_1 = "ams-1"
+
+    @classmethod
+    def get_region(cls, zone: str) -> Optional[str]:
+        # pylint: disable=too-many-return-statements
+        if zone in [cls.SPB_1, cls.SPB_2, cls.SPB_3, cls.SPB_4]:
+            return ServiceRegion.RU_1
+        if zone == cls.NSK_1:
+            return ServiceRegion.RU_2
+        if zone == cls.MSK_1:
+            return ServiceRegion.RU_3
+        if zone == cls.ALA_1:
+            return ServiceRegion.KZ_1
+        if zone == cls.GDN_1:
+            return ServiceRegion.PL_1
+        if zone == cls.AMS_1:
+            return ServiceRegion.NL_1
+        return None
+
 
 class ServerAction(str, Enum):
     """Available actions on Cloud Server."""
@@ -64,13 +113,11 @@ class IPVersion(str, Enum):
     IPV6 = "ipv6"
 
 
-class ServerConfiguration(NamedTuple):
+class ServerConfiguration(TypedDict):
     """
     For `confugurator_id` see `get_server_configurators()`. `disk` and
-    `ram` must be in megabytes. Values must values must comply with the
-    configurator constraints.
-
-    TODO: Replace NamedTuple with TypedDict when drop Python 3.7
+    `ram` must be in megabytes. Values must comply with the configurator
+    constraints.
     """
 
     configurator_id: int
@@ -181,6 +228,9 @@ class FirewallProto(str, Enum):
     TCP = "tcp"
     UDP = "udp"
     ICMP = "icmp"
+    TCP6 = "tcp6"
+    UDP6 = "udp6"
+    ICMP6 = "icmp6"
 
 
 class FirewallDirection(str, Enum):
@@ -188,3 +238,10 @@ class FirewallDirection(str, Enum):
 
     INGRESS = "ingress"
     EGRESS = "egress"
+
+
+class FirewallPolicy(str, Enum):
+    """Firewall default policy."""
+
+    DROP = "DROP"
+    ACCEPT = "ACCEPT"

twc/apiwrap.py

@@ -73,8 +73,8 @@ def create_client(config: Path, profile: str, **kwargs) -> TimewebCloud:
 
     if log_settings:
         for param in log_settings.split(","):
-            if param == "log_response":
-                kwargs["log_response_body"] = True
+            if param.lower() == "debug":
+                pass  # FUTURE: set logging.DEBUG
 
     if token:
         debug("Config: use API token from environment")

twc/commands/__init__.py

@@ -13,3 +13,4 @@ from .kubernetes import cluster
 from .domain import domain
 from .vpc import vpc
 from .firewall import firewall
+from .floating_ip import floating_ip

twc/commands/common.py

@@ -13,7 +13,7 @@ from typer.core import TyperOption
 from click import UsageError
 
 from twc.__version__ import __version__
-from twc.api.types import ServiceRegion
+from twc.api.types import ServiceRegion, ServiceAvailabilityZone
 
 
 class OutputFormat(str, Enum):
@@ -109,6 +109,11 @@ def load_from_config_callback(
         regions = [v.value for v in ServiceRegion]
         if value not in regions:
             sys.exit(f"Error: Location not in {regions}")
+    if param.name == "zone":
+        value = value.lower()
+        zones = [z.value for z in ServiceAvailabilityZone]
+        if value not in zones:
+            sys.exit(f"Error: Availability zone not in {zones}")
     return value
 
 
@@ -275,5 +280,16 @@ region_option = typer.Option(
     envvar="TWC_REGION",
     show_envvar=False,
     callback=load_from_config_callback,
-    help="Use region (location).",
+    help="Region (location).",
+)
+
+# availability_zone: Optional[str] = zone_option,
+
+zone_option = typer.Option(
+    None,
+    metavar="ZONE",
+    envvar="TWC_AVAILABILITY_ZONE",
+    show_envvar=False,
+    callback=load_from_config_callback,
+    help="Availability zone.",
 )