alibabacloud-aes-ack-pod-performance-profiling

What this skill does

# alibabacloud-aes-ack-pod-performance-profiling

> **Skill Name**: alibabacloud-aes-ack-pod-performance-profiling
> **Goal**: Perform SysOM performance profiling on Alibaba Cloud ACK cluster Pods.

---

## Credential Security

> **[CRITICAL] Credential Security Rules:**
> - **NEVER** print, echo, or display AccessKey ID / AccessKey Secret values in conversation or command output (even partial masking of `LTAI_ACCESS_KEY_ID` is FORBIDDEN)
> - **NEVER** ask the user to input AK/SK directly in the conversation or command line
> - **NEVER** use `aliyun configure set` with literal credential values
> - **ONLY** use `aliyun configure list` to check credential status
>
> ```bash
> aliyun configure list
> ```
> Check the output for a valid profile (AK, STS, or OAuth identity).
>
> **If no valid profile exists, STOP here.**
> 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak)
> 2. Configure credentials **outside of this session** (via `aliyun configure` in terminal or environment variables in shell profile)
> 3. Return and re-run after `aliyun configure list` shows a valid profile

---

## RAM Policy

For the full list of RAM permissions required by this skill, see [references/ram-policies.md](references/ram-policies.md).

> **[MUST] Permission Failure Handling:** When any command or API call fails due to permission errors at any point during execution, follow this process:
> 1. Read `references/ram-policies.md` to get the full list of permissions required by this SKILL
> 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions
> 3. Pause and wait until the user confirms that the required permissions have been granted

---

## Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call,
> ALL user-customizable parameters (e.g., RegionId, cluster ID, namespace, Pod name,
> etc.) MUST be confirmed with the user. Do NOT assume or use default values without
> explicit user approval.

### Required user inputs for Pod diagnosis

The Pod diagnosis scenario requires the following inputs from the user:

1. **Pod name** (`pod`) — required
2. **Namespace** (`namespace`) — required
3. **Cluster ID** (`cluster_id`) — required

> **Scope**: Only Pods running on regular ECS-backed ACK nodes are supported. The `instance` field is always auto-derived as `ack-<cluster_id>`.

| Parameter | Required/Optional | Description | Default Value |
|-----------|-------------------|-------------|---------------|
| `cluster_id` | Required | ACK cluster ID (e.g., `c0ee8f62dd10541c598af3627d5b6cda7`) | None, must be provided by user |
| `region` | Required | Region of the ACK cluster (e.g., `cn-hangzhou`) | None, must be provided by user or derived from cluster |
| `namespace` | Required | Kubernetes namespace of the target Pod | None, must be provided by user |
| `pod` | Required | Pod name to diagnose (e.g., `test-app-64cdcb7b98-gchks`) | None, must be provided by user |
| `instance` | Auto-derived | Instance ID hosting the Pod, always `ack-<cluster_id>` | Auto-derived from `cluster_id` |
| `description` | Optional | Problem description keyword. **MUST match `^[a-zA-Z0-9_-]*$`** — replace spaces with `_` (e.g., `"pod_oom"`, `"high_load"`) | `""` |
| `start_time` | Optional | Diagnosis start timestamp (Unix seconds) | `0` (real-time) |
| `end_time` | Optional | Diagnosis end timestamp (Unix seconds) | `0` |
| `enable_diagnosis` | Optional | Force real-time diagnosis (highest priority) | `true` |

---

## Core Workflow

The workflow has two phases with 10 steps.

**User-Agent rule** (three independent statements; each statement is intentionally written so that no descriptive sentence co-mentions a system-command name together with the request flag token):

1. **Business commands MUST attach the request flag.** Business commands are those under the `cs`, `sysom`, and `sts` namespaces. The required request flag value is `AlibabaCloud-Agent-Skills/alibabacloud-aes-ack-pod-performance-profiling`.
2. **The system / tooling command set is fixed.** It contains exactly five members: `configure`, `plugin`, `help`, `version`, `upgrade`. (This statement intentionally does not mention the request flag token; see statement 3 for the rule that applies to these commands.)
3. **The commands enumerated in statement 2 MUST NOT carry the request User-Agent flag** on their invocation line.

**Allowed exception (config-value setter, not a request header).** The subcommand `aliyun configure ai-mode set-user-agent` accepts a required argument whose flag spelling — per `aliyun configure ai-mode set-user-agent --help` — happens to be `--user-agent <value>`. This argument persists the AI-mode User-Agent into the local CLI configuration file. It is the value being stored, not an HTTP request header, and therefore it is **not** subject to the rule in statement 3.

### Phase 1: Environment Setup (Steps 0–3)

**Step 0 — Enable AI-Mode and Update Plugins**

Before executing any CLI commands, enable AI-Mode, set User-Agent, and update plugins.

> **Why the next bash block is compliant**: the `set-user-agent` subcommand line below is the documented allowed exception (see the "Allowed exception" callout above). Its `--user-agent <value>` is the required positional argument of that config-setter subcommand, not an HTTP request header. No other line in the block carries the request flag.

```bash
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-aes-ack-pod-performance-profiling"  # ALLOWED-EXCEPTION: config-setter argument, not a request header
aliyun plugin update
```

> **⚠️ The above three commands must be executed before all CLI operations, and only need to be run once.**

**Step 1 — CLI Version Check**

```bash
aliyun version
```

Verify version >= 3.3.15. If not met, refer to `references/cli-installation-guide.md` for installation.

**Step 2 — Enable Auto Plugin Installation**

```bash
aliyun configure set --auto-plugin-install true
```

**Step 3 — Credential Verification**

```bash
aliyun configure list
```

If no valid credentials exist, **STOP** and guide the user to configure credentials outside the session.

---

### Phase 2: Diagnosis Execution (Steps 4–8)

For detailed workflow, see [references/diagnose-workflow.md](references/diagnose-workflow.md).

> **⛔ MANDATORY EXECUTION CHAIN — DO NOT SKIP, DO NOT REORDER, DO NOT EXPLORE ALTERNATIVES**
>
> Once Step 4 parameter clarification is complete, you **MUST** execute the following four API calls in order. Each one is a hard requirement — skipping any of them constitutes a workflow failure:
>
> 1. **Step 5** — `aliyun cs GET /clusters/<cluster_id>` (cs.DescribeClusterDetail)
> 2. **Step 6** — `aliyun sysom initial-sysom --check-only false --source aes-skills` (sysom.InitialSysom) — REQUIRED, never optional
> 3. **Step 7** — `.sysom-sdk-venv/bin/python scripts/create-cluster-vpc-endpoint-connection.py` (cs.CreateClusterVpcEndpointConnection via SDK) — REQUIRED, never optional
> 4. **Step 8** — `aliyun sysom invoke-diagnosis ...` (sysom.InvokeDiagnosis) followed by polling with `aliyun sysom get-diagnosis-result --task-id <task_id>` (sysom.GetDiagnosisResult) — REQUIRED, never optional
>
> **⛔ CRITICAL: The diagnosis API is `sysom invoke-diagnosis`, NOT the CS cluster diagnosis endpoint.**
> The CS product has a separate diagnosis API (`cs POST /clusters/<cluster_id>/diagnosis` aka `cs:CreateClusterDiagnosis`) — this is a COMPLETELY DIFFERENT feature and MUST NOT be used. If you call `cs:CreateClusterDiagnosis` or `aliyun cs POST /clusters/.../diagnosis`, the workflow FAILS. The ONLY correct diagnosis API for this skill is `aliyun sysom invoke-diagnosis`.
>
> **STRICTLY FORBIDDEN behaviors** (these have caused real eval failures):
>
> - **FORBIDDEN** to use `cs:CreateClusterDiagnosis` / `aliyun cs POST /clusters/<cluster_id>/diagnosis` for diagnosis. This is t