# airec-instance

Part of **AIREC**

<!-- intent-backlink:auto -->

> 💡 **Path Selection**: This skill is one implementation path for the following routing skills. If you're unsure which path to take, check the corresponding routing skill:

> - [Troubleshoot AIRec deployment failures](../../intent/airec-troubleshoot-failure/SKILL.md)
> - [Deploy AIRec service](../../intent/airec-deploy-service/SKILL.md)

# AIRec Instance Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Add Nonstandard Machine Model | Synchronous | Register or add a nonstandard machine model to the system for deployment purposes. |

## API Calling Patterns

### Authentication
No authentication is required for the AIRec Instance Management APIs described in this skill. The endpoints can be accessed directly without API keys, tokens, or credentials.

> **Note**: These endpoints appear to be internal or intranet-facing (e.g., `zhuquenew.alibaba-inc.com`), intended for use within Alibaba Cloud's internal or Apsara Stack Agility environments. Public internet access may not be supported.

### Service Endpoint
The API uses direct HTTP GET requests to specific internal endpoints. There is no single standardized base URL across all deployments. Examples include:

- `http://apiServer address/addNonStandardMachineType`
- `http://zhuquenew.alibaba-inc.com/addNonStandardMachineType`

These endpoints are typically region-agnostic (`region: all`) and used within private networks. Replace placeholders like `apiServer address` with the actual internal server hostname provided by your Apsara Stack Agility deployment.

### Synchronous Request Pattern
The API follows a simple synchronous pattern:
1. Construct a GET request with all required parameters as query string arguments.
2. Send the request directly to the endpoint.
3. Receive an immediate response (success or failure) — though no explicit success response format is documented.

All parameters must be URL-encoded and passed in the query string. No request body is used.

## Parameter Reference

### Add Nonstandard Machine Model

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| cloudId | string | Yes | — | — | The cloud instance ID for the project |
| product | string | Yes | — | — | The product corresponding to the nonstandard model |
| feature | string | Yes | — | — | The feature corresponding to the nonstandard model |
| clusterType | string | Yes | — | — | The cluster type corresponding to the nonstandard model |
| serverRoleGroup | string | Yes | — | — | The server role group corresponding to the nonstandard model |
| machineType | string | Yes | — | — | The code for the nonstandard model, such as Q45.22 |
| os | string | No | — | — | The operating system of the nonstandard model |
| template | string | No | — | — | The template of the nonstandard model |

## Code Examples

### Add Nonstandard Machine Model - Bash - All Regions

```bash
curl "http://apiServer%20address/addNonStandardMachineType?cloudId=Cloud%20instance%20ID&product=ecs-blockstorage&feature=RiverHybrid&clusterType=RiverHybridCluster&serverRoleGroup=ChunkServer&machineType=N48.2B&os=AliOS5U7-x86-64&template=houyi_kvmserver_5u7_hybrid_private"
```

### Add Nonstandard Machine Model (Internal Endpoint) - Bash - All Regions

```bash
curl "http://zhuquenew.alibaba-inc.com/addNonStandardMachineType?cloudId=liantong_8c9f&product=ecs&feature=controller&clusterType=Basic&serverRoleGroup=srgroup&machineType=Q46.22&os=AliOS6U2-x86-64&template=houyi_kvmserver_5u7_hybrid_private"
```

> **Note**: Replace `apiServer address` with the actual internal hostname. Spaces in URLs (as shown in raw examples) must be percent-encoded (`%20`) when used with `curl` or other HTTP clients.

### Python Example Using Requests

```python
import requests

params = {
    "cloudId": "liantong_8c9f",
    "product": "ecs",
    "feature": "controller",
    "clusterType": "Basic",
    "serverRoleGroup": "srgroup",
    "machineType": "Q46.22",
    "os": "AliOS6U2-x86-64",
    "template": "houyi_kvmserver_5u7_hybrid_private"
}

response = requests.get(
    "http://zhuquenew.alibaba-inc.com/addNonStandardMachineType",
    params=params
)
print(response.status_code)
print(response.text)
```

### Java Example Using HttpURLConnection

```java
import java.net.*;
import java.io.*;

public class AddNonstandardModel {
    public static void main(String[] args) throws Exception {
        String url = "http://zhuquenew.alibaba-inc.com/addNonStandardMachineType" +
            "?cloudId=liantong_8c9f" +
            "&product=ecs" +
            "&feature=controller" +
            "&clusterType=Basic" +
            "&serverRoleGroup=srgroup" +
            "&machineType=Q46.22" +
            "&os=AliOS6U2-x86-64" +
            "&template=houyi_kvmserver_5u7_hybrid_private";

        URL obj = new URL(url);
        HttpURLConnection con = (HttpURLConnection) obj.openConnection();
        con.setRequestMethod("GET");

        int responseCode = con.getResponseCode();
        System.out.println("Response Code: " + responseCode);

        BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
        String inputLine;
        StringBuilder response = new StringBuilder();
        while ((inputLine = in.readLine()) != null) {
            response.append(inputLine);
        }
        in.close();
        System.out.println(response.toString());
    }
}
```

## Error Handling

No specific error codes are documented for this API. Given the internal nature of the endpoints, errors may manifest as:
- HTTP 4xx/5xx responses from the server
- Connection timeouts or DNS resolution failures if the internal hostname is unreachable
- Missing or invalid parameter errors (likely returning HTTP 400)

Always validate that all required parameters (`cloudId`, `product`, `feature`, `clusterType`, `serverRoleGroup`, `machineType`) are provided and properly URL-encoded.

## FAQ

Q: Do I need an API key or authentication token to use these endpoints?
A: No. The documented endpoints do not require any authentication headers or credentials. However, they are likely only accessible from within Alibaba Cloud's internal network or Apsara Stack Agility environments.

Q: Why does the example URL contain spaces like "apiServer address"?
A: That is a placeholder meant to be replaced with an actual hostname (e.g., `airec-api.internal`). In real usage, the hostname must be a valid DNS name or IP address with no spaces.

Q: Can I use POST instead of GET?
A: Based on the documentation, only GET requests with query parameters are supported. There is no indication that POST or JSON bodies are accepted.

Q: What happens if I omit optional parameters like `os` or `template`?
A: The request may still succeed if the backend has defaults for those fields, but behavior is not guaranteed. Include them if your deployment requires specific OS or template configurations.

Q: Are these APIs available on the public internet?
A: Unlikely. The example domains (e.g., `zhuquenew.alibaba-inc.com`) suggest internal Alibaba usage. For public cloud equivalents, consult the official Alibaba Cloud AIRec public API documentation.

## Pricing & Billing

### Billing Model
This functionality is provided at no cost as part of the Apsara Stack Agility infrastructure management layer.

### Free Tier
Not applicable — the service is free to use within supported deployments.

### Usage Limits
No usage limits or quotas are documented for this internal API.