mtn-cloud 0.2.16__tar.gz → 0.2.19__tar.gz

{mtn_cloud-0.2.16 → mtn_cloud-0.2.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtn-cloud
-Version: 0.2.16
+Version: 0.2.19
 Summary: Community Python SDK for MTN Cloud - Deploy and manage cloud resources with ease
 Project-URL: Homepage, https://github.com/mahveotm/mtn-cloud-python
 Project-URL: Documentation, https://github.com/mahveotm/mtn-cloud-python#readme
@@ -50,7 +50,7 @@ Description-Content-Type: text/markdown
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Modern Python SDK for [MTN Cloud](https://console.cloud.mtn.ng) with typed models, clear resource managers, and practical workflows for compute, networking, storage, and archives.
+A Modern Python SDK for [MTN Cloud](https://console.cloud.mtn.ng) with typed models, clear resource managers, and practical workflows for compute, networking, storage, archives, security groups, backups, and more.
 
 Docs: [mtn-cloud-python](https://mahveotm.github.io/mtn-cloud-python/)
 
@@ -78,6 +78,9 @@ pip install mtn-cloud
 - [Instances](https://mahveotm.github.io/mtn-cloud-python/instances/)
 - [Networking](https://mahveotm.github.io/mtn-cloud-python/networking/)
 - [Storage](https://mahveotm.github.io/mtn-cloud-python/storage/)
+- [Security Groups](https://mahveotm.github.io/mtn-cloud-python/security-groups/)
+- [Backups](https://mahveotm.github.io/mtn-cloud-python/backups/)
+- [Virtual Images](https://mahveotm.github.io/mtn-cloud-python/virtual-images/)
 - [Advanced Cookbook](https://mahveotm.github.io/mtn-cloud-python/advanced-cookbook/)
 - [API Overview](https://mahveotm.github.io/mtn-cloud-python/api-overview/)
 - [API Reference](https://mahveotm.github.io/mtn-cloud-python/api-reference/)
@@ -124,23 +127,45 @@ User Icon (top-right) -> User Settings -> API Access.
 
 ### 1. Discover Reference Data
 
-Use these lookups before provisioning so your scripts stay deterministic.
+Use these lookups before provisioning so your scripts stay deterministic. They all use permission-safe endpoints (the admin-level `clouds`/`plans` endpoints are restricted on most tenant accounts — you don't need them).
 
 ```python
-# Groups (sites)
-groups = cloud.groups.list()
-for group in groups[:5]:
-    print(group.id, group.name)
-
-# Instance types
-types = cloud.instance_types.list_os()
-for t in types[:5]:
-    print(t.code, t.name, t.default_layout_id)
+# Groups (sites) — also carry the cloud/zone IDs you need
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+print(group.id, group.name, group.cloud_ids)
+
+# Instance types — each carries its own default_layout_id
+itype = cloud.instance_types.get_by_code("MTN-CS10")
+print(itype.code, itype.default_layout_id)
+
+# Resource pools — where the instance is hosted (the resource_pool_id)
+for pool in cloud.instances.list_resource_pools(group="MTNNG_CLOUD_AZ_1"):
+    print(pool.code, pool.name)
+
+# Service plans — CPU/memory/storage tiers for this zone + layout
+for plan in cloud.instances.list_service_plans(
+    zone_id=group.cloud_ids[0],
+    layout_id=itype.default_layout_id,
+    group_id=group.id,
+):
+    print(plan["id"], plan["name"])
+```
+
+A **resource pool is required** to create an instance — it's where the VM is hosted. Discover it by group name (the cloud/zone is resolved for you), or fetch one directly by name:
+
+```python
+pool = cloud.instances.get_resource_pool(
+    "my-project-name",
+    group="MTNNG_CLOUD_AZ_1",
+)
+print(pool.code)   # e.g. "pool-214" — pass this as resource_pool_id
 ```
 
 ### 2. Create an Instance
 
 ```python
+pool = cloud.instances.get_resource_pool("my-project-name", group="MTNNG_CLOUD_AZ_1")
+
 instance = cloud.instances.create(
     name="my-server",
     cloud="MTNNG_CLOUD_AZ_1",
@@ -148,7 +173,7 @@ instance = cloud.instances.create(
     group="MTNNG_CLOUD_AZ_1",
     layout=327,
     plan=6776,
-    resource_pool_id="pool-214",
+    resource_pool_id=pool.code,   # "pool-214" — or pass the numeric ID 214
     labels=["production", "web"],
 )
 
@@ -200,7 +225,79 @@ subnets = cloud.networks.list_subnets(new_network.id)
 print(f"Subnets: {len(subnets)}")
 ```
 
-### 5. Work with Storage and Archives
+### 5. Manage Security Groups
+
+```python
+# Create a security group and add rules
+sg = cloud.security_groups.create(
+    name="web-servers",
+    description="HTTP, HTTPS, and SSH access",
+)
+
+cloud.security_groups.create_rule(
+    sg.id,
+    name="allow-ssh",
+    direction="ingress",
+    protocol="tcp",
+    port_range="22",
+)
+
+cloud.security_groups.create_rule(
+    sg.id,
+    name="allow-https",
+    direction="ingress",
+    protocol="tcp",
+    port_range="443",
+)
+
+# Use the security group when provisioning
+instance = cloud.instances.create(
+    name="app-server-01",
+    cloud="MTNNG_CLOUD_AZ_1",
+    type="MTN-CS10",
+    group="MTNNG_CLOUD_AZ_1",
+    layout=327,
+    plan=6776,
+    resource_pool_id="pool-214",
+    security_group="web-servers",
+)
+```
+
+### 6. Snapshot Instances
+
+```python
+# Create a snapshot before a risky operation
+snap = cloud.instances.create_snapshot(
+    instance_id=instance.id,
+    name="pre-upgrade",
+)
+
+# Revert if something goes wrong (stop the instance first)
+cloud.instances.stop(instance.id)
+cloud.instances.wait_until_stopped(instance.id)
+cloud.instances.revert_snapshot(instance.id, snapshot_id=snap.id)
+```
+
+### 7. Work with Backups
+
+```python
+# List configured backups and their status
+for backup in cloud.backups.list():
+    print(f"{backup.name}: last_run={backup.last_run} status={backup.last_status}")
+
+# Trigger an immediate backup run
+cloud.backups.execute(backup_id=42)
+
+# Check execution history
+for result in cloud.backups.list_results(backup_id=42):
+    print(f"{result.start_date}: {result.status} ({result.size_in_mb} MB)")
+
+# List and execute backup jobs (schedules)
+for job in cloud.backups.list_jobs():
+    print(f"{job.name}: cron={job.cron_expression}")
+```
+
+### 8. Work with Storage and Archives
 
 ```python
 # Create S3-compatible storage provider

{mtn_cloud-0.2.16 → mtn_cloud-0.2.19}/README.md

@@ -6,7 +6,7 @@
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Modern Python SDK for [MTN Cloud](https://console.cloud.mtn.ng) with typed models, clear resource managers, and practical workflows for compute, networking, storage, and archives.
+A Modern Python SDK for [MTN Cloud](https://console.cloud.mtn.ng) with typed models, clear resource managers, and practical workflows for compute, networking, storage, archives, security groups, backups, and more.
 
 Docs: [mtn-cloud-python](https://mahveotm.github.io/mtn-cloud-python/)
 
@@ -34,6 +34,9 @@ pip install mtn-cloud
 - [Instances](https://mahveotm.github.io/mtn-cloud-python/instances/)
 - [Networking](https://mahveotm.github.io/mtn-cloud-python/networking/)
 - [Storage](https://mahveotm.github.io/mtn-cloud-python/storage/)
+- [Security Groups](https://mahveotm.github.io/mtn-cloud-python/security-groups/)
+- [Backups](https://mahveotm.github.io/mtn-cloud-python/backups/)
+- [Virtual Images](https://mahveotm.github.io/mtn-cloud-python/virtual-images/)
 - [Advanced Cookbook](https://mahveotm.github.io/mtn-cloud-python/advanced-cookbook/)
 - [API Overview](https://mahveotm.github.io/mtn-cloud-python/api-overview/)
 - [API Reference](https://mahveotm.github.io/mtn-cloud-python/api-reference/)
@@ -80,23 +83,45 @@ User Icon (top-right) -> User Settings -> API Access.
 
 ### 1. Discover Reference Data
 
-Use these lookups before provisioning so your scripts stay deterministic.
+Use these lookups before provisioning so your scripts stay deterministic. They all use permission-safe endpoints (the admin-level `clouds`/`plans` endpoints are restricted on most tenant accounts — you don't need them).
 
 ```python
-# Groups (sites)
-groups = cloud.groups.list()
-for group in groups[:5]:
-    print(group.id, group.name)
-
-# Instance types
-types = cloud.instance_types.list_os()
-for t in types[:5]:
-    print(t.code, t.name, t.default_layout_id)
+# Groups (sites) — also carry the cloud/zone IDs you need
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+print(group.id, group.name, group.cloud_ids)
+
+# Instance types — each carries its own default_layout_id
+itype = cloud.instance_types.get_by_code("MTN-CS10")
+print(itype.code, itype.default_layout_id)
+
+# Resource pools — where the instance is hosted (the resource_pool_id)
+for pool in cloud.instances.list_resource_pools(group="MTNNG_CLOUD_AZ_1"):
+    print(pool.code, pool.name)
+
+# Service plans — CPU/memory/storage tiers for this zone + layout
+for plan in cloud.instances.list_service_plans(
+    zone_id=group.cloud_ids[0],
+    layout_id=itype.default_layout_id,
+    group_id=group.id,
+):
+    print(plan["id"], plan["name"])
+```
+
+A **resource pool is required** to create an instance — it's where the VM is hosted. Discover it by group name (the cloud/zone is resolved for you), or fetch one directly by name:
+
+```python
+pool = cloud.instances.get_resource_pool(
+    "my-project-name",
+    group="MTNNG_CLOUD_AZ_1",
+)
+print(pool.code)   # e.g. "pool-214" — pass this as resource_pool_id
 ```
 
 ### 2. Create an Instance
 
 ```python
+pool = cloud.instances.get_resource_pool("my-project-name", group="MTNNG_CLOUD_AZ_1")
+
 instance = cloud.instances.create(
     name="my-server",
     cloud="MTNNG_CLOUD_AZ_1",
@@ -104,7 +129,7 @@ instance = cloud.instances.create(
     group="MTNNG_CLOUD_AZ_1",
     layout=327,
     plan=6776,
-    resource_pool_id="pool-214",
+    resource_pool_id=pool.code,   # "pool-214" — or pass the numeric ID 214
     labels=["production", "web"],
 )
 
@@ -156,7 +181,79 @@ subnets = cloud.networks.list_subnets(new_network.id)
 print(f"Subnets: {len(subnets)}")
 ```
 
-### 5. Work with Storage and Archives
+### 5. Manage Security Groups
+
+```python
+# Create a security group and add rules
+sg = cloud.security_groups.create(
+    name="web-servers",
+    description="HTTP, HTTPS, and SSH access",
+)
+
+cloud.security_groups.create_rule(
+    sg.id,
+    name="allow-ssh",
+    direction="ingress",
+    protocol="tcp",
+    port_range="22",
+)
+
+cloud.security_groups.create_rule(
+    sg.id,
+    name="allow-https",
+    direction="ingress",
+    protocol="tcp",
+    port_range="443",
+)
+
+# Use the security group when provisioning
+instance = cloud.instances.create(
+    name="app-server-01",
+    cloud="MTNNG_CLOUD_AZ_1",
+    type="MTN-CS10",
+    group="MTNNG_CLOUD_AZ_1",
+    layout=327,
+    plan=6776,
+    resource_pool_id="pool-214",
+    security_group="web-servers",
+)
+```
+
+### 6. Snapshot Instances
+
+```python
+# Create a snapshot before a risky operation
+snap = cloud.instances.create_snapshot(
+    instance_id=instance.id,
+    name="pre-upgrade",
+)
+
+# Revert if something goes wrong (stop the instance first)
+cloud.instances.stop(instance.id)
+cloud.instances.wait_until_stopped(instance.id)
+cloud.instances.revert_snapshot(instance.id, snapshot_id=snap.id)
+```
+
+### 7. Work with Backups
+
+```python
+# List configured backups and their status
+for backup in cloud.backups.list():
+    print(f"{backup.name}: last_run={backup.last_run} status={backup.last_status}")
+
+# Trigger an immediate backup run
+cloud.backups.execute(backup_id=42)
+
+# Check execution history
+for result in cloud.backups.list_results(backup_id=42):
+    print(f"{result.start_date}: {result.status} ({result.size_in_mb} MB)")
+
+# List and execute backup jobs (schedules)
+for job in cloud.backups.list_jobs():
+    print(f"{job.name}: cron={job.cron_expression}")
+```
+
+### 8. Work with Storage and Archives
 
 ```python
 # Create S3-compatible storage provider

{mtn_cloud-0.2.16 → mtn_cloud-0.2.19}/docs/api-overview.md

@@ -19,6 +19,9 @@ from mtn_cloud import MTNCloud
 - `plans`
 - `storage_buckets`
 - `archive_buckets`
+- `security_groups`
+- `backups`
+- `virtual_images`
 
 ## Authentication Options
 
@@ -39,10 +42,16 @@ cloud.instance_types.get_by_code("MTN-CS10")
 ## Common Write Operations
 
 ```python
-cloud.instances.create(...)
+# Discover the resource pool an instance will be hosted in
+pool = cloud.instances.get_resource_pool("my-project", group="MTNNG_CLOUD_AZ_1")
+
+cloud.instances.create(..., resource_pool_id=pool.code)
 cloud.instances.update(instance_id=123, name="new-name")
 cloud.instances.delete(123)
 
+cloud.instances.create_snapshot(123, "pre-upgrade")
+cloud.instances.revert_snapshot(123, snapshot_id=456)
+
 cloud.networks.create(...)
 cloud.networks.update(298, description="updated")
 cloud.networks.delete(298)
@@ -50,6 +59,11 @@ cloud.networks.delete(298)
 cloud.storage_buckets.create_s3(...)
 cloud.archive_buckets.create(...)
 cloud.archive_buckets.upload_file(...)
+
+cloud.security_groups.create(name="web-servers")
+cloud.security_groups.create_rule(sg_id, direction="ingress", protocol="tcp", port_range="22")
+
+cloud.backups.execute(backup_id=42)
 ```
 
 ## Exception Hierarchy
@@ -80,6 +94,11 @@ Resource methods return typed Pydantic models, for example:
 - `StorageBucket`
 - `ArchiveBucket`
 - `ArchiveFile`
+- `SecurityGroup`, `SecurityGroupRule`
+- `Snapshot`
+- `ResourcePool`
+- `Backup`, `BackupJob`, `BackupResult`
+- `VirtualImage`
 
 ## Naming Conventions
 

mtn_cloud-0.2.19/docs/api-reference/backups.md

@@ -0,0 +1,59 @@
+# Resource: `cloud.backups` (`BackupsResource`)
+
+### `list(max_results=None, offset=0, phrase=None, **filters) -> list[Backup]`
+
+- Endpoint: `GET /api/backups`
+- Parameters:
+    - Shared list args (see [API Reference](./index.md#shared-list-query-arguments))
+- Returns: `list[Backup]`
+- Raises: common API exceptions
+
+### `get(backup_id: int) -> Backup`
+
+- Endpoint: `GET /api/backups/{backup_id}`
+- Returns: `Backup`
+- Raises: common API exceptions
+
+### `execute(backup_id: int) -> dict[str, Any]`
+
+- Endpoint: `POST /api/backups/{backup_id}/execute`
+- Triggers an immediate out-of-schedule backup run
+- Returns: raw execution status response
+- Raises: common API exceptions
+
+### `list_results(backup_id: int, max_results=None) -> list[BackupResult]`
+
+- Endpoint: `GET /api/backups/{backup_id}/results`
+- Parameters:
+    - `max_results`: maps to query `max`
+- Returns: `list[BackupResult]` — each result carries `status`, `size_in_mb`, `duration_millis`, `start_date`, `end_date`
+- Raises: common API exceptions
+
+### `delete(backup_id: int) -> bool`
+
+- Endpoint: `DELETE /api/backups/{backup_id}`
+- Returns: `True` on success
+- Raises: common API exceptions
+
+---
+
+## Job management
+
+### `list_jobs(max_results=None, offset=0) -> list[BackupJob]`
+
+- Endpoint: `GET /api/backups/jobs`
+- Returns: `list[BackupJob]`
+- Raises: common API exceptions
+
+### `get_job(job_id: int) -> BackupJob`
+
+- Endpoint: `GET /api/backups/jobs/{job_id}`
+- Returns: `BackupJob`
+- Raises: common API exceptions
+
+### `execute_job(job_id: int) -> dict[str, Any]`
+
+- Endpoint: `POST /api/backups/jobs/{job_id}/execute`
+- Triggers an immediate run of all backups under the job
+- Returns: raw execution status response
+- Raises: common API exceptions

{mtn_cloud-0.2.16 → mtn_cloud-0.2.19}/docs/api-reference/index.md

@@ -13,6 +13,9 @@ This section documents the public SDK surface in endpoint-first format.
 - [Plans (`cloud.plans`)](./plans.md)
 - [Storage Buckets (`cloud.storage_buckets`)](./storage-buckets.md)
 - [Archive Buckets (`cloud.archive_buckets`)](./archive-buckets.md)
+- [Security Groups (`cloud.security_groups`)](./security-groups.md)
+- [Backups (`cloud.backups`)](./backups.md)
+- [Virtual Images (`cloud.virtual_images`)](./virtual-images.md)
 
 ## Conventions
 

{mtn_cloud-0.2.16 → mtn_cloud-0.2.19}/docs/api-reference/instances.md

@@ -32,7 +32,7 @@
     - common API exceptions
     - `NotFoundError` when no instance matches
 
-### `create(name: str, *, cloud: str, type: str, group: str, layout: int, plan: int, resource_pool_id: str, description=None, environment=None, labels=None, tags=None, copies=1, layout_size=1, availability_zone=None, security_group="default", os_external_network_id=None, create_user=True, workflow_id=None, shutdown_days=None, expire_days=None, create_backup=None, security_groups=None, ports=None, volumes=None, network_interfaces=None, options=None) -> Instance`
+### `create(name: str, *, cloud: str, type: str, group: str, layout: int, plan: int, resource_pool_id: str | int, description=None, environment=None, labels=None, tags=None, copies=1, layout_size=1, availability_zone=None, security_group="default", os_external_network_id=None, create_user=True, workflow_id=None, shutdown_days=None, expire_days=None, create_backup=None, security_groups=None, ports=None, volumes=None, network_interfaces=None, options=None) -> Instance`
 
 - Endpoint sequence:
     - `GET /api/groups?name=<group>&max=1` (resolve group name to `group_id`)
@@ -45,7 +45,7 @@
         - `group`: group/site name (resolved to ID)
         - `layout`: layout ID
         - `plan`: service plan ID
-        - `resource_pool_id`: project resource pool ID
+        - `resource_pool_id`: resource pool code (`"pool-214"`) or numeric ID (`214`); both normalize to the code. Discover with `list_resource_pools()` / `get_resource_pool()`
     - Optional metadata:
         - `description`, `environment`, `labels`, `tags`
     - Optional sizing/provisioning:
@@ -165,3 +165,68 @@ Client-side polling helper.
     - `max_results`: maps to query `max`
 - Returns: list from response key `processes`
 - Raises: common API exceptions
+
+---
+
+## Snapshot management
+
+### `list_snapshots(instance_id: int) -> list[Snapshot]`
+
+- Endpoint: `GET /api/instances/{instance_id}/snapshots`
+- Returns: `list[Snapshot]`
+- Raises: common API exceptions
+
+### `create_snapshot(instance_id: int, name: str, *, description=None) -> Snapshot`
+
+- Endpoint: `POST /api/instances/{instance_id}/snapshots`
+- Parameters:
+    - `name`: snapshot name
+    - `description`: optional description
+- Returns: `Snapshot`
+- Raises: common API exceptions
+
+### `revert_snapshot(instance_id: int, snapshot_id: int) -> bool`
+
+- Endpoint: `PUT /api/instances/{instance_id}/revert-snapshot/{snapshot_id}`
+- The instance should be stopped before reverting
+- Returns: `True` when revert is initiated
+- Raises: common API exceptions
+
+### `delete_snapshot(instance_id: int, snapshot_id: int) -> bool`
+
+- Endpoint: `DELETE /api/instances/{instance_id}/snapshots/{snapshot_id}`
+- Returns: `True` on success
+- Raises: common API exceptions
+
+---
+
+## Provisioning discovery
+
+These helpers resolve the IDs and codes required by `create()` using permission-safe endpoints (the admin-level `clouds`/`plans` endpoints are restricted on most accounts).
+
+### `list_resource_pools(group=None, *, cloud_id=None, group_id=None, provision_type_code="openstack") -> list[ResourcePool]`
+
+- Endpoint: `GET /api/options/zonePools?cloudId={cloud_id}&groupId={group_id}`
+- A resource pool is where an instance is hosted; its `code` is the `resource_pool_id` for `create()`
+- Parameters:
+    - `group`: group name or ID — when given, `cloud_id` and `group_id` are resolved from it automatically (the group embeds its cloud/zone IDs)
+    - `cloud_id` / `group_id`: explicit IDs, required if `group` is not given
+    - `provision_type_code`: provisioning type, defaults to `"openstack"`
+- Returns: `list[ResourcePool]` (group-header rows are filtered out)
+- Raises: `ValueError` if neither `group` nor both `cloud_id`/`group_id` are provided, or the group has no associated cloud
+
+### `get_resource_pool(name: str, *, group=None, cloud_id=None, group_id=None, provision_type_code="openstack") -> ResourcePool`
+
+- Fetches a single pool by display name **or** code (e.g. `"pool-214"`)
+- Same resolution rules as `list_resource_pools`
+- Returns: `ResourcePool`
+- Raises: `NotFoundError` if no pool matches `name`
+
+### `list_service_plans(zone_id=None, layout_id=None, group_id=None) -> list[dict[str, Any]]`
+
+- Endpoint: `GET /api/instances/service-plans?zoneId={zone_id}&layoutId={layout_id}&siteId={group_id}`
+- Returns available service plans (CPU/memory/storage tiers) scoped to the provisioning context
+- `layout_id` is required by the API; use `instance_type.default_layout_id`
+- Returns: list of plan dicts from response key `plans`
+
+**`ResourcePool` model fields:** `id` (numeric), `code` (alias of API `value`, e.g. `"pool-214"`), `name`, `external_id` (OpenStack pool ID), `is_default`.

{mtn_cloud-0.2.16 → mtn_cloud-0.2.19}/docs/api-reference/networks.md

@@ -88,36 +88,32 @@
 - Returns: `NetworkTypeInfo`
 - Raises: common API exceptions
 
-### `list_floating_ips(*, phrase=None, ip_address=None, ip_status=None, cloud_id=None, server_id=None) -> list[NetworkFloatingIP]`
+### `list_pools(max_results=None, offset=0, phrase=None) -> list[NetworkPool]`
 
-- Endpoint: `GET /api/networks/floating-ips`
+- Endpoint: `GET /api/networks/pools`
 - Parameters:
+    - `max_results`: maps to query `max`
+    - `offset`: pagination offset
     - `phrase`: search phrase
-    - `ip_address`: exact IP match
-    - `ip_status`: provider status value
-    - `cloud_id`: mapped to `zoneId`
-    - `server_id`: mapped to `serverId`
-- Returns: `list[NetworkFloatingIP]`
+- Returns: `list[NetworkPool]` (each includes its `ip_ranges`, `ip_count`, `free_count`)
 - Raises: common API exceptions
 
-### `get_floating_ip(floating_ip_id: int) -> NetworkFloatingIP`
+### `get_pool(pool_id: int) -> NetworkPool`
 
-- Endpoint: `GET /api/networks/floating-ips/{floating_ip_id}`
-- Returns: `NetworkFloatingIP`
+- Endpoint: `GET /api/networks/pools/{pool_id}`
+- Returns: `NetworkPool`
 - Raises: common API exceptions
 
-### `allocate_floating_ip(*, network_server_id: int, floating_ip_pool_id: int) -> NetworkFloatingIP`
+### `list_pool_ips(pool_id: int, *, max_results=None, phrase=None, ip_address=None, hostname=None) -> list[NetworkPoolIp]`
 
-- Endpoint: `POST /api/networks/floating-ips`
+- Endpoint: `GET /api/networks/pools/{pool_id}/ips`
 - Parameters:
-    - `network_server_id`: backend network server ID
-    - `floating_ip_pool_id`: floating IP pool ID
-- Returns: `NetworkFloatingIP`
+    - `max_results`: maps to query `max`
+    - `phrase`: partial match on `ipAddress` or `hostname`
+    - `ip_address`: exact IP match
+    - `hostname`: exact hostname match
+- Returns: `list[NetworkPoolIp]`
 - Raises: common API exceptions
 
-### `release_floating_ip(floating_ip_id: int) -> bool`
-
-- Endpoint: `PUT /api/networks/floating-ips/{floating_ip_id}/release`
-- Returns: `True`
-- Raises: common API exceptions
+> **Note:** Standalone floating-IP endpoints (`/api/networks/floating-ips`) are restricted (HTTP 403) on MTN Cloud tenant accounts and are not exposed by the SDK. Assign external/public connectivity at provisioning time via the instance's `os_external_network_id` instead.