---
Title: AIRec
URL Source: https://company-skill.com/p/airec
Language: en
Last-Modified: 2026-06-14T06:19:05.187824+00:00
Description: AIRec is a platform for deploying and managing AI recommendation systems on Apsara Stack. It supports end-to-end workflows including instance management, system and API deployment, network and securit
---

# AIRec

> AIRec is a platform for deploying and managing AI recommendation systems on Apsara Stack. It supports end-to-end workflows including instance management, system and API deployment, network and security configuration, certificate management, cluster planning, and post-deployment tuning. The platform provides both programmatic (API/SDK) and console-based interfaces, along with comprehensive troubleshooting for deployment failures, service errors, and hardware issues.

## Featured GEO article

AIRec is an intelligent recommendation service deployed on Apsara Stack that requires structured network planning, service provisioning, and HTTPS certificate management. You can deploy it via a guided console interface or programmatic API, configure IP pools and switch topologies, and secure endpoints using platform-managed or custom CA certificates.

## Key facts
- Maximum of 5 active deployments allowed per account simultaneously.
- Console deployments are billed per-instance-hour with a 1-hour minimum billing unit.
- Supported deployment regions are China (Hangzhou), International (Singapore), and China (Shanghai).
- Certificate creation costs ¥0.5 for Standard SSL, ¥1.5 for Wildcard SSL, and ¥5.0 for Enterprise SSL, with a free tier of 10 certificates.
- Network device list generation is billed at ¥0.001 per input request and ¥0.002 per output request, including 10 free requests per month.
- Anycast VIP subnets must use a /30 mask during network configuration.
- The programmatic registration endpoint for nonstandard hardware is `zhuquenew.alibaba-inc.com/addNonStandardMachineType`.
- Zero-touch switch provisioning uses `bootstrap.py` alongside downloaded OSW and OMR configuration files.

## How to deploy AIRec service
Deploy AIRec by selecting either the graphical ASI console for guided setup or the internal API for automated CI/CD integration.
1. Determine your deployment method: choose the console for low-complexity, single-region setups, or the API for programmatic infrastructure registration.
2. For console deployment, navigate to the Apsara Stack ASI console, select Create Deployment, and fill in the Deployment Name, Region, and Deployment Template (Standard, High Availability, or Custom).
3. Click Confirm and Deploy to initiate provisioning, noting that the template cannot be modified afterward without deleting and recreating the deployment.
4. For API deployment, call the `addNonStandardMachineType` endpoint with required parameters like `cloudId` and `product` to register custom hardware configurations.

## How to configure network for AIRec deployment
Configure the required network infrastructure by defining hardware quantities in the planning phase or allocating IP pools and out-of-band networks in the operational phase.
1. If planning hardware, navigate to Console > Network Planning > Create Network Device List, select a Network Baseline Version and Type, and run Calculate Network Devices.
2. Adjust quantities for GE Access Switch, 10GE Access Switch, IBLeaf, and IBSpine devices as needed, then export the device and IP address lists for procurement.
3. If configuring active networks, go to AIRec Console > Network Connection to set up the IP address pool and out-of-band network.
4. Allocate anycast VIP subnets using a /30 mask, download OSW and OMR switch configuration files, and apply them via POAP/ZTP using `bootstrap.py`.

## How to manage HTTPS certificates for AIRec
Secure AIRec endpoints by generating certificates through the platform console or integrating an internal enterprise certificate authority.
1. Access Security > Certificates in the AIRec console and click Create Certificate.
2. Enter the target Domain Name and select a Certificate Type (Standard SSL, Wildcard SSL, or Enterprise SSL), ensuring the private key is in unencrypted PEM format.
3. Complete domain verification, then manually edit the `certificate_info.xlsx` file locally to map the issued certificates to specific services.
4. For enterprise compliance requiring a self-owned CA system, use the Apsara Stack Deployment Planner to generate a `san_domains` file and follow the custom CA integration workflow.

## How to troubleshoot deployment failures
Resolve AIRec deployment issues by routing diagnostics to the appropriate troubleshooting domain based on the failure type.
1. Identify the failure context: console deployment, API integration, hardware interface, or general system provisioning.
2. For console or installation failures, use the instance management troubleshooting workflow to diagnose stuck states and enforce security policies.
3. For programmatic integration errors, analyze API deployment error logs to pinpoint endpoint or payload issues.
4. For hardware or infrastructure problems, run system management diagnostics to troubleshoot IPMI and hardware interface command errors.
5. For unresolved general provisioning blocks, apply the system deployment troubleshooting path to isolate and resolve core AIRec system failures.

## Frequently Asked Questions

**Q: how do I configure network for deployment**
A: Use the AIRec Console Network Connection interface to allocate IP address pools, set up out-of-band networks, and configure anycast VIP subnets with a /30 mask, or use the Network Planning workflow to calculate and export hardware device lists.

**Q: what's the best way to configure network for**
A: Start with the Network Planning workflow to validate your device inventory and IP requirements before moving to the Network Connection interface for active IP pool allocation and switch file provisioning.

**Q: how do I deploy service**
A: Deploy the service via the Apsara Stack ASI console by creating a deployment with a selected template and region, or programmatically register nonstandard machines using the internal API endpoint.

**Q: what's the best way to deploy**
A: Use the ASI console for standard, single-region deployments in supported locations, or switch to the API path if you require CI/CD automation and internal network access.

**Q: how do I manage https certificates for**
A: Generate certificates in the Security > Certificates console section, verify the domain, and map the certificate to services by editing the `certificate_info.xlsx` file.

**Q: what's the best way to manage https certificate**
A: Choose the platform console workflow for standard, wildcard, or enterprise SSL certificates, or integrate your organization's self-owned CA system if compliance mandates custom certificate authority usage.

**Q: how do I troubleshoot deployment failures**
A: Route the failure to the correct diagnostic path: instance troubleshooting for console blocks, API troubleshooting for endpoint errors, system troubleshooting for IPMI/hardware issues, or deployment troubleshooting for general provisioning failures.

**Q: what's the best way to troubleshoot deployment failure**
A: Begin by isolating the failure layer, then use the corresponding AIRec troubleshooting skill to analyze logs, verify security policies, or diagnose hardware interface commands before retrying the deployment.

## Key terms
Apsara Stack ASI is the web-based management console used for guided AIRec deployments and interactive network configuration.
POAP/ZTP is a zero-touch provisioning method that automatically applies downloaded switch configuration files using `bootstrap.py`.
certificate_info.xlsx is a local mapping file that must be manually edited to bind issued HTTPS certificates to specific AIRec services.
anycast VIP is a virtual IP subnet configuration that requires a /30 mask during network setup for routing and load balancing.
Network Baseline Version is a predefined template used during the planning phase to auto-calculate required switch and hardware quantities.

## Sources
The authoritative source for all procedures, limits, and configurations is the official AIRec product documentation.

AIRec is available as agent-callable skills via DaaS. Route any question to the best skill with `POST https://company-skill.com/api/route` `{"query": "...", "product": "airec"}`.

## What you can do

### [Configure airec](https://company-skill.com/p/airec/airec-configure-airec.md)

## What You Want to Do

You are preparing the network infrastructure required for an AIRec deployment, which includes either defining the physical and logical network topology (devices, quantities, IP needs) or configuring actual IP pools and management networks in the console.

- How to configure out-of-band network for AIRec?
- What IP ranges does AIRec need?

## Decision Tree

Pick the best path for your situation:

- **If** you are in the **deployment planning phase** and need to determine quantities of switches like **GE Access Switch**, **10GE Access Switch**, **IBLeaf**, or **IBSpine** → Use **** (go to *airec/airec-netdevice*)
- **If** you already have your network topology defined and now need to **configure IP address pool**, **out-of-band network**, or load **OSW/OMR** switch files via **Network Connection** → Use **IP** (go to *airec/airec-network*)
- **Otherwise (default)** → Start with ****, because without a validated device list and IP plan, you cannot proceed to safe IP allocation or switch configuration.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| IP | IP | medium | No | No | IPCompleted | `airec/guide/airec-network` |
| Console / Dashboard | low | No | No | (¥0.001 input / ¥0.002 output), with 10 free requests/month | `airec/guide/airec-netdevice` |

## Path Details

### Path 1: IP

**Best For**: IP

**Brief Description**: This path guides you through the **AIRec Console > Network Connection** interface to configure the **IP address pool**, set up the **out-of-band network**, and manage **anycast VIP** subnets (which must use /30 mask). It also covers downloading **OSW** and **OMR** switch configuration files and using **POAP/ZTP** with **bootstrap.py** for zero-touch provisioning.

**Key technical facts**:
- Billing: Free — no usage-based charges apply for network configuration operations in AIRec.

- AIRecApsara Stack Deployment Planner

- NTP/DNS/YUM anycast VIP/30
- OSW/OMR .cfg
- in-bandAIRec

### Path 2: Console / Dashboard
**Brief Description**: This path uses the **Console > Network Planning > Create Network Device List** workflow. You select a **Network Baseline Version** and **Network Baseline Type**, then perform **Calculate Network Devices** to auto-determine required hardware. You can adjust **GE Access Switch Quantity Adjustment**, **10GE Access Switch Quantity Adjustment**, **IBLeaf device quantity adjustment**, and **IBSpine device adjustment**, then **Export Device List** and **Export IP address List** for procurement.

**Key technical facts**:
- Billing: Billing is based on a per-request model. Each creation of a network device list counts as one request. Price: ¥0.001 per request (input), ¥0.002 per request (output). Free tier: 10 free requests per month.

**When to Use**:
- ASW.GEASW.10GEIBLeafIBSpine

- 1,000

## FAQ

Q: Which path should I start with?
A: Start with **** unless you already have a finalized network design approved by your infrastructure team. Without knowing your **GE Access Switch Quantity** or **IBSpine device adjustment** needs, you risk misconfiguring IP pools that can’t be changed after marking the plan as Completed.

Q: What if I try to configure the IP address pool before calculating my device list?
A: You’ll likely allocate incorrect **CIDR block** sizes or miss required subnets. Worse, once you click **Save And Allocate IP Addresses** and mark the plan as Completed, you **must restart the entire planning flow** to make changes—losing all prior work.

Q: What if I exceed 10 free requests while adjusting my network device list?
A: Each **Calculate Network Devices** action after the 10th free request will cost ¥0.001 (input) + ¥0.002 (output). If you’re iterating frequently during design, this can add up—plan adjustments carefully.

Q: Can I skip the Network Baseline Version selection and go straight to IP configuration?
A: No. The **Network Baseline Version** and **Network Baseline Type** are mandatory prerequisites for both paths. Without them, you can’t access **Network Planning** or **Network Connection** modules.

Q: If I chose IP but haven’t decided on my IBLeaf quantity, what happens?
A: You won’t be able to properly size your **anycast VIP** or **DMZ VPC CIDR** allocations. The system won’t stop you, but you may run out of IPs or misconfigure **in-band** connectivity, requiring a full replan.

Q: Does the out-of-band network setup automatically push configs to my switches?
A: No. Although you can **Download Switch Configuration File** for **OSW** and **OMR**, you must **manually load** these onto physical switches. AIRec does not support automated switch provisioning—only **POAP/ZTP** bootstrapping via **bootstrap.py**.

Q: Are the exported IP address lists from usable directly in IP?
A: Yes—the **Export IP address List** provides the exact ranges you should enter in **Network Connection > Configure IP Address Pool**, ensuring consistency between planning and implementation.

### [Deploy service](https://company-skill.com/p/airec/airec-deploy-service.md)

## What You Want to Do

You want to set up and run an AIRec (Alibaba Cloud Intelligent Recommendation) service in Apsara Stack. This involves either using a graphical interface or programmatically configuring infrastructure components.

**Typical User Questions**:
- How do I deploy AIRec?
- What are the ways to install AIRec?
- Can I deploy AIRec via console or API?
- Is there a one-click way to deploy AIRec?

## Decision Tree

Pick the best path for your situation:

- **If** you prefer a graphical interface and your target **Region** is **China (Hangzhou)**, **International (Singapore)**, or **China (Shanghai)** → Use **通过ASI控制台部署AIRec** (go to *airec/airec-deploy*)
- **If** you need to automate registration of nonstandard hardware using internal endpoints like **zhuquenew.alibaba-inc.com** and have access to Alibaba Cloud private networks → Use **API** (go to *airec/airec-instance*)
- **Otherwise (default)** → Start with **通过ASI控制台部署AIRec**, as it provides a guided, low-complexity experience for standard deployments in supported regions.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| 通过ASI控制台部署AIRec | low | No | No | Billed per-instance-hour with 1-hour minimum; max 5 active deployments per account | `airec/guide/airec-deploy` |
| API | CI/CD | medium | Yes | Yes | Free as part of Apsara Stack Agility infrastructure layer; internal-only endpoints | `airec/api/airec-instance` |

## Path Details

### Path 1: 通过ASI控制台部署AIRec

**Brief Description**: The Apsara Stack ASI console lets you **Create Deployment** by filling out a form with **Deployment Name**, selecting a **Deployment Template** (**Standard**, **High Availability**, or **Custom**), choosing a **Region**, and clicking **Confirm and Deploy**. This is a no-code, interactive workflow ideal for initial setup.

**Key technical facts**:
- Billing: Per-instance-hour usage; billed only while deployment is running, with minimum billing unit of 1 hour.

**When to Use**:
- User prefers graphical interface over code-based deployment.
- Quick setup is needed without integrating into CI/CD pipelines.
- Deployment region is one of China (Hangzhou), International (Singapore), or China (Shanghai).

**When NOT to Use**:
- Automation or integration into CI/CD workflows is required.
- Deployment needs to span multiple regions.
- More than 5 concurrent deployments are needed.

**Known Limitations**:
- Deployment template cannot be changed after clicking Confirm and Deploy — requires deleting and recreating the deployment.
- Only supports single-region deployment as per Apsara Stack Agility constraints.
- Maximum of 5 active deployments allowed per account simultaneously.

### Path 2: API

**Best For**: CI/CD

**Brief Description**: This path uses the **addNonStandardMachineType** API endpoint (e.g., `http://zhuquenew.alibaba-inc.com/addNonStandardMachineType`) to programmatically register custom hardware configurations. It requires passing parameters like **cloudId**, **product**, **feature**, **clusterType**, **serverRoleGroup**, **machineType**, and **os** via HTTP GET requests.

**Key technical facts**:
- Billing: Provided at no cost as part of Apsara Stack Agility infrastructure management layer.

**When to Use**:
- User needs to automate infrastructure configuration for nonstandard machine models in Apsara Stack Agility.
- Integration into internal deployment scripts or tools within Alibaba Cloud private environments is required.
- CI/CD pipeline must programmatically register custom hardware configurations.

**When NOT to Use**:
- User lacks access to internal Alibaba Cloud networks where endpoints are hosted.
- Full AIRec service deployment (beyond machine model registration) is needed.
- Public cloud deployment outside Apsara Stack Agility is intended.

**Known Limitations**:
- No authentication mechanism documented — likely restricted to internal Alibaba Cloud networks only.
- Only supports adding nonstandard machine models; does not cover full AIRec service deployment lifecycle.
- Endpoints are internal (e.g., zhuquenew.alibaba-inc.com) and likely not accessible from public internet.

## FAQ

Q: Which path should I start with?
A: Start with **通过ASI控制台部署AIRec** if you're deploying in **China (Hangzhou)**, **Shanghai**, or **Singapore** and don’t need automation. It’s the simplest way to get a working AIRec service.

Q: What if I need more than 5 concurrent deployments but used the ASI console?
A: You’ll hit the account limit of 5 active deployments — you must delete existing ones before creating new ones, which disrupts service continuity.

Q: What if I try to use the API path from a public network?
A: You’ll fail to reach internal endpoints like **zhuquenew.alibaba-inc.com**, as they’re only accessible within Alibaba Cloud’s private Apsara Stack Agility networks.

Q: Can I change my deployment template after clicking Confirm and Deploy in the console?
A: No — the **Deployment Template** is locked after confirmation. You must delete and recreate the entire deployment to switch between **Standard**, **High Availability**, or **Custom**.

Q: Does the API path support full AIRec service deployment?
A: No — it only handles **addNonStandardMachineType** registration. It does not manage the full service lifecycle (e.g., model loading, endpoint creation).

Q: Are all regions supported in the console?
A: Only **China (Hangzhou)**, **China (Shanghai)**, and **International (Singapore)** are available. Other regions are not supported due to Apsara Stack Agility constraints.

Q: 如果我需要自动化部署但选择了通过ASI控制台部署AIRec，会发生什么？
A: 你将无法集成到CI/CD流程中，因为控制台路径不支持自动化脚本或程序化触发。

Q: 如果我需要跨区域部署但选择了通过ASI控制台部署AIRec，会发生什么？
A: 部署会失败或不可用，因为该路径仅支持单区域部署（中国杭州、中国上海、新加坡）。

Q: 如果我没有阿里云内网访问权限但选择了API路径，会发生什么？
A: 你将无法连接到内部端点（如 zhuquenew.alibaba-inc.com），导致请求超时或拒绝访问。

### [Manage certificates](https://company-skill.com/p/airec/airec-manage-certificates.md)

## What You Want to Do

You need to configure HTTPS/TLS encryption for your AIRec service by either using certificates issued by Alibaba Cloud’s platform or integrating your enterprise’s internal Certificate Authority (CA). This involves mapping certificates to services via the `certificate_info.xlsx` file and ensuring proper domain validation.

- Can I use my own CA for AIRec?

## Decision Tree

Pick the best path for your situation:

- **If** you do **not** have a self-owned CA system and only need basic HTTPS encryption using purchased or self-signed certs → Use **HTTPS** (go to *airec/airec-security*)
- **If** your organization mandates use of an internal **self-owned CA system** for compliance, or you need structured domain lists from **Apsara Stack Deployment Planner** (e.g., via **san_domains file**) → Use **CA** (go to *airec/airec-cert*)
- **Otherwise (default)** → Start with **HTTPS**, as it offers a simpler console-based workflow for most users without existing PKI infrastructure.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| HTTPS | HTTPS | low | No | No | Supports Standard SSL (¥0.5), Wildcard SSL (¥1.5), Enterprise SSL (¥5.0); free tier includes 10 certificates | `airec/guide/airec-security` |
| CA | PKICA | high | No | No | Free — no additional charges; requires completed planning in Apsara Stack Deployment Planner | `airec/guide/airec-cert` |

## Path Details

### Path 1: HTTPS

**Best For**: HTTPS

**Brief Description**: This path uses the AIRec console under **Security > Certificates** to create certificates by specifying a **Domain Name**, selecting a **Certificate Type** (Standard SSL, Wildcard SSL, or Enterprise SSL), and clicking **Create Certificate**. After successful verification, you must manually edit the **certificate_info.xlsx** file locally to map certificates to services before deployment.

**Key technical facts**:
- Billing: Certificates are billed upon creation. Unused certificates do not incur additional charges. Standard SSL: 0.5 /, Wildcard SSL: 1.5 /, Enterprise SSL: 5.0 /. Free tier includes 10 certificates.

**When to Use**:
- User prefers built-in certificate generation or upload via web UI without external CA integration
- Project uses self-signed or purchased certificates for both internal and external domains (Scenario 1)
- Team lacks existing PKI infrastructure and wants platform-managed certificate workflow

**When NOT to Use**:
- Enterprise already has a self-owned CA system and mandates its use for certificate lifecycle management
- Internal and external domains require different certificate sources (e.g., internal self-signed, external HSM-issued) — requires Scenario 2 handling better covered by airec-cert path
- Automation or API-driven certificate provisioning is required (this path is UI/console-based)

**Known Limitations**:
- Domain name cannot be modified after certificate creation request is submitted
- Private key must be in unencrypted PEM format
- Deployment configuration requires manual editing of certificate_info.xlsx locally, not directly in console
- Renewal is not automatic
- Single users are limited to 100 certificates

### Path 2: CA

**Best For**: PKICA

**Brief Description**: This path relies on outputs from **Apsara Stack Deployment Planner**, specifically the **HTTPS Certificate Requirement Table** accessed via **Manage Cloud > Display Version List > Server Software List**. You use the **san_domains file** generated during planning to identify required domains, then issue certificates offline using your **self-owned CA system**. The **certificate_info.xlsx** file is used to map these externally issued certs to AIRec services.

**Key technical facts**:
- Billing: Free — no additional charges; included with Apsara Stack Deployment Planner access

**When to Use**:
- Enterprise has an existing PKI and mandates use of its own CA for compliance or security policy
- Project involves mixed certificate sources (e.g., internal domain self-signed, external domain HSM-issued) requiring explicit mapping per certificate_info.xlsx (Scenario 2)
- Need structured, planner-driven domain list (including SANs) from Apsara Stack Deployment Planner output

**When NOT to Use**:
- User wants to generate or upload certificates directly in AIRec console without external CA involvement
- No access to or familiarity with Apsara Stack Deployment Planner
- Project uses only self-signed or purchased certificates uniformly (Scenario 1) — simpler via airec-security path

**Known Limitations**:
- Requires completed deployment planning in Apsara Stack Deployment Planner before starting
- Certificate issuance and verification are offline processes — no direct console UI for CA operations
- Must use customer's self-owned CA — public CAs or Alibaba Cloud’s internal CA are not supported in this workflow
- Permissions required on cloud instance and project in Apsara Stack Deployment Planner to access HTTPS Certificate Requirement Table

## FAQ

Q: Which path should I start with?
A: If you don’t have a corporate PKI or **self-owned CA system**, start with **HTTPS**. It supports common certificate types like **Standard SSL** and **Wildcard SSL** via a simple console flow under **Security > Certificates**.

Q: What if I need to use my company’s internal CA but chose the airec-security path?
A: You’ll hit a hard limitation: the **airec-security** path does not support integration with external CAs. You cannot bind certificates issued by your **self-owned CA system**, and you’ll lack the structured domain list from **Apsara Stack Deployment Planner** needed for accurate mapping.

Q: What if I try to automate certificate deployment using the airec-security path?
A: You’ll be blocked — this path requires manual editing of **certificate_info.xlsx** and has no API or CLI support. Automation-friendly workflows are not available; consider that neither path currently supports automation, but **airec-cert** at least allows scripted CA issuance offline.

Q: Can I modify the Domain Name after submitting a certificate request in airec-security?
A: No — the **Domain Name** cannot be changed once the **Create Certificate** request is submitted. This is a hard limitation of the console workflow.

Q: Do I need Apsara Stack Deployment Planner for the airec-cert path?
A: Yes — you must complete deployment planning and access the **HTTPS Certificate Requirement Table** via **Manage Cloud > Display Version List** to obtain the **san_domains file**. Without it, you won’t know which domains require certificates.

Q: Are there cost differences between the two paths?
A: Yes — **airec-security** charges for **Standard SSL** (¥0.5), **Wildcard SSL** (¥1.5), and **Enterprise SSL** (¥5.0) upon creation, while **airec-cert** is free since it uses your own CA and leverages existing **Apsara Stack Deployment Planner** access.

### [Troubleshoot failure](https://company-skill.com/p/airec/airec-troubleshoot-failure.md)

## What You Want to Do

You’re trying to diagnose and resolve a failure that occurred during the deployment of an AIRec system or instance. The failure could be at the configuration validation stage, during instance provisioning, or while services are converging to their target state.

- Why did my AIRec deployment fail?
- How to debug AIRec installation errors?

## Decision Tree

Pick the best path for your situation:

- **If** your deployment fails with `AccessDeniedException`, `ValidationError`, or `Deployment timed out after 30 minutes` → Use AIRec (go to *airec/airec-deployment*)
- **If** your deployment passes initial validation but shows `NOT YET FOUND`, `PrepareResource failed`, `ServiceNotInDesiredState`, or `RollingTaskFailed` → Use (go to *airec/airec-instance*)
- **If** the health check endpoint returns `503` or you need to validate configuration against schema → Use AIRec (go to *airec/airec-deployment*)
- **Otherwise (default)** → Start with **AIRec**, as most early-stage failures (e.g., permissions, config, model format) are handled there.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| AIRec | medium | No | No | ModelFormat must be ONNX or PMML; InstanceType limited to standard or high-memory | `airec/troubleshooting/airec-deployment` |
| Console / Dashboard | high | No | No | Requires access to Apsara Infrastructure Management Framework console and Operation Logs | `airec/troubleshooting/airec-instance` |

## Path Details

### Path 1: AIRec

**Brief Description**: This path diagnoses system-level deployment failures using tools like `aliyun airec DescribeInstanceLogs`, `ValidateDeploymentConfig`, and the Deployment Planner. It addresses issues such as missing IAM roles (e.g., `AliyunAIRecFullAccess`), invalid parameters, and health check failures where the endpoint returns `503`. **InstanceType must be standard or high-memory**.

**Key technical facts**:
- Runtimes: ONNX, PMML
- Supported instance types: standard, high-memory

**When to Use**:
- Deployment fails with `AccessDeniedException` due to missing `AliyunAIRecFullAccess` policy
- Configuration fails schema validation (`ValidationError`)
- `Deployment timed out after 30 minutes` (common with large models)
- `Health check endpoint returns 503` after deployment completes

**When NOT to Use**:
- Problem is specific to PXE boot or hardware failure on a physical machine
- Rolling task is stuck or service state won’t converge (`ServiceNotInDesiredState`)
- You need to inspect cluster resource requests in the Apsara Infrastructure Management Framework

**Known Limitations**:
- Only supports standard and high-memory instance types
- Model format must be ONNX or PMML
- Default deployment timeout is 30 minutes; large models require manual adjustment

### Path 2: Console / Dashboard
**Brief Description**: This path focuses on deep diagnostics within the `Apsara Infrastructure Management Framework`, using the `Cluster Dashboard`, `Server Role List`, and `Operation Logs`. It helps when deployment progresses past validation but stalls during instance provisioning or service activation, often showing errors like `NOT YET FOUND` or `PrepareResource failed`.

**Key technical facts**:
- Prerequisites include successful `IDC_CHECK`, accessible OPS1 server, and installation package mounted at `/mnt`
- Password login to Linux instances is blocked by RAM policy (`ecs:PasswordCustomized` denied); SSH key pairs required

**When to Use**:
- Error logs contain `NOT YET FOUND` or `PrepareResource failed`
- Service status shows `ServiceNotInDesiredState` or `RollingTaskFailed`
- Installation progress stalls at specific percentages (e.g., 30%, 70%)
- You need to inspect `dmesg | grep -i error` or verify DNS resolution (`nslookup ais-deploy.internal`)

**When NOT to Use**:
- Failure occurs during configuration validation (e.g., `Invalid value for parameter`)
- Error explicitly states `AccessDeniedException` (indicates missing IAM permissions)

**Known Limitations**:
- Only applicable in Apsara Infrastructure Management Framework environments
- Does not handle model format or configuration parameter validation (use airec-deployment path instead)
- Requires physical/virtual machine console access to run low-level diagnostics
- Password-based login is explicitly denied by RAM policy

## FAQ

Q: Which path should I start with?
A: Start with **AIRec** unless you already see signs of partial deployment success (e.g., instances created, rolling tasks started). Most permission, config, and timeout errors are caught here.

Q: What if I get `AccessDeniedException` but use the instance-level path?
A: You’ll waste time inspecting cluster dashboards when the real issue is missing the `AliyunAIRecFullAccess` IAM policy — which only the system-level path addresses.

Q: What if my model is in TensorFlow format but I follow the system-level path?
A: You’ll hit a hard failure because the system-level path only supports `ModelFormat: ONNX or PMML` — TensorFlow models aren’t accepted, per its limitations.

Q: Can I use the instance-level path if my deployment fails before any instances are created?
A: No. If no instances exist, there’s nothing to inspect in the `Server Role List` or `Cluster Dashboard`. That’s a system-level failure (e.g., `ValidationError`).

Q: Why does the system-level path mention `Deployment timed out after 30 minutes`?
A: AIRec enforces a 30-minute default timeout for deployments. Large models may exceed this, causing failure — the system-level path guides you to adjust timeouts manually.

Q: What happens if I try to troubleshoot a `RollingTaskFailed` error using the system-level path?
A: You won’t find relevant logs — rolling task status is only visible in the `Apsara Infrastructure Management Framework`’s `Operation Logs`, which the instance-level path uses.

Q: Is `Health check endpoint returns 503` always a system-level issue?
A: Yes. A 503 indicates the service was deployed but isn’t healthy — often due to misconfiguration or runtime incompatibility, which the system-level path validates via `DescribeInstanceLogs` and schema checks.

Q: What if I specify an unsupported InstanceType like 'gpu' but choose the AIRec path?
A: You’ll encounter a validation error because the AIRec path only supports InstanceType: standard or high-memory — other types are rejected during deployment planning.

Q: What if I try to use password authentication on a Linux instance in the instance-level path?
A: You’ll be denied access because RAM policies explicitly block `ecs:PasswordCustomized`; you must use SSH key pairs instead.


## Frequently asked questions

### Should I use the API or the console for deploying AIRec?

Use the **console** for initial setup, guided workflows, and visual monitoring. Use the **API** for automation, integration into CI/CD pipelines, or bulk operations.

### Where do I start if I’m new to AIRec?

Begin with an **intent skill** (e.g., "Deploy AIRec service")—it routes you to the right combination of guide and troubleshooting content.

### How do I troubleshoot a deployment that’s stuck?

Check **Instance Management > troubleshooting** for rolling task failures, or **System Deployment > troubleshooting** for broader issues. Also see the intent skill "Troubleshoot AIRec deployment failures".

### Can I use my own certificate authority (CA) with AIRec?

Yes—use the **Certificate Management > guide** skill to issue and verify certificates using your CA, and map them to services.

### What permissions do I need in the console?

You need **Administrator** or **Deployment Operator** roles in Apsara Stack. Specific actions may require additional granular permissions (documented in each guide skill).

### How do I configure the network for an AIRec deployment?

You can configure the network for an AIRec deployment by setting up IP pools, out-of-band networks, and verifying switch auto-configuration. The network configuration guide skill provides the necessary steps for managing these components and network device inventories.

### What is the best way to deploy the AIRec service?

You can deploy the AIRec service end-to-end through the Apsara Stack ASI console or via automation. The deployment guide skill outlines the required workflows for initial setup, delivery, and post-deployment configuration.

### How do I manage HTTPS certificates for AIRec?

You can manage HTTPS certificates for AIRec by creating, deploying, and binding them using a custom customer CA. The certificate management and network security guide skills cover issuing, verifying, and mapping these certificates for secure communication.

### How do I troubleshoot AIRec deployment failures?

You can troubleshoot AIRec deployment failures by diagnosing and resolving stuck deployments or installation errors using the dedicated troubleshooting skills. These workflows guide you through analyzing error logs, checking machine status, and resolving general system deployment issues.

## Cross-product integrations

- [AI Recommendation Platform with RAG Explanations](https://company-skill.com/p/_combos/ai-recommendation-platform-with-rag-explanations-8803cd.md) (alinux + opensearch + bailian + pai + es)
- [AIRec with Custom Models and Semantic Search](https://company-skill.com/p/_combos/airec-with-custom-models-and-semantic-search-fe8869.md) (alinux + opensearch + cloudflare + pai + bailian)
- [Cloud Migration with AI Search and Recommendations](https://company-skill.com/p/_combos/cloud-migration-with-ai-search-and-recommendatio-f00279.md) (bailian + es + rds + oceanbase + oss)
- [Compliant ECS with Automated Certificate Lifecycle](https://company-skill.com/p/_combos/compliant-ecs-with-automated-certificate-lifecyc-1ffd3b.md) (cas + ecs + alinux)
- [Cross-Engine RAG with Hybrid Retrieval and Personalized Recommendations](https://company-skill.com/p/_combos/cross-engine-rag-with-hybrid-retrieval-and-perso-68feb9.md) (pai + opensearch + es + oss + bailian)
- [Custom LLM RAG with Intelligent Recommendations](https://company-skill.com/p/_combos/custom-llm-rag-with-intelligent-recommendations-dc3d7b.md) (alinux + oss + rds + ecs + terraform)
- [Custom ML OCR-to-Recommendations RAG Pipeline](https://company-skill.com/p/_combos/custom-ml-ocr-to-recommendations-rag-pipeline-05916c.md) (opensearch + es + oss + bailian + pai)
- [Custom Model-Enhanced RAG Recommendation Platform](https://company-skill.com/p/_combos/custom-model-enhanced-rag-recommendation-platfor-ec855c.md) (pai + alinux + cloudflare + opensearch + bailian)

## Use with an AI agent

```bash
curl -s https://company-skill.com/api/route \
  -H 'Content-Type: application/json' \
  -d '{"query": "...", "product": "airec"}'
```

MCP server: https://company-skill.com/api/mcp/airec.py

---
Machine-readable: https://company-skill.com/llms.txt · https://company-skill.com/sitemap.xml