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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtn-cloud
-Version: 0.2.19
+Version: 0.3.2
 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
@@ -10,7 +10,7 @@ Author-email: Marvellous Osuolale <m@rvellous.com>
 Maintainer-email: Marvellous Osuolale <m@rvellous.com>
 License: MIT
 License-File: LICENSE
-Keywords: api,cloud,devops,infrastructure,mtn,mtn-cloud,sdk
+Keywords: api,cloud,cloud-management,devops,infrastructure,mtn,mtn-cloud,mtn-cloud-python,sdk
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -31,10 +31,8 @@ Requires-Dist: typing-extensions>=4.5.0
 Requires-Dist: urllib3>=2.0.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0.0; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
-Requires-Dist: respx>=0.20.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Requires-Dist: types-requests>=2.28.0; extra == 'dev'
 Provides-Extra: docs
@@ -84,7 +82,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
 
@@ -151,33 +148,36 @@ for plan in cloud.instances.list_service_plans(
     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:
+A **resource pool is required** to create an instance — it's where the VM is hosted. `provision()` (below) discovers it for you; or fetch one yourself with `cloud.instances.get_resource_pool("my-project", group="MTNNG_CLOUD_AZ_1")`.
+
+### 2. Create an Instance
+
+The guided `provision()` resolves layout, plan, and resource pool from names — the fastest path:
 
 ```python
-pool = cloud.instances.get_resource_pool(
-    "my-project-name",
-    group="MTNNG_CLOUD_AZ_1",
+instance = cloud.instances.provision(
+    name="web-01",
+    type="MTN-CS10",                # type code
+    group="MTNNG_CLOUD_AZ_1",       # also used as the cloud/zone
+    plan="G2S4",                    # plan name (or numeric id)
+    resource_pool="my-project",     # pool name; auto-selected if the group has only one
 )
-print(pool.code)   # e.g. "pool-214" — pass this as resource_pool_id
+print(instance.id, instance.status, instance.primary_ip)
 ```
 
-### 2. Create an Instance
+For full control over every ID, use `create()` directly:
 
 ```python
-pool = cloud.instances.get_resource_pool("my-project-name", group="MTNNG_CLOUD_AZ_1")
-
 instance = cloud.instances.create(
-    name="my-server",
+    name="web-01",
     cloud="MTNNG_CLOUD_AZ_1",
     type="MTN-CS10",
     group="MTNNG_CLOUD_AZ_1",
     layout=327,
     plan=6776,
-    resource_pool_id=pool.code,   # "pool-214" — or pass the numeric ID 214
+    resource_pool_id="pool-214",    # or the numeric ID 214
     labels=["production", "web"],
 )
-
-print(f"Created: {instance.id} {instance.name} ({instance.status})")
 ```
 
 ### 3. Manage an Instance
@@ -200,27 +200,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.19 → mtn_cloud-0.3.2}/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
 
@@ -107,33 +106,36 @@ for plan in cloud.instances.list_service_plans(
     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:
+A **resource pool is required** to create an instance — it's where the VM is hosted. `provision()` (below) discovers it for you; or fetch one yourself with `cloud.instances.get_resource_pool("my-project", group="MTNNG_CLOUD_AZ_1")`.
+
+### 2. Create an Instance
+
+The guided `provision()` resolves layout, plan, and resource pool from names — the fastest path:
 
 ```python
-pool = cloud.instances.get_resource_pool(
-    "my-project-name",
-    group="MTNNG_CLOUD_AZ_1",
+instance = cloud.instances.provision(
+    name="web-01",
+    type="MTN-CS10",                # type code
+    group="MTNNG_CLOUD_AZ_1",       # also used as the cloud/zone
+    plan="G2S4",                    # plan name (or numeric id)
+    resource_pool="my-project",     # pool name; auto-selected if the group has only one
 )
-print(pool.code)   # e.g. "pool-214" — pass this as resource_pool_id
+print(instance.id, instance.status, instance.primary_ip)
 ```
 
-### 2. Create an Instance
+For full control over every ID, use `create()` directly:
 
 ```python
-pool = cloud.instances.get_resource_pool("my-project-name", group="MTNNG_CLOUD_AZ_1")
-
 instance = cloud.instances.create(
-    name="my-server",
+    name="web-01",
     cloud="MTNNG_CLOUD_AZ_1",
     type="MTN-CS10",
     group="MTNNG_CLOUD_AZ_1",
     layout=327,
     plan=6776,
-    resource_pool_id=pool.code,   # "pool-214" — or pass the numeric ID 214
+    resource_pool_id="pool-214",    # or the numeric ID 214
     labels=["production", "web"],
 )
-
-print(f"Created: {instance.id} {instance.name} ({instance.status})")
 ```
 
 ### 3. Manage an Instance
@@ -156,27 +158,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.19 → mtn_cloud-0.3.2}/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.19 → mtn_cloud-0.3.2}/docs/api-overview.md

@@ -42,10 +42,11 @@ cloud.instance_types.get_by_code("MTN-CS10")
 ## Common Write Operations
 
 ```python
-# 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)
+# Guided: resolves layout, plan, and resource pool from names
+cloud.instances.provision(name="web-01", type="MTN-CS10",
+                          group="MTNNG_CLOUD_AZ_1", plan="G2S4", resource_pool="my-project")
+# Explicit: full control over each ID
+cloud.instances.create(..., resource_pool_id="pool-214")
 cloud.instances.update(instance_id=123, name="new-name")
 cloud.instances.delete(123)
 

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

@@ -61,6 +61,31 @@
     - common API exceptions
     - `NotFoundError` when `group` cannot be resolved
 
+### `provision(name: str, *, type: str, group: str, plan: str | int, resource_pool=None, cloud=None, availability_zone=None, security_group="default", wait=True, timeout=600, dry_run=False, **create_kwargs) -> Instance | dict`
+
+Guided wrapper over `create()` that resolves IDs from names.
+
+- Endpoint sequence:
+    - `GET /api/groups?name=<group>` (resolve group → `cloud_ids`)
+    - `GET /api/instance-types?code=<type>` (resolve `layout` via `default_layout_id`)
+    - `GET /api/instances/service-plans` (resolve `plan` name → ID, unless `plan` is an int)
+    - `GET /api/options/zonePools` (resolve/auto-select `resource_pool`, unless given as int)
+    - `POST /api/instances`, then polls `GET /api/instances/{id}` when `wait=True`
+- Parameters:
+    - `type`: instance type code; its `default_layout_id` becomes `layout`
+    - `group`: group name; also used as `cloud` unless `cloud` is given
+    - `plan`: plan name (resolved against the live list) or numeric ID
+    - `resource_pool`: pool name, code, or numeric ID. If omitted, the group's single pool is used; if it has several, a `ValidationError` lists them
+    - `cloud`: cloud/zone name; defaults to `group`
+    - `wait`: block until running (default `True`)
+    - `timeout`: max seconds to wait when `wait=True`
+    - `dry_run`: return the resolved config dict instead of creating
+    - `**create_kwargs`: forwarded to `create()` (labels, tags, volumes, network_interfaces, ports, …)
+- Returns: the created `Instance` (running if `wait=True`), or a config `dict` when `dry_run=True`
+- Raises:
+    - `NotFoundError` when the group or instance type can't be resolved
+    - `ValidationError` when the plan or resource pool can't be resolved
+
 ### `update(instance_id: int, name=None, description=None, labels=None) -> Instance`
 
 - Endpoint: `PUT /api/instances/{instance_id}`

{mtn_cloud-0.2.19 → mtn_cloud-0.3.2}/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`

{mtn_cloud-0.2.19 → mtn_cloud-0.3.2}/docs/index.md

@@ -15,10 +15,10 @@ Use this guide in two ways:
 5. [Security Groups](./security-groups.md)
 6. [Backups](./backups.md)
 7. [Virtual Images](./virtual-images.md)
-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)
+8. [Recipes](./recipes.md)
+9. [Advanced Cookbook](./advanced-cookbook.md)
+10. [API Overview](./api-overview.md)
+11. [API Reference](./api-reference/index.md)
 
 ## Who This Is For
 
@@ -42,6 +42,7 @@ Use this guide in two ways:
 5. Security Groups
 6. Backups
 7. Virtual Images
-8. API Overview
-9. API Reference
-10. Advanced Cookbook
+8. Recipes
+9. API Overview
+10. API Reference
+11. Advanced Cookbook

{mtn_cloud-0.2.19 → mtn_cloud-0.3.2}/docs/instances.md

@@ -106,15 +106,44 @@ If you already know the cloud and group IDs, pass them explicitly to skip the gr
 pools = cloud.instances.list_resource_pools(cloud_id=4, group_id=621)
 ```
 
-## Create an Instance
+## Provision an Instance (guided)
+
+`provision()` is the fastest way to create an instance: it takes the names you already know and resolves the numeric IDs for you — the layout from the type code, the plan from its name, and the resource pool from its name (or auto-selects it when the group has exactly one).
 
 ```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.provision(
+    name="app-server-01",
+    type="MTN-CS10",                    # type code -> resolves the layout
+    group="MTNNG_CLOUD_AZ_1",           # also used as the cloud/zone
+    plan="G2S4",                        # plan name (or pass a numeric plan ID)
+    resource_pool="my-project",         # pool name; omit if the group has one pool
+    availability_zone="Lagos-AZ-1-fd1",
+    security_group="default",
 )
 
+# wait=True by default, so the instance is already running here
+print(instance.id, instance.name, instance.status, instance.primary_ip)
+```
+
+If a name can't be resolved, the error tells you what's available (e.g. the valid plan names, or the pools to choose from). Set `wait=False` to return immediately, or `dry_run=True` to get the resolved config back without creating anything:
+
+```python
+config = cloud.instances.provision(
+    name="app-server-01", type="MTN-CS10", group="MTNNG_CLOUD_AZ_1",
+    plan="G2S4", resource_pool="my-project", dry_run=True,
+)
+# {"layout": 327, "plan": 6776, "resource_pool_id": "pool-214", ...}
+```
+
+Any extra keyword (labels, tags, volumes, network_interfaces, ports, …) passes straight through to `create()`.
+
+## Create an Instance (explicit)
+
+When you want full control over each ID, call `create()` directly. Resolve the inputs yourself first (see [Discover Required IDs](#discover-required-ids-and-codes)):
+
+```python
+pool = cloud.instances.get_resource_pool("my-project", group="MTNNG_CLOUD_AZ_1")
+
 instance = cloud.instances.create(
     name="app-server-01",
     cloud="MTNNG_CLOUD_AZ_1",
@@ -124,7 +153,7 @@ instance = cloud.instances.create(
     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
+    security_group="default",
 )
 
 print(instance.id, instance.name, instance.status, instance.primary_ip)

{mtn_cloud-0.2.19 → mtn_cloud-0.3.2}/docs/networking.md

@@ -33,21 +33,25 @@ 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=network_types[0].id,        # from list_types(openstack_only=True)
+    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",
-    visibility="private",
-    dhcp_server=True,                   # enables automatic IP assignment
 )
 
 print(new_network.id, new_network.name)

{mtn_cloud-0.2.19 → mtn_cloud-0.3.2}/docs/quickstart.md

@@ -57,11 +57,28 @@ One tenancy can have multiple resource pools — useful for separating dev, stag
 
 Security groups are the firewall layer for your VMs. Without one, you will not be able to SSH or RDP in after provisioning.
 
-1. Go to **Infrastructure → Network → Security Groups** and create a group.
-2. Add an inbound rule: SSH port 22 (TCP) for Linux VMs, or RDP port 3389 (TCP) for Windows VMs.
-3. Restrict the source to your IP range, e.g., `200.200.113.15/32` for a single machine.
+You can create one either in the console (**Infrastructure → Network → Security Groups**) or directly with the SDK:
 
-The group name (e.g., `"default"`) is passed as the `security_group` parameter when creating an instance.
+```python
+# Create the group
+sg = cloud.security_groups.create(
+    name="web-servers",
+    description="SSH + HTTPS access",
+)
+
+# Allow SSH from a single machine (use 3389/tcp instead for Windows RDP)
+cloud.security_groups.create_rule(
+    sg.id,
+    name="allow-ssh",
+    direction="ingress",
+    protocol="tcp",
+    port_range="22",
+    source_type="cidr",
+    source="200.200.113.15/32",   # restrict to your IP range
+)
+```
+
+The group name (e.g., `"web-servers"` or `"default"`) is passed as the `security_group` parameter when creating an instance. See the [Security Groups guide](./security-groups.md) for the full workflow.
 
 Optionally, add an SSH key pair under **User Settings → SSH Keys** for key-based access.
 
@@ -77,18 +94,30 @@ Keep the credentials from that email — you will pass them directly into the SD
 
 ## 5. Discover Core Reference Data
 
-Before creating resources, look up the valid IDs and codes for your account. These are tenant-specific and cannot be copied from documentation or other accounts.
+Before creating resources, look up the valid IDs and codes for your account. These are tenant-specific and cannot be copied from documentation or other accounts. Everything below uses permission-safe endpoints — the admin-level `clouds.list()` and `plans.list()` are restricted on most tenant accounts and aren't needed.
 
 ```python
-groups = cloud.groups.list()
-clouds = cloud.clouds.list_openstack()
-instance_types = cloud.instance_types.list_os()
-plans = cloud.plans.list()
-
-print("Groups:", [(g.id, g.name) for g in groups[:5]])
-print("Clouds:", [(c.id, c.name) for c in clouds[:5]])
-print("Instance types:", [(t.code, t.default_layout_id) for t in instance_types[:5]])
-print("Plans:", [(p.id, p.name, p.cores, p.memory_gb) for p in plans[:5]])
+# Group — also carries the cloud/zone IDs you need
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+cloud_id = group.cloud_ids[0]
+
+# Instance type — carries its own default_layout_id
+itype = cloud.instance_types.get_by_code("MTN-CS10")
+
+# Resource pool — the resource_pool_id, where the instance is hosted
+pools = cloud.instances.list_resource_pools(group=group.name)
+
+# Service plans — CPU/memory/storage tiers for this zone + layout
+plans = cloud.instances.list_service_plans(
+    zone_id=cloud_id,
+    layout_id=itype.default_layout_id,
+    group_id=group.id,
+)
+
+print("group:", group.id, "cloud_id:", cloud_id)
+print("layout:", itype.default_layout_id)
+print("pools:", [(p.code, p.name) for p in pools[:5]])
+print("plans:", [(pl["id"], pl["name"]) for pl in plans[:5]])
 ```
 
 MTN Cloud currently has two live zones: **Lagos AZ1** (`MTNNG_CLOUD_AZ_1`) and **Lagos AZ2** (`MTNNG_CLOUD_AZ_2`).
@@ -105,9 +134,9 @@ instance = cloud.instances.create(
     group="MTNNG_CLOUD_AZ_1",
     layout=327,
     plan=6923,
-    resource_pool_id="pool-214",        # from your project order
+    resource_pool_id=pools[0].code,     # from list_resource_pools() above
     availability_zone="Lagos-AZ-1-fd1",
-    security_group="default",           # security group name from the console
+    security_group="web-servers",       # the security group you created above
 )
 
 print(instance.id, instance.name, instance.status, instance.primary_ip)

mtn_cloud-0.3.2/docs/recipes.md

@@ -0,0 +1,110 @@
+# Recipes
+
+Three complete, real-world workflows. Each assumes an authenticated client:
+
+```python
+from mtn_cloud import MTNCloud
+
+cloud = MTNCloud(token="your-api-token")
+```
+
+For isolated patterns (retries, pagination, idempotency), see the [Advanced Cookbook](./advanced-cookbook.md).
+
+## Provision a Linux VM with SSH
+
+Discover the inputs, open SSH in a security group, provision, and wait until it's reachable.
+
+```python
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+itype = cloud.instance_types.get_by_code("MTN-CS10")
+pool = cloud.instances.get_resource_pool("my-project", group=group.name)
+plans = cloud.instances.list_service_plans(
+    zone_id=group.cloud_ids[0], layout_id=itype.default_layout_id, group_id=group.id,
+)
+
+sg = cloud.security_groups.create(name="linux-ssh", description="SSH access")
+cloud.security_groups.create_rule(
+    sg.id, name="allow-ssh", direction="ingress", protocol="tcp",
+    port_range="22", source_type="cidr", source="200.200.113.15/32",
+)
+
+instance = cloud.instances.create(
+    name="linux-web-01",
+    cloud=group.name,
+    type=itype.code,
+    group=group.name,
+    layout=itype.default_layout_id,
+    plan=plans[0]["id"],
+    resource_pool_id=pool.code,
+    availability_zone="Lagos-AZ-1-fd1",
+    security_group=sg.name,
+    create_user=True,
+)
+instance = cloud.instances.wait_until_running(instance.id, timeout=600)
+print("ready:", instance.primary_ip)
+```
+
+SSH **keys** are uploaded once in the console (**User Settings → SSH Keys**); the SDK controls the firewall rule and user creation. Then: `ssh <your-user>@<instance.primary_ip>`.
+
+## Back up a folder to MTN Object Storage
+
+Register the provider and bucket idempotently, preview with a dry run, then upload.
+
+```python
+from mtn_cloud import NotFoundError
+
+try:
+    storage = cloud.storage_buckets.get_by_name("my-s3-storage")
+except NotFoundError:
+    storage = cloud.storage_buckets.create_s3(
+        name="my-s3-storage",
+        bucket_name="my-app-objects",
+        access_key="your-access-key",                      # from MOS email
+        secret_key="your-secret-key",                      # from MOS email
+        endpoint="https://ps1csp-s3.ict.mtn.com.ng:9021",
+        create_bucket=True,
+    )
+
+try:
+    archive = cloud.archive_buckets.get_by_name("my-app-archives")
+except NotFoundError:
+    archive = cloud.archive_buckets.create(
+        name="my-app-archives", storage_provider_id=storage.id, visibility="private",
+    )
+
+preview = cloud.archive_buckets.upload_directory(
+    bucket_name=archive.name, remote_path="/backups/",
+    local_directory="./data", recursive=True, dry_run=True,
+)
+if preview.skipped_count:
+    raise RuntimeError(f"{preview.skipped_count} files would be skipped")
+
+result = cloud.archive_buckets.upload_directory(
+    bucket_name=archive.name, remote_path="/backups/",
+    local_directory="./data", recursive=True, strict=True,
+)
+print(f"uploaded={result.uploaded_count} failed={result.failed_count}")
+```
+
+## Tear down demo resources
+
+Delete in dependency order — instances first, then the firewall and network they used. Deletes are best-effort so one failure doesn't block the rest.
+
+```python
+from mtn_cloud import MTNCloudError
+
+def cleanup(manager, items, label):
+    for item in items:
+        if (item.name or "").startswith("demo-"):
+            try:
+                manager.delete(item.id)
+                print("deleted", label, item.id)
+            except MTNCloudError as exc:
+                print("skip", label, item.id, exc)
+
+cleanup(cloud.instances, cloud.instances.list(max_results=100), "instance")
+cleanup(cloud.security_groups, cloud.security_groups.list(), "security-group")
+cleanup(cloud.networks, cloud.networks.list(), "network")
+```
+
+A network or security group can't be deleted while an instance still references it — always remove instances first and let them finish.