alibabacloud-cms-manage

name	alibabacloud-cms-manage
description	Entry skill for the aliyun CLI distribution of CloudMonitor (CMS). Use when the user mentions aliyun cms2, CloudMonitor, CMS commands, or any CMS module operation such as Integration Policy/Center, APM, RUM, Prometheus Service, Recording rule, alert rule, alert template, alert history, event hub, SLS event, PromQL, cloud resource, service observability, monitoring onboarding, metric query, etc.
license	Apache-2.0
compatibility	aliyun-cli>=3.3.15
metadata	{"domain":"aiops","owner":"cms","contact":"[e-mail]"}

CMS CLI — aliyun cms2

Prerequisite Check

Once per session: perform this prerequisite check only on the first invocation of this skill in a conversation. If all checks already passed earlier in the same session, skip directly to the relevant module.

1. Check aliyun exists — which aliyun (macOS/Linux) or where aliyun (Windows).

   • Not found → ask the user to install the aliyun CLI first: https://help.aliyun.com/document_detail/121541.html. Stop and wait.

2. Check CLI version — run aliyun version. Minimum required: 3.3.15 (see compatibility in frontmatter).

   ⚠️ Compare version segments as integers (semver): 3.3.4 < 3.3.15 because 4 < 15. Shell verification: printf '%s\n' "3.3.15" "$(aliyun version)" | sort -V | head -1 If the output equals the current version, the requirement is NOT met.

   • Version OK → go to step 3.
   • Version too old or unrecognized →
     1. Run aliyun upgrade --help to test whether the upgrade subcommand exists.
        • Available → run aliyun upgrade -y to update to the latest version automatically, then re-check aliyun version.
     2. If upgrade not available → ask the user to upgrade manually following the official guide: https://help.aliyun.com/zh/cli/update-cli. Wait for the user to confirm the upgrade is complete, then re-check aliyun version.
     3. If upgrade succeeded → go to step 3.
     4. If upgrade failed → ask the user to upgrade manually: https://help.aliyun.com/zh/cli/update-cli. Stop and exit.

3. Check cms2 plugin — run aliyun cms2 --help.

   • Help output OK → continue to Credentials.
   • unknown command / missing → stop immediately, output the error report below (append CLI version, OS, and error message), and make no further CLI calls.

---

Credentials

aliyun cms2 reuses the aliyun CLI credential system (aliyun configure). Use --profile <name> to switch profiles.

Observability

Upon loading this skill, generate a random session ID (32-char lowercase hex string) once per session...

For every aliyun cms2 command, append: --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-cms-manage/{session-id}"

Local utility commands (e.g. version, configure, plugin, --help) do not support this flag and are excluded.

Global Conventions

Hard constraint: fallback to aliyun cms, other API versions, or any workaround is strictly prohibited.

Run aliyun cms2 <command> [subcommand] --help before first use of a subcommand in a session to get the full flag list and examples. Once the help for the same subcommand has been read in the current session and the command shape has not changed, reuse that knowledge instead of repeating the help call. A named subcommand's --help / --show-schema / --show-example-body is the authority for that command's flags, body envelope, response fields, and environment behaviour — do not search other skill files for a copy of those fields.

• Prefer -o text (default) to reduce token consumption for list/get; use -o json only when the output is parsed field by field rather than read.
• Addon-release values: expand each field's fieldPath into nested JSON as specified in Addon Values Defaults. Do not write a dotted fieldPath as one literal key. How to pick --env-type, where child fields sit on create vs update, and when a subset is (or is not) a valid body, are in that section.
• Region parameter required for mutating and detail commands: unless otherwise specified by a module-specific rule, all create, update, delete, and single-resource get/detail commands MUST include the --region parameter so the request is routed to the correct backend OpenAPI endpoint. Omitting --region on these commands may cause routing failures or operate against an unintended region, and the error can name something else entirely — integration policy create returns status 400: The workspace can not be created even when the workspace exists and the body is valid. This does not apply to list/query commands that intentionally span multiple regions (e.g. entity query --source CloudResource all-region queries). Requiring the flag is not permission to choose its value — resolve it per Region Confirmation Gate.
• One choice, one question: every enumerated choice (region, workspace, policy, addon, scope mode, tag match mode, and any other mutually exclusive parameter) is asked as one question carrying all of its options. Never split them across questions or into a （续）... continuation, and never drop the ones that do not fit — a split turns one choice into two answers that can conflict or be left incomplete, and a truncated list hides valid choices entirely. When the structured input form cannot render every option, ask as plain text and spell out every option with its explanation in the question body. A mutually exclusive choice stays single-select; only a genuinely multi-valued one (several regions) is multi-select. A prompt may carry several distinct choices, each its own question. Put any recommended value directly in the option label (for example (Recommended)); recommendations are advisory only and do not permit cloud-side writes unless another rule permits defaulting or the user confirms.

Region Confirmation Gate (Hard Requirement)

Applies to every module and to every command that takes --region or a region/regionId body field. Settle the region before the workspace, since workspace verification is region-scoped.

List/query commands omit --region only when a module rule says the call is all-region. Omitting the flag is not all-region: the CLI supplies the profile default. Mutating and detail commands must carry it per Region parameter required.

There are exactly three legitimate sources for the value:

1. The user stated it in the current request — not an earlier unrelated turn of the same session.
2. The user picked it from a candidate list you presented, and you waited for that answer before running the next command.
3. The host injected it as runtime context (the console session's current region). Say which region you are operating on before using it.

Anything else is a violation, including: a CLI profile / aliyun configure / ALIYUN_REGION default, or an omitted required --region; the cn-hangzhou of docs and examples, or a region only stated in narration; splitting default-cms-{userId}-{regionId} (or any workspace name); passing controlRegionId.

A module may bind --region to the regionId of a resource the user already confirmed (named cluster, workspace that already passed this gate, instance). That is still Source 1 or 2. Module references do not loosen this.

If Source 1 and 2 are absent, present the region as a choice per One choice, one question and stop. Gather candidates with aliyun cms2 meta regions and offer every regionId (never showName or controlRegionId); only consuming that output is wrong. Source 3, when present, is a recommended option only — it routes the call and does not decide scope. Onboarding region scope is collected by Resource Scope Selection Gate; do not ask a second region question here.

controlRegionId is the control-plane region and may differ for dedicated / exclusive locations — never pass it as --region.

Workspace Confirmation Gate (Hard Requirement)

Applies to every module and to every command that takes --workspace or a workspace body field. There are exactly three legitimate sources for the value:

1. The user stated it in the current conversation. Verify it exists in the target region by exact workspaceName match; no exact match → report and ask, never substitute a near match.
2. The user picked it from a candidate list you presented, and you waited for that answer before running the next command.
3. The environment supplied it as runtime context (e.g. the console session the skill runs inside) and its region matches the target region. Say which workspace you are operating on before using it.

Anything else is a violation: adopting the single row aliyun cms2 workspace list returned, picking the default-cms-{userId}-{regionId} entry because it looks like the account default, assembling that name from aliyun sts get-caller-identity plus a region, or reusing a workspace from an earlier unrelated request in the same session.

So aliyun cms2 workspace list remains the right way to gather candidates — only consuming its output instead of presenting it is wrong. Mark the best candidate (Recommended) inside the option per One choice, one question, then stop and wait.

Module references do not loosen this. Where one gives default-cms-{userId}-{regionId} as the workspace's "default format" or builds it from an account ID and a region, that describes how the account's default workspace is named — it is the candidate to recommend, never permission to skip the question.

Pagination & Query Failure Handling

• Paginate to completion: for every list command that supports --next-token, keep querying until no nextToken remains or accumulated count ≥ totalCount. Do not trust the first page as complete when pagination metadata indicates more data.
• Page size on paginated list: when the command accepts --max-results, pass 100 and then paginate to completion. The 20-page cap times the CLI default page size can truncate a large policy list.
• Accumulated count ≥ totalCount: stop even if nextToken is non-empty or truncated=true; totalCount is the stronger signal.
• Empty page with satisfied totalCount: stop even if nextToken is present.
• Token loop protection: track seen tokens; stop on repeat and report as partial.
• Page limit: default 20 pages; report partial if reached.
• Truncated results: do not conclude absence from partial results. Use filters (--search, --query, --policy-name, etc.) or paginate fully.
• Transient query failure: retry once on a transient server-side error (DEADLINE_EXCEEDED, timeout); if it still fails, mark as Unknown/QueryFailed — do not treat as healthy or unhealthy.

Error Handling

Error codes and actions are listed in aliyun cms2 --help. Additional tips:

• InvalidJSON usually means malformed --body; validate with jq . <<<'<value>' before passing to the CLI.
• --body and stdin are mutually exclusive; specify only one — means both --body (or --file) and stdin data were provided. Fix: keep only one input source. In agent/CI environments where stdin may be a pipe, append < /dev/null to the command to ensure stdin is empty.

Output Language and Terminology

• Write user-facing explanations, analysis, recommendations, summaries, and conclusions in the user's language; default to Simplified Chinese when that language is unclear or mixed. Follow a mid-conversation switch from that point on, and let an explicit instruction about output language override both.
• Question prompts, option labels, table headers, and reports are user-facing text too — phrase them in the answer language even where a reference file spells them out in one language.
• CLI command names, flags, API paths, JSON field names, enum values, resource IDs, metric names, and log/error messages MUST remain verbatim English/code, whatever the answer language.
• Answering in English: use the Glossary's English column as the canonical vocabulary rather than inventing synonyms.
• Answering in Chinese: use the Glossary's Chinese terms in all prose, never leaving a mapped term in English. Write 中文（English） on first mention only when it disambiguates, then the Chinese term alone. Before sending, scan for mapped English terms and replace them, except inside code, commands, JSON fields, IDs, or quoted CLI output.

Examples (Chinese answers):

• Good: 接入配置（AddonRelease，CLI 命令为 addon-release）
• Good: 查询接入配置状态：aliyun cms2 integration addon-release list ...
• Bad: all releases are Ready
• Better: 所有接入配置均 Ready

Glossary

English	中文
Cloud Monitor / CMS	云监控
Workspace	工作空间
Application Monitoring / APM	应用监控
RUM	用户体验监控
Synthetic Monitoring / Synthetic	云拨测
CloudResource	云资源
EntityStore	实体仓库
Entity	实体
Integration Policy / policy	接入策略
Addon / addon	组件
Addon Catalog	组件目录
AddonRelease / addon release / release	接入配置
Collector	采集器
Prometheus View	Prometheus 聚合视图
AggTaskGroup	聚合任务
Delivery Task	数据投递任务
Alert Rule	告警规则
Alert Template	告警模板
Alert History	告警历史
Notification Channel	通知渠道
Contact	联系人
Event Hub	事件中心
Metric Meta	指标元数据
ClusterCollector	集群采集器
NodeCollector	节点采集器
Cluster probe	集群探针
Metric drop	指标废弃
CMS resource tag	CMS 资源标签
Grafana workspace	Grafana工作区

Metadata Query Mapping

What You Need	How to Get It
Metric business metadata (namespaces & product codes via meta namespaces; metric name, type, unit, dimensions via meta metrics)	meta namespaces / meta metrics
Prometheus labels, values & series inspection	metric promql labels / label-values / series

Integration-module lookups (resource metadata, onboarding status, policy-scoped Kubernetes resources, Prometheus instance by policy) live in references/integration-common.md.

Module Routing

User Intent Keywords	Commands	Module
onboarding, monitoring addon, policy, integration, addon release, integration resource, Kubernetes resource list, Namespace resources under policy, resources managed by policy, teardown, offboarding — common rules, load for every onboarding operation	integration integration resource	references/integration-common.md
container onboarding, ACK/ACS/ASI cluster onboarding, cluster fleet audit, which clusters are not onboarded	integration entity query	references/cs-onboarding.md (+ integration-common.md)
ECS host onboarding, ECS fleet audit, NodeCollector	integration entity query	references/ecs-onboarding.md (+ integration-common.md)
cloud service onboarding, RDS/SLB/ALB/Redis/MongoDB/PolarDB onboarding, cloud resource fleet audit	integration entity query	references/cloud-onboarding.md (+ integration-common.md)
batch cloud service metric onboarding, batch onboarding, cloud-batch-metrics	integration meta entity query	references/batch-onboarding-workflow.md (+ integration-common.md)
integration policy diagnosis, health-check, troubleshoot policy, scrape config, ServiceMonitor/PodMonitor/custom collection diagnosis, job target	integration check-scrape-config integration job-target integration check-collector-target	references/integration-diagnosis.md
metric drop, drop metrics, dropMetrics, 指标废弃, 丢弃指标, 废弃指标, cluster probe metric-agent	integration collector integration addon-release	references/integration-management.md (+ integration-common.md)
add / change / remove CMS resource tags, 打标签, 修改标签, 删除标签, CMS resource tags, application service (APM/RUM) tags

Commands not listed above — see aliyun cms2 --help.