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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtn-cloud
-Version: 0.3.1
+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
@@ -150,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

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

@@ -106,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

{mtn_cloud-0.3.1 → 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.3.1 → 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.3.1 → mtn_cloud-0.3.2}/docs/index.md

@@ -15,9 +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)
+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
 
@@ -41,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.3.1 → 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.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.

{mtn_cloud-0.3.1 → mtn_cloud-0.3.2}/pyproject.toml

@@ -21,7 +21,9 @@ keywords = [
     "sdk",
     "api",
     "infrastructure",
-    "devops"
+    "devops",
+    "cloud-management",
+    "mtn-cloud-python"    
 ]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -50,8 +52,6 @@ dependencies = [
 dev = [
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
-    "pytest-asyncio>=0.21.0",
-    "respx>=0.20.0",
     "ruff>=0.1.0",
     "mypy>=1.0.0",
     "types-requests>=2.28.0",
@@ -121,4 +121,3 @@ ignore_missing_imports = true
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-asyncio_mode = "auto"

{mtn_cloud-0.3.1 → mtn_cloud-0.3.2}/src/mtn_cloud/_version.py

@@ -1,3 +1,3 @@
 """Package version metadata."""
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"

{mtn_cloud-0.3.1 → mtn_cloud-0.3.2}/src/mtn_cloud/http.py

@@ -69,8 +69,9 @@ class HTTPClient:
         retry_strategy = Retry(
             total=self.config.max_retries,
             backoff_factor=self.config.retry_delay,
-            status_forcelist=[500, 502, 503, 504],
+            status_forcelist=[429, 500, 502, 503, 504],
             allowed_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
+            respect_retry_after_header=True,
             raise_on_status=False,
         )
 

{mtn_cloud-0.3.1 → mtn_cloud-0.3.2}/src/mtn_cloud/resources/instances.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import time
 from typing import TYPE_CHECKING, Any, Dict, List
 
-from mtn_cloud.exceptions import NotFoundError, TimeoutError
+from mtn_cloud.exceptions import NotFoundError, TimeoutError, ValidationError
 from mtn_cloud.models.group import Group
 from mtn_cloud.models.instance import (
     Instance,
@@ -305,6 +305,190 @@ class InstancesResource(BaseResource[Instance]):
         payload = create_model.to_api_payload()
         return self._create(payload)
 
+    def provision(
+        self,
+        name: str,
+        *,
+        type: str,
+        group: str,
+        plan: str | int,
+        resource_pool: str | int | None = None,
+        cloud: str | None = None,
+        availability_zone: str | None = None,
+        security_group: str = "default",
+        wait: bool = True,
+        timeout: int = 600,
+        dry_run: bool = False,
+        description: str | None = None,
+        environment: str | None = None,
+        labels: List[str] | None = None,
+        tags: Dict[str, str] | None = None,
+        copies: int = 1,
+        layout_size: int = 1,
+        os_external_network_id: str | None = None,
+        create_user: bool = True,
+        workflow_id: int | None = None,
+        shutdown_days: int | None = None,
+        expire_days: int | None = None,
+        create_backup: bool | None = None,
+        security_groups: List[str] | None = None,
+        ports: List[Dict[str, Any]] | None = None,
+        volumes: List[InstanceVolume | Dict[str, Any]] | None = None,
+        network_interfaces: List[InstanceNetwork | Dict[str, Any]] | None = None,
+        options: Dict[str, Any] | None = None,
+    ) -> Instance | Dict[str, Any]:
+        """
+        Provision an instance from human-friendly names.
+
+        A guided wrapper over :meth:`create` that resolves the IDs an instance
+        needs from names you already know:
+
+        - ``layout`` from the instance type ``code``
+        - ``plan`` ID from a plan name (or pass the numeric ID directly)
+        - ``resource_pool_id`` from a pool name (or auto-selected when the group
+          has exactly one pool)
+        - ``cloud`` defaults to ``group`` (the MTN convention)
+
+        Args:
+            name: Instance name
+            type: Instance type code (e.g. ``"MTN-CS10"``)
+            group: Group name; also used as the cloud/zone unless ``cloud`` is set
+            plan: Service plan name (resolved) or numeric ID
+            resource_pool: Pool name, code, or numeric ID. If omitted, the group's
+                single pool is used; if the group has several, an error lists them.
+            cloud: Cloud/zone name; defaults to ``group``
+            availability_zone: Availability zone (e.g. ``"Lagos-AZ-1-fd1"``)
+            security_group: Security group name (default ``"default"``)
+            wait: Block until the instance is running (default True)
+            timeout: Max seconds to wait when ``wait`` is True
+            dry_run: Return the resolved config without creating anything
+            **: Remaining options pass straight through to :meth:`create`
+
+        Returns:
+            The created :class:`Instance` (running if ``wait``), or the resolved
+            config dict when ``dry_run`` is True.
+
+        Raises:
+            NotFoundError: If the group or instance type cannot be resolved
+            ValidationError: If the plan or resource pool cannot be resolved
+
+        Example:
+            instance = cloud.instances.provision(
+                name="web-01",
+                type="MTN-CS10",
+                group="MTNNG_CLOUD_AZ_1",
+                plan="G2S4",
+                resource_pool="my-project",
+            )
+        """
+        grp = self._resolve_group(group)
+        if not grp.cloud_ids:
+            raise ValidationError(f"Group '{group}' has no associated cloud.")
+        zone_id = grp.cloud_ids[0]
+        group_name = grp.name or group
+        cloud_name = cloud or group_name
+
+        from mtn_cloud.resources.instance_types import InstanceTypesResource
+
+        instance_type = InstanceTypesResource(self._http).get_by_code(type)
+        layout_id = instance_type.default_layout_id
+        if layout_id is None:
+            raise ValidationError(f"Instance type '{type}' has no available layout.")
+
+        plan_id = self._resolve_plan_id(plan, zone_id=zone_id, layout_id=layout_id, group_id=grp.id)
+        pool_code = self._resolve_provision_pool(resource_pool, grp)
+
+        if dry_run:
+            return {
+                "name": name,
+                "cloud": cloud_name,
+                "type": type,
+                "group": group_name,
+                "layout": layout_id,
+                "plan": plan_id,
+                "resource_pool_id": pool_code,
+                "availability_zone": availability_zone,
+                "security_group": security_group,
+            }
+
+        instance = self.create(
+            name=name,
+            cloud=cloud_name,
+            type=type,
+            group=group_name,
+            layout=layout_id,
+            plan=plan_id,
+            resource_pool_id=pool_code,
+            availability_zone=availability_zone,
+            security_group=security_group,
+            description=description,
+            environment=environment,
+            labels=labels,
+            tags=tags,
+            copies=copies,
+            layout_size=layout_size,
+            os_external_network_id=os_external_network_id,
+            create_user=create_user,
+            workflow_id=workflow_id,
+            shutdown_days=shutdown_days,
+            expire_days=expire_days,
+            create_backup=create_backup,
+            security_groups=security_groups,
+            ports=ports,
+            volumes=volumes,
+            network_interfaces=network_interfaces,
+            options=options,
+        )
+        if wait:
+            return self.wait_until_running(instance.id, timeout=timeout)
+        return instance
+
+    def _resolve_plan_id(
+        self,
+        plan: str | int,
+        *,
+        zone_id: int,
+        layout_id: int,
+        group_id: int,
+    ) -> int:
+        """Resolve a plan name to its ID; pass numeric IDs through unchanged."""
+        if isinstance(plan, int):
+            return plan
+        if plan.isdigit():
+            return int(plan)
+
+        plans = self.list_service_plans(zone_id=zone_id, layout_id=layout_id, group_id=group_id)
+        for candidate in plans:
+            if candidate.get("name") == plan or candidate.get("code") == plan:
+                return int(candidate["id"])
+
+        available = ", ".join(sorted(str(p.get("name")) for p in plans)) or "none"
+        raise ValidationError(
+            f"Service plan {plan!r} not found for this type/zone. Available: {available}"
+        )
+
+    def _resolve_provision_pool(self, resource_pool: str | int | None, group: Group) -> str:
+        """Resolve the resource pool code, auto-selecting the only pool if needed."""
+        if isinstance(resource_pool, int):
+            return self._normalize_resource_pool_id(resource_pool)
+        if resource_pool is not None:
+            return self.get_resource_pool(
+                resource_pool, cloud_id=group.cloud_ids[0], group_id=group.id
+            ).code
+
+        pools = self.list_resource_pools(cloud_id=group.cloud_ids[0], group_id=group.id)
+        if not pools:
+            raise ValidationError(
+                f"Group '{group.name}' has no resource pool. Create a project first."
+            )
+        if len(pools) > 1:
+            names = ", ".join(sorted(p.name or p.code for p in pools))
+            raise ValidationError(
+                f"Group '{group.name}' has multiple resource pools; "
+                f"pass resource_pool=. Available: {names}"
+            )
+        return pools[0].code
+
     def _resolve_group(self, group: str | int) -> Group:
         """
         Resolve a group name or ID to a full Group object.

{mtn_cloud-0.3.1 → mtn_cloud-0.3.2}/tests/test_instances.py

@@ -5,6 +5,8 @@ from unittest.mock import MagicMock
 
 import pytest
 
+from mtn_cloud.exceptions import ValidationError
+from mtn_cloud.models.group import Group
 from mtn_cloud.models.instance import (
     Instance,
     InstanceCreate,
@@ -547,3 +549,111 @@ class TestInstancesResource:
             return pages.get(offset, {"instances": []})
 
         mock_http.get.side_effect = get_side_effect
+
+
+def _provision_group() -> Group:
+    """A group with one cloud/zone, for provision helper tests."""
+    return Group.model_validate({"id": 621, "name": "MTNNG_CLOUD_AZ_1", "zones": [{"id": 4}]})
+
+
+class TestProvision:
+    """Tests for the guided provision() helper and its resolvers."""
+
+    def test_resolve_plan_id_passes_int_through(self, resource: InstancesResource) -> None:
+        """A numeric plan is used directly without a lookup."""
+        assert resource._resolve_plan_id(6776, zone_id=4, layout_id=327, group_id=621) == 6776
+
+    def test_resolve_plan_id_by_name(
+        self, resource: InstancesResource, mock_http: MagicMock
+    ) -> None:
+        """A plan name resolves to its ID from the live plan list."""
+        mock_http.get.return_value = {
+            "plans": [{"id": 1, "name": "G1S1"}, {"id": 6776, "name": "G2S4"}]
+        }
+
+        assert resource._resolve_plan_id("G2S4", zone_id=4, layout_id=327, group_id=621) == 6776
+
+    def test_resolve_plan_id_unknown_lists_available(
+        self, resource: InstancesResource, mock_http: MagicMock
+    ) -> None:
+        """An unknown plan name raises with the available names."""
+        mock_http.get.return_value = {"plans": [{"id": 1, "name": "G1S1"}]}
+
+        with pytest.raises(ValidationError, match="G1S1"):
+            resource._resolve_plan_id("G99", zone_id=4, layout_id=327, group_id=621)
+
+    def test_resolve_pool_int_is_normalized(self, resource: InstancesResource) -> None:
+        """A numeric pool ID is normalized to its code with no lookup."""
+        assert resource._resolve_provision_pool(214, _provision_group()) == "pool-214"
+
+    def test_resolve_pool_auto_selects_single(
+        self, resource: InstancesResource, mock_http: MagicMock
+    ) -> None:
+        """With exactly one pool, it is auto-selected when none is given."""
+        mock_http.get.return_value = {
+            "data": [{"id": 230, "value": "pool-230", "name": "only-project"}]
+        }
+
+        assert resource._resolve_provision_pool(None, _provision_group()) == "pool-230"
+
+    def test_resolve_pool_multiple_requires_choice(
+        self, resource: InstancesResource, mock_http: MagicMock
+    ) -> None:
+        """With several pools and none given, the error lists them."""
+        mock_http.get.return_value = {
+            "data": [
+                {"id": 1, "value": "pool-1", "name": "alpha"},
+                {"id": 2, "value": "pool-2", "name": "beta"},
+            ]
+        }
+
+        with pytest.raises(ValidationError, match="alpha"):
+            resource._resolve_provision_pool(None, _provision_group())
+
+    def test_provision_dry_run_resolves_config(
+        self, resource: InstancesResource, mock_http: MagicMock
+    ) -> None:
+        """dry_run returns the resolved config without creating anything."""
+
+        def route(path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+            if path.startswith("/groups"):
+                return {"groups": [{"id": 621, "name": "MTNNG_CLOUD_AZ_1", "zones": [{"id": 4}]}]}
+            if path.startswith("/instance-types"):
+                return {
+                    "instanceTypes": [
+                        {
+                            "id": 1,
+                            "name": "CS10",
+                            "code": "MTN-CS10",
+                            "instanceTypeLayouts": [{"id": 327, "name": "single"}],
+                        }
+                    ]
+                }
+            if "service-plans" in path:
+                return {"plans": [{"id": 6776, "name": "G2S4"}]}
+            if "zonePools" in path:
+                return {"data": [{"id": 230, "value": "pool-230", "name": "my-project"}]}
+            raise AssertionError(f"Unexpected path: {path}")
+
+        mock_http.get.side_effect = route
+
+        config = resource.provision(
+            name="web-01",
+            type="MTN-CS10",
+            group="MTNNG_CLOUD_AZ_1",
+            plan="G2S4",
+            dry_run=True,
+        )
+
+        assert config == {
+            "name": "web-01",
+            "cloud": "MTNNG_CLOUD_AZ_1",
+            "type": "MTN-CS10",
+            "group": "MTNNG_CLOUD_AZ_1",
+            "layout": 327,
+            "plan": 6776,
+            "resource_pool_id": "pool-230",
+            "availability_zone": None,
+            "security_group": "default",
+        }
+        mock_http.post.assert_not_called()