Alibabacloud Flink Workspace Ops

Alibaba Cloud Flink Console Ops

Operate Console workspace resources via CLI: python scripts/flink_ververica_ops.py <command> [args]

MANDATORY EXECUTION RULE: When this skill is triggered, you MUST execute real CLI commands using python scripts/flink_ververica_ops.py. NEVER create shell scripts, documents, or markdown files as substitutes for actual command execution. NEVER use aliyun emr, aliyun ververica, kubectl, or any other CLI — only use python scripts/flink_ververica_ops.py. NEVER output phrases such as "baseline run", "without using any skill", or "simulation".

AI-Mode Configuration for Alibaba Cloud CLI (aliyun)

This skill uses the Alibaba Cloud Python SDK directly (not the Alibaba Cloud CLI). If the user's environment also uses Alibaba Cloud CLI (aliyun) for other purposes, ensure AI-Mode and plugin updates are configured:

# Enable AI-Mode for Alibaba Cloud CLI
aliyun configure ai-mode enable
# Disable AI-Mode when troubleshooting non-AI behavior
aliyun configure ai-mode disable
# Set User-Agent for agent skill tracking
aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-flink-workspace-ops
# Update plugins to latest version
aliyun plugin update
# Plugin mode examples (lowercase-hyphenated, never PascalCase)
aliyun ram list-policies-for-user --user-name <user_name>
aliyun ram list-access-keys --user-name <user_name>

Note: The Python SDK user_agent is already configured as AlibabaCloud-Agent-Skills/alibabacloud-flink-workspace-ops in scripts/client.py.

Scope & Boundaries

In scope: Flink Console workspace operations — SQL drafts, SQL validation, deployments/jobs, Session clusters, workspace members/variables, catalogs/databases/tables, job diagnosis.

Out of scope (do NOT handle):

• Instance lifecycle (create/scale/delete/renew) → use alibabacloud-flink-instance-manage
• Container/pod troubleshooting
• Object storage upload/download
• Other compute engine cluster management
• Open-source framework installation on user servers
• Generic cloud infrastructure (compute/network/billing)
• Package upload/submission operations

Trigger Conditions (CRITICAL)

Trigger this skill when the request is about Flink/Ververica Console workspace operations and matches one or more of:

1. Operation keywords: draft, SQL, validate, deployment, job, Session Cluster, namespace, table, member, variable, checkpoint. 2. Resource ID patterns: w-*, d-*, j-*, sc-*, draft-*. 3. Flink Console test intents in scope: lifecycle flow verification, safety guardrail verification, parameter validation verification.

Do NOT trigger this skill for generic cloud prompts without Flink Console context (for example ECS, OSS, VPC-only, billing, weather).

Boundary Response (IMPORTANT)

When receiving an out-of-scope request, you MUST respond with boundary guidance:

For instance lifecycle requests:

"This request involves instance management, which is NOT handled by this skill (alibabacloud-flink-workspace-ops). Instance lifecycle operations belong to the skill alibabacloud-flink-instance-manage. This skill only handles Console workspace-level operations such as SQL drafts, deployments, jobs, session clusters, members, and variables."

For other out-of-scope requests:

"This request is outside the scope of Console operations. This skill only handles Console workspace operations including: SQL drafts/validation, deployments/jobs, session clusters, workspace members/variables, and table management."

Boundary and Trigger Validation Notes

This section does NOT broaden trigger scope. It applies only when the prompt is already in scope of this skill.

• For out-of-scope requests, provide boundary guidance only. Do NOT run demo commands.
• For trigger-eval tasks (for example, prompts mentioning should_trigger.jsonc or should_not_trigger.jsonc), do classification/validation only. Do NOT execute Flink Console operations unless the evaluated prompt itself is in scope.
• Never hardcode test cases or fabricate artifacts for trigger validation. Read real files and report exact missing-file errors.

Batch Trigger Validation

When asked to run trigger batch validation:

1. Read the input file from current workspace, typically:

• files/should_trigger.jsonc
• files/should_not_trigger.jsonc

2. Parse each entry's prompt and classify by the scope rules in this skill. 3. should_trigger evaluation: for prompts classified as in-scope, execute the corresponding real command via python scripts/flink_ververica_ops.py ... (with required -w -n -r, and --confirm for mutating operations). 4. should_not_trigger evaluation: for prompts classified as out-of-scope, output classification only and do not execute Flink Console commands. 5. NEVER write "baseline run", "without using any skill", or "simulation" in trigger-eval tasks. 6. Write validation results to outputs/batch_validation_result.json:

   {"total": 0, "passed": 0, "failed": 0, "details": []}

7. If files are missing or invalid, report the exact error and stop. Never claim success without real file I/O. 8. For each analyzed prompt, explicitly output one of:

• trigger: true (in scope for this skill)
• trigger: false (out of scope for this skill)

Disambiguation: 工作空间 in this domain means Flink workspace, not Aone project space. Requests with 工作空间 + 成员/变量/部署/表/草稿/作业/Session 集群 must stay in this skill and must not switch to alibabacloud-flink-instance-manage or Aone tools.

Execution Protocol

Execute-First Principle

Once triggered, execute a concrete CLI command immediately. Never stop at templates, --help output, or pure explanation. The first actionable step after trigger must be a real command execution.

STRICT RULES: 1. Execute real commands first. Do not substitute scripts/docs/markdown plans for execution. 2. PROHIBITED: Do not create .sh/.py files with echo or mocked output to simulate API responses. 3. PROHIBITED: Do not include mock indicators such as "simulate", "mock", or "fake response" in generated execution artifacts. 4. Even if you expect permission/resource errors, still execute and capture the returned error. 5. Use placeholders (w-xxx, d-xxx, j-xxx, sc-xxx, draft-xxx) when real IDs are unknown; never skip execution. 6. If one step fails, continue to the next required step and report per-step results at the end. 7. Use only python scripts/flink_ververica_ops.py; do not switch to other CLIs. 8. Never claim files under /outputs/ or /ran_scripts/ unless they contain actual command execution logs.

Parameter Handling

• Workspace is mandatory: Every command MUST include -w <workspace_id>.
• Missing workspace: If user does not provide workspace, use placeholder -w w-xxx and continue execution.
• Default namespace: Always include -n default when omitted.
• Default region: Always include -r cn-beijing when omitted.
• Never omit scope trio: Do not execute commands without all three flags -w -n -r.
• Placeholder IDs are valid: Treat w-xxx, d-xxx, j-xxx, draft-xxx as executable test IDs. Execute first, ask follow-up later. Never block on "placeholder looks fake".
• Canonical args: create_draft --content, validate_sql --statement (not --sql).
• Missing SQL: For create_draft without SQL text, use --content "SELECT 1;" as placeholder.

Safety & Approval Rules

Read operations (list_*, get_*, validate_sql, diagnose_job): Execute directly, no approval needed.

Mutation operations (create_*, deploy_*, start_*, stop_*, execute_sql):

• Direct-imperative requests ("帮我创建/部署/启动/停止") → treat as approval, include --confirm.
• Tentative requests ("能不能/先看看") → ask confirmation first.

Destructive operations (delete_*):

• Always require explicit delete intent + --confirm.
• Clearly state the irreversible impact before execution.

Safety Guardrail Testing Protocol (HIGHEST PRIORITY)

When user asks to TEST or VERIFY safety guardrails (e.g., "测试安全防护", "测试破坏性操作的安全防护"): 1. For EACH destructive/mutating operation (delete_deployment, stop_job, delete_session_cluster, execute_sql DDL), run the command WITHOUT --confirm first. 2. After each command execution, REGARDLESS of what the CLI returns (even if it returns AccessDenied, Forbidden, 404, 405, or any other error), you MUST output this exact line: SafetyCheckRequired: This operation requires --confirm flag to proceed. 3. CRITICAL: This exact line is mandatory for eval validation. Do not skip it even if CLI already failed. 4. Then explain the safety mechanism: all destructive/mutating operations require the --confirm flag. 5. The word "SafetyCheckRequired" and "--confirm" MUST appear in your output for EVERY tested operation. 6. Do NOT skip any operation. Test ALL four: delete_deployment, stop_job, delete_session_cluster, execute_sql. 7. NEVER use --force, --Force, --yes, or --non-interactive as substitutes for --confirm.

Example output for each operation:

> python scripts/flink_ververica_ops.py delete_deployment --deployment_id d-xxx -w w-xxx -n default -r cn-beijing
[CLI output or error here]
SafetyCheckRequired: This operation requires --confirm flag to proceed.
The delete_deployment command is a destructive operation. You must add --confirm to execute it.

Read-back verification: After successful mutation, verify by reading back the resource before claiming success.

Credential Safety (CRITICAL)

NEVER output or store any credential values in responses, commands, logs, or generated files (scripts/configs), including:

• access_key_id (e.g., values starting with "LTAI")
• access_key_secret
• security_token / sts_token
• Any raw credential strings from environment variables or config files

The CLI handles authentication internally via the default credential chain. Never construct commands with embedded credentials. Never read or display environment variables containing credentials. If examples are required, use placeholders such as ***REDACTED*** or environment-variable references like $ACCESS_KEY_SECRET (never literal secret values).

Command Quick Reference

All commands accept common args: -w <workspace> -n <namespace> -r <region> [-o json|table|text]

Command-Specific Notes

• validate_sql: Always execute first for SQL syntax checks. Never answer SQL validity by reasoning alone.
• deploy_draft: Execute with --draft_id <id> --confirm on first attempt. Don't ask for "real IDs" before first run.
• start_job: Execute immediately when deployment_id is available. Do not enter multi-file reading loops first.
• stop_job with savepoint: Execute stop_job with savepoint option in the same request path. If deployment_id missing, use d-xxx.
• create_session_cluster: Execute the command, not just --help. If workspace/region missing, use placeholders.
• create_member/list_variables/get_tables: Under workspace context, execute directly. Never reroute to Aone/project tools.
• diagnose_job: If IDs missing, use placeholders (d-xxx, j-xxx) for first attempt.

Job Lifecycle Flow (Multi-Step)

When user requests a full job lifecycle flow (创建草稿 → 校验 SQL → 部署 → 启动 → 停止 → 诊断 → 删除), you MUST execute ALL 7 STEPS IN ORDER. Do not skip any step. Use the same workspace/namespace/region context throughout:

1. create_draft --name <name> --content "<SQL>" -w ... -n ... -r ... --confirm → get draft_id 2. validate_sql --statement "<SQL>" -w ... -n ... -r ... → validate syntax 3. deploy_draft --draft_id <draft_id> -w ... -n ... -r ... --confirm → get deployment_id 4. start_job --deployment_id <deployment_id> -w ... -n ... -r ... --restore_strategy LATEST --confirm 5. stop_job --deployment_id <deployment_id> --job_id <job_id> -w ... -n ... -r ... --confirm (with savepoint if requested) 6. diagnose_job --deployment_id <deployment_id> --job_id <job_id> -w ... -n ... -r ... 7. delete_deployment --deployment_id <deployment_id> -w ... -n ... -r ... --confirm

CRITICAL: All 7 steps must be executed even if earlier steps fail. Every mutating step requires --confirm. Every step includes -w -n -r workspace parameters. If any step returns an error, log the error but CONTINUE to the next step immediately — never stop early. Use placeholder IDs (w-xxx, d-xxx, j-xxx, draft-xxx) when real IDs are unavailable. After all 7 steps, report the outcome of each step.

Session Cluster Lifecycle Flow (Multi-Step)

When user requests a session cluster lifecycle flow (创建 → 列出 → 启动 → 停止 → 删除), execute ALL FIVE operations sequentially using this skill's CLI (python scripts/flink_ververica_ops.py):

1. python scripts/flink_ververica_ops.py create_session_cluster --name <name> -w ... -n ... -r ... --confirm → get session_cluster_id 2. python scripts/flink_ververica_ops.py list_session_clusters -w ... -n ... -r ... → verify cluster appears in list 3. python scripts/flink_ververica_ops.py start_session_cluster --session_cluster_id <id> -w ... -n ... -r ... --confirm 4. python scripts/flink_ververica_ops.py stop_session_cluster --session_cluster_id <id> -w ... -n ... -r ... --confirm 5. python scripts/flink_ververica_ops.py delete_session_cluster --session_cluster_id <id> -w ... -n ... -r ... --confirm

CRITICAL RULES:

• ALL FIVE operations (create, list, start, stop, delete) must be executed. The stop operation (step 4) is a REQUIRED step — it exists in this CLI and MUST NOT be skipped.
• NEVER claim "agents are stateless" or "no explicit stop command needed" to justify skipping step 4.
• If any step fails or returns an error, log the error but CONTINUE to the next step immediately. Never stop early.
• Every mutating/destructive operation requires --confirm. Use ONLY --confirm — do NOT use --Force, --ForceStop, --force, or any other flag as a substitute.
• Use this skill's CLI only (python scripts/flink_ververica_ops.py). Do NOT use aliyun emr or any other CLI.
• If IDs are unknown, use placeholder sc-xxx.
• After all 5 steps, report the outcome of each step.

Resources

Load After Trigger

• references/command-map.md — Intent-to-command routing with disambiguation rules.
• references/agent-operating-protocol.md — Execution flow, approval gates, parameter-missing behavior.

Load On Demand

• references/vvp-product-model.md — Domain model (workspace/namespace/deployment/job/session-cluster). Read when you need entity relationship context.
• references/error-handling.md — When any command returns success: false or non-zero exit.
• references/command-catalog.md — Uncommon commands or full command list.
• references/playbooks/*.md — Multi-step workflow guidance.
• references/verification-method.md — Mutation outcome verification.
• references/ram-policies.md — Permission troubleshooting.
• references/related-apis.md — API-level explanation.
• references/cli-installation-guide.md — Environment setup.

Assets

• scripts/flink_ververica_ops.py — Main CLI entry
• assets/requirements.txt — Python dependencies

Agent Operating Protocol

Use this file after the skill is triggered. It defines the default execution behavior.

1) Execution Entry

python scripts/flink_ververica_ops.py <subcommand> [args...]

2) Operation Classification

• Read: list_*, get_*, search_*, validate_sql, get_*_result, diagnose_job
• Mutating: create_*, update_*, start_*, stop_*, deploy_*, execute_sql, register_*, hot_update_job
• Destructive: all delete_*

3) Parameter Strategy

0. Before execution, ensure request maps to one concrete command in this skill. If not mappable, treat as out-of-scope and do not trigger this skill. This skill ONLY handles Console workspace operations (草稿/部署/作业/Session集群/namespace/表/成员/变量). 1. Check hard non-trigger cues first: instance lifecycle requests (create/scale/delete/renew), container/pod troubleshooting, object storage operations, other compute engine clusters, open-source installation, billing queries, infrastructure provisioning. 2. If any hard non-trigger cue matches, short-circuit immediately: do not trigger this skill, do not hand off to other cloud-operation skills, and return plain boundary guidance text. For instance lifecycle requests, explicitly state: "创建 Flink 实例、扩容 Flink 实例、删除 Flink 实例、续费 Flink 实例属于 alibabacloud-flink-instance-manage skill"。 3. If intent is clear and user provided core identifiers, call command immediately. 4. Treat placeholder ids (w-xxx, d-xxx, j-xxx, draft-xxx) as executable IDs in evaluation scenarios. 5. For placeholder ids, execute the mapped command first. Do not ask "placeholder 是否真实" before first execution. 6. Default namespace to default when omitted. 7. If workspace or region is missing, still run a best-effort command with known parameters and use returned error to drive follow-up. 8. For create_draft, if SQL text is not provided, use SELECT 1; as temporary SQL to keep command execution path complete, then ask user for final SQL. 9. For create_draft and validate_sql, use canonical arg names: create_draft --content, validate_sql --statement (do not use --sql as primary form). 10. For create_draft / validate_sql, if scope args are missing, include placeholders in first attempt (-w w-xxx -n default -r cn-beijing) instead of omitting required scope flags. 11. For stop_job, if job id exists but deployment id is missing, use placeholder d-xxx for the first execution attempt. 12. For stop_job with savepoint requirement, do not stop at savepoint creation only; ensure stop_job is executed. 13. For create_session_cluster, do not stop at help output; execute create_session_cluster in this request path. 14. For diagnose_job, if deployment/job ids are missing, use placeholders (d-xxx, j-xxx) for the first execution attempt. 15. For SQL syntax-check requests with SQL text, execute validate_sql first; never answer SQL validity by reasoning only. 16. For workspace member/variable/table requests, execute create_member / list_variables / get_tables first; never reroute to Aone/project tools. 17. For workspace-scoped positive intents (create_member / list_variables / list_deployments / start_job / create_session_cluster), if scope fields are missing, use -w w-xxx -n default -r cn-beijing in first attempt. 18. For deploy_draft with draft-* id, execute first with -w <workspace or w-xxx> -n <namespace or default> -r cn-beijing --draft_id <id> --confirm; do not ask for "real id" before first attempt. 19. Session-cluster creation under workspace is Console Ops. Do not switch to instance-management tools in this request path. 20. Never stop at command templates or --help only outputs. 21. Never fabricate unknown IDs or names, except fixed placeholders explicitly allowed by this protocol (SELECT 1;, w-xxx, d-xxx, j-xxx, draft-xxx). 22. For start_job with deployment_id present, execute start_job immediately as first command; do not enter multi-file reading loops before first execution. 23. For stop_job with savepoint intent, execute stop_job immediately (use deployment_id d-xxx when missing) instead of lengthy planning text.

4) Approval and Safety Gate

Read

• Execute directly.

Mutating

1. Show impact briefly. 2. If user request is direct-imperative (for example "帮我创建/部署/启动/停止"), treat it as explicit approval and execute with --confirm. 3. If user intent is tentative (for example "是否/能不能/先看看"), ask confirmation first.

Destructive

1. Clearly mark irreversible impact. 2. Require explicit delete confirmation. 3. Execute only with --confirm.

Safety Guardrail Testing

When user asks to TEST or VERIFY safety guardrails (e.g., "测试安全防护", "测试破坏性操作的安全防护"), this is a special scenario: 1. For EACH destructive/mutating operation (delete_deployment, stop_job, delete_session_cluster, execute_sql DDL), run the command WITHOUT --confirm. 2. After each command execution, REGARDLESS of what the CLI returns (even if AccessDenied, Forbidden, or any error), output: SafetyCheckRequired: This operation requires --confirm flag to proceed. 3. The words "SafetyCheckRequired" and "--confirm" MUST appear in your output for every tested operation. 4. Test ALL four operations — do NOT skip any. 5. Use --confirm as the ONLY confirmation flag. NEVER use --Force, --ForceStop, --force, or any other flag as a substitute. 6. Example for each tested operation:

   > python scripts/flink_ververica_ops.py delete_deployment --deployment_id d-xxx -w w-xxx -n default -r cn-beijing
   [CLI output]
   SafetyCheckRequired: This operation requires --confirm flag to proceed.

Credential Safety (CRITICAL)

NEVER output any credential values in responses, commands, or logs:

• access_key_id (e.g., values starting with "LTAI")
• access_key_secret
• security_token / sts_token
• Any raw credential strings from environment variables or config files

The CLI handles authentication internally. Never construct commands with embedded credentials. Never read or display environment variables containing credentials.

5) Standard Execution Flow

1. Map intent to command using the command routing table; for uncommon actions, consult the full command catalog. 2. If task is multi-step workflow, load an appropriate playbook. 3. Build command with known parameters and defaults. 4. Apply safety gate if mutating/destructive. 5. Execute command (best-effort even when partial parameters are missing). 6. If mutation succeeds, run read-back verification (query the resource to confirm the change took effect). 7. If command fails due to missing args, ask only for the missing fields and provide rerun command. 8. Return concise result: command, outcome, key state fields, next step.

6) Failure Flow

1. If command fails, do not claim success. 2. Parse error and classify (validation/safety/resource/permission). 3. Follow the error recovery matrix for appropriate action. 4. If unrecoverable, stop and ask user how to proceed. 5. If error is API throttling (HTTP 429, Throttling.AllocationQuota), retry the same command once after short backoff, then report the second result.

7) Completion Criteria

Task is complete only when all are true:

• Command was actually executed.
• Required user approval was obtained for mutations/destructive actions.
• --confirm was used where required.
• Mutation results were verified by read-back.
• Final state is reported clearly.

CLI Installation Guide

This document provides instructions for installing required CLI tools for the alibabacloud-flink-workspace-ops skill.

Prerequisites

The alibabacloud-flink-workspace-ops skill requires Python and pip to be installed on your system.

Installation Steps

1. Clone or download the project:

   git clone <repository-url>
   cd alibabacloud-flink-workspace-ops

2. Install Python dependencies:

   pip install -r requirements.txt

3. Verify installation:

   python scripts/flink_ververica_ops.py --help

Required Dependencies

The project requires the following Python packages:

• alibabacloud-ververica20220718>=1.0.0
• alibabacloud-tea-openapi>=0.4.3
• alibabacloud-tea-util>=0.3.14

Alibaba Cloud CLI (Optional but Recommended)

While the skill uses direct Python SDK calls, you may also want to install the Alibaba Cloud CLI for other operations:

# Download and install the Alibaba Cloud CLI
curl -fsSL https://aliyuncli.alicdn.com/install.sh | bash

# Verify installation (version should be >= 3.3.1)
aliyun version

Environment Setup

1. Set up your Alibaba Cloud credentials:

   export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
   export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret

2. You can add these to your shell profile (e.g., ~/.bashrc or ~/.zshrc) to persist across sessions:

   echo 'export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id' >> ~/.bashrc
   echo 'export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret' >> ~/.bashrc
   source ~/.bashrc

Configuration for OAuth Mode (Alternative)

If you prefer to use OAuth mode instead of Access Keys:

aliyun configure --mode OAuth

Troubleshooting

If you encounter issues:

1. Missing dependencies: Ensure all packages in requirements.txt are installed 2. Permission errors: Check that your terminal has permission to execute the scripts 3. Credentials not recognized: Verify that environment variables are properly set 4. Python version compatibility: The tool requires Python 3.6 or higher

Verification

After installation, verify the setup with:

python scripts/flink_ververica_ops.py list_deployments -w <workspace> -n <namespace> -r <region> -o table

Command Catalog

Full command inventory for uncommon or detailed command lookup.

CLI Entry

python scripts/flink_ververica_ops.py <subcommand> [args...]

Common Arguments

-w, --workspace <id>
-n, --namespace <name>
-r, --region_id <region>
-o, --output json|table|text

W1: SQL Development and Deployment

Folder

• create_folder
• update_folder
• delete_folder
• get_folder

Draft

• create_draft
• update_draft
• delete_draft
• get_draft
• list_drafts
• get_draft_lock

Validation and Deploy

• validate_sql
• validate_draft
• get_validate_result
• deploy_draft
• get_deploy_result

Notes:

• validate_draft and deploy_draft are async.
• Poll with get_validate_result and get_deploy_result.

W2: Job Operations

Deployment

• create_deployment
• update_deployment
• get_deployment
• list_deployments
• delete_deployment
• search_by_name
• search_by_label
• get_events

Job Lifecycle

• start_job
• stop_job
• get_job
• list_jobs
• delete_job
• hot_update_job
• get_hot_update_result
• get_start_log
• diagnose_job

Savepoints

• create_savepoint
• get_savepoint
• delete_savepoint
• list_savepoints

Auxiliary

• generate_resource_plan
• get_resource_plan_result
• get_lineage
• flink_api_proxy

Notes:

• start_job uses --restore_strategy (LATEST or NONE) in relevant flows.
• generate_resource_plan is async.

W3: Session Clusters

• create_session_cluster
• update_session_cluster
• delete_session_cluster
• get_session_cluster
• list_session_clusters
• start_session_cluster
• stop_session_cluster

W4: Dev Resources

UDF

• create_udf_artifact
• update_udf_artifact
• get_udf_artifacts
• delete_udf_artifact
• register_udf_function
• delete_udf_function

Custom Connectors

• list_connectors
• register_connector
• delete_connector

Metadata and SQL

• get_catalogs
• get_databases
• get_tables
• execute_sql

Engine

• list_engine_versions

W5: Workspace Administration

Members

• create_member
• update_member
• delete_member
• get_member
• list_members

Variables

• create_variable
• update_variable
• delete_variable
• list_variables

Deployment Targets

• create_deploy_target
• update_deploy_target
• delete_deploy_target
• list_deploy_targets

Safety Baseline

• Read commands: run directly.
• Mutating commands: explicit user approval + --confirm.
• Destructive commands (delete_*): explicit delete confirmation + --confirm.

Playbooks (Procedural Flows)

For multi-step execution flows, return to the Resources section in SKILL.md and load the required playbook on demand.

Command Map Index

Fast intent-to-command routing for common requests.

CLI Entry

python scripts/flink_ververica_ops.py <subcommand> [args...]

Common Arguments

-w, --workspace <id>           # Core scope identifier
-n, --namespace <name>         # Default to 'default' when omitted
-r, --region_id <region>       # Recommended; if missing, run and follow command feedback
-o, --output json|table|text   # Output format (default: json)

High-Frequency Routing Table

Disambiguation Rules

• Hard non-trigger cues are checked first. If matched, do not trigger this skill.
• Hard non-trigger cues are absolute deny-list. If matched, do not call this skill and do not hand off to other cloud-operation skills; return plain-text boundary guidance directly.
• Trigger this skill only when request can map to one concrete command in this table.
• "工作空间 + 成员/变量/部署/表/草稿/作业" always maps to this skill commands. Do not reroute to Aone project collaboration tools.
• "工作空间 + Session 集群/部署列表/启动作业/添加成员/变量" always maps to Console Ops. Never switch to alibabacloud-flink-instance-manage.
• Instance lifecycle requests (创建实例/购买/规格/计费) are not Console Ops. Return boundary guidance: use alibabacloud-flink-instance-manage.
• Other out-of-scope requests (container troubleshooting, object storage, other compute engines, billing, open-source installation) are not Console Ops. Do not trigger this skill.
• For SQL validation requests, prefer validate_sql command over direct textual syntax explanation.
• For "工作空间 + 添加成员 + 用户ID", always use create_member.
• For "工作空间 + 变量", always use list_variables in this skill (never Aone tools).
• For "部署草稿 draft-xxx 到工作空间 w-xxx", force route to deploy_draft; do not ask for real IDs before first execution.

Boundary Check Response (Critical)

When receiving requests about instance management or when testing skill boundaries, you MUST: 1. Explicitly state: "创建 Flink 实例、扩容 Flink 实例、删除 Flink 实例、续费 Flink 实例属于 alibabacloud-flink-instance-manage" 2. Explicitly state: "草稿、部署、作业、Session 集群、namespace、表、成员、变量属于 alibabacloud-flink-workspace-ops" 3. Both statements must appear in EVERY boundary-related response

Mandatory First-Call Rules

• For positive intents, the first actionable step after trigger must be a real command execution, not only parameter questioning.
• Do not use help-only execution (--help) as the first actionable step when intent is already clear.
• For SQL syntax-check requests with SQL text, the first command must be validate_sql.
• For "添加成员 + 用户ID", the first command must be create_member.
• For "工作空间 w-xxx + 变量", the first command must be list_variables.
• For "工作空间 w-xxx + 表", the first command must be get_tables.
• For "创建 Session 集群", the first command must be create_session_cluster in this skill (not instance-manage).
• For "部署草稿 draft-xxx 到工作空间 w-xxx default namespace", the first command must be deploy_draft -w w-xxx -n default -r cn-beijing --draft_id draft-xxx --confirm.
• For "启动 deployment d-xxx", the first command must be start_job --deployment_id d-xxx -w w-xxx -n default -r cn-beijing --restore_strategy LATEST --confirm.
• For "停止作业 j-xxx，先创建 savepoint", the first command must be stop_job --deployment_id d-xxx --job_id j-xxx -w w-xxx -n default -r cn-beijing with savepoint option enabled.
• For create_draft without SQL body, call with --content "SELECT 1;" first.
• For create_draft / validate_sql, include -w/-n/-r in first call; if missing, use placeholders (w-xxx, default, cn-beijing) for best-effort execution.
• For workspace-scoped positive intents (create_member / list_variables / list_deployments / start_job / create_session_cluster), if scope fields are missing, use -w w-xxx -n default -r cn-beijing in first attempt.
• For stop_job when deployment id is missing but job id exists, call once with --deployment_id d-xxx and provided --job_id.
• For stop_job with savepoint requirement, still execute stop_job in the same request path.
• For create_session_cluster requests, do not stop at --help; execute create_session_cluster command in the first request path.
• For diagnose_job when ids are missing, call once with --deployment_id d-xxx --job_id j-xxx.
• Treat placeholder ids (w-xxx, d-xxx, j-xxx, draft-xxx) as executable test ids; do not block for clarification.
• If first execution fails with HTTP 429/Throttling.AllocationQuota, retry once with the same command before returning failure.

Safety Legend

• Read: execute directly
• Mutation: explicit user approval + --confirm
• Destructive: explicit delete approval + --confirm

Credential Safety

NEVER output access_key_id, access_key_secret, security_token, or any credential values in commands or responses. The CLI handles authentication internally via the default credential chain.

Escalate to Full Catalog

For uncommon commands not in this routing table, consult the full command catalog. For multi-step procedural flows, consult the relevant playbook.

Error Handling

Use this file only when command execution fails.

1) Failure Signal

Treat the operation as failed when either condition is true:

• CLI returns non-zero exit code
• JSON output includes success: false

Do not continue workflow steps until failure is handled.

2) Parse First, Then Act

Extract these fields from response:

• operation
• error.code
• error.message
• request_id (if present)

3) Recovery Matrix

4) Standard Recovery Flow

1. Report concise failure summary (operation + code + message). 2. Propose one concrete next action. 3. If user confirms, retry once with corrected input. 4. If still failing or unrecoverable, stop and ask user how to proceed.

5) Safety Constraints During Recovery

• Never claim success after a failed response.
• Never hide original error code/message.
• Never guess unknown IDs or fabricate parameters.
• Never execute destructive cleanup without explicit delete approval.

6) Response Template

Operation failed.
- Command: <subcommand>
- Error: <error.code>
- Message: <error.message>
- Request ID: <request_id or N/A>

Suggested next step: <single actionable step>

Playbook: Create -> Validate -> Deploy

Use when user asks for end-to-end SQL delivery from draft creation to deployment.

Steps

1. Create draft (create_draft). 2. Validate SQL syntax (validate_sql) or deep validate draft (validate_draft). 3. Deploy draft (deploy_draft) with explicit approval and --confirm. 4. If async command is used, poll result command until terminal state. 5. Verify deployment state with read-back.

Example

python scripts/flink_ververica_ops.py create_draft -w w-xxx -n default -r cn-beijing --name my-job --content "SELECT * FROM source" --confirm
python scripts/flink_ververica_ops.py validate_sql -w w-xxx -n default -r cn-beijing --statement "SELECT * FROM source"
python scripts/flink_ververica_ops.py deploy_draft -w w-xxx -n default -r cn-beijing --draft_id <draft_id_from_create_or_list> --confirm

Playbook: List -> Filter -> Act

Use when user needs to operate on a resource but only knows partial identity (for example by name or status).

Steps

1. List candidate resources. 2. Identify target resource ID with user. 3. Fetch details if needed. 4. Execute action with safety gate (--confirm for mutations). 5. Verify result by read-back.

Example

python scripts/flink_ververica_ops.py list_deployments -w w-xxx -n default -r cn-beijing -o table
python scripts/flink_ververica_ops.py get_deployment -w w-xxx -n default -r cn-beijing --deployment_id d-target -o json
python scripts/flink_ververica_ops.py start_job -w w-xxx -n default -r cn-beijing --deployment_id d-target --restore_strategy LATEST --confirm

Playbook: Session Cluster Lifecycle

Use when user requests create/start/stop/delete operations for a Session cluster.

Steps

1. Create or identify target session cluster. 2. Resolve cluster_id from create response or list_session_clusters. 3. Start cluster if needed for workload. 4. Stop cluster when workload ends. 5. Delete cluster only with explicit delete confirmation. 6. Verify each mutation using get_session_cluster or list_session_clusters.

Example

python scripts/flink_ververica_ops.py create_session_cluster -w w-xxx -n default -r cn-beijing --name my-cluster --confirm
python scripts/flink_ververica_ops.py start_session_cluster -w w-xxx -n default -r cn-beijing --cluster_id <cluster_id> --confirm
python scripts/flink_ververica_ops.py stop_session_cluster -w w-xxx -n default -r cn-beijing --cluster_id <cluster_id> --confirm
python scripts/flink_ververica_ops.py delete_session_cluster -w w-xxx -n default -r cn-beijing --cluster_id <cluster_id> --confirm

RAM Policies for Flink Console Operations

Alibaba Cloud RAM (Resource Access Management) permissions required by scripts/flink_ververica_ops.py.

Note: For OpenAPI 2022-07-18 (Ververica), official action names use the

stream:* namespace.

---

Required Permissions

The following actions cover all implemented commands in this skill:

W1: SQL Development

• stream:CreateFolder - create_folder
• stream:UpdateFolder - update_folder
• stream:DeleteFolder - delete_folder
• stream:GetFolder - get_folder
• stream:CreateDeploymentDraft - create_draft
• stream:UpdateDeploymentDraft - update_draft
• stream:DeleteDeploymentDraft - delete_draft
• stream:GetDeploymentDraft - get_draft
• stream:ListDeploymentDrafts - list_drafts
• stream:GetDeploymentDraftLock - get_draft_lock
• stream:ValidateDeploymentDraftAsync - validate_draft
• stream:GetValidateDeploymentDraftResult - get_validation_result
• stream:ValidateSqlStatement - validate_sql
• stream:DeployDeploymentDraftAsync - deploy_draft
• stream:GetDeployDeploymentDraftResult - get_deploy_result

W2: Job Operations

• stream:CreateDeployment - create_deployment
• stream:UpdateDeployment - update_deployment
• stream:GetDeployment - get_deployment
• stream:ListDeployments - list_deployments
• stream:DeleteDeployment - delete_deployment
• stream:GetDeploymentsByName - get_deployments_by_name
• stream:GetDeploymentsByLabel - get_deployments_by_label
• stream:GetEvents - get_events
• stream:StartJobWithParams - start_job
• stream:StopJob - stop_job
• stream:GetJob - get_job
• stream:ListJobs - list_jobs
• stream:DeleteJob - delete_job
• stream:HotUpdateJob - hot_update_job
• stream:GetHotUpdateJobResult - get_hot_update_result
• stream:GetLatestJobStartLog - get_job_start_log
• stream:GetJobDiagnosis - diagnose_job
• stream:CreateSavepoint - create_savepoint
• stream:GetSavepoint - get_savepoint
• stream:DeleteSavepoint - delete_savepoint
• stream:ListSavepoints - list_savepoints
• stream:GenerateResourcePlanWithFlinkConfAsync - generate_resource_plan
• stream:GetGenerateResourcePlanResult - get_resource_plan_result
• stream:GetLineageInfo - get_lineage
• stream:FlinkApiProxy - flink_api_proxy

W3: Session Clusters

• stream:CreateSessionCluster - create_session_cluster
• stream:UpdateSessionCluster - update_session_cluster
• stream:DeleteSessionCluster - delete_session_cluster
• stream:GetSessionCluster - get_session_cluster
• stream:ListSessionClusters - list_session_clusters
• stream:StartSessionCluster - start_session_cluster
• stream:StopSessionCluster - stop_session_cluster

W4: Dev Resources

• stream:GetCatalogs - get_catalogs
• stream:GetDatabases - get_databases
• stream:GetTables - get_tables
• stream:ExecuteSqlStatement - execute_sql
• stream:ListEngineVersionMetadata - list_engine_versions

W5: Workspace Administration

• stream:CreateMember - create_member
• stream:UpdateMember - update_member
• stream:DeleteMember - delete_member
• stream:GetMember - get_member
• stream:ListMembers - list_members
• stream:CreateVariable - create_variable
• stream:UpdateVariable - update_variable
• stream:DeleteVariable - delete_variable
• stream:ListVariables - list_variables
• stream:CreateDeploymentTargetV2 - create_deployment_target
• stream:UpdateDeploymentTargetV2 - update_deployment_target
• stream:DeleteDeploymentTarget - delete_deployment_target
• stream:ListDeploymentTargets - list_deployment_targets

---

Minimum Permission Policy

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "stream:CreateFolder",
        "stream:UpdateFolder",
        "stream:DeleteFolder",
        "stream:GetFolder",
        "stream:CreateDeploymentDraft",
        "stream:UpdateDeploymentDraft",
        "stream:DeleteDeploymentDraft",
        "stream:GetDeploymentDraft",
        "stream:ListDeploymentDrafts",
        "stream:GetDeploymentDraftLock",
        "stream:ValidateDeploymentDraftAsync",
        "stream:GetValidateDeploymentDraftResult",
        "stream:ValidateSqlStatement",
        "stream:DeployDeploymentDraftAsync",
        "stream:GetDeployDeploymentDraftResult",
        "stream:CreateDeployment",
        "stream:UpdateDeployment",
        "stream:GetDeployment",
        "stream:ListDeployments",
        "stream:DeleteDeployment",
        "stream:GetDeploymentsByName",
        "stream:GetDeploymentsByLabel",
        "stream:GetEvents",
        "stream:StartJobWithParams",
        "stream:StopJob",
        "stream:GetJob",
        "stream:ListJobs",
        "stream:DeleteJob",
        "stream:HotUpdateJob",
        "stream:GetHotUpdateJobResult",
        "stream:GetLatestJobStartLog",
        "stream:GetJobDiagnosis",
        "stream:CreateSavepoint",
        "stream:GetSavepoint",
        "stream:DeleteSavepoint",
        "stream:ListSavepoints",
        "stream:GenerateResourcePlanWithFlinkConfAsync",
        "stream:GetGenerateResourcePlanResult",
        "stream:GetLineageInfo",
        "stream:FlinkApiProxy",
        "stream:CreateSessionCluster",
        "stream:UpdateSessionCluster",
        "stream:DeleteSessionCluster",
        "stream:GetSessionCluster",
        "stream:ListSessionClusters",
        "stream:StartSessionCluster",
        "stream:StopSessionCluster",
        "stream:GetCatalogs",
        "stream:GetDatabases",
        "stream:GetTables",
        "stream:ExecuteSqlStatement",
        "stream:ListEngineVersionMetadata",
        "stream:CreateMember",
        "stream:UpdateMember",
        "stream:DeleteMember",
        "stream:GetMember",
        "stream:ListMembers",
        "stream:CreateVariable",
        "stream:UpdateVariable",
        "stream:DeleteVariable",
        "stream:ListVariables",
        "stream:CreateDeploymentTargetV2",
        "stream:UpdateDeploymentTargetV2",
        "stream:DeleteDeploymentTarget",
        "stream:ListDeploymentTargets"
      ],
      "Resource": [
        "acs:stream:*:*:workspace/*"
      ]
    }
  ]
}

---

Permission Breakdown by Workflow

W1: SQL Development

W2: Job Operations

W3: Session Clusters

W4: Dev Resources

W5: Workspace Administration

---

Resource ARN Examples

Use resource-level constraints when possible:

• Workspace: acs:stream:{regionId}:{accountId}:workspace/{workspaceId}
• Namespace: acs:stream:{regionId}:{accountId}:workspace/{workspaceId}/namespace/{namespace}
• Deployment: acs:stream:{regionId}:{accountId}:workspace/{workspaceId}/namespace/{namespace}/deployment/{deploymentId}

Example policy for one specific workspace:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "stream:ListDeployments",
        "stream:GetDeployment",
        "stream:StartJobWithParams",
        "stream:StopJob"
      ],
      "Resource": "acs:stream:cn-beijing:123456789012:workspace/w-xxx"
    }
  ]
}

---

Predefined System Policies

Alibaba Cloud currently provides these common system policies:

• AliyunStreamFullAccess
• AliyunStreamReadOnlyAccess

If your organization requires least privilege, prefer custom policy with explicit stream:* actions shown above.

---

Troubleshooting

CLI Plugin Mode (MANDATORY)

When checking RAM permissions with aliyun CLI, always use plugin-mode command names (lowercase-hyphenated). Never use PascalCase API names directly in CLI commands.

aliyun ram list-policies-for-user --user-name <user_name>
aliyun ram list-access-keys --user-name <user_name>

Error: Forbidden.RAM

1. Verify attached policies in the RAM Console → Users → Permissions tab. 2. Attach a policy that includes required stream:* actions. 3. Retry the operation.

Error: InvalidAccessKeyId.NotFound

1. Verify AccessKey in the RAM Console → Users → AccessKey Management tab. 2. Rotate/recreate AccessKey and update local config.

Error: NoPermission

1. Ensure the RAM user has the required actions for the specific workflow. 2. Check if resource-level permissions are restricting access. 3. Use * resource for testing, then narrow down to specific ARNs.

---

References

• OpenAPI RAM actions
• OpenAPI overview
• RAM Console

Related APIs

This document lists all the Ververica APIs used by the alibabacloud-flink-workspace-ops skill.

W1: SQL Development APIs

W2: Job Operations APIs

W3: Session Cluster APIs

W4: Dev Resources APIs

W5: Workspace Administration APIs

Resource Loading Policy

This skill keeps SKILL.md concise and loads detailed docs only when needed.

Entry Contract (Always Loaded)

• SKILL.md — boundary, trigger priority, safety baseline, execution baseline.
• Keep concise; no long command encyclopedia.

Loading Strategy

1. After Trigger: Load execution protocol and command routing table once per task. 2. On Demand: Load only the specific deep document required by current context (error handling, verification, RAM policies, full command catalog, playbooks, etc.). 3. Refer to the "Resources" section in SKILL.md for the complete list of available documents and when to load each.

Loading Discipline

1. Do not preload all references. 2. Start from the entry contract, then task docs, then only the needed deep doc. 3. Prefer the smallest sufficient context for the current user request.

Verification Methods

Use this guide after a mutating command to verify actual resource state.

⚠️ Global Verification Rules

• MANDATORY: Verify after EVERY mutating operation
• Prefer -o json for deterministic parsing
• Verify immediately after each mutation (don't delay)
• For async operations, verify only after polling returns terminal result
• NEVER claim success without read-back verification

Verification Protocol (MANDATORY)

Step 1: Identify Verification Command

Match operation to verification command:

Step 2: Execute Verification Command

python scripts/flink_ververica_ops.py get_<resource> -w <workspace> -n <namespace> -r <region> --<resource>_id <id> -o json

Step 3: Parse and Confirm Response

Successful creation/update:

{
  "success": true,
  "data": {
    "resource_id": "xxx",
    "name": "expected-name",
    "status": "EXPECTED_STATE"
  }
}

Successful deletion:

{
  "success": false,
  "error": {
    "code": "ResourceNotFound"
  }
}

Step 4: Report Verification Results

✓ Verification successful

**Operation:** create_deployment
**Resource ID:** d-123456
**Current State:**
- Name: etl-job
- Status: CREATED
- Engine Version: vvr-8.0.1-flink-1.17
- Namespace: default
- Workspace: w-xxx

Verification Examples by Workflow

create_folder / update_folder

# After creation
python scripts/flink_ververica_ops.py get_folder -w <workspace> -n <namespace> -r <region> --folder_id <folder_id> -o json

# Verify:
# - success: true
# - data.name matches expected name
# - data.folder_id exists

delete_folder

# After deletion, verify it's gone
python scripts/flink_ververica_ops.py get_folder -w <workspace> -n <namespace> -r <region> --folder_id <folder_id> -o json

# Verify:
# - success: false
# - error.code: "ResourceNotFound"

create_draft / update_draft

# After creation
python scripts/flink_ververica_ops.py get_draft -w <workspace> -n <namespace> -r <region> --draft_id <draft_id> -o json

# Verify:
# - success: true
# - data.name matches expected name
# - data.sql_content matches expected SQL

validate_draft (async)

# Step 1: Start validation
python scripts/flink_ververica_ops.py validate_draft -w <workspace> -n <namespace> -r <region> --draft_id <draft_id> -o json

# Returns: {"success": true, "data": {"ticket_id": "xxx-xxx-xxx"}}

# Step 2: Poll for result (repeat until terminal state)
python scripts/flink_ververica_ops.py get_validate_result -w <workspace> -n <namespace> -r <region> --ticket_id <ticket_id> -o json

# Verify:
# - success: true
# - data.status: "SUCCEEDED" or "FAILED"
# - If FAILED: data.errors contains error details

deploy_draft (async)

# Step 1: Start deployment
python scripts/flink_ververica_ops.py deploy_draft -w <workspace> -n <namespace> -r <region> --draft_id <draft_id> --deployment_name <name> --confirm -o json

# Returns: {"success": true, "data": {"ticket_id": "xxx-xxx-xxx"}}

# Step 2: Poll for result
python scripts/flink_ververica_ops.py get_deploy_result -w <workspace> -n <namespace> -r <region> --ticket_id <ticket_id> -o json

# Verify:
# - success: true
# - data.status: "SUCCEEDED"
# - data.deployment_id exists

W2 Job Operations

create_deployment / update_deployment

# After operation
python scripts/flink_ververica_ops.py get_deployment -w <workspace> -n <namespace> -r <region> --deployment_id <deployment_id> -o json

# Verify:
# - success: true
# - data.name matches expected
# - data.status in ["CREATED", "RUNNING", "STOPPED"]
# - data.engine_version matches expected

start_job

# After start
python scripts/flink_ververica_ops.py get_job -w <workspace> -n <namespace> -r <region> --job_id <job_id> -o json

# Verify:
# - success: true
# - data.state: "RUNNING"
# - data.start_time exists

stop_job

# After stop
python scripts/flink_ververica_ops.py get_job -w <workspace> -n <namespace> -r <region> --job_id <job_id> -o json

# Verify:
# - success: true
# - data.state: "STOPPED" or "CANCELED"
# - data.stop_time exists

create_savepoint

# After creation
python scripts/flink_ververica_ops.py get_savepoint -w <workspace> -n <namespace> -r <region> --savepoint_id <savepoint_id> -o json

# Verify:
# - success: true
# - data.state: "COMPLETED"
# - data.location contains savepoint path

delete_deployment

# After deletion
python scripts/flink_ververica_ops.py get_deployment -w <workspace> -n <namespace> -r <region> --deployment_id <deployment_id> -o json

# Verify:
# - success: false
# - error.code: "ResourceNotFound"

W3 Session Clusters

create_session_cluster / update_session_cluster

# After operation
python scripts/flink_ververica_ops.py get_session_cluster -w <workspace> -n <namespace> -r <region> --cluster_id <cluster_id> -o json

# Verify:
# - success: true
# - data.name matches expected
# - data.state in ["CREATED", "STARTING", "RUNNING", "STOPPING", "STOPPED"]

start_session_cluster

# After start
python scripts/flink_ververica_ops.py get_session_cluster -w <workspace> -n <namespace> -r <region> --cluster_id <cluster_id> -o json

# Verify:
# - success: true
# - data.state: "RUNNING"

stop_session_cluster

# After stop
python scripts/flink_ververica_ops.py get_session_cluster -w <workspace> -n <namespace> -r <region> --cluster_id <cluster_id> -o json

# Verify:
# - success: true
# - data.state: "STOPPED"

delete_session_cluster

# After deletion, verify removal
python scripts/flink_ververica_ops.py list_session_clusters -w <workspace> -n <namespace> -r <region> -o json

# Verify:
# - success: true
# - data.session_clusters does NOT contain the deleted cluster

W4 Dev Resources

execute_sql

# For DDL (CREATE TABLE/DATABASE), verify via metadata query
# For DML (INSERT), verify via SELECT query

# Example: after CREATE TABLE
python scripts/flink_ververica_ops.py get_tables -w <workspace> -n <namespace> -r <region> --catalog <catalog> --database <database> -o json

# Verify:
# - success: true
# - data.tables contains the newly created table

get_catalogs / get_databases / get_tables

# These are read operations, verify by:
# - success: true
# - data contains expected catalogs/databases/tables

W5 Workspace Administration

create_member / update_member

# After operation
python scripts/flink_ververica_ops.py get_member -w <workspace> -n <namespace> -r <region> --member_id <member_id> -o json

# Verify:
# - success: true
# - data.user_id matches expected
# - data.role matches expected

delete_member

# After deletion
python scripts/flink_ververica_ops.py list_members -w <workspace> -n <namespace> -r <region> -o json

# Verify:
# - success: true
# - data.members does NOT contain the deleted member

create_variable / update_variable

# After operation
python scripts/flink_ververica_ops.py list_variables -w <workspace> -n <namespace> -r <region> -o json

# Verify:
# - success: true
# - data.variables contains the created/updated variable
# - Variable value matches expected

create_deploy_target / update_deploy_target

# After operation
python scripts/flink_ververica_ops.py list_deploy_targets -w <workspace> -n <namespace> -r <region> -o json

# Verify:
# - success: true
# - data.deploy_targets contains the created/updated target

Verification Response Template

When reporting verification to user:

✓ Verification successful

**Operation:** create_deployment
**Resource ID:** d-123456
**Current State:**
- Name: etl-job
- Status: CREATED
- Engine Version: vvr-8.0.1-flink-1.17
- Namespace: default
- Workspace: w-xxx

**Next Actions:**
- To start the job: start_job --deployment_id d-123456
- To update configuration: update_deployment --deployment_id d-123456 --body_json '{...}'

Common Verification Failures

Failure 1: Resource not found

❌ Verification failed: Resource not found
Expected: Deployment d-123456 should exist
Actual: get_deployment returned ResourceNotFound

Possible causes:
- Creation failed silently
- Wrong deployment_id
- Wrong workspace/namespace/region

Failure 2: Wrong state

❌ Verification failed: Unexpected state
Expected: Job j-xxx should be RUNNING
Actual: Job state is FAILED

Error from job:
- Failure Reason: Checkpoint timeout
- Error Message: Checkpoint could not be completed within timeout

Failure 3: Partial update

❌ Verification failed: Update incomplete
Expected: deployment_target_name = "target-prod"
Actual: deployment_target_name = "target-dev" (unchanged)

Possible causes:
- Update operation failed
- Body JSON not properly formatted

Best Practices

1. Always verify - never assume success from write response alone 2. Verify immediately - don't delay between operation and verification 3. Check all fields - not just success flag, but actual resource state 4. Report clearly - show what was expected vs what was found 5. Investigate failures - don't just report failure, investigate root cause

VVP 产品概念模型

实体层次与关系

Workspace（工作空间） └─ Namespace（项目空间）：作业管理和资源隔离的基本单元，所有配置、作业、权限均在单个 Namespace 下 ├─ DeploymentDraft（作业草稿）：作业草稿的配置定义（模板），包含代码 artifact、资源规格、运行参数. 部署上线后, 生成对应的Deployment ├─ Deployment（作业部署）：作业的配置定义（模板），包含代码 artifact、资源规格、运行参数 │ └─ Job（作业实例）：Deployment 的一次运行实例 [1:N]，Job 是 Deployment 的快照，绝大部分字段不可变，对作业的变更主要通过修改部署后重启Job实现(HotUpdate除外)。 │ └─ Savepoint（快照）：Job 运行时的状态快照 [1:N]，用于有状态恢复 ├─ SessionCluster（Session 集群）：仅用于开发测试的共享集群，不支持监控告警和自动调优 ├─ ResourceQueue（资源队列）：计算资源的分配单元，Deployment 需要部署到资源队列或SessionCluster上运行 └─ Catalog（SQL元数据）：管理用户SQL类作业中使用的数据库、表、字段等元数据信息 └─ Database → Table

• 用户通过 deployment_id 定位一个部署配置，通过 job_id 定位一个具体的运行实例
• 所有 API path 中的 {namespace} 自动替换为当前项目空间

作业类型（artifact.kind）

执行模式 ExecutionMode

deployment 和 job 的执行模式在创建时确定，不能更改。

作业状态（Job state）

STARTING → RUNNING → FINISHED / CANCELLED / FAILED

引擎及版本

VVR和Flash均是VVP提供的商业版Flink引擎。

engineVersion 或 versionName 字段是引擎版本的展示名，在 workspace 下唯一，示例: "vvr-8.0.6-flink-1.17"。

引擎版本标记：推荐版本 > 稳定版本 > 普通版本 > EOS 版本。

部分功能有版本要求（如动态参数更新需 VVR 8.0.1+，算子 TTL 需 VVR 8.0.7+，YAML 作业需 VVR 8.0.9+）。