Volcengine Cli

Volcengine CLI Skill

Create and manage Volcengine cloud resources by calling Volcengine OpenAPIs through the ve command.

---

0. Install the ve CLI

If the ve command is not available on the system:

Option 1: npm (recommended)

npm i -g @volcengine/cli

Option 2: GitHub Releases Download: https://github.com/volcengine/volcengine-cli/releases

Verify the installation: ve --version

---

1. Initialization (run at the start of every session)

Run the identity verification command to confirm that credentials are usable:

ve sts GetCallerIdentity

Success — inform the user of the current account identity and region, then proceed with the task.

Switching regions later: once a profile is set up, --region and VOLCENGINE_REGION do not override the region baked into it. Switch via ve configure profile --profile <name> (use ve configure list to see profiles). This does not apply to the --region flag on ve login itself, which is required (see below).

Failure — no usable profile. Default plan: use ve login (Console Login, OAuth 2.0 + PKCE). Announce this to the user up front, and tell them they can say "use AK/SK", "use STS token", or "use SSO" to switch.

First check the ve version:

ve --version

Default: Console Login (requires ve >= 1.0.42)

Use ve login --remote via the helper script scripts/ve_login_remote.sh. It handles the OAuth device-flow subprocess lifecycle (FIFO-bound stdin, URL extraction, code feeding, cleanup) so the agent doesn't have to.

Resolve the login region:

1. If the user named a region in this conversation, use it. 2. Else if VOLCENGINE_REGION is set, use it. 3. Else default to cn-beijing.

Default procedure — commit to this path; do NOT present a menu of login methods:

1. Announce + give the user an off-ramp, then immediately start:

"I'll start ve login --remote --region <region> now. Say 'use AK/SK' anytime to switch."

2. Start the login subprocess and get the URL:

   scripts/ve_login_remote.sh start <region>

Prints a https://signin.volcengine.com/... URL on stdout. Forward it verbatim to the user with: "Open this URL in any browser, complete login, then send me the 'Authorization code' shown on the page."

3. When the user replies with the code, complete the flow:

   scripts/ve_login_remote.sh complete <code>

The script writes the code into the FIFO bound to the still-running ve, waits for ve to exit, then runs ve sts GetCallerIdentity to verify.

4. If the user interrupts (says "use AK/SK", "cancel", "this is taking too long", etc.):

   scripts/ve_login_remote.sh abort

Then switch to the chosen alternative below.

Critical rules — do NOT improvise OAuth:

• ❌ Do NOT present a menu like "A. URL B. local browser C. AK/SK". Commit to --remote; let the user interrupt to switch.
• ❌ Do NOT pre-fetch the URL by running ve login --remote and exiting. The PKCE challenge dies with the subprocess; the URL becomes useless and the next attempt fails with PKCE mismatch.
• ❌ Do NOT construct signin.volcengine.com/authorize/... URLs yourself.
• ❌ Do NOT decode, parse, or transform the user's reply. Whatever they paste IS the authorization code — pass it verbatim to complete <code>. No base64 decode (even if the string looks base64-shaped), no URL query-string parsing, no extracting code= from callback URLs.
• ❌ Do NOT pipe codes in (echo "<code>" | ve login --remote). The code arrives before the user completes browser login and fails verification.
• ❌ Do NOT spawn parallel ve login subprocesses. One at a time, tracked by the helper.
• ❌ Do NOT call ve login --remote directly. Always go through scripts/ve_login_remote.sh. The script binds ve's stdin to a FIFO so the still-running ve can receive the user's code via a separate complete call. Calling ve directly orphans the subprocess and breaks the code-feeding step.
• ✅ Use scripts/ve_login_remote.sh start / complete / abort.

Switching region mid-flow: scripts/ve_login_remote.sh abort, then start <new-region>.

No browser on any device (true offline / CI): skip ve login, fall back to AK/SK below.

If ve login fails (network error, non-interactive terminal, version too old), or the user explicitly asks for a different method, fall back to one of the alternatives below. If installed via npm, upgrade with npm i -g @volcengine/cli@latest.

Alternative: AK/SK (long-term credentials, for CI/CD or scripting)

Ask the user for AccessKey and SecretKey, then:

ve configure set --profile default --region cn-beijing \
  --endpoint open.volcengineapi.com \
  --access-key <AK> --secret-key <SK>

For STS (temporary) credentials, also pass --session-token <TOKEN>.

Alternative for the current shell only: export VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY, VOLCENGINE_REGION, optionally VOLCENGINE_SESSION_TOKEN.

Alternative: SSO / Cloud Identity Center (requires ve >= 1.0.38, for enterprise federation)

Three-step setup; ask the user for the SSO start URL and session name first:

ve configure sso-session --name <session-name> \
  --start-url https://<sso-host>/userportal \
  --region cn-beijing \
  --registration-scopes cloudidentity:account:access,offline_access

ve configure sso --profile <profile-name> --sso-session <session-name>

ve configure profile --profile <profile-name>

Then ve sso login --sso-session <session-name> (use --no-browser on headless machines).

Credential safety

• Never read `~/.volcengine/config.json` — it contains AK/SK and session tokens.
• When running ve configure set with --secret-key, prefer letting the user paste and run the command in their own shell rather than executing it via Claude — secrets passed as command-line arguments end up in shell history and process listings.
• Never echo AK/SK, secret keys, or session tokens back to the user in plain text.

---

2. Safety Rules (mandatory)

Read/Write Classification

Core Principles

1. Default to read-only — unless the user explicitly requests a change, execute in read-only mode 2. DryRun first — if a write/destructive operation supports --DryRun true, run a DryRun to preview the plan, then confirm before executing 3. Confirm before executing — show the full command for write operations and wait for approval 4. Protect credentials — never read ~/.volcengine/config.json; never expose access-key, secret-key, or session-token in output

DryRun Notes

A successful DryRun validation returns exit code 1 (non-zero) with DryRunOperation in stderr. This is expected behavior:

output=$(ve <svc> <action> --DryRun true ... 2>&1)
if echo "$output" | grep -q "DryRunOperation"; then
  echo "Parameter validation passed"
fi

---

3. Locate APIs and Retrieve Parameters

Locate the API (find the service name + Action name)

Step 1: Service name + Action known? -> Use them directly; skip to "Retrieve parameters"
Step 2: Service name known, Action unknown?
  -> ve <service> 2>&1 | grep -i <keyword>
Step 3: Service name also unknown?
  -> ve 2>&1 | grep -i <service keyword>
Step 4: None of the above work?
  -> python3 scripts/find_api.py <keyword>

Retrieve parameters (once the Action is known)

Choose a strategy based on operation type:

# Read-only — --help is sufficient
ve ecs DescribeInstances --help

# Write — retrieve full documentation
python3 scripts/fetch_swagger.py --service ecs --action RunInstances

ve command name and API version relationship

• Default version -> ve command = base service name (e.g., iam)
• Non-default version -> ve command = service name + version without hyphens (e.g., iam v2021-08-01 -> iam20210801)
• When in doubt: ve 2>&1 | grep <service> to confirm

Python helper usage

# Search for an API (when the service name is unknown)
python3 scripts/find_api.py <keyword> [--limit N]

# Get full API parameter documentation (when descriptions/examples are needed)
python3 scripts/fetch_swagger.py --service <ServiceCode> --action <ActionName>

# List all APIs for a service
python3 scripts/fetch_swagger.py --service <ServiceCode> --list

# Call Extension APIs that public API Explorer/ve does not expose
python3 scripts/call_extend_api.py --list
python3 scripts/call_extend_api.py --describe QueryMetrics

Always pass the base service name to scripts/fetch_swagger.py (e.g., --service iam, not iam20210801) — the script auto-detects the version.

Extension APIs

Some extension APIs are not exposed through ve. For those, consult references/extend-apis.md and use:

python3 scripts/call_extend_api.py --api <APIName> --params '{"Key":"Value"}'

The helper resolves service, version, method, endpoint, content type, and credentials from its registry/environment. Credentials prefer VOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY; when those environment variables are missing, it warns the user and falls back to the Python SDK's CLIConfigCredentialProvider so ve profiles from ak, ramrolearn, oidc, ecsrole, sso, and console-login modes can be reused. Apply the same read/write/destructive confirmation rules before running extension APIs.

---

4. Execute API Calls

Basic Format

ve <ServiceCode> <ActionName> --ParamName "value"

Parameter Passing Rules

Determine the format from --help output:

• Flat parameter format: --help lists individual --Key type entries (e.g., ECS, VPC, IAM) -> pass with --Key "value"
• Array parameters: prefer the numbered CLI form shown by --help, such as --InstanceIds.1 "$instance_id" or --SubnetIds.1 "$subnet_id". Do not assume JSON-array strings are accepted by every action.
• JSON format: --help only shows --body '{...}' (e.g., Redis, CR, and other POST APIs) -> pass with --body '{...}'

# Flat parameters — nested fields use dot notation; arrays use .N index (starting from 1)
ve ecs RunInstances --ZoneId "cn-beijing-a"
ve ecs RunInstances --NetworkInterfaces.1.SubnetId "subnet-xxxx"
ve ecs RunInstances --Tags.1.Key "publish-by" --Tags.1.Value "deploy-skill"

# JSON format (when --help only shows --body)
ve redis CreateDBInstance --body '{"InstanceName":"demo","RegionId":"cn-beijing","ConfigureNodes":[{"AZ":"cn-beijing-a"}],"ShardedCluster":0,"NodeNumber":2,"ShardCapacity":1024,"ShardNumber":1,"EngineVersion":"6.0","SubnetId":"subnet-xxxx","VpcId":"vpc-xxxx","Password":"<secret>","Tags":[{"Key":"publish-by","Value":"deploy-skill"}]}'

Response Format

// Success
{ "ResponseMetadata": { "RequestId": "..." }, "Result": { ... } }

// Failure
{ "ResponseMetadata": { "Error": { "Code": "...", "Message": "..." } } }

Async Resource Creation Requires Polling

Some resources (VKE clusters, RDS instances, ECS instances, etc.) take several minutes to create. After creation, poll the Describe endpoint until the resource reaches the desired status before proceeding.

Creating sub-resources (e.g., security groups) immediately after VPC creation may fail with InvalidVpc.InvalidStatus. Create sub-resources sequentially (subnet first, then security group), or wait a few seconds and retry.

# General polling pattern: check every 30 seconds until the target status is reached
while true; do
  cur_status=$(ve <svc> Describe<Resource> --<IdParam> "xxx" 2>&1 | grep -o '"Status":"[^"]*"')
  echo "$(date +%H:%M:%S) $cur_status"
  echo "$cur_status" | grep -q '"Status":"Running"' && break
  sleep 30
done

---

5. End-to-End Execution Flow (Summary)

1. Initialize: verify credentials -> GetCallerIdentity -> confirm region
2. Understand the task: is the user querying or making changes?
3. Locate the API: ve --help first -> Python helpers as fallback
4. Query dependent resources: use Describe*/List* to obtain required IDs
5. Read operation -> execute directly and display results
   Write operation -> show command -> DryRun (if supported) -> user confirmation -> execute
6. Parse the response and report results to the user

---

6. Service-Specific Notes

Consult or update the corresponding notes file when encountering service-specific issues:

• ECS: references/ecs.md
• VPC: references/vpc.md
• CR: references/cr.md
• ALB: references/alb.md
• CLB: references/clb.md
• VKE: references/vke.md
• veFaaS: references/vefaas.md
• RDS: references/rds.md
• Message Queue: references/mq.md
• Storage: references/storage.md
• Observability: references/observability.md
• DNS/Edge: references/dns-edge.md
• IAM: references/iam.md
• KMS: references/kms.md
• Redis: references/redis.md
• NAT Gateway: references/natgateway.md
• EBS: references/ebs.md
• Extension APIs: references/extend-apis.md

ALB Service Notes

Flat Parameter Mode

ALB create APIs use flat CLI parameters, not JSON body mode. Nested arrays use indexed dot notation such as --ZoneMappings.1.ZoneId.

For private ALB smoke tests, keep all EIP/public address fields unset unless public exposure is explicitly under test:

ve alb CreateLoadBalancer \
  --RegionId cn-beijing \
  --LoadBalancerName cli-skill-test-alb \
  --Type private \
  --VpcId vpc-xxxx \
  --SubnetId subnet-xxxx \
  --ZoneMappings.1.ZoneId cn-beijing-b \
  --ZoneMappings.1.SubnetId subnet-xxxx \
  --LoadBalancerBillingType 1 \
  --LoadBalancerEdition Basic \
  --Tags.1.Key publish-by \
  --Tags.1.Value deploy-skill

Observed in cn-beijing: a private Basic ALB created with publish-by=deploy-skill appeared in DescribeLoadBalancers with the tag attached, then DeleteLoadBalancer removed it. ALB creation is billable and depends on real VPC/subnet choices, so keep lifecycle tests short and delete the test load balancer after validation.

CLB Service Notes

Zone and EIP Behavior

DescribeZones returns master/slave zone pairs, not a flat zone list. Do not feed the raw structure into single-zone fields without choosing the intended master/slave relationship.

For private CLB tests, leave EipBillingConfig.* unset. The create API exposes EIP billing fields, so copying a public example can accidentally allocate a public endpoint.

The delete API supports force deletion:

ve clb DeleteLoadBalancer --LoadBalancerId <clb-id> --ForceDelete true

Observed in cn-beijing: CLBs, listeners, server groups, and certificates returned empty lists. No lifecycle test was run because CLB is billable and may allocate dependent resources.

CR Service Notes

Namespace and Repository Calls Need a Registry

ListNamespaces without Registry fails with:

MissingParameter.Registry: The required parameter Registry is missing.

Passing a non-existent registry reaches the service and fails with:

NotFound.Registry: The specified resource dummy not found.

Use these errors to distinguish JSON/CLI formatting mistakes from a legitimately missing registry.

Write APIs Use JSON Body Mode

CR create APIs use --body JSON mode. Do not create namespaces or repositories until the registry ID/name is known from ListRegistries or CreateRegistry output.

Observed in cn-beijing: ListRegistries returned TotalCount: 0; no CR lifecycle test was run.

Docker Authentication

For push/pull outside the VKE cr-credential-controller passwordless path, authenticate Docker with a short-lived CR authorization token:

token_json=$(ve cr GetAuthorizationToken --Registry "$registry_name")
cr_username=$(printf '%s' "$token_json" | jq -r '.Result.Username // empty')
cr_password=$(printf '%s' "$token_json" | jq -r '.Result.AuthorizationToken')
[ -n "$cr_username" ] || { echo "CR token response missing Result.Username" >&2; exit 1; }
[ -n "$cr_password" ] || { echo "CR token response missing Result.AuthorizationToken" >&2; exit 1; }
printf '%s' "$cr_password" | docker login "$registry_endpoint" \
  --username "$cr_username" \
  --password-stdin

Rules:

• Do not print or write AuthorizationToken to logs.
• Re-run GetAuthorizationToken when Docker push/pull starts failing after a long session; the token is temporary.
• If Username is missing from the response, stop and inspect the CR API response; do not invent a fallback username.
• For VKE private CR pulls, prefer the cr-credential-controller addon when available; otherwise use an explicit Kubernetes imagePullSecret.

DNS and Edge Service Notes

CDN Can Be Disabled at Account Level

ve cdn ListCdnDomains can fail even though the CLI command exists:

OperationDenied.ServiceStopped: 服务处于停用状态，不支持该操作。

Treat this as account service state, not as a request-format bug. CDN domain validation requires the service to be enabled first.

DNS, PrivateZone, and WAF Need Real Inputs

ve dns ListZones, ve privatezone ListPrivateZones, and ve waf ListDomain returned successfully in cn-beijing.

Do not use DNS/PrivateZone/WAF creation as a generic smoke test:

• public DNS zones need a real domain ownership/context;
• PrivateZone record tests need an intended VPC binding;
• WAF domain creation needs a real domain/backend/load-balancer context.

EBS Service Notes

Existing Volumes Are Often ECS System Disks

ve storageebs DescribeVolumes returned an existing system volume attached to an ECS instance. Treat every existing volume as a user resource; never detach or delete it during smoke tests.

Explorer Helper Gap

scripts/fetch_swagger.py --service storageebs --list returned HTTP 404 from the Explorer versions endpoint. Use ve storageebs <Action> --help for parameter discovery.

Lifecycle Risk

CreateVolume is billable. If lifecycle testing is approved, use a small postpaid data disk, never attach it to a non-test instance, delete it immediately, and verify the test volume disappears from DescribeVolumes.

ECS Service Notes

Resource Discovery Pitfalls

DescribeInstanceTypes returns only a small default page and does not prove zone inventory. For placement decisions, query the target zone with DescribeAvailableResource; otherwise RunInstances can fail with InvalidInstanceType.NotFound even when the type exists globally.

For instance type inventory, read .Result.AvailableZones[].AvailableResources[] | select(.Type=="InstanceType").SupportedResources[], then keep entries whose Status is Available; do not look for a top-level InstanceTypes list.

veLinux image search should use an exact name prefix. A fuzzy keyword like velinux also matches GPU, Docker, ARM, and other variants. Known useful names:

• veLinux 2.0 64
• veLinux 2.0 ARM 64

Current RunInstances Shape

Current CLI accepts --ZoneId for RunInstances; older examples may show --Placement.ZoneId. Check the installed CLI help before assuming one shape.

RunInstances requires either --Password or --KeyPairName, even when SSH is not opened. For Cloud Assistant-only deployments, generate a one-time strong password and do not log or persist it.

For no-EIP validation, remove all EipAddress.* parameters and use --DryRun true. A successful DryRun exits non-zero and prints DryRunOperation; this is expected and creates no instance.

Inline EIP ChargeType values observed in help/validation are PayByBandwidth, PayByTraffic, and PrePaid.

If creating the VPC/subnet/security group immediately before RunInstances, wait for VPC and security group readiness first. The API can return InvalidVpc.InvalidStatus when a subnet is created right after CreateVpc, and InvalidSecurityGroup.InvalidStatus when an ingress rule is written right after CreateSecurityGroup.

DeleteInstance Status Casing

DescribeInstances can return uppercase statuses such as CREATING and RUNNING. Do not compare only against title-case values.

Calling DeleteInstance while the instance is still CREATING fails with InvalidInstanceStatus. Poll until RUNNING, STOPPED, or another deletable final state before deletion.

Verified no-EIP lifecycle: created a disposable instance, confirmed EipAddress: null, waited for RUNNING, deleted it, and verified a follow-up name query returned TotalCount: 0.

Cloud Assistant Gotchas

After InstallCloudAssistant, the agent can report ReadyReboot; RunCommand may keep timing out until the instance is rebooted. Prefer --InstallRunCommandAgent true during instance creation.

RunCommand requires an explicit --InvocationName. Use a name no longer than 64 characters, containing only Chinese characters, letters, digits, underscores, or hyphens, and do not start it with a digit or hyphen. Keep it short and stable, for example deploy-check; if omitted, some ve CLI versions can derive the invocation name from CommandContent, and base64 or long shell payloads then fail with LimitExceeded.MaximumInvocationName.

RunCommand --Timeout minimum is 60 seconds. Lower values fail with LimitExceeded.MaximumTimeout.

RunCommand --CommandContent must be base64-encoded shell content. Passing plain text such as echo OK can fail with InvalidBase64Content.Malformed.

Treat RunCommand as scheduling only. Poll invocation results and read the result status from .Result.InvocationResults[0].InvocationResultStatus; terminal values include Success, Failed, and Timeout. Pair it with .Result.InvocationResults[0].ExitCode, and decode .Result.InvocationResults[0].Output from base64 when inspecting command output.

command_b64=$(printf '%s' 'systemctl is-active --quiet app && echo OK' | base64 | tr -d '\n')
invocation_id=$(ve ecs RunCommand \
  --Type Shell \
  --InstanceIds.1 "$instance_id" \
  --InvocationName "deploy-check" \
  --Timeout 60 \
  --CommandContent "$command_b64" \
  | jq -r '.Result.InvocationId')

for _ in $(seq 1 30); do
  result=$(ve ecs DescribeInvocationResults --InvocationId "$invocation_id" --InstanceId "$instance_id")
  result_status=$(printf '%s' "$result" | jq -r '.Result.InvocationResults[0].InvocationResultStatus // empty')
  exit_code=$(printf '%s' "$result" | jq -r '.Result.InvocationResults[0].ExitCode // empty')
  case "$result_status" in
    Success|Failed|Timeout) break ;;
  esac
  sleep 5
done

echo "$result" \
  | jq -r '.Result.InvocationResults[0] | [.InvocationResultStatus, (.ExitCode | tostring)] | @tsv'
if [ "$result_status" != "Success" ] || [ "$exit_code" != "0" ]; then
  echo "RunCommand failed or timed out" >&2
  exit 1
fi
echo "$result" \
  | jq -r '.Result.InvocationResults[0].Output // ""' \
  | base64 -d

veLinux Docker Deployment

veLinux 2 may report VERSION_CODENAME=lyra; do not use lyra as the Docker official Debian repository codename. For quick deployments, prefer the distribution package:

apt-get update
apt-get install -y docker.io
systemctl enable --now docker

Docker Hub and GHCR can time out from China regions. Prefer Volcengine CR, user-provided registries, or verified mirror pull commands from the mirror's own image detail page. docker.aityp.com can be used as a search/sync candidate for some images, but do not assume docker.aityp.com/<image> is a universal drop-in registry path.

Extended APIs

Use this reference when a Volcengine API is missing from the normal ve command surface but can still be called as a Volcengine OpenAPI extension.

The helper script is:

python3 scripts/call_extend_api.py

It embeds the extension API registry and the request-signing code needed by these APIs. It does not import external repositories.

Credentials

The script resolves credentials in this order:

1. Environment variables. 2. Volcengine CLI config through the Python SDK CLIConfigCredentialProvider.

If VOLCENGINE_ACCESS_KEY or VOLCENGINE_SECRET_KEY is not detected, the helper prints a notice and then tries to reuse the active ve CLI profile. The SDK provider supports CLI profiles whose mode is ak, ramrolearn, oidc, ecsrole, sso, or console-login.

Environment variables:

export VOLCENGINE_ACCESS_KEY="AK..."
export VOLCENGINE_SECRET_KEY="SK..."
export VOLCENGINE_REGION="cn-beijing"
# Optional:
export VOLCENGINE_SESSION_TOKEN="..."

CLI profile fallback:

python3 scripts/call_extend_api.py \
  --profile default \
  --api QueryMetrics \
  --params '{"workspace":"vmp-workspace-id","query":"up"}'

Use --config-file /path/to/config.json only when the CLI config is not in the default location. Do not print or echo secrets in the conversation. If both environment credentials and CLI profile resolution fail, ask the user to run ve login, configure a ve profile, or set VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY in their shell.

Discover Supported APIs

List the registry:

python3 scripts/call_extend_api.py --list

Describe one API:

python3 scripts/call_extend_api.py --describe QueryMetrics

Include test-only entries:

python3 scripts/call_extend_api.py --list --include-test

Call An API

Basic form:

python3 scripts/call_extend_api.py \
  --api QueryMetrics \
  --params '{"workspace":"vmp-workspace-id","query":"up"}'

Pass params from a file:

python3 scripts/call_extend_api.py \
  --api ListPipelineRunStagesInner \
  --params @request.json

Assert the expected method:

python3 scripts/call_extend_api.py \
  --api ListAccelerateAreas \
  --method GET \
  --params '{}'

Override endpoint host only when the registry has a product endpoint or the user provides one:

python3 scripts/call_extend_api.py \
  --api QueryMetrics \
  --host open.volcengineapi.com \
  --params '{"workspace":"vmp-workspace-id","query":"up"}'

The script resolves service, version, method, default endpoint, scheme, and default content_type from the registry. If --method disagrees with the registry, it fails before making a request. For APIs marked with query parameters in the registry, include those keys in --params; the helper signs them as URL query parameters and sends the remaining keys as the body.

VMP Metric API Notes

The VMP extension APIs mirror Prometheus query APIs but are signed through Volcengine OpenAPI:

• QueryMetrics, QueryMetricsRange, GetLabels, and GetSeries put workspace in the URL query.
• GetLabelValues puts both workspace and label in the URL query.
• Remaining parameters are sent in an application/x-www-form-urlencoded body.
• Series selector parameters must use the Prometheus HTTP API name match[]. Do not pass match or matches for GetSeries, GetLabels, or GetLabelValues.

Example:

python3 scripts/call_extend_api.py \
  --api GetSeries \
  --params '{"workspace":"vmp-workspace-id","match[]":["up{job=\"node\"}"]}'

To validate VMP APIs with real data, create a temporary VMP workspace, enable public access, and configure authentication before writing samples:

ve vmp CreateWorkspace --body '{
  "Name":"codex-vmp-api-verify",
  "InstanceTypeId":"vmp.standard.15d",
  "Tags":[{"Key":"publish-by","Value":"deploy-skill"}],
  "DeleteProtectionEnabled":false,
  "PublicAccessEnabled":true,
  "PublicWriteBandwidth":1,
  "PublicQueryBandwidth":1
}'

Set BasicAuth with Username and a base64-encoded Password. Do not set AuthType to Basic; the service reports InvalidParameter.AuthType. Confirm with GetWorkspaceAuthInfo, which should return AuthType: BasicAuth.

ve vmp UpdateWorkspace --body '{
  "Id":"vmp-workspace-id",
  "Username":"user-name",
  "Password":"base64-encoded-password"
}'

Use GetWorkspace to obtain PrometheusWriteEndpoint; append /api/v1/write for Prometheus remote write. A successful remote-write request returns HTTP 204. The path /api/v1/push was not accepted for this workspace during validation.

After writing a sample such as codex_vmp_verify_value{run_id="..."} 42, verify all five extension APIs:

python3 scripts/call_extend_api.py \
  --api QueryMetrics \
  --params '{"workspace":"vmp-workspace-id","query":"codex_vmp_verify_value{run_id=\"run-id\"}","time":"sample-or-later-unix-second"}'

python3 scripts/call_extend_api.py \
  --api QueryMetricsRange \
  --params '{"workspace":"vmp-workspace-id","query":"codex_vmp_verify_value{run_id=\"run-id\"}","start":"sample-start","end":"sample-end","step":"10s"}'

python3 scripts/call_extend_api.py \
  --api GetLabels \
  --params '{"workspace":"vmp-workspace-id","match[]":["codex_vmp_verify_value{run_id=\"run-id\"}"]}'

python3 scripts/call_extend_api.py \
  --api GetLabelValues \
  --params '{"workspace":"vmp-workspace-id","label":"run_id","match[]":["codex_vmp_verify_value{run_id=\"run-id\"}"]}'

python3 scripts/call_extend_api.py \
  --api GetSeries \
  --params '{"workspace":"vmp-workspace-id","match[]":["codex_vmp_verify_value{run_id=\"run-id\"}"]}'

For instant queries against freshly written remote-write data, query at or after the stored sample timestamp. A query before the sample timestamp can correctly return an empty vector even though range queries already show the sample.

Safety

Apply the same safety rules as normal ve calls:

• Read-only actions such as Describe*, List*, Get*, Query*, Check*, and Search* can be run directly when the user asks for them.
• Write actions such as Create*, Run*, Update*, Set*, Start*, Register*, and Import* require confirmation.
• Destructive actions such as Delete*, Stop*, and Cancel* require explicit confirmation and an impact summary.

Parameter names and semantics are captured below so this file remains self-contained. Keep params explicit and prefer small read-only calls first.

API Index

Use this index for quick lookup by service or API name.

Supported APIs

Parameter Reference

Unless noted otherwise, pass all fields in --params as one JSON object. The helper resolves Action, Version, Service, Method, endpoint host, and content type from the registry.

CDN

DescribeOriginTopStatisticalData:

• Required: Domain, StartTime, EndTime, Item, Metric.
• StartTime and EndTime are Unix timestamps in seconds.
• Item currently supports url.
• Metric supports flux, pv, status_2xx, status_3xx, status_4xx, status_5xx.

CodePipeline

ListPipelineRunStagesInner:

• Required: WorkspaceId, PipelineId, PipelineRunId.
• Use it after listing workspaces, pipelines, and pipeline runs with normal ve cp APIs.

DCDN

DescribeRealtimeData and DescribeOriginRealtimeData:

• Required: StartTime, EndTime, Metrics.
• StartTime and EndTime use "YYYY-MM-DD HH:MM:SS" and the range must be within 24 hours.
• Metrics is an array. Common values: all, traffic, bandwidth, request, QPS, 2xx, 3xx, 4xx, 5xx; edge realtime also supports RequestHitRate and TrafficHitRate.
• Optional filters include Domains, ProjectName, IspNameEn, RegionNameEn, Protocol, Type, IPVersion.

DescribeTopIPs, DescribeTopReferers, and DescribeTopUrls:

• Required: StartTime, EndTime, Sort.
• Sort supports traffic, bandwidth, request, QPS.
• Optional: Limit (1-100), ProjectName, Domain, StatusCode.

Domain

CheckFee:

• Required query field: domain.

GetDomain:

• Optional query fields: domain, instance_no. Provide at least one useful identifier.

GetAsyncTask:

• Required query field: task_no.

GetTemplate:

• Required query field: tag.

ListDomains:

• Optional query fields: domain, status, verify_status, expired_after, is_auto_renew, domain_name_audit_status, order_by, asc_or_desc, page_number, page_size.

ListTemplates:

• Optional query fields: registrant_zh, registration_type, tag, status, page_number, page_size.

RegisterDomain:

• Required body fields: domain, template_tag.
• Optional: period, ns_list, is_auto_renew, package_id.
• This is billable and creates an async task. Confirm with the user before calling.

Flink

GET actions:

• ListGMSProject: optional SearchKey, PageSize, PageNum.
• GetGMSProjectDetail: required ProjectName.
• ListGMCSResourcePool: ProjectId, optional Name, NameKey, PageSize, PageNum; use version 2022-06-01.
• GetGRSAppById: required AppIdKey.

GWS/GAS POST actions:

• ListGWSDirectory: query-style fields ProjectId, Type (JOB or QUERY).
• GetGWSApplicationDraft: ProjectId, Id.
• CreateGWSApplicationDraft: ProjectId, JobName, DirectoryId, optional JobType, EngineVersion.
• UpdateGWSApplicationDraft: Id, ProjectId, AccountId, UserId, JobName, JobId, DirectoryId, DirectoryName, SqlText, optional DynamicOptions, JobType, EngineVersion.
• DeployGWSApplicationDraft: ProjectId, Id, ResourcePool, Queue, optional Priority, SchedulePolicy, ScheduleTimeout.
• DeleteGWSApplication, StartGWSApplication, CancelGWSApplication, RestartGWSApplication: ProjectId, Id; start/restart also support Type such as FROM_NEW or FROM_LATEST.
• ListGWSApplication: optional ProjectId, JobName, ResourcePool, JobType, State, PageSize, PageNum, SortField, SortOrder.
• GetGWSApplication: required Id, optional AccountId.
• GWSGetEventList: ProjectId, optional Id, Limit.
• ListGASLogs: Application, Project, StartTime, EndTime; optional Level, Properties.component, Properties.podName, Cursor, PageSize.

Global Accelerator

ListAccelerateAreas:

• No required parameters.

ListBandwidthPackages:

• Required in observed request shape: BandwidthType, PageNumber, PageSize.
• Optional: AcceleratorId, AccountId, BandwidthPackageId, Domain, Isp, OrderType, State, States, ProjectName, ResourceTagFilter.

GetBandwidthPackage:

• Required: BandwidthPackageId.

GetAcceleratorDimension:

• Required: AcceleratorType, TargetName, Filters.
• Filters is an array of { "Name": "...", "Values": ["..."] }.

DescribeListenerLogs:

• Required: InputIdType, InputId, StartTime, EndTime, Interval.
• Optional: Metrics, RegionType, Region, grouping fields.

GetBasicEndpointRelatedAccInstanceInfos and GetEndpointRelatedAccInstanceInfos:

• Require the endpoint identifier used by the corresponding GA endpoint type. Include pagination fields such as PageNum/PageSize when listing related instances.

IoT

The IoT extension APIs use product-specific identifiers. Common fields are:

• Instance: InstanceId.
• Product: ProductKey or ProductID.
• Device: DeviceName, DeviceID, DeviceSecret, depending on the API.
• Thing model: ModuleKey, Identifier, PropertyIdentifier, EventIdentifier, ServiceIdentifier.
• Pagination and time range: PageNumber, PageSize, StartTime, EndTime.
• CallService needs target device identifiers plus service identifier and input params.
• SetProperty needs target device identifiers plus property values.

IoT was not business-tested in this account because the service could not be opened.

Live

DescribeLiveBatchStreamTranscodeData:

• Required: StartTime, EndTime.
• Optional: DomainList, PageNum, PageSize.
• Times are RFC3339 strings, for example 2022-11-10T00:00:00+08:00.

DescribeLiveBatchStreamSessionData:

• Required: StartTime, EndTime.
• Optional: DomainList, PageNum, PageSize, OnlineUserType, plus stream/session dimensions when available.
• Times are RFC3339 strings.

MCDN

DescribeCdnDomainConfig:

• Optional identifiers: DomainId, DomainName, Vendor, DomainVersion, NormalizeOptions.
• Prefer DomainId when known.

Metrics

ListWorkspace:

• Recommended: PageNumber, PageSize, ListGlobal.
• Optional: Filters, ProjectName.

GetWorkspaceInfo:

• Required: WorkspaceId.

ListQueryClusters:

• Recommended: Page object with PageNumber and PageSize.
• Optional: Name, ProjectName.

GetQueryCluster:

• Required: Id.

ListPreagg:

• Recommended: PageNumber, PageSize, onlyShowMine.
• Optional: Filters, such as {"WorkspaceName":"..."}.

InfluxQuery and MetricsQuery:

• Require a real workspace/query context and query payload. Include workspace identifier, query expression(s), and time range fields according to the query type.

Security Workflows

RunAlertInvestigator, RunPcapAnalyzer, RunAlertFormatter, RunThreatIntelProducer, RunWebRiskAssessor, RunDlpScreenshotAnalyzer, RunSensitiveDataDetector:

• Require real workflow input such as alert details, PCAP content/reference, URL, screenshot/image data, or text to inspect.
• Do not treat an empty workflow request as validation.

Trademark

GET actions:

• GetApplicant: required ApplicantID.
• GetTrademark: required TrademarkID.
• GetRequirement: required RequirementID.
• ListApplicants: optional ApplicantType, ApplicantName, Status, Country, PageNumber, PageSize, OrderBy.
• ListRequirements: optional status/type filters plus PageNumber, PageSize.
• ListTrademarks: optional trademark/applicant/status filters plus PageNumber, PageSize.
• ListBarrierTrademarks: optional requirement/trademark identifiers and pagination fields.

POST actions:

• SearchTrademarkInfo: required ClassID and RegistrationNumber.
• SearchTrademark: provide at least one useful search condition such as TrademarkName, ApplicantName, or RegistrationNumber; optional PageNumber, PageSize, class/status filters.

VEEN

StartCloudServer, StopCloudServer, RebootCloudServer:

• Require the target cloud-server identifier. Confirm before start/stop/reboot.

GetVEENInstanceUsage, GetVEEWInstanceUsage, GetBandwidthUsage, GetBillingUsageDetail:

• Usage queries require a billing or resource time range and resource filters. During validation, these GET actions reached veenedge.volcengineapi.com but returned Method Not Allowed.

VKE

ListVirtualNodes:

• Optional pagination and filters such as PageNumber, PageSize, cluster or virtual-node identifiers.

CreateVirtualNode:

• Required: Kubeconfig, VirtualNodeConfig.
• This creates infrastructure and needs a cleanup plan before execution.

VMP

The VMP action-specific parameter details are in "VMP Metric API Notes" above. The short form:

• QueryMetrics: URL query key workspace; body fields include query, optional time.
• QueryMetricsRange: URL query key workspace; body fields include query, start, end, step.
• GetLabelValues: URL query keys workspace, label; body supports match[], start, end.
• GetLabels: URL query key workspace; body supports match[], start, end.
• GetSeries: URL query key workspace; body supports match[], start, end.

Notes For Agents

• Prefer normal ve commands when available. Use this helper only when ve does not expose the needed API.
• The registry is exact-match by APIName. If duplicate names appear, pass --service.
• Do not invent params. Use the parameter reference in this file; if a required business ID is missing, ask the user for it or locate it with a read-only list/get command.
• Some registry entries have product-specific default hosts such as cdn.volcengineapi.com, live.volcengineapi.com, iot.cn-shanghai.volcengineapi.com, or veenedge.volcengineapi.com.

Verification Notes

• ListPipelineRunStagesInner was tested with an existing CP workspace, pipeline, and pipeline run and returned HTTP 200 with stage/task data.
• ListVirtualNodes returned HTTP 200 with an empty list.
• ListPreagg returned HTTP 200 with an empty response.
• VMP metric APIs (QueryMetrics, QueryMetricsRange, GetLabelValues, GetLabels, GetSeries) were validated against a temporary vmp.standard.15d workspace with a real remote-write sample codex_vmp_verify_value{run_id="run_20260602_1916",source="codex"} 42. QueryMetrics and QueryMetricsRange returned value 42; GetLabels returned __name__, run_id, and source; GetLabelValues returned the test run_id; GetSeries returned the complete series. The temporary workspace was deleted afterwards and GetWorkspace returned ResourceNotExist.
• Live batch stream APIs returned permission errors after valid StartTime/EndTime parameters were supplied, confirming the earlier InvalidParam was only parameter-shape related.
• CreateVirtualNode reached VKE and requires Kubeconfig plus VirtualNodeConfig. It was not executed because it needs an external Kubernetes kubeconfig and the registry does not include a matching virtual-node delete API for cleanup.
• Most domain, IoT, trademark, metrics, sec_agent, VEEN, and Flink APIs returned AccessDenied for the tested account. Creating dependent resources cannot bypass IAM denial; use an account with the relevant service permissions for full business-flow testing.

Implementation notes:

Current business validation status:

Resource creation gaps for full positive validation:

• Flink: create a temporary Flink project/resource pool/application only after confirming cost/specs, then validate GWS/GAS APIs and delete resources.
• DCDN/CDN/MCDN/Live: require real domains and, for CDN/DCDN stats, actual traffic. Domain ownership, ICP/filing, origin, and certificate setup may be required.
• GA: create accelerator/bandwidth/listener/endpoint resources only after confirming cost and cleanup commands.
• VKE virtual node: requires an existing VKE cluster and kubeconfig; the helper registry does not include a matching virtual-node delete API, so cleanup must be planned through public VKE APIs.
• SecAgent: requires real security workflow input samples and expected-output criteria.

IAM Service Notes

UpdateUser does not support Tags

UpdateUser can only modify basic attributes such as Description and DisplayName. It cannot manage tags.

Correct approach: use TagResources to tag users separately:

ve iam TagResources --ResourceType "User" --ResourceNames.1 "<UserName>" --Tags.1.Key "key" --Tags.1.Value "value"

The same applies to roles — use TagResources with ResourceType set to Role.

---

Verified temporary user tag flow

For testing IAM user tagging, create a disposable user and delete it in the same run. CreateUser can set initial tags, and TagResources adds more tags afterward.

user_name="cli-skill-test-user"

ve iam CreateUser \
  --UserName "$user_name" \
  --Description "cli-skill-test" \
  --Tags.1.Key "publish-by" \
  --Tags.1.Value "deploy-skill"

ve iam TagResources \
  --ResourceType "User" \
  --ResourceNames.1 "$user_name" \
  --Tags.1.Key "purpose2" \
  --Tags.1.Value "cli-skill-test"

ve iam GetUser --UserName "$user_name"

ve iam UntagResources \
  --ResourceType "User" \
  --ResourceNames.1 "$user_name" \
  --TagKeys.1 "purpose2"

ve iam DeleteUser --UserName "$user_name"

After deletion, ve iam GetUser --UserName "$user_name" should fail with UserNotExist; use that as the release confirmation for disposable IAM users.

KMS Service Notes

DescribeKeys Requires a Keyring

DescribeKeys requires KeyringName or KeyringID; omitting both returns MissingParameter.

Observed in cn-beijing: DescribeKeyrings returned an existing keyring, DescribeKeys worked when scoped to that keyring, and DescribeSecrets returned TotalCount: 0.

Deletion Is Scheduled

KMS keys and secrets are not immediate-delete resources. The current action list exposes ScheduleKeyDeletion, CancelKeyDeletion, ScheduleSecretDeletion, and CancelSecretDeletion.

Prefer read/help validation unless the test explicitly accepts scheduled deletion and follow-up cleanup tracking. Disposable tests should use a dedicated keyring name prefix.

Message Queue Service Notes

Kafka and RocketMQ Need Pagination

Kafka and RocketMQ DescribeInstances require PageNumber and PageSize; omitting them returns an invalid page parameter error.

ve kafka DescribeInstances --body '{"RegionId":"cn-beijing","PageNumber":1,"PageSize":10}'
ve rocketmq DescribeInstances --body '{"RegionId":"cn-beijing","PageNumber":1,"PageSize":10}'

RabbitMQ DescribeInstances worked without the same pagination body in this environment.

Safer Smoke-Test Surface

Kafka/RabbitMQ/RocketMQ allow-list read APIs returned successfully. Allow-list create/delete is a safer lifecycle candidate than full broker instance creation, but still requires explicit approval and final cleanup verification.

Observed in cn-beijing: Kafka, RabbitMQ, RocketMQ, and BMQ instance lists were empty. BMQ reported cn-beijing-b as sold out while other Beijing zones were available.

NAT Gateway Service Notes

Existing NAT Resources Must Be Treated as User-Owned

DescribeNatGateways returned existing account resources in cn-beijing, including EIP-backed SNAT configuration. Do not delete or modify them unless they were created by the current test run.

Observed:

• NAT gateway available zones included cn-beijing-a through cn-beijing-d.
• DescribeSnatEntries returned existing SNAT entries.
• DescribeDnatEntries returned TotalCount: 0.

EIP-Dependent Paths Are Separate

Public NAT SNAT/DNAT flows usually require EIP allocation or association. If EIP allocation is out of scope, validate only read/discovery behavior or use an explicitly approved test-owned EIP.

Observability Service Notes

TLS Is Not Available in This ve Build

The current ve command list does not include tls. Running ve tls --help returns unknown command.

Do not troubleshoot TLS resource operations as CLI parameter mistakes in this environment; there is no matching ve tls command to validate.

CloudMonitor Read Path Works

ve cloudmonitor ListRules returned an empty Data array in cn-beijing. No CloudMonitor rule lifecycle test was run.

RDS Service Notes

Explorer Helper Gap

scripts/fetch_swagger.py --service rdsmysql --list, rdspostgresql, and rdsmssql returned HTTP 404 from the Explorer versions endpoint. Use ve <service> <Action> --help for these service schemas.

Verified CLI service names in the current ve build:

Do not use ve rds_postgresql or ve rds_mssql; they return unknown command.

PostgreSQL CLI Pitfalls

CreateDBInstance uses --body JSON. For HA PostgreSQL, include both a Primary and a Secondary item in NodeInfo; a single primary node fails with Secondary Node Number is not equal to 1.

CreateDBAccount accepts AccountPrivileges = "Inherit,Login" for application login accounts. Do not use MySQL/Redis-style ReadWrite for PostgreSQL accounts.

Create the database with Owner set to the app account when possible. If migrations still fail on the default public schema, call ModifySchemaOwner for SchemaName = "public" and the application database/account before running migrations.

For CreateDatabase, omit CharacterSetName unless the accepted enum has been verified for that API call. A real CLI deployment rejected uppercase UTF8; the Terraform provider example uses lowercase utf8.

PostgreSQL instance creation takes several minutes. Even after the instance reports Running, account/database/schema/endpoint operations can briefly fail because the instance is in exclusive status. Retry those follow-up operations with short sleeps instead of recreating the instance.

Lifecycle and Cleanup Risk

RDS instance creation is long-running and billable. Lifecycle tests should create the smallest postpaid instance, wait until the engine-specific status is available, delete it immediately, and verify the engine-specific list/detail API no longer returns it.

Observed in cn-beijing:

• MySQL, PostgreSQL, and SQL Server instance lists returned 0.
• MySQL, PostgreSQL, and SQL Server allow-list read APIs returned successfully.

Existing allow lists are account resources and must not be deleted unless created by the current test run.

Redis Service Notes

Swagger/Explorer Gaps

scripts/fetch_swagger.py --service redis --action <Action> can fail with OpenAPI Explorer HTTP 500 for Redis actions including allow-list and instance lifecycle APIs. Fall back to ve redis <Action> --help for the JSON body schema.

Allow-List Cleanup Ordering

Calling DeleteAllowList immediately after DeleteDBInstance can fail with AllowListBindInstanceCannotDelete because the instance has not been fully removed. Wait until DescribeDBInstanceDetail returns not found, then delete the allow list.

DescribeAllowLists requires RegionId and has no useful name filter in CLI help. Passing AllowListName can still return an unfiltered list, so it cannot prove cleanup.

Correct cleanup proof: query the deleted allow-list ID directly and expect AllowListNotExist.

ve redis DescribeAllowListDetail --body '{"AllowListId":"acl-xxx"}'

Observed lifecycle note: creating an allow list with AllowListType set to IPv4 returned detail output with AllowListType shown as DualStack; do not use that field alone as an echo check.

Parameter Groups Need Pagination

DescribeParameterGroups requires RegionId, PageNumber, and PageSize. Calling it with only RegionId fails with:

Missing Params: PageNumber,PageSize

Observed in cn-beijing: the paginated call returned system default parameter groups for Redis 4.0, 5.0, 6.0, and 7.0.

Minimal Instance Parameters That Were Easy to Get Wrong

For the disposable Redis instance lifecycle test, the following details mattered:

• NoAuthMode uses close, not disabled.
• ConfigureNodes must include the subnet AZ, for example {"AZ":"cn-beijing-b"}.
• Deletion protection must be disabled for disposable tests.
• Poll DescribeDBInstanceDetail through Deleting until the detail API returns not found; only then clean dependent allow lists.

Verified lifecycle: created a minimal postpaid Redis 6.0 instance with one 512 MB shard, deleted it, confirmed DescribeDBInstances had no test instance, then deleted the associated allow list and verified AllowListNotExist.

Shell Cleanup Trap

With set -o pipefail, password snippets like tr -dc ... | head -c 14 can exit with code 141 because head closes the pipe. If used inside a cleanup-protected resource test, this can abort after prerequisites are created.

Use a generator that does not rely on an early-closing pipe, or temporarily disable pipefail around password generation. Do not print Redis passwords in logs.

Storage Service Notes

TOS Is Not Available in This ve Build

The current ve command list does not include tos. Running ve tos --help returns unknown command.

Do not troubleshoot TOS bucket operations as CLI parameter mistakes in this environment; there is no matching ve tos command to validate.

Use tosutil for TOS bucket/object operations when it is installed. Verified local tosutil v4.1.4 help exposes:

tosutil mb tos://bucket-name -acl=private -sc=STANDARD
tosutil cp ./dist/app.tar.gz tos://bucket-name/artifacts/app.tar.gz
tosutil presign tos://bucket-name/artifacts/app.tar.gz -vp=15min
tosutil stat tos://bucket-name/artifacts/app.tar.gz

If a deployment path cannot require tosutil, keep it optional and provide SSH/scp or user-provided artifact URL fallback.

File-System Creation Is Billable

EFS, FileNAS, and vePFS read paths worked in cn-beijing; all returned empty filesystem lists.

Creation is billable and may require zone/product sale checks. FileNAS and vePFS zone APIs include sale/status details; inspect those before choosing a zone.

veFaaS Service Notes

Dependent APIs Require FunctionId

ListSandboxes requires FunctionId; a dummy ID reaches the service and returns ResourceNotFound.

CreateTimer, CreateKafkaTrigger, and CreateSandbox all depend on an existing function ID. Validate function creation before testing dependent resources.

Delete order for disposable tests:

DeleteKafkaTrigger / DeleteTimer -> KillSandbox if needed -> DeleteFunction

Keep EnableVpc, TOS mount, NAS mount, and TLS log delivery disabled unless those integrations are specifically under test.

Observed in cn-beijing: ListFunctions returned Total: 0, and availability zones were cn-beijing-a through cn-beijing-d.

VKE Service Notes

Cluster APIs Use JSON Body Mode

CreateCluster and DeleteCluster use --body JSON mode.

ve vke CreateCluster --body '{
  "Name": "<cluster-name>",
  "ClusterConfig": {"SubnetIds": ["<subnet-id>"]},
  "PodsConfig": {
    "PodNetworkMode": "Flannel",
    "FlannelConfig": {"PodCidrs": ["172.16.0.0/16"]}
  },
  "ServicesConfig": {"ServiceCidrsv4": ["172.20.0.0/16"]},
  "Tags": [{"Key": "publish-by", "Value": "deploy-skill"}]
}'
ve vke DeleteCluster --body '{"Id":"<cluster-id>","Force":true}'

Lifecycle Risk

Cluster creation is high-cost and long-running, and can create dependent ECS, network, log, and addon resources. Do not run it as a casual smoke test.

If explicitly approved, record every returned resource ID, use DeleteCluster with an explicit retention/deletion policy, and verify ListClusters no longer returns the test cluster. A newly created cluster can reject deletion while its status is Creating or addon sync is still Progressing; poll ListClusters until the cluster reaches Running/Ok, then delete.

Observed in cn-beijing: clusters, node pools, kubeconfigs, and addons all returned empty lists; supported addon/resource-type discovery worked.

Validation note: a no-node Flannel cluster with Tags: [{"Key":"publish-by","Value":"deploy-skill"}] was created in cn-beijing, the tag appeared in ListClusters, then DeleteCluster removed it after the cluster reached Running/Ok.

Addons That Affect Basic Deployments

ListSupportedAddons returned both core-dns and cr-credential-controller as Unmanaged addons.

• core-dns is the cluster DNS/service-discovery foundation. If workloads cannot resolve Kubernetes service names, check ListAddons/cluster addon state before debugging application DNS.
• cr-credential-controller supports passwordless pulls from Volcengine CR. Without it, private CR images may require explicit image pull credentials, and Pods can fail with image pull authentication errors.

VPC Service Notes

Creation Has Short Consistency Windows

CreateVpc can return before the VPC accepts child resources. In a cn-beijing ECS+EIP smoke test, creating a subnet immediately after CreateVpc failed once with:

InvalidVpc.InvalidStatus: The specified VPC is not in the correct status for the request.

Poll DescribeVpcs --VpcIds.1 "$vpc_id" until .Result.Vpcs[0].Status == "Available" before creating subnets or security groups. Similarly, CreateSecurityGroup can return before ingress rules are accepted; wait until DescribeSecurityGroups --SecurityGroupIds.1 "$sg_id" returns the group before AuthorizeSecurityGroupIngress, or retry InvalidSecurityGroup.InvalidStatus.

Security Group Name Filter Is Indexed

DescribeSecurityGroups does not accept --SecurityGroupName. Passing it is ignored by the CLI because it is not in help output, so the command returns an unfiltered page and cannot prove cleanup.

Use --SecurityGroupNames.1 instead:

ve vpc DescribeSecurityGroups --SecurityGroupNames.1 "cli-skill-test-sg"

After deleting a test security group, confirm cleanup with the same indexed filter and require TotalCount: 0.

Security Group Operations Are Async

CreateSecurityGroup, AuthorizeSecurityGroupIngress, RevokeSecurityGroupIngress, and DeleteSecurityGroup return AsyncTaskId.

AuthorizeSecurityGroupIngress uses flat parameters such as --PortStart, --PortEnd, --Protocol, and --CidrIp; do not use --SourceCidrIp or Permissions.* for this CLI command.

For small test resources the next operation usually succeeds immediately, but cleanup verification should still query after delete. The default egress all rule is created automatically and does not need to be revoked before deleting the test security group.

Verified lifecycle: created a disposable security group, added/revoked one ingress rule, deleted it, and verified the indexed name filter returned no match.

EIP Safety

DescribeEipAddresses returned existing EIPs attached to NAT gateways in cn-beijing. Treat them as user resources; never release or disassociate an EIP unless it was created by the current test run.