mtn-cloud 0.2.17__tar.gz → 0.3.1__tar.gz

{mtn_cloud-0.2.17 → mtn_cloud-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtn-cloud
-Version: 0.2.17
+Version: 0.3.1
 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
@@ -84,7 +84,6 @@ pip install mtn-cloud
 - [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/)
-- [Docstring Style Standard](https://mahveotm.github.io/mtn-cloud-python/docstring-style/)
 
 ## Quick Start
 
@@ -127,23 +126,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",
@@ -151,7 +172,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"],
 )
 
@@ -178,27 +199,32 @@ cloud.instances.delete(123, force=True, preserve_volumes=True)
 ### 4. Work with Networks
 
 ```python
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+
 # List networks
-networks = cloud.networks.list(cloud_id=1)
+networks = cloud.networks.list(cloud_id=group.cloud_ids[0])
 for n in networks[:5]:
     print(n.id, n.name, n.cidr)
 
-# Create an OpenStack-focused network
-network_types = cloud.networks.list_types(openstack_only=True)
+# Create an OpenStack network (needs an OpenStack type + a resource pool)
+net_type = next(
+    t for t in cloud.networks.list_types(openstack_only=True)
+    if t.code == "openstackPrivate"
+)
+pool = cloud.instances.get_resource_pool("my-project", group=group.name)
+
 new_network = cloud.networks.create(
     name="mtn-prod-net",
-    cloud_id=1,
-    group_id=621,
-    type_id=network_types[0].id,
+    cloud_id=group.cloud_ids[0],
+    group_id=group.id,
+    type_id=net_type.id,
+    resource_pool_id=pool.id,
     cidr="10.42.10.0/24",
     gateway="10.42.10.1",
     dns_primary="8.8.8.8",
-    visibility="private",
-    dhcp_server=True,
 )
 
-# Update and list subnets
-cloud.networks.update(new_network.id, description="Production network")
+# Inspect subnets
 subnets = cloud.networks.list_subnets(new_network.id)
 print(f"Subnets: {len(subnets)}")
 ```

{mtn_cloud-0.2.17 → mtn_cloud-0.3.1}/README.md

@@ -40,7 +40,6 @@ pip install mtn-cloud
 - [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/)
-- [Docstring Style Standard](https://mahveotm.github.io/mtn-cloud-python/docstring-style/)
 
 ## Quick Start
 
@@ -83,23 +82,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",
@@ -107,7 +128,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"],
 )
 
@@ -134,27 +155,32 @@ cloud.instances.delete(123, force=True, preserve_volumes=True)
 ### 4. Work with Networks
 
 ```python
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+
 # List networks
-networks = cloud.networks.list(cloud_id=1)
+networks = cloud.networks.list(cloud_id=group.cloud_ids[0])
 for n in networks[:5]:
     print(n.id, n.name, n.cidr)
 
-# Create an OpenStack-focused network
-network_types = cloud.networks.list_types(openstack_only=True)
+# Create an OpenStack network (needs an OpenStack type + a resource pool)
+net_type = next(
+    t for t in cloud.networks.list_types(openstack_only=True)
+    if t.code == "openstackPrivate"
+)
+pool = cloud.instances.get_resource_pool("my-project", group=group.name)
+
 new_network = cloud.networks.create(
     name="mtn-prod-net",
-    cloud_id=1,
-    group_id=621,
-    type_id=network_types[0].id,
+    cloud_id=group.cloud_ids[0],
+    group_id=group.id,
+    type_id=net_type.id,
+    resource_pool_id=pool.id,
     cidr="10.42.10.0/24",
     gateway="10.42.10.1",
     dns_primary="8.8.8.8",
-    visibility="private",
-    dhcp_server=True,
 )
 
-# Update and list subnets
-cloud.networks.update(new_network.id, description="Production network")
+# Inspect subnets
 subnets = cloud.networks.list_subnets(new_network.id)
 print(f"Subnets: {len(subnets)}")
 ```

{mtn_cloud-0.2.17 → mtn_cloud-0.3.1}/docs/advanced-cookbook.md

@@ -103,9 +103,10 @@ from mtn_cloud import (
 try:
     cloud.networks.create(
         name="prod-net",
-        cloud_id=1,
+        cloud_id=4,
         group_id=621,
-        type_id=8,
+        type_id=12,             # an OpenStack type from list_types(openstack_only=True)
+        resource_pool_id=230,   # numeric pool ID from get_resource_pool(...).id
         cidr="10.42.10.0/24",
     )
 except AuthenticationError:
@@ -149,8 +150,17 @@ with MTNCloud(token="your-api-token") as cloud:
 Pick explicit templates and plans instead of "first result" in production.
 
 ```python
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
 target_type = cloud.instance_types.get_by_code("MTN-U24.04LTS")
-target_plan = cloud.plans.get_by_name("G2S4")
+
+plans = cloud.instances.list_service_plans(
+    zone_id=group.cloud_ids[0],
+    layout_id=target_type.default_layout_id,
+    group_id=group.id,
+)
+target_plan = next(p for p in plans if p["name"] == "G2S4")
+
+pool = cloud.instances.get_resource_pool("my-project", group=group.name)
 
 instance = cloud.instances.create(
     name="api-worker-01",
@@ -158,8 +168,8 @@ instance = cloud.instances.create(
     type=target_type.code,
     group="MTNNG_CLOUD_AZ_1",
     layout=target_type.default_layout_id,
-    plan=target_plan.id,
-    resource_pool_id="pool-214",
+    plan=target_plan["id"],
+    resource_pool_id=pool.code,
 )
 ```
 

{mtn_cloud-0.2.17 → mtn_cloud-0.3.1}/docs/api-overview.md

@@ -42,7 +42,10 @@ 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)
 
@@ -93,6 +96,7 @@ Resource methods return typed Pydantic models, for example:
 - `ArchiveFile`
 - `SecurityGroup`, `SecurityGroupRule`
 - `Snapshot`
+- `ResourcePool`
 - `Backup`, `BackupJob`, `BackupResult`
 - `VirtualImage`
 

{mtn_cloud-0.2.17 → mtn_cloud-0.3.1}/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:
@@ -197,3 +197,36 @@ Client-side polling helper.
 - 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.17 → mtn_cloud-0.3.1}/docs/api-reference/networks.md

@@ -32,7 +32,7 @@
 - Returns: `list[Network]`
 - Raises: common API exceptions
 
-### `create(name: str, *, cloud_id: int, group_id: int, type_id=None, display_name=None, labels=None, description=None, cidr=None, gateway=None, dns_primary=None, dns_secondary=None, vlan_id=None, switch_id=None, pool_id=None, allow_static_override=None, assign_public_ip=None, active=None, dhcp_server=None, network_domain_id=None, search_domains=None, network_proxy_id=None, appliance_url_proxy_bypass=None, no_proxy=None, visibility=None, tenant_ids=None, resource_permission_all=None, resource_permission_site_ids=None) -> Network`
+### `create(name: str, *, cloud_id: int, group_id: int, type_id=None, resource_pool_id=None, display_name=None, labels=None, description=None, cidr=None, gateway=None, dns_primary=None, dns_secondary=None, vlan_id=None, switch_id=None, pool_id=None, allow_static_override=None, assign_public_ip=None, active=None, dhcp_server=None, network_domain_id=None, search_domains=None, network_proxy_id=None, appliance_url_proxy_bypass=None, no_proxy=None, visibility=None, tenant_ids=None, resource_permission_all=None, resource_permission_site_ids=None) -> Network`
 
 - Endpoint: `POST /api/networks`
 - Parameters:
@@ -40,8 +40,11 @@
         - `name`: network name
         - `cloud_id`: cloud/zone ID
         - `group_id`: group/site ID
+    - Required for OpenStack networks (e.g. `openstackPrivate`):
+        - `type_id`: an OpenStack network type ID from `list_types(openstack_only=True)`
+        - `resource_pool_id`: numeric resource pool ID (sent as `zonePool`); get it from `instances.get_resource_pool(...).id`
     - Common optional network config:
-        - `type_id`, `display_name`, `labels`, `description`, `cidr`, `gateway`
+        - `display_name`, `labels`, `description`, `cidr`, `gateway`
         - `dns_primary`, `dns_secondary`, `vlan_id`, `switch_id`, `pool_id`
         - `allow_static_override`, `assign_public_ip`, `active`, `dhcp_server`
         - `network_domain_id`, `search_domains`, `network_proxy_id`
@@ -88,36 +91,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.
 

{mtn_cloud-0.2.17 → mtn_cloud-0.3.1}/docs/index.md

@@ -18,7 +18,6 @@ Use this guide in two ways:
 8. [Advanced Cookbook](./advanced-cookbook.md)
 9. [API Overview](./api-overview.md)
 10. [API Reference](./api-reference/index.md)
-11. [Docstring Style Standard](./docstring-style.md)
 
 ## Who This Is For
 

{mtn_cloud-0.2.17 → mtn_cloud-0.3.1}/docs/instances.md

@@ -50,35 +50,79 @@ Lagos AZ3 (Lagos Mainland) is in progress. Each zone has independent power, cool
 
 Run this before creating an instance. All IDs are account-specific.
 
+Provisioning inputs are discovered from **groups, instance types, resource pools, and service plans** — all permission-safe endpoints. (The admin-level `clouds.list()` and `plans.list()` endpoints are restricted on most tenant accounts and will raise `ForbiddenError`; you do not need them.)
+
 ```python
 from mtn_cloud import MTNCloud
 
 cloud = MTNCloud(token="your-api-token")
 
-groups = cloud.groups.list()
-clouds = cloud.clouds.list_openstack()
-types = cloud.instance_types.list_os()
-plans = cloud.plans.list()
-
-print([(g.id, g.name) for g in groups[:5]])
-print([(c.id, c.name) for c in clouds[:5]])
-print([(t.code, t.default_layout_id) for t in types[:5]])
-print([(p.id, p.name) for p in plans[:5]])
+# 1. Group — gives you the group name AND its cloud/zone IDs
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+cloud_id = group.cloud_ids[0]
+print("group:", group.id, group.name, "cloud_ids:", group.cloud_ids)
+
+# 2. Instance type — each carries its own default_layout_id
+itype = cloud.instance_types.get_by_code("MTN-CS10")
+print("type:", itype.code, "layout:", itype.default_layout_id)
+
+# 3. Resource pool — where the instance is hosted (the resource_pool_id)
+for pool in cloud.instances.list_resource_pools(group="MTNNG_CLOUD_AZ_1"):
+    print("pool:", pool.code, pool.name)
+
+# 4. Service plans — available CPU/memory/storage tiers for this zone + layout
+for plan in cloud.instances.list_service_plans(
+    zone_id=cloud_id,
+    layout_id=itype.default_layout_id,
+    group_id=group.id,
+):
+    print("plan:", plan["id"], plan["name"])
 ```
 
 The `default_layout_id` on each instance type is the correct `layout` value to use for that type. Always read it from your account rather than hardcoding a value from an example.
 
+### Resource Pools (the `resource_pool_id`)
+
+A resource pool is **where your instance is hosted** — you cannot create an instance without one. List them by group name (the cloud/zone is resolved for you):
+
+```python
+# List every pool available to a group
+for pool in cloud.instances.list_resource_pools(group="MTNNG_CLOUD_AZ_1"):
+    print(pool.code, pool.name, "(default)" if pool.is_default else "")
+
+# Or fetch a single pool by name (or by its code)
+pool = cloud.instances.get_resource_pool(
+    "my-project-Marv-Osuolale",
+    group="MTNNG_CLOUD_AZ_1",
+)
+print(pool.code)   # e.g. "pool-214" — pass this as resource_pool_id
+```
+
+`pool.code` (e.g. `"pool-214"`) is the exact value `create()` expects. When passing it to `create()`, you can use the code (`"pool-214"`), the numeric ID (`214`), or its string form (`"214"`) — they are all normalized to the code internally.
+
+If you already know the cloud and group IDs, pass them explicitly to skip the group lookup:
+
+```python
+pools = cloud.instances.list_resource_pools(cloud_id=4, group_id=621)
+```
+
 ## Create an Instance
 
 ```python
+# Resolve the resource pool once, then use its code directly
+pool = cloud.instances.get_resource_pool(
+    "my-project-Marv-Osuolale",
+    group="MTNNG_CLOUD_AZ_1",
+)
+
 instance = cloud.instances.create(
     name="app-server-01",
     cloud="MTNNG_CLOUD_AZ_1",
     type="MTN-CS10",
     group="MTNNG_CLOUD_AZ_1",
     layout=327,                         # use default_layout_id from your type lookup
-    plan=6776,                          # use plan ID from your plans lookup
-    resource_pool_id="pool-214",        # from your project order
+    plan=6776,                          # use a plan ID from list_service_plans()
+    resource_pool_id=pool.code,         # e.g. "pool-214" (or pass 214 directly)
     availability_zone="Lagos-AZ-1-fd1",
     security_group="default",           # security group name from the console
 )

mtn_cloud-0.3.1/docs/networking.md

@@ -0,0 +1,100 @@
+# Networking
+
+Use this guide for creating and managing MTN Cloud networks via the SDK.
+
+## Before You Start
+
+- You need an existing Resource Pool (Project). Create one from **Provisioning → Catalog → Create Project** if you haven't already.
+- MTN Cloud networking runs on OpenStack Neutron. Networks you create are private by default — VMs get private IPs automatically. Public internet access is configured at provisioning time via the instance's external network (`os_external_network_id`), not through a standalone floating-IP API.
+- Use `list_types(openstack_only=True)` to discover the valid network type IDs for your account.
+
+## Typical Networking Flow
+
+1. Create a network (with CIDR, gateway, DHCP).
+2. Provision instances on your network.
+3. For public access, set `os_external_network_id` when creating the instance (see the [Instances guide](./instances.md)).
+
+## Discover Reference Data
+
+The `cloud_id` (zone) comes from the group — the admin-level `clouds.list()` endpoint is restricted on most tenant accounts and isn't needed.
+
+```python
+from mtn_cloud import MTNCloud
+
+cloud = MTNCloud(token="your-api-token")
+
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+cloud_id = group.cloud_ids[0]
+network_types = cloud.networks.list_types(openstack_only=True)
+
+print("group:", group.id, "cloud_id:", cloud_id)
+print([(t.id, t.name) for t in network_types[:5]])
+```
+
+## Create a Network
+
+An OpenStack network requires an OpenStack `type_id` and a `resource_pool_id` (the numeric pool ID — the network is created inside that resource pool). Pick a private network type and a pool:
+
+```python
+networks = cloud.networks.list(cloud_id=cloud_id)
+for network in networks[:5]:
+    print(network.id, network.name, network.cidr)
+
+net_type = next(t for t in network_types if t.code == "openstackPrivate")
+pool = cloud.instances.get_resource_pool("my-project", group=group.name)
+
+new_network = cloud.networks.create(
+    name="mtn-prod-net",
+    cloud_id=cloud_id,                  # from group.cloud_ids[0]
+    group_id=group.id,                  # from groups.get_by_name(...)
+    type_id=net_type.id,                # an OpenStack type from list_types(openstack_only=True)
+    resource_pool_id=pool.id,           # numeric pool ID from get_resource_pool(...)
+    cidr="10.42.10.0/24",
+    gateway="10.42.10.1",
+    dns_primary="8.8.8.8",
+)
+
+print(new_network.id, new_network.name)
+```
+
+## Update and Inspect
+
+```python
+updated = cloud.networks.update(
+    new_network.id,
+    description="Production network",
+    allow_static_override=True,
+)
+
+subnets = cloud.networks.list_subnets(updated.id)
+print(f"Subnets: {len(subnets)}")
+```
+
+## Delete a Network
+
+```python
+cloud.networks.delete(new_network.id)
+```
+
+## Network Pools
+
+Network pools are managed ranges of IP addresses used for static assignment. Inspect them and the individual addresses they track:
+
+```python
+# List pools with usage counts
+for pool in cloud.networks.list_pools():
+    print(pool.id, pool.name, f"{pool.free_count}/{pool.ip_count} free")
+    for r in pool.ip_ranges:
+        print("   range:", r.start_address, "-", r.end_address)
+
+# Inspect a single pool and the addresses in use
+pool = cloud.networks.get_pool(9)
+for ip in cloud.networks.list_pool_ips(pool.id):
+    print(ip.ip_address, ip.ip_type, ip.hostname)
+```
+
+## Notes
+
+- Many networking fields are OpenStack-specific. The SDK exposes the fields most relevant to MTN Cloud's environment.
+- Always discover and validate IDs (`cloud_id`, `group_id`, `type_id`) for your own account — they are tenant-specific and differ between environments.
+- Security groups (firewall rules) are separate from network configuration. Manage them via `cloud.security_groups` — see the [Security Groups guide](./security-groups.md).