Alibabacloud Flink Instance Manage

Alibaba Cloud Flink Instance Manage

Operate Alibaba Cloud Flink VVP resources with a strict create/query scope through one wrapper script.

Scope and Entrypoint

• Always run operations through:

  python scripts/instance_ops.py <command> [options]

• Allowed commands: create, create_namespace, describe, describe_regions, describe_zones, describe_namespaces, list_tags
• Out of scope: update/delete, Flink SQL/job runtime operations, and non-Flink services

Trigger Rules

Use this skill when prompts are about Flink instance/namespace lifecycle operations.

• Positive intent examples:
• "Create a Flink instance in cn-beijing"
• "List Flink instances and status"
• "Describe namespaces for instance f-cn-xxx"
• "查询 Flink 实例标签"
• "Flink 可用区有哪些"
• Negative intent examples:
• ECS/Kafka/OSS/DataWorks operations
• Generic questions (weather, translation, etc.)
• Flink SQL / Flink job authoring or runtime tuning
• Ambiguous prompts:
• Ask one clarification question: instance/namespace management vs SQL/job operations.

Intent to Command Mapping

Operating Rules

1. Confirmation is mandatory for create commands

• create and create_namespace must include --confirm.

2. Verify create results with read-back

• Do not conclude success from create response alone.

3. Retry policy is strict

• Maximum 2 attempts for the same command (initial + one corrected retry).

4. No automatic operation switching

• If an operation fails, do not switch to a different operation without user approval.

5. Lifecycle target lock

• In create -> create_namespace flow, namespace must target the same newly created InstanceId unless user approves fallback.

6. Namespace pre-check is required

• Before create_namespace, check instance status/resources and existing namespace allocation.

7. No secret exposure

• Do not output or request plaintext AK/SK. Use default credential chain guidance.

8. Do not invent parameters

• Never fabricate VPC/VSwitch/instance IDs.

9. Keep auditable confirmation evidence

• Lifecycle outputs must contain SafetyCheckRequired or explicit --confirm evidence.

10. No partial-completion claims for lifecycle flows

• For flows requiring both create and create_namespace, overall status can be completed only when both create operations succeed.

11. No automatic capacity scaling

• If create_namespace fails due to insufficient resources, report it clearly and ask user to manually scale resources outside this skill scope.

Execution Protocol

Step 1: Classify request

• In-scope create/query for Flink instance/namespace/tag/region/zone -> continue.
• Out-of-scope or non-Flink -> reject or route with explanation.

Step 2: Validate parameters

• Apply references/parameter-validation.md.
• If required parameters are missing, ask user or return clear remediation.

Step 3: Execute command

• Query commands: run once unless transient query error.
• Create commands: construct final command string and verify --confirm is present before execution.

Step 4: Verify create outcomes

• For create: verify with describe --region_id <REGION>.
• For create_namespace: verify with describe_namespaces --region_id <REGION> --instance_id <ID>.
• Use up to 3 read checks with short backoff before concluding the create is not reflected yet.
• For chained create -> create_namespace:
• poll describe --region_id <REGION> on the same InstanceId every 30 seconds
• max wait: 10 minutes
• if still not RUNNING, stop and provide next action (wait/retry later)
• do not switch to another instance without explicit user approval
• if namespace create fails, mark lifecycle chain as failed/not_ready, not completed
• for InsufficientResources, ask user to manually scale the instance and retry later

Key References

• Start here:
• references/README.md
• references/quick-start.md
• references/trigger-recognition-guide.md
• references/core-execution-flow.md
• references/command-templates.md

Output Format

All commands return JSON:

{
  "success": true,
  "operation": "<command>",
  "confirmation_check": {
    "required_flag": "--confirm",
    "provided": true,
    "status": "passed"
  },
  "data": {},
  "request_id": "..."
}

confirmation_check appears on create operations and is used for auditable safety evidence.

Exit codes: 0 = success, 1 = error.

Operation Completion Checklist

Use this checklist to decide whether an instance/namespace operation is actually complete.

1) Entrypoint

Run resource operations only through:

python scripts/instance_ops.py <command> ...

Do not replace with raw aliyun foasconsole commands.

2) Confirmation flags

• create requires --confirm
• create_namespace requires --confirm

If --confirm is missing, fix the command before execution.

3) Read-back verification

A create operation is complete only when:

1. create response is successful (or idempotent equivalent), and 2. follow-up read-back confirms target state.

Create response without read-back is not complete.

4) Retry and fallback

• Max attempts for one command: 2 (initial + one corrected retry)
• No blind retries
• No automatic operation switching without explicit user approval

5) Lifecycle chain consistency

For create + create_namespace in one flow:

• namespace must target the same InstanceId returned by create
• if instance is not RUNNING, wait/poll the same instance first
• do not switch to a different instance without explicit user approval
• final completed status requires both create commands to return success: true

6) Security baseline

• No AK/SK hardcoding in commands or scripts
• Use default credential chain (CLI profile or RAM role)
• No secret values in normal response content

7) Response completeness

Final response should include:

• operation
• create_result
• verify_result
• status (completed / failed / not_ready)
• next_action when not completed

8) No partial-success closure for lifecycle flow

For lifecycle tasks that require instance + namespace create:

• if create_namespace fails, do not mark overall status as completed
• use failed or not_ready with explicit next action

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.1+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.1 or later for full plugin ecosystem coverage.

Table of Contents

• Installation
• Configuration
• Verification
• Security Best Practices
• Troubleshooting
• Advanced Configuration
• Next Steps
• References

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.1)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then refresh configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=<proxy-url>
export HTTPS_PROXY=<proxy-url>

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.1+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

Command Templates

Copy-paste ready command templates for all operations.

Query Operations

List all regions

python scripts/instance_ops.py describe_regions

List zones in a region

python scripts/instance_ops.py describe_zones --region_id cn-beijing

Query instances in a region

python scripts/instance_ops.py describe --region_id cn-beijing

Query namespaces in an instance

python scripts/instance_ops.py describe_namespaces \
  --region_id cn-beijing \
  --instance_id f-cn-xxx

List tags for resources

python scripts/instance_ops.py list_tags \
  --region_id cn-beijing \
  --resource_type vvpinstance \
  --resource_ids f-cn-xxx,f-cn-yyy

Create Operations

Create instance (PayAsYouGo) - using cu_count

python scripts/instance_ops.py create \
  --region_id cn-beijing \
  --name my-flink-instance \
  --instance_type PayAsYouGo \
  --vswitch_id vsw-xxx \
  --vpc_id vpc-xxx \
  --cu_count 4 \
  --confirm

Note: --cu_count N = N cores + (N × 4) GB memory

Create instance (PayAsYouGo) - using cpu + memory

python scripts/instance_ops.py create \
  --region_id cn-beijing \
  --name my-flink-instance \
  --instance_type PayAsYouGo \
  --vswitch_id vsw-xxx \
  --vpc_id vpc-xxx \
  --cpu 4 \
  --memory_gb 16 \
  --confirm

Create instance (Subscription)

python scripts/instance_ops.py create \
  --region_id cn-beijing \
  --name my-flink-instance \
  --instance_type Subscription \
  --vswitch_id vsw-xxx \
  --vpc_id vpc-xxx \
  --cpu 4 \
  --memory_gb 16 \
  --period 12 \
  --confirm

Create namespace (with resources)

python scripts/instance_ops.py create_namespace \
  --region_id cn-beijing \
  --instance_id f-cn-xxx \
  --name prod-namespace \
  --cpu 100 \
  --memory_gb 400 \
  --confirm

Required Parameters Summary

Resource Specification for Create

Option 1: --cu_count N

• Automatically calculates: N cores + (N × 4) GB
• Example: --cu_count 4 = 4 cores + 16 GB

Option 2: --cpu N --memory_gb M

• Both flags required together
• Example: --cpu 4 --memory_gb 16

❌ Invalid: --cpu alone or --memory_gb alone

Common Failure Patterns

Patterns to avoid. Each pattern shows the wrong approach and the correct fix.

Pattern 1: Missing Confirmation Flag

Scenario: Create command without --confirm

❌ Wrong:

python scripts/instance_ops.py create \
  --region_id cn-beijing \
  --name my-instance \
  --instance_type PayAsYouGo \
  --vswitch_id vsw-xxx \
  --vpc_id vpc-xxx \
  --cu_count 4

Error: SafetyCheckRequired

✓ Correct:

python scripts/instance_ops.py create \
  --region_id cn-beijing \
  --name my-instance \
  --instance_type PayAsYouGo \
  --vswitch_id vsw-xxx \
  --vpc_id vpc-xxx \
  --cu_count 4 \
  --confirm

Why: --confirm is a safety gate for all create operations.

---

Pattern 2: Incomplete Resource Specification

Scenario: Providing only --cpu or only --memory_gb

❌ Wrong:

--cpu 4

→ Error: MissingParameter (memory_gb required)

❌ Wrong:

--memory_gb 16

→ Error: MissingParameter (cpu required)

✓ Correct Option A:

--cpu 4 --memory_gb 16

✓ Correct Option B:

--cu_count 4

(automatically calculates as 4 cores + 16 GB)

Why: Resource specification must be complete. Use either --cu_count OR both --cpu and --memory_gb.

---

Pattern 3: Invalid instance_type

Scenario: Wrong case or format for --instance_type

❌ Wrong:

--instance_type pay-as-you-go
--instance_type PAYASYOUGO
--instance_type payasyougo

✓ Correct:

--instance_type PayAsYouGo
--instance_type Subscription

Why: Value must match exactly (case-sensitive).

---

Pattern 4: Missing Required Parameters

Scenario: Omitting required flags for create

❌ Wrong:

python scripts/instance_ops.py create \
  --region_id cn-beijing \
  --name my-instance \
  --confirm

→ Error: MissingParameter (instance_type, vswitch_id, vpc_id required)

✓ Correct:

python scripts/instance_ops.py create \
  --region_id cn-beijing \
  --name my-instance \
  --instance_type PayAsYouGo \
  --vswitch_id vsw-xxx \
  --vpc_id vpc-xxx \
  --cu_count 4 \
  --confirm

Why: All required flags must be present. See parameter-validation.md for complete list.

---

Pattern 5: Blind Retries Without Fixing Root Cause

Scenario: Repeating the same failed command

❌ Wrong:

# First attempt fails with SafetyCheckRequired
python scripts/instance_ops.py create ... --region_id cn-beijing

# Retry with same command (still fails)
python scripts/instance_ops.py create ... --region_id cn-beijing

✓ Correct:

# First attempt fails
python scripts/instance_ops.py create ... --region_id cn-beijing

# Fix the root cause (add --confirm)
python scripts/instance_ops.py create ... --region_id cn-beijing --confirm

Why: Maximum 2 attempts total. Second attempt must correct the error.

---

Pattern 6: Claiming Success Without Verification

Scenario: Reporting success after create response only

❌ Wrong:

Create command returned success: true
→ Reporting: "Instance created successfully"

✓ Correct:

# Step 1: Create command
python scripts/instance_ops.py create ... --confirm

# Step 2: Verify with query
python scripts/instance_ops.py describe --region_id cn-beijing

# Step 3: Confirm instance exists with correct spec
→ Reporting: "Instance created and verified: found my-instance with 4 cores, 16 GB"

Why: Success requires create response + read-back verification.

---

Pattern 7: Auto-switching Operations on Failure

Scenario: Create fails, agent switches to different operation

❌ Wrong:

# Create instance fails
python scripts/instance_ops.py create ... --confirm
# Error: InstanceNameConflict

# Agent tries different operation without user approval
python scripts/instance_ops.py create_namespace ...

✓ Correct:

# Create instance fails
python scripts/instance_ops.py create ... --confirm
# Error: InstanceNameConflict

# Report error and ask user
"Instance creation failed: name 'my-instance' already exists with different configuration.
Options:
1. Use a different name
2. Verify existing instance spec
3. Delete existing instance (requires update/delete scope - outside skill)"

Why: Never switch operations without explicit user approval.

---

Pattern 8: Creating Duplicate Resources

Scenario: Creating resource that already exists

❌ Wrong:

# Create instance without checking if it exists
python scripts/instance_ops.py create \
  --name my-instance \
  ...

✓ Correct:

# Step 1: Query existing instances
python scripts/instance_ops.py describe --region_id cn-beijing

# Step 2: Check if my-instance exists
# If exists with same config: skip creation (idempotent success)
# If exists with different config: report conflict
# If not exists: proceed with creation

Why: Check existing state before create to avoid conflicts and enable idempotent behavior.

---

Pattern 9: Operating on Not-Ready Instance

Scenario: Creating namespace immediately after instance creation

❌ Wrong:

# Create instance
python scripts/instance_ops.py create ... --confirm
# Immediately create namespace (fails)
python scripts/instance_ops.py create_namespace --instance_id f-cn-xxx --name ns --confirm

Error: "Resource adjustment in progress" or "Instance is not ready"

✓ Correct:

# Create instance
python scripts/instance_ops.py create ... --confirm

# Wait for instance to be RUNNING (not just AVAILABLE)
sleep 60
python scripts/instance_ops.py describe --region_id cn-beijing
# Check status is RUNNING before proceeding

# Then create namespace
python scripts/instance_ops.py create_namespace --instance_id f-cn-xxx --name ns --confirm

Why: Instances need time to fully initialize. AVAILABLE status is not sufficient; wait for RUNNING.

---

Pattern 10: Insufficient Resources for Namespace

Scenario: Creating namespace with resources that exceed instance capacity

❌ Wrong:

# Instance has 1 CPU, 4 GB total
# Existing namespace uses 1 CPU, 4 GB
python scripts/instance_ops.py create_namespace \
  --instance_id f-cn-xxx \
  --name new-ns \
  --cpu 2 \
  --memory_gb 8 \
  --confirm

Error: "Insufficient resources" or similar

✓ Correct:

# Step 1: Check instance resources
python scripts/instance_ops.py describe --region_id cn-beijing
# Note: Total = 1 CPU, 4 GB

# Step 2: Check existing namespaces
python scripts/instance_ops.py describe_namespaces --instance_id f-cn-xxx --region_id cn-beijing
# Note: Allocated = 1 CPU, 4 GB

# Step 3: Calculate available
# Available = Total - Allocated = 0 CPU, 0 GB

# Report clearly and request manual capacity action
# (this skill does not support scaling operations)
# "Insufficient resources for new namespace.
#  Please manually expand or reallocate the instance resources, then retry."

Why: Resources are pre-allocated to namespaces. Check availability before creating.

---

Pattern 11: Using Decimal CPU Values

Scenario: Specifying fractional CPU for namespace

❌ Wrong:

python scripts/instance_ops.py create_namespace \
  --instance_id f-cn-xxx \
  --name ns \
  --cpu 0.5 \
  --memory_gb 2 \
  --confirm

Error: "CPU must be an integer"

✓ Correct:

python scripts/instance_ops.py create_namespace \
  --instance_id f-cn-xxx \
  --name ns \
  --cpu 1 \
  --memory_gb 2 \
  --confirm

Why: CPU allocation must be integer values only.

---

Pattern 12: Parsing Output with Grep

Scenario: Using grep to extract instance details from JSON

❌ Wrong:

python scripts/instance_ops.py describe --region_id cn-beijing | grep "InstanceId"

This is fragile and may miss context.

✓ Correct Option A (Parse JSON):

python scripts/instance_ops.py describe --region_id cn-beijing | \
  python -c "import json,sys; data=json.load(sys.stdin); print(json.dumps([x for x in data['data']['Instances'] if x['InstanceId']=='f-cn-xxx'], indent=2))"

✓ Correct Option B (Save and parse):

python scripts/instance_ops.py describe --region_id cn-beijing > /tmp/instances.json
python -c "import json; data=json.load(open('/tmp/instances.json')); inst=[x for x in data['data']['Instances'] if x['InstanceId']=='f-cn-xxx']; print(f\"Status: {inst[0]['Status']}\") if inst else print('Not found')"

Why: JSON parsing is reliable. Grep is fragile for structured data.

---

Pattern 13: Fake Closed Loop by Switching Instance

Scenario: Created instance is still CREATING, then namespace is created on another pre-existing instance

❌ Wrong:

# create returns new instance: f-cn-new
python scripts/instance_ops.py create ... --confirm

# f-cn-new still CREATING
python scripts/instance_ops.py describe --region_id cn-beijing

# agent switches target without user approval
python scripts/instance_ops.py create_namespace --instance_id f-cn-old --name ns --confirm

✓ Correct:

# keep target locked to f-cn-new
python scripts/instance_ops.py describe --region_id cn-beijing
# poll until f-cn-new status is RUNNING (up to timeout window)

# then create namespace on f-cn-new
python scripts/instance_ops.py create_namespace --instance_id f-cn-new --name ns --confirm

Why: Minimal lifecycle loop requires same-target chain integrity.

---

Pattern 14: Declaring Completion While Namespace Step Is Pending

Scenario: Instance is created, but namespace step has not been executed or verified yet.

❌ Wrong:

Instance created successfully.
Namespace will be created later when instance becomes RUNNING.
Final: completed

✓ Correct:

operation: create + create_namespace
create_result: success
verify_result: instance still CREATING after wait window; namespace not executed
status: not_ready
next_action: wait until RUNNING, then create namespace on the same instance

Why: Lifecycle completion requires both steps to be executed and verified on the same target instance.

---

Pattern 15: Declaring Completion After Namespace Create Failure

Scenario: create_namespace was attempted but returned success: false, yet final report says workflow completed.

❌ Wrong:

Instance create succeeded.
Namespace create failed due to capacity.
Final: completed

✓ Correct:

operation: create + create_namespace
create_result: instance created
verify_result: namespace create failed (InsufficientResources)
status: failed
next_action: manually expand/reallocate instance resources, then retry create_namespace

Why: For lifecycle create/create_namespace flow, completion requires BOTH create commands to succeed.

---

Quick Reference: Error Code → Fix

Maximum retries: 2 total (initial + one corrected retry)

Core execution flow

This document defines the execution flow for Alibaba Cloud Flink VVP instance operations.

When to Use This Skill

Trigger when user request is about Flink instance/namespace lifecycle create/query.

English triggers

• "create a Flink instance" / "create Flink"
• "query Flink instance" / "describe Flink"
• "list Flink namespaces" / "query namespace"
• "what regions support Flink" / "Flink regions"
• "Flink VVP" / "Flink on Cloud"

Chinese triggers (中文触发词)

• "创建Flink实例" / "创建实时计算实例"
• "查询Flink实例" / "查询实例信息"
• "创建命名空间" / "Flink命名空间"
• "Flink VVP实例" / "实时计算Flink版"
• "查询Flink区域" / "Flink可用区"

Explicitly DO NOT trigger for

• Flink SQL queries ("运行Flink SQL", "Flink job")
• Other Alibaba Cloud services (ECS, Kafka, OSS, DataWorks)
• Update/delete operations (拒绝此类请求并说明scope)

Execution Entry Point

Use the Python script as the default execution entrypoint. For initial validation, run a query-only command.

python scripts/instance_ops.py describe_regions

1) Lifecycle chain

Use this minimal chain for end-to-end requests:

1. discover target scope 2. create resource 3. query read-back verification

Rules:

• Capture InstanceId from create response and keep it as the single target.
• Do not switch to a different instance in the same chain unless user explicitly approves.
• If resource is not visible immediately after create, use repeated read checks

before deciding retry/failure.

• Do not mark lifecycle flow completed when namespace create fails.

2) Discover and inspect

python scripts/instance_ops.py describe_regions
python scripts/instance_ops.py describe --region_id cn-hangzhou
python scripts/instance_ops.py describe_zones --region_id cn-hangzhou

3) Create instance

python scripts/instance_ops.py create \
  --region_id cn-hangzhou \
  --name my-flink-instance \
  --instance_type PayAsYouGo \
  --zone_id cn-hangzhou-g \
  --vswitch_id vsw-xxx \
  --vpc_id vpc-xxx \
  --cpu 200 \
  --memory_gb 800 \
  --confirm

If required network parameters (--vpc_id, --vswitch_id) are missing, stop and ask user to provide explicit values. Do not fabricate values.

python scripts/instance_ops.py describe --region_id cn-hangzhou

4) Create namespace

python scripts/instance_ops.py create_namespace \
  --region_id cn-hangzhou \
  --instance_id f-cn-xxx \
  --name prod-ns \
  --cpu 100 \
  --memory_gb 400 \
  --confirm

python scripts/instance_ops.py describe_namespaces \
  --region_id cn-hangzhou \
  --instance_id f-cn-xxx

5) Query tag state

python scripts/instance_ops.py list_tags \
  --region_id cn-hangzhou \
  --resource_type vvpinstance \
  --resource_ids f-cn-xxx

6) Completion reminders

• Every create command must have a follow-up read check (describe* or list*).
• Report completion based on read-back result, not create response alone.
• Max attempts: 2 total for the same operation (initial + one corrected retry).
• Keep auditable confirmation evidence in output (SafetyCheckRequired or --confirm).
• For lifecycle requests requiring instance+namespace create, completed means both

create operations succeeded.

End-to-end playbooks

Complete execution sequences for common scenarios. Each playbook includes discovery, execution, and verification.

Core principle: Never claim success without read-back verification.

Playbook 1: Create Instance (PayAsYouGo)

Step 1: Discover

python scripts/instance_ops.py describe_regions
python scripts/instance_ops.py describe --region_id <REGION>

Decision: Check if target instance name already exists

Step 2: Execute

python scripts/instance_ops.py create \
  --region_id <REGION> \
  --name <NAME> \
  --instance_type PayAsYouGo \
  --vswitch_id <VSWITCH_ID> \
  --vpc_id <VPC_ID> \
  --cu_count <N> \
  --confirm

Step 3: Verify

python scripts/instance_ops.py describe --region_id <REGION>

Verify: InstanceId, InstanceName, CPU/memory all match

CRITICAL: Check instance status is RUNNING (not just AVAILABLE)

• If status is CREATING or not RUNNING, wait 60 seconds and re-check
• Instance must be RUNNING before creating namespaces
• See instance-state-management.md for detailed state handling

Step 4: Report

{
  "operation": "create",
  "create_result": "success",
  "instance_id": "f-cn-xxx",
  "verify_result": "Instance found with matching spec",
  "final_status": "completed"
}

Done when: Create success + read-back verification confirms presence and spec

2) Create namespace

Target lock for lifecycle chain

If this namespace step is part of a create instance -> create namespace closed loop:

• use the InstanceId returned by that same create operation
• do not switch to another existing RUNNING instance without explicit user approval
• if not ready, wait/poll on the same target instead of pivoting

Pre-requisite Checks

1. Verify instance exists and is READY:

   python scripts/instance_ops.py describe --region_id <region>

• Confirm instance status is RUNNING (not CREATING or AVAILABLE)
• If not RUNNING, wait before proceeding (see instance-state-management.md)

2. Check available resources:

   python scripts/instance_ops.py describe_namespaces --region_id <region> --instance_id <id>

• Note total instance CPU/memory
• Calculate used resources from existing namespaces
• Ensure sufficient resources available

Execution Steps

1. Run describe --region_id <region> and verify target instance exists AND status is RUNNING. 2. Run describe_namespaces and check whether target namespace already exists. 3. If namespace does not exist:

• Calculate required resources (must be integer CPU, GB memory)
• Verify resources are available (total - used >= required)
• Run create_namespace --cpu <N> --memory_gb <M> --confirm
• If resources insufficient: do not blind retry; explicitly tell user to manually

expand or reallocate instance resources (this skill does not support scaling) and retry later. 4. If namespace already exists: treat as idempotent success only when existing spec matches expected; otherwise report mismatch and remediation. 5. Run describe_namespaces for the same instance. 6. Verify namespace exists; if CPU/memory was requested, verify spec matches.

If target instance is not ready

• Poll every 30 seconds (same InstanceId) until status becomes RUNNING
• Maximum wait time: 10 minutes
• If still not RUNNING, stop and provide a clear next action
• Do not claim closed-loop completion before namespace is actually created and verified

Common Errors

• Resource adjustment in progress: Instance not fully ready → Wait 2-5 minutes
• Insufficient resources: Namespace resources exceed available → Ask user to

manually expand/reallocate resources, then retry

• CPU must be integer: Decimal CPU value → Use integer (1, 2, 4, etc.)

Done when:

• namespace exists in describe_namespaces
• expected namespace spec is verified (or explicitly confirmed unchanged)

Not done when:

• create_namespace returns success: false for all allowed attempts
• namespace step was skipped due to capacity issues
• chain switched to another instance without explicit user approval

3) Query-only inspection

When user requests inspection without create:

1. Instance scope:

• run describe --region_id <region>

2. Namespace scope:

• run describe_namespaces --region_id <region> --instance_id <id>

3. Region/zone scope:

• run describe_regions
• run describe_zones --region_id <region>

4. Tag scope:

• run list_tags --region_id <region> --resource_type vvpinstance --resource_ids <ids>

Done when:

• returned data clearly answers user query
• response includes the exact filters used (region, instance_id, resource_ids)

4) Batch operation checklist

When request includes multiple targets (IDs/names):

1. Parse all items in input order. 2. For each item: execute create/query -> run read-back verification -> record status. 3. Continue remaining items after single-item failure unless all-or-nothing is required. 4. Return per-item final table (item, result, verify, status, reason).

Evaluation Deliverables Contract

Use this document for evaluator-facing tasks. It defines required artifacts and auditable evidence patterns.

1) Required Artifact Matrix

Hard rule: do not replace required jsonc artifacts with markdown-only summaries.

2) Generate Trigger Artifacts (Recommended)

Use the standard template copier:

python scripts/prepare_trigger_batch.py --type positive --output outputs/should_trigger.jsonc
python scripts/prepare_trigger_batch.py --type negative --output outputs/should_not_trigger.jsonc

If file exists and should be refreshed:

python scripts/prepare_trigger_batch.py --type positive --output outputs/should_trigger.jsonc --force

3) Safety Confirmation Evidence Requirements

For lifecycle checks involving create or create_namespace, evaluator evidence must match SafetyCheckRequired|--confirm.

Use at least one of the following evidence paths:

1. Negative probe: run a create command without --confirm and capture SafetyCheckRequired. 2. Positive execution evidence: keep successful create JSON output that includes confirmation_check.required_flag = "--confirm".

Do not claim confirmation enforcement without one of the above in logs/output.

4) Minimal Closure Checklist

Before finishing any evaluator task, verify:

• required output file names exist exactly (should_trigger.jsonc / should_not_trigger.jsonc)
• trigger files are valid JSONC with triggering.type and triggering.test_cases
• create steps include confirmation evidence (SafetyCheckRequired or --confirm)
• final summary references generated artifact paths

Instance State Management

This document provides guidance on handling instance states and waiting for readiness.

Instance States

Common States

• CREATING - Instance is being created
• RUNNING - Instance is operational and ready
• AVAILABLE - Instance is available but may not be fully ready
• RELEASING - Instance is being deleted
• EXCEPTION - Instance has errors

State Transitions

CREATING → RUNNING (normal flow)
CREATING → EXCEPTION (creation failed)
RUNNING → RELEASING (deletion initiated)

Waiting for Instance Readiness

After creating an instance, you MUST wait for it to become fully ready before creating namespaces.

Step 1: Check Initial State

python scripts/instance_ops.py describe --region_id <REGION>

Look for:

• ClusterStatus or Status field
• Instance should be RUNNING (not just AVAILABLE)

Step 2: Poll for Readiness (if needed)

If instance is in CREATING or AVAILABLE but not RUNNING:

# Wait loop (check every 30 seconds)
for i in {1..10}; do
  python scripts/instance_ops.py describe --region_id <REGION> > /tmp/instance_status.json
  status=$(python -c "import json; data=json.load(open('/tmp/instance_status.json')); inst=[x for x in data['data']['Instances'] if x['InstanceId']=='<INSTANCE_ID>']; print(inst[0].get('Status', 'UNKNOWN') if inst else 'NOT_FOUND')")
  
  if [ "$status" == "RUNNING" ]; then
    echo "Instance is ready"
    break
  fi
  
  echo "Instance status: $status, waiting..."
  sleep 30
done

Step 3: Verify Readiness for Namespace Operations

Before creating namespaces, verify: 1. Instance status is RUNNING 2. No "resource adjustment in progress" errors 3. Instance has available resources (CPU/Memory not fully allocated)

# Check available resources
python scripts/instance_ops.py describe --region_id <REGION> | \
  python -c "import json,sys; data=json.load(sys.stdin); inst=[x for x in data['data']['Instances'] if x['InstanceId']=='<INSTANCE_ID>']; print(f\"Total: {inst[0]['Cpu']} CPU, {inst[0]['MemoryGB']} GB\" if inst else 'Not found')"

# Check existing namespaces to see resource usage
python scripts/instance_ops.py describe_namespaces --region_id <REGION> --instance_id <INSTANCE_ID>

Common Errors and Solutions

Error: "Resource adjustment in progress"

Cause: Instance is still initializing or undergoing resource changes

Solution: 1. Wait 2-5 minutes for initialization to complete 2. Check instance status until it shows RUNNING 3. Retry namespace creation

Do NOT:

• Blindly retry without waiting
• Switch to a different instance without user approval
• Report failure immediately

Error: "Insufficient resources"

Cause: Instance doesn't have enough free CPU/memory for namespace

Solution: 1. Query existing namespaces to see resource allocation 2. Check total instance resources vs allocated resources 3. Either:

• Create namespace with smaller resources
• Use a different instance with more available resources (with user approval)
• Create namespace without resource specification (shares instance pool)

Error: "Instance not found"

Cause: Instance ID is incorrect or instance was deleted

Solution: 1. Verify instance exists with describe command 2. Check correct region_id was used 3. If instance was deleted, report to user

Resource Calculation for Namespaces

Minimum Resources

• CPU: 1 (minimum integer value)
• Memory: 1 GB (minimum)

Resource Allocation Rules

• CPU must be integer (no decimals)
• Memory must be in GB (integer)
• Both CPU and memory must be specified together
• Resources cannot exceed instance total capacity

Example Calculations

Instance: 4 CPU, 16 GB Existing namespace: 1 CPU, 4 GB (already allocated) Available for new namespace: 3 CPU, 12 GB maximum

Valid namespace creation:

# Within available resources
python scripts/instance_ops.py create_namespace \
  --region_id cn-hangzhou \
  --instance_id f-cn-xxx \
  --name new-ns \
  --cpu 2 \
  --memory_gb 8 \
  --confirm

Invalid namespace creation (would fail):

# Exceeds available resources
--cpu 5 --memory_gb 20  # Too much

# Decimal CPU (invalid)
--cpu 0.5 --memory_gb 2  # CPU must be integer

Timeout Guidelines

Creation Timeouts

• Instance creation: 5-10 minutes
• Namespace creation: 30-60 seconds
• Status transitions: 2-5 minutes

Polling Intervals

• Check instance status: Every 30 seconds
• Maximum wait time: 10 minutes
• Polling checks are separate from command retry policy in output-handling.md

Best Practices

1. Always verify state before proceeding to next operation 2. Use JSON parsing instead of grep for reliability 3. Check resource availability before creating namespaces 4. Wait for RUNNING state not just AVAILABLE 5. Report temporary states to user with expected timeline

Output handling

scripts/instance_ops.py writes JSON results. Always inspect:

• success: true or false
• operation: operation name
• data: successful response payload
• error.code and error.message: failure diagnostics
• confirmation_check (create operations): auditable confirmation gate status

Retry policy (strict)

Never use blind retries. Maximum attempts for the same command: 2 total (initial run + one corrected retry).

1. error.code == SafetyCheckRequired

• Cause: missing confirmation flag.
• Action: add the required flag from required-confirmation-model.md and retry once.

2. Input/argument issues (MissingParameter, ValueError, invalid format)

• Action: correct parameters according to error.message, then retry once.
• If error indicates missing credentials, fix default credential chain and retry once.

3. Permission issues (AccessDenied, Forbidden, Unauthorized)

• Action: do not retry until permissions are fixed; report required RAM policy.

4. Transient platform issues (Throttling, timeout, internal error)

• Query operations: retry once after short backoff.
• Create operations: first run a read check to verify whether request already took effect;

only retry once if not applied. 5. Create command reports success, but read-back verification fails

• Treat as incomplete, not successful.
• Check region/instance/resource identifiers first.
• Run one corrected create retry only when verification confirms state did not change.

6. Idempotent result handling

• AlreadyExists: success only if read-back fully matches expected target state.
• Any mismatch after read-back means incomplete task.

7. Create command fails with business mismatch (NamespaceNotFound, missing required options)

• Action: stop and ask user for clarification.
• Do not switch to a different operation automatically.

8. create_namespace fails with InsufficientResources

• Action: mark lifecycle chain as not completed; provide next action.
• State clearly that this skill does not support instance scale-up/update.
• Ask user to manually expand/reallocate resources, then retry.
• Do not label overall flow as completed.

If the corrected retry still fails, stop and return a clear remediation message instead of continuing attempts.

Eventual consistency read-back

After successful create, read-back may lag briefly. Use this sequence:

1. immediate read check 2. short backoff, second read check 3. short backoff, third read check

Do not perform extra create retries before completing these read checks.

Completion rule

Do not conclude task success from create response alone. Success requires:

1. create response success 2. read-back state verification success

Final response template (recommended)

Use a concise closure report:

• operation: target operation name
• create_result: success/failure + key error code when failed
• verify_result: read-back result summary
• status: completed/failed/not_ready
• next_action: remediation when not completed

For lifecycle flows requiring both instance and namespace create:

• status=completed is allowed only when both create operations succeeded and were verified.

Parameter Validation Rules

Pre-execution validation checklist. If any check fails, do not execute.

Create Command Validation

1. Confirmation flag (MANDATORY)

• ✓ --confirm flag MUST be present
• ❌ Missing flag → SafetyCheckRequired error
• Action: Add --confirm and retry ONCE

2. Resource specification (EXACTLY ONE option)

Option A: --cu_count N

• Valid: --cu_count 4
• Auto-calculates: 4 cores + 16 GB

Option B: --cpu N --memory_gb M

• Valid: --cpu 4 --memory_gb 16
• Both flags required together

Invalid patterns:

• ❌ --cpu 4 alone (missing memory_gb)
• ❌ --memory_gb 16 alone (missing cpu)
• ❌ --cu_count 4 --cpu 2 (conflicting specs)
• ❌ No resource spec at all

Action: Fix parameter combination and retry ONCE

3. Required flags for create

All of these MUST be present:

• --region_id (never assume default)
• --name (instance name)
• --instance_type (exact: "PayAsYouGo" or "Subscription", case-sensitive)
• --vswitch_id
• --vpc_id

Invalid patterns:

• ❌ --instance_type pay-as-you-go (wrong case)
• ❌ --instance_type PAYASYOUGO (wrong format)
• ✓ --instance_type PayAsYouGo (correct)

4. Subscription-specific requirements

If --instance_type Subscription:

• Optional: --period (1, 2, 3, 6, or 12 months)
• Optional: --auto_renew (flag)

Create Namespace Validation

1. Confirmation flag (MANDATORY)

• ✓ --confirm flag MUST be present
• ❌ Missing → SafetyCheckRequired error

2. Required flags

• --region_id
• --instance_id (must reference existing instance)
• --name (namespace name)

3. Resource specification (optional)

For creating a NEW namespace:

• Both --cpu AND --memory_gb are required together
• ❌ Invalid: only --cpu or only --memory_gb
• ❌ Invalid: omit both for a new namespace

Idempotent exception:

• If namespace already exists with the same --name, create operation can return

idempotent success without requiring new resource values.

Query Command Validation

Query commands have minimal validation:

• describe_regions: no parameters required
• describe_zones: requires --region_id
• describe: requires --region_id
• describe_namespaces: requires --region_id and --instance_id
• list_tags: requires --region_id and --resource_type

Error Code to Validation Mapping

Validation Checklist Template

Before executing create:

□ --confirm flag present
□ --region_id present
□ --name present
□ --instance_type valid (PayAsYouGo or Subscription)
□ --vswitch_id present
□ --vpc_id present
□ Resource spec: either --cu_count OR (--cpu AND --memory_gb)
□ No conflicting parameters

Before executing create_namespace:

□ --confirm flag present
□ --region_id present
□ --instance_id present
□ --name present
□ For new namespace: both --cpu AND --memory_gb present
□ Resource request does not exceed available instance capacity

Python Environment Setup Guide

Complete guide for setting up the Python environment for Flink instance operations.

Table of Contents

• Prerequisites
• Step 1: Verify Python Installation
• Step 2: Install Dependencies
• Step 3: Configure Authentication
• Step 4: Verify Setup
• Troubleshooting
• Virtual Environment (Optional)
• Prepare RAM Identity
• Security Best Practices
• Next Steps

Prerequisites

• Python 3.6 or higher
• pip (Python package manager)
• Alibaba Cloud credentials available from the default credential chain

---

Step 1: Verify Python Installation

# Check Python version (must be 3.6+)
python3 --version

Expected Output:

Python 3.6.0 or higher

If Python is not installed:

macOS

# Using Homebrew
brew install python@3.9

Linux (Ubuntu/Debian)

sudo apt-get install python3 python3-pip

Linux (CentOS/RHEL)

sudo yum install python3 python3-pip

Windows

Download from https://www.python.org/downloads/

---

Step 2: Install Dependencies

# Navigate to the project directory
cd alibabacloud-flink-instance-manage

# Install required packages
pip install -r assets/requirements.txt

This installs:

• alibabacloud-foasconsole20211028>=2.2.1 - Flink OpenAPI SDK
• alibabacloud-tea-openapi>=0.4.3 - OpenAPI client
• alibabacloud-tea-util>=0.3.14 - Utility library

Verify installation:

pip show alibabacloud-foasconsole20211028

---

Step 3: Configure Authentication

Method 1: Default Aliyun CLI Profile

Use the default profile once, then let the SDK resolve credentials from the default credential chain automatically:

aliyun configure
aliyun configure list

Method 2: RAM Role (Recommended on Alibaba Cloud runtime)

When running on ECS/ACK/FC/SAE with a RAM role attached, credentials are automatically retrieved from role metadata. No AK/SK export is needed.

---

Step 4: Verify Setup

# Test the script
python scripts/instance_ops.py describe_regions

Expected Output:

{
  "success": true,
  "operation": "describe_regions",
  "data": {
    "Regions": {
      "Region": [
        {
          "RegionId": "cn-hangzhou",
          ...
        }
      ]
    }
  },
  "request_id": "..."
}

---

Troubleshooting

Issue: Python version too low

Symptom:

Python 3.5.2
# or lower

Solution: Upgrade Python to 3.6 or higher using your system's package manager.

Issue: Module not found

Symptom:

ModuleNotFoundError: No module named 'alibabacloud_foasconsole20211028'

Solution:

pip install -r assets/requirements.txt

Issue: Missing credentials

Symptom:

NoCredentialError: unable to resolve credentials from default credential chain

Solution:

aliyun configure
aliyun configure list

Issue: Permission denied

Symptom:

Forbidden.RAM: Insufficient permissions

Solution: 1. Check RAM user permissions according to the RAM policy document 2. Attach required policies to the RAM user 3. Verify the RAM identity is active and authorized

Issue: pip not found

Symptom:

bash: pip: command not found

Solution:

# Use pip3 instead
pip3 install -r assets/requirements.txt

# Or install pip
sudo apt-get install python3-pip  # Ubuntu/Debian
sudo yum install python3-pip      # CentOS/RHEL

---

Virtual Environment (Optional)

For isolated dependencies, use a virtual environment:

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r assets/requirements.txt

# Deactivate when done
deactivate

---

Prepare RAM Identity

1. Log in to Alibaba Cloud Console: https://ram.console.aliyun.com/ 2. Create or select a RAM identity (user/role) with required policies 3. Prefer temporary credentials via RAM role when possible 4. If using a local profile, configure it once with aliyun configure 5. Verify permissions with the RAM policy document

---

Security Best Practices

1. Never commit credentials - Never hardcode AK/SK in code or scripts 2. Use RAM users - Don't use the root account for daily operations 3. Rotate AccessKeys regularly - Every 90 days recommended 4. Principle of least privilege - Grant only necessary permissions 5. Use RAM roles/default chain - Prefer temporary credentials over explicit AK/SK handling

---

Next Steps

After setup: 1. Read SKILL.md in the project root for usage documentation 2. Try the quick start examples in the quick-start document 3. Review RAM policy requirements before production use

Quick Start

Alibaba Cloud Flink VVP instance operations with create/query command scope.

Trigger Recognition

Use this skill when request is about:

• Flink instance create/query
• Flink namespace create/query
• Flink region/zone/tag queries

Do not use this skill for:

• Flink SQL or Flink jobs
• Other Alibaba Cloud services (ECS, Kafka, OSS, DataWorks)
• Update or delete operations

1) Install Dependencies

pip install -r assets/requirements.txt

2) Configure Credentials

aliyun configure
aliyun configure list

3) Run Read-only Checks

python scripts/instance_ops.py describe_regions
python scripts/instance_ops.py describe_zones --region_id cn-hangzhou
python scripts/instance_ops.py describe --region_id cn-hangzhou

4) Create Instance and Verify

python scripts/instance_ops.py create \
  --region_id cn-hangzhou \
  --name my-instance \
  --instance_type PayAsYouGo \
  --zone_id cn-hangzhou-g \
  --vswitch_id vsw-xxx \
  --vpc_id vpc-xxx \
  --cpu 200 \
  --memory_gb 800 \
  --confirm

python scripts/instance_ops.py describe --region_id cn-hangzhou

5) Create Namespace and Verify

python scripts/instance_ops.py create_namespace \
  --region_id cn-hangzhou \
  --instance_id f-cn-xxx \
  --name prod-ns \
  --cpu 100 \
  --memory_gb 400 \
  --confirm

python scripts/instance_ops.py describe_namespaces \
  --region_id cn-hangzhou \
  --instance_id f-cn-xxx

Command Scope

Required Confirmation

Reference Map

Output Shape

{
  "success": true,
  "operation": "describe",
  "data": {},
  "request_id": "..."
}

Exit codes: 0 = success, 1 = error.

RAM Policies for Flink Instance Operations

Alibaba Cloud RAM permissions required by scripts/instance_ops.py under a create/query-only execution model.

Note: For OpenAPI 2021-10-28, official action names use the stream:*

namespace.

Required Permissions

The following actions cover allowed commands in this skill:

• stream:CreateVvpInstance - create
• stream:DescribeVvpInstances - describe
• stream:CreateVvpNamespace - create_namespace
• stream:DescribeVvpNamespaces - describe_namespaces
• stream:QueryTagVvpResources - list_tags

DescribeSupportedRegions and DescribeSupportedZones pages currently state "暂无授权信息透出", so they are intentionally not listed as mandatory actions.

Minimum Permission Policy

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "stream:CreateVvpInstance",
        "stream:DescribeVvpInstances",
        "stream:CreateVvpNamespace",
        "stream:DescribeVvpNamespaces",
        "stream:QueryTagVvpResources"
      ],
      "Resource": [
        "acs:stream:*:*:vvpinstance/*",
        "acs:stream:*:*:vvpinstance/*/vvpnamespace/*"
      ]
    }
  ]
}

Permission Breakdown by Operation

Resource ARN Examples

Use resource-level constraints when possible:

• Instance: acs:stream:{regionId}:{accountId}:vvpinstance/{instanceId}
• Namespace:

acs:stream:{regionId}:{accountId}:vvpinstance/{instanceId}/vvpnamespace/{namespace}

Example policy for one specific instance:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "stream:DescribeVvpInstances",
        "stream:DescribeVvpNamespaces"
      ],
      "Resource": "acs:stream:cn-hangzhou:123456789012:vvpinstance/f-cn-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 listed above.

Troubleshooting

Error: Forbidden.RAM

1. Verify attached policies:

   aliyun ram ListPoliciesForUser --UserName <your-username>

2. Attach a policy that includes required stream:* actions. 3. Retry the operation.

Error: InvalidAccessKeyId.NotFound

1. Verify AccessKey:

   aliyun ram ListAccessKeys --UserName <your-username>

2. Rotate/recreate AccessKey and refresh local profile.

References

• OpenAPI RAM actions
• OpenAPI overview
• RAM Console

References Index

This folder is organized by operation lifecycle, not by evaluation workflow.

1) Start Here

• quick-start.md: install, auth, first commands
• trigger-recognition-guide.md: when to use this skill
• core-execution-flow.md: standard flow for create/query tasks

2) Execute Commands

• command-templates.md: copy-paste command templates
• parameter-validation.md: pre-execution parameter checks
• required-confirmation-model.md: mandatory --confirm rules

3) Verify and Close

• verification-method.md: read-back verification patterns
• instance-state-management.md: readiness and polling rules
• output-handling.md: output parsing, retry policy, completion status
• acceptance-criteria.md: operation completion checklist

4) Troubleshooting

• common-failures.md: common error patterns and fixes
• python-environment-setup.md: Python/runtime troubleshooting
• cli-installation-guide.md: Aliyun CLI diagnostics and setup

5) Permissions and APIs

• ram-policies.md: RAM policy requirements
• related-apis.md: OpenAPI action mapping

Related APIs and Command Mapping

Alibaba Cloud Flink (Real-Time Compute) API version 2021-10-28.

Mandatory execution rule

Use this document for mapping/reference only. During task execution, always run operations through:

python scripts/instance_ops.py <command> ...

Do not execute raw product commands such as aliyun foasconsole ....

Command to API mapping (create/query only)

Notes

• Product code is still foasconsole, but this remains an internal implementation detail.
• Confirmation checks are required only for create commands.
• For executable examples, follow SKILL.md and core-execution-flow.md.

Required confirmation model

Use a hard confirmation gate for every create operation. Missing confirmation flags is a policy violation.

1) Pre-execution hard gate (mandatory)

Before executing any create command:

1. Build the full command string first. 2. Validate the required confirmation flag is present. 3. If the flag is missing, do not execute. Rebuild the command with the correct flag. 4. Never bypass this check, even if a previous step failed. 5. Keep confirmation evidence in logs/output (SafetyCheckRequired or --confirm).

2) Command-to-flag mapping

• create: --confirm
• create_namespace: --confirm

Query commands do not require confirmation flags.

Trigger Recognition Guide

This guide helps identify when to use the alibabacloud-flink-instance-manage skill.

Quick Rule

Use this skill when the prompt is about Flink VVP instance/namespace create or query.

Positive Triggers (Use Skill)

Instance Operations

Namespace Operations

Negative Triggers (Do Not Use Skill)

Different Service Domain

Different Flink Domain

In-Domain but Rejected (Trigger + Reject)

Ambiguous Cases

When request intent is unclear, ask one clarifying question:

• "Do you need Flink instance/namespace management, or Flink SQL/job operations?"

Decision Tree

User request about Flink
    │
    ├─ Mentions "instance" or "namespace" or "VVP"?
    │   ├─ YES → USE THIS SKILL
    │   │   ├─ create/query → Execute
    │   │   └─ update/delete → Reject with explanation
    │   │
    │   └─ NO → Check further
    │       ├─ Mentions "SQL" or "job" → Different Flink skill
    │       └─ Unclear → Ask user to clarify
    │
    └─ Request about other service (ECS, Kafka, OSS)?
        └─ YES → Do NOT use this skill

Verification Methods

Step-by-step verification methods for Flink instance create/query operations.

Mandatory rule

All executable examples in this document use:

python scripts/instance_ops.py <command> ...

Do not run raw aliyun foasconsole resource commands as substitutes.

Pre-operation verification

1) Environment diagnostics

aliyun version
aliyun configure list
python scripts/instance_ops.py describe_regions

If the Python command fails with missing modules, follow python-environment-setup.md.

2) Region/network readiness (when create is needed)

python scripts/instance_ops.py describe_regions
python scripts/instance_ops.py describe_zones --region_id cn-hangzhou

If VPC/VSwitch is missing, provide explicit parameters before create execution.

Operation verification pattern

For every create operation, follow:

1. execute create with required confirmation flag 2. run read-back verification 3. conclude status based on read-back result

Example: create instance

python scripts/instance_ops.py create \
  --region_id cn-hangzhou \
  --name verify-demo \
  --instance_type PayAsYouGo \
  --vswitch_id vsw-xxx \
  --vpc_id vpc-xxx \
  --cpu 200 \
  --memory_gb 800 \
  --confirm

Read-back:

python scripts/instance_ops.py describe --region_id cn-hangzhou

Example: create namespace

python scripts/instance_ops.py create_namespace \
  --region_id cn-hangzhou \
  --instance_id f-cn-xxx \
  --name verify-ns \
  --cpu 100 \
  --memory_gb 400 \
  --confirm

Read-back:

python scripts/instance_ops.py describe_namespaces \
  --region_id cn-hangzhou \
  --instance_id f-cn-xxx

Failure verification

• Parse error.code and error.message from command output
• For create operations, also inspect confirmation_check for auditable --confirm evidence
• Apply retry policy in output-handling.md
• Retry only same operation with corrected parameters (max one retry)
• If unresolved, report as incomplete with remediation
• For lifecycle flows requiring both create steps, keep overall status non-completed when

namespace create fails (for example InsufficientResources)

References

• core-execution-flow.md
• required-confirmation-model.md
• output-handling.md
• python-environment-setup.md