docs: add templates, cgroups, listing, and metrics to instances

[JeromeJaggi]

Summary

Extends the instances page with several new reference sections.

What's included

• Instance templates: snapshotted instances as reusable clone sources, nested templates, template state immutability
• Linux cgroups support: clone3() + CLONE_INTO_CGROUP for resource isolation
• Listing: filtering by state/tag, sort order, pagination
• Creating instances: replicas field, timeout_s wait-for-running, delete-on-stop feature flag
• Stopping instances: drain_timeout_ms with behaviour table
• Instance metrics: endpoint reference with full JSON field table

Source verification

Content verified against the Unikraft Cloud REST API (/v1/instances, /v1/instances/templates) and platform implementation.

[dosubot]

Related Documentation

1 document(s) may need updating based on files changed in this PR:

Unikraft's Space

Pagination in Unikraft Cloud

View Suggested Changes

@@ -1,11 +1,13 @@
-The Unikraft Cloud Platform HTTP Instances API supports cursor-based pagination for listing instances. This allows clients to efficiently retrieve large sets of instances in manageable pages, using UUIDs as cursors. The API endpoint for listing instances is `/v1/instances` (sometimes `/instances` in documentation and OpenAPI specs) and requires bearer token authentication via the `Authorization: Bearer <token>` header [source](https://github.com/unikraft-cloud/openapi/blob/3ad398956ba262a9cae627a8baad93eed4c108bc/platform.yaml#L220-L2527).
+The Unikraft Cloud Platform HTTP API supports offset-based pagination for listing resources. This allows clients to efficiently retrieve large sets of resources in manageable pages using page numbers. The pagination model applies to all list endpoints: instances (`/v1/instances`), volumes, service groups, images, and certificates. All endpoints require bearer token authentication via the `Authorization: Bearer <token>` header [source](https://github.com/unikraft-cloud/openapi/blob/3ad398956ba262a9cae627a8baad93eed4c108bc/platform.yaml#L220-L2527).
 
 ## Pagination Parameters
 
 Pagination is controlled by two main query parameters:
 
-- `count`: Specifies the maximum number of instances to return in the response (i.e., the page size). If omitted, all instances are returned.
-- `from_uuid`: Specifies the UUID from which to start listing instances. This acts as a cursor for pagination. If omitted, listing starts from the beginning of the instance list [source](https://github.com/unikraft-cloud/platform/blob/0443d73fe6a3e7cb8e4c8cd57c9ed5e603bbf276/src/api/http/v1/instances/status.c#L30-L840).
+- `page`: Specifies which page of results to return. Page numbering starts from 1. If omitted, the first page is returned.
+- `per_page`: Specifies the maximum number of items to return per page (i.e., the page size). If omitted, a default page size is used.
+
+To navigate through results, increment the `page` parameter while keeping `per_page` constant. For example, use `page=1&per_page=10` for the first page, then `page=2&per_page=10` for the second page, and so on.
 
 Additional useful parameters include:
 
@@ -13,39 +15,39 @@
 - `tags`: Comma-separated list of tags to filter instances.
 - `metrics`: Boolean (default: false). If true, includes metrics in the response.
 
-## Pagination Conditions
+## How Pagination Works
 
-Pagination is activated when the `count` parameter is provided. If `from_uuid` is also specified, the API returns up to `count` instances starting after the given UUID. If multiple instance IDs are provided (via `uuid` or `name`) and `count` is specified, the API returns an error due to an invalid query combination [source](https://github.com/unikraft-cloud/platform/blob/0443d73fe6a3e7cb8e4c8cd57c9ed5e603bbf276/src/api/http/v1/instances/status.c#L30-L840).
+When using pagination, the API returns only the requested page of results based on the `page` and `per_page` parameters. Each page contains up to `per_page` items, and you can navigate between pages by changing the `page` number.
 
-The response does not include explicit pagination metadata (such as a next cursor). To fetch the next page, use the UUID of the last instance in the current response as the new `from_uuid` value.
+If you do not specify pagination parameters, the API may return all results or use a default page size, which could be inefficient for large datasets. Always use pagination when working with potentially large result sets.
 
 ## Example: Paginated Listing with curl
 
-To list the first page of instances (e.g., 5 per page):
+To list the first page of instances (e.g., 10 per page):
 
 ```sh
-curl -X GET "https://api.unikraft.cloud/v1/instances?count=5" \
+curl -X GET "https://api.unikraft.cloud/v1/instances?page=1&per_page=10" \
      -H "Authorization: Bearer <your_token>"
 ```
 
-To fetch the next page, use the UUID of the last instance from the previous response:
+To fetch the next page:
 
 ```sh
-curl -X GET "https://api.unikraft.cloud/v1/instances?count=5&from_uuid=<last_uuid>" \
+curl -X GET "https://api.unikraft.cloud/v1/instances?page=2&per_page=10" \
      -H "Authorization: Bearer <your_token>"
 ```
 
 To filter by tags and return only basic identifiers:
 
 ```sh
-curl -X GET "https://api.unikraft.cloud/v1/instances?count=5&tags=web,prod&details=false" \
+curl -X GET "https://api.unikraft.cloud/v1/instances?page=1&per_page=10&tags=web,prod&details=false" \
      -H "Authorization: Bearer <your_token>"
 ```
 
 To include metrics in the response:
 
 ```sh
-curl -X GET "https://api.unikraft.cloud/v1/instances?count=5&metrics=true" \
+curl -X GET "https://api.unikraft.cloud/v1/instances?page=1&per_page=10&metrics=true" \
      -H "Authorization: Bearer <your_token>"
 ```
 
@@ -68,7 +70,7 @@
         "tags": ["web", "prod"]
         // ... other fields if details=true
       }
-      // ... up to 'count' instances
+      // ... up to 'per_page' instances
     ]
   }
 }
@@ -77,8 +79,9 @@
 
 ## Notes
 
-- Always use the last instance's UUID from the current page as the `from_uuid` for the next page.
-- If you do not specify `count`, the API returns all instances, which may be inefficient for large datasets.
+- Use the `page` parameter to navigate between pages, incrementing it by 1 for each subsequent page.
+- Keep the `per_page` value consistent across requests to ensure predictable pagination behavior.
+- If you do not specify pagination parameters, the API behavior depends on the endpoint defaults, which may be inefficient for large datasets.
 - Filtering and detail level can be controlled with `tags` and `details` parameters.
 - The API requires a valid bearer token for authentication.
 

[Accept] [Decline]

Note: You must be authenticated to accept/decline updates.

^{How did I do? Any feedback?}  

[JeromeJaggi]

@marcrittinghaus
@victorduta
@mdaria11