Alibabacloud Tablestore Ops

Tablestore Read-Only Operations

This skill provides CLI-based read-only operations for querying Alibaba Cloud Tablestore (OTS) instances and data tables. Tablestore is a fully managed NoSQL database service that supports storing and accessing large amounts of structured data.

Architecture: Aliyun CLI (otsutil) → Tablestore Instance → Data Tables (Wide Table / TimeSeries)

Scope: This skill only covers read/query operations. No create, update, or delete operations are included.

Prerequisites

• Tablestore service must be activated. See Alibaba Cloud Console
• Obtain AccessKey ID and AccessKey Secret from RAM Console

Pre-check: Aliyun CLI Required (Version 3.3.0+)

>

Tablestore operations are performed via aliyun otsutil command, which is part of the Aliyun CLI.

IMPORTANT: The otsutil subcommand is only available in Aliyun CLI version 3.3.0 or later.

The Homebrew version may be outdated - download directly from the official CDN.

See references/cli-installation-guide.md for installation instructions.

Installation

Install Aliyun CLI (Version 3.3.0+)

WARNING: The Homebrew version (brew install aliyun-cli) may not include otsutil.

Always download from the official CDN to ensure you get version 3.3.0+ with otsutil support.

Option 1: Download Binary (Recommended)

Option 2: Mac GUI Installer

Download Mac PKG and double-click to install.

macOS / Linux Binary Setup

# Download (example for macOS Universal)
curl -L -o aliyun-cli.tgz https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz

# Extract
tar -xzf aliyun-cli.tgz

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

# Verify installation and version (must be 3.3.0+)
aliyun version

# Verify otsutil is available
aliyun otsutil help

Windows Setup

1. Download the zip file from the download link above 2. Extract the zip file to get aliyun.exe 3. Add the directory to your PATH environment variable 4. Verify: aliyun version (must show 3.3.0 or later)

Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command,

ALL user-customizable parameters (e.g., RegionId, instance names, AccessKey, endpoint, etc.)

MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Note: AccessKey credentials are configured via aliyun configure, not passed as command parameters.

Authentication

Pre-check: Alibaba Cloud Credentials Required

>

Security Rules:

- NEVER echo or print AccessKey values

- NEVER ask the user to input AccessKey directly in plain text

- ONLY configure credentials using aliyun configure

>

If no valid credentials exist:

1. Obtain AccessKey from Alibaba Cloud Console

2. For security, use RAM user credentials with AliyunOTSReadOnlyAccess permission

3. Configure credentials using Aliyun CLI

Configure Credentials (Aliyun CLI)

# Interactive configuration (recommended)
aliyun configure

# Follow prompts:
# Aliyun Access Key ID [None]: <YOUR_ACCESS_KEY_ID>
# Aliyun Access Key Secret [None]: <YOUR_ACCESS_KEY_SECRET>
# Default Region Id [None]: cn-hangzhou
# Default output format [json]: json
# Default Language [zh]: en

Configure with Specific Profile

# Create a named profile
aliyun configure --profile tablestore-user

# Use the profile for otsutil commands
aliyun otsutil --profile tablestore-user list_instance -r cn-hangzhou

Supported Authentication Modes

RAM Policy

Required permissions for Tablestore read-only operations:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ots:GetInstance",
        "ots:ListInstance",
        "ots:ListTable",
        "ots:DescribeTable"
      ],
      "Resource": "acs:ots:*:*:instance/*"
    }
  ]
}

Or use the managed policy: AliyunOTSReadOnlyAccess

See references/ram-policies.md for detailed permissions.

Core Workflow

Part 1: Instance Read Operations

Task 1: Configure Instance (Connect to Instance)

Configure the endpoint to select which instance to operate on.

Important: You must configure the instance before performing any table operations.

Command Format:

aliyun otsutil config --endpoint <endpoint> --instance <instanceName>

Endpoint Format:

• Public: https://<instance_name>.<region_id>.ots.aliyuncs.com
• VPC: https://<instance_name>.<region_id>.vpc.tablestore.aliyuncs.com

Example:

aliyun otsutil config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance

Response:

{
  "Endpoint": "https://myinstance.cn-hangzhou.ots.aliyuncs.com",
  "AccessKeyId": "NTS**********************",
  "AccessKeySecret": "7NR2****************************************",
  "AccessKeySecretToken": "",
  "Instance": "myinstance"
}

Task 2: Describe Instance

View instance details including name, creation time, status, and quota.

Command Format:

aliyun otsutil describe_instance -r <regionId> -n <instanceName>

Example:

aliyun otsutil describe_instance -r cn-hangzhou -n myinstance

Response:

{
  "ClusterType": "ssd",
  "CreateTime": "2024-07-18 09:15:10",
  "Description": "First instance created by CLI.",
  "InstanceName": "myinstance",
  "Network": "NORMAL",
  "Quota": { "EntityQuota": 64 },
  "ReadCapacity": 5000,
  "Status": 1,
  "TagInfos": {},
  "UserId": "1379************",
  "WriteCapacity": 5000
}

Status Values: 1 = Running. Other values indicate abnormal status.

Task 3: List Instances

Get all instances in a specified region.

Command Format:

aliyun otsutil list_instance -r <regionId>

Example:

aliyun otsutil list_instance -r cn-hangzhou

Response:

["myinstance", "another-instance"]

Note: Returns empty array [] if no instances exist in the region.

---

Part 2: Data Table Read Operations

Prerequisite: You must first configure an instance endpoint using aliyun otsutil config (Task 1) before running table operations.

Task 4: Select Table (use)

Select a data table for subsequent operations.

Command Format:

aliyun otsutil use --wc -t <tableName>

Example:

aliyun otsutil use -t mytable

Task 5: List Tables (list)

List table names under the current instance.

Command Format:

aliyun otsutil list [options]

Examples:

# List tables of the current type
aliyun otsutil list

# List all tables
aliyun otsutil list -a

# List only data tables
aliyun otsutil list -w

# List only timeseries tables
aliyun otsutil list -t

Task 6: Describe Table (desc)

View detailed table information including primary keys, TTL, max versions, and throughput.

Command Format:

aliyun otsutil desc [-t <tableName>] [-f <format>] [-o <outputPath>]

Examples:

# Describe the currently selected table
aliyun otsutil desc

# Describe a specific table
aliyun otsutil desc -t mytable

# Output in table format
aliyun otsutil desc -t mytable -f table

# Save table info to file
aliyun otsutil desc -t mytable -o /tmp/table_meta.json

Example Response:

{
  "Name": "mytable",
  "Meta": {
    "Pk": [
      { "C": "uid", "T": "string", "Opt": "none" },
      { "C": "pid", "T": "integer", "Opt": "none" }
    ]
  },
  "Option": {
    "TTL": -1,
    "Version": 1
  },
  "CU": {
    "Read": 0,
    "Write": 0
  }
}

Response Fields:

Success Verification

See references/verification-method.md for detailed verification steps.

Quick Verification: 1. After aliyun otsutil config: Response should show correct Endpoint and Instance 2. After aliyun otsutil list_instance: Verify expected instance names appear in the list 3. After aliyun otsutil describe_instance: Verify Status=1 (Running) 4. After aliyun otsutil list: Verify expected table names appear 5. After aliyun otsutil desc: Verify table schema and configuration are correct

Related APIs

See references/related-apis.md for complete API reference.

Best Practices

1. Use RAM Users: Create RAM users with read-only permissions instead of using root account credentials 2. Use ReadOnly Policy: Apply AliyunOTSReadOnlyAccess for query-only workflows 3. Region Selection: Choose the region closest to your application for lower latency 4. Network Type: Use VPC endpoint for better security in production environments 5. Credential Security: Use aliyun configure for credential management; never hardcode credentials 6. Use Profiles: Create dedicated profiles for different environments using aliyun configure --profile <name> 7. Export Table Schema: Use aliyun otsutil desc -o <file> to export and backup table definitions

Reference Links

Acceptance Criteria: Tablestore Read-Only Operations

Scenario: Tablestore CLI Read-Only Instance & Table Operations via aliyun otsutil Purpose: Skill testing acceptance criteria

CRITICAL: Version Requirement

- Aliyun CLI version 3.3.0 or later is required

- Homebrew version is often outdated and does NOT include otsutil

- Always download from official CDN: https://aliyuncli.alicdn.com/

- Credentials are configured via aliyun configure

---

Pre-requisite: Version Check

✅ CORRECT Version Check

# Check version
aliyun version
# Output: 3.3.3 (or any version >= 3.3.0)

# Verify otsutil works
aliyun otsutil help
# Output: Shows available commands

❌ INCORRECT (Version Too Old)

aliyun version
# Output: 3.0.278 (version < 3.3.0)

aliyun otsutil help
# Output: ERROR: 'otsutil' is not a valid command or product

---

Correct CLI Command Patterns

1. config Command

Configure instance endpoint. Credentials are handled by aliyun configure, not this command.

✅ CORRECT

# Configure instance endpoint only (credentials already configured via aliyun configure)
aliyun otsutil config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance

❌ INCORRECT

# Wrong: Invalid endpoint format (missing https://)
aliyun otsutil config --endpoint myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance

# Wrong: Mismatched endpoint and instance name
aliyun otsutil config --endpoint https://instance1.cn-hangzhou.ots.aliyuncs.com --instance instance2

2. describe_instance Command

✅ CORRECT

aliyun otsutil describe_instance -r cn-hangzhou -n myinstance
aliyun otsutil describe_instance -n prod-orders -r cn-shanghai

❌ INCORRECT

# Wrong: Using --region instead of -r
aliyun otsutil describe_instance --region cn-hangzhou -n myinstance

# Wrong: Missing -n parameter
aliyun otsutil describe_instance -r cn-hangzhou

# Wrong: Missing -r parameter
aliyun otsutil describe_instance -n myinstance

# Wrong: Invalid region ID
aliyun otsutil describe_instance -r hangzhou -n myinstance

3. list_instance Command

✅ CORRECT

aliyun otsutil list_instance -r cn-hangzhou
aliyun otsutil list_instance -r cn-shanghai
aliyun otsutil list_instance -r ap-southeast-1

❌ INCORRECT

# Wrong: Using --region instead of -r
aliyun otsutil list_instance --region cn-hangzhou

# Wrong: Missing required -r parameter
aliyun otsutil list_instance

# Wrong: Invalid region format
aliyun otsutil list_instance -r hangzhou

4. use Command (Select Table)

✅ CORRECT

aliyun otsutil use -t mytable
aliyun otsutil use --wc -t mytable

❌ INCORRECT

# Wrong: Missing required -t parameter
aliyun otsutil use

# Wrong: Using --wc without table name
aliyun otsutil use --wc

5. list Command (List Tables)

✅ CORRECT

aliyun otsutil list
aliyun otsutil list -a
aliyun otsutil list -w
aliyun otsutil list -t
aliyun otsutil list -d

❌ INCORRECT

# Wrong: Using list_table (not the correct command)
aliyun otsutil list_table

# Wrong: Combining -w and -t (mutually exclusive)
aliyun otsutil list -w -t

6. desc Command (Describe Table)

✅ CORRECT

aliyun otsutil desc
aliyun otsutil desc -t mytable
aliyun otsutil desc -t mytable -f json
aliyun otsutil desc -t mytable -f table
aliyun otsutil desc -t mytable -o /tmp/table_meta.json

❌ INCORRECT

# Wrong: Using describe_table (not the correct command)
aliyun otsutil describe_table -t mytable

# Wrong: Invalid format option
aliyun otsutil desc -t mytable -f xml

# Wrong: Using --name instead of -t
aliyun otsutil desc --name mytable

---

Endpoint Format Patterns

✅ CORRECT Endpoint Formats

# Public endpoint
https://myinstance.cn-hangzhou.ots.aliyuncs.com
https://prod-orders.cn-shanghai.ots.aliyuncs.com

# VPC endpoint
https://myinstance.cn-hangzhou.vpc.tablestore.aliyuncs.com
https://prod-orders.cn-shanghai.vpc.tablestore.aliyuncs.com

# HTTP (allowed but not recommended)
http://myinstance.cn-hangzhou.ots.aliyuncs.com

❌ INCORRECT Endpoint Formats

# Wrong: Missing protocol
myinstance.cn-hangzhou.ots.aliyuncs.com

# Wrong: Using .com instead of .aliyuncs.com
https://myinstance.cn-hangzhou.ots.com

# Wrong: Missing instance name
https://cn-hangzhou.ots.aliyuncs.com

# Wrong: Wrong domain structure
https://ots.cn-hangzhou.myinstance.aliyuncs.com

# Wrong: Using region name instead of ID
https://myinstance.hangzhou.ots.aliyuncs.com

---

Instance Name Patterns

✅ CORRECT Instance Names

myinstance
prod-orders
test-data-2024
a1b2c3
my-instance-123

❌ INCORRECT Instance Names

# Wrong: Uppercase letters
MyInstance
MYINSTANCE

# Wrong: Starting with number
123instance

# Wrong: Too short (less than 3 characters)
ab

# Wrong: Too long (more than 16 characters)
my-very-long-instance-name-here

# Wrong: Special characters other than hyphen
my_instance
my.instance
my@instance

# Wrong: Starting with hyphen
-myinstance

# Wrong: Ending with hyphen
myinstance-

---

Region ID Patterns

✅ CORRECT Region IDs

cn-hangzhou
cn-shanghai
cn-beijing
cn-shenzhen
cn-hongkong
ap-southeast-1
ap-northeast-1
us-west-1
us-east-1
eu-central-1

❌ INCORRECT Region IDs

# Wrong: Using region name
hangzhou
shanghai

# Wrong: Missing cn- prefix for China regions
hangzhou

# Wrong: Incorrect format
cn_hangzhou
cn.hangzhou
CN-HANGZHOU

---

Response Validation Patterns

describe_instance Response

✅ CORRECT Response Structure

{
  "ClusterType": "ssd",
  "CreateTime": "2024-07-18 09:15:10",
  "Description": "Instance description",
  "InstanceName": "myinstance",
  "Network": "NORMAL",
  "Quota": {
    "EntityQuota": 64
  },
  "ReadCapacity": 5000,
  "Status": 1,
  "TagInfos": {},
  "UserId": "1379123456789012",
  "WriteCapacity": 5000
}

Required Fields:

• InstanceName - Must match requested instance
• Status - Should be 1 for healthy instance
• ClusterType - ssd or hybrid
• CreateTime - Valid timestamp format

list_instance Response

✅ CORRECT Response Structure

["instance1", "instance2", "instance3"]

Or empty:

[]

❌ INCORRECT Response

# Wrong: Not an array
{"instances": ["instance1", "instance2"]}

# Wrong: Contains non-string values
[1, 2, 3]

---

Common Anti-Patterns

1. Forgetting to Configure Aliyun CLI Credentials

❌ WRONG

# Running otsutil commands without configuring aliyun credentials
aliyun otsutil list_instance -r cn-hangzhou
# Error: credentials not found

✅ CORRECT

# First configure aliyun credentials
aliyun configure
# Then run otsutil commands
aliyun otsutil list_instance -r cn-hangzhou

2. Assuming Default Region

❌ WRONG

# Assuming cn-hangzhou without asking user
aliyun otsutil list_instance -r cn-hangzhou

✅ CORRECT

# Ask user to confirm region before execution
# User confirms: cn-hangzhou
aliyun otsutil list_instance -r cn-hangzhou

3. Forgetting to Configure Instance Before Table Operations

❌ WRONG

# Running table commands without configuring instance first
aliyun otsutil list
# Error: no instance configured

✅ CORRECT

# First configure the instance
aliyun otsutil config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance

# Then run table commands
aliyun otsutil list -w
aliyun otsutil desc -t mytable

---

Test Scenarios

Scenario 1: Instance Discovery

Steps: 1. Configure Aliyun CLI credentials with aliyun configure 2. List instances in region 3. Describe each instance

Expected Results:

• aliyun otsutil list_instance -r <region> returns array of instance names
• Each aliyun otsutil describe_instance returns valid instance info with Status = 1

Scenario 2: Table Discovery

Steps: 1. Configure Aliyun CLI credentials 2. Configure instance endpoint with aliyun otsutil config 3. List all data tables 4. Describe each table

Expected Results:

• aliyun otsutil list -w returns data table names
• aliyun otsutil desc -t <name> returns table schema with primary keys

Scenario 3: Multi-Region Instance Exploration

Steps: 1. Configure Aliyun CLI credentials 2. List instances in cn-hangzhou 3. List instances in cn-shanghai 4. Switch between instances using config 5. List tables in each instance

Expected Results:

• Each region returns its own instance list
• Config command updates current context
• Each instance returns its own table list

Scenario 4: Export Table Schema

Steps: 1. Configure Aliyun CLI credentials 2. Configure instance endpoint 3. Describe table and export to file

Expected Results:

• aliyun otsutil desc -t mytable -o /tmp/meta.json creates file with valid JSON
• File contains Name, Meta.Pk, Option, CU fields

Aliyun CLI Installation Guide (with otsutil for Tablestore)

Complete guide for installing and configuring Aliyun CLI to use Tablestore operations via aliyun otsutil.

CRITICAL: Version Requirement

>

The otsutil subcommand is only available in Aliyun CLI version 3.3.0 or later.

- Homebrew version may be outdated (e.g., 3.0.x) and does NOT include otsutil

- Always download directly from the official CDN to ensure you get the latest version

- The otsutil subcommand automatically downloads and manages the Tablestore CLI binary on first use

Installation

Recommended: Download from Official CDN

WARNING: Do NOT use brew install aliyun-cli - it may install an outdated version without otsutil support.

macOS (Universal Binary - Recommended)

# Download
curl -L -o aliyun-cli.tgz https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz

# Extract
tar -xzf aliyun-cli.tgz

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

# Verify version (MUST be 3.3.0 or later)
aliyun version

# Verify otsutil is available
aliyun otsutil help

macOS (GUI Installer)

1. Download the Mac PKG 2. Double-click the PKG file to install 3. Follow the installer prompts 4. Verify: aliyun version (must show 3.3.0+) 5. Verify otsutil: aliyun otsutil help

Linux (AMD64)

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

# Extract
tar -xzf aliyun-cli.tgz

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

# Verify version (MUST be 3.3.0 or later)
aliyun version

# Verify otsutil is available
aliyun otsutil help

Linux (ARM64)

# Download
curl -L -o aliyun-cli.tgz https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract
tar -xzf aliyun-cli.tgz

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

# Verify version (MUST be 3.3.0 or later)
aliyun version

# Verify otsutil is available
aliyun otsutil help

Windows

1. Download the Windows ZIP 2. Extract the zip file to get aliyun.exe 3. Add the directory to your PATH environment variable 4. Run from Command Prompt or PowerShell:

• aliyun version (must show 3.3.0+)
• aliyun otsutil help (verify otsutil is available)

Configuration

Basic Configuration (Interactive)

aliyun configure

Follow the prompts:

Configuring profile 'default' ...
Aliyun Access Key ID [None]: <Your AccessKey ID>
Aliyun Access Key Secret [None]: <Your AccessKey Secret>
Default Region Id [None]: cn-hangzhou
Default output format [json]: json
Default Language [zh]: en

Configuration with Named Profile

# Create a dedicated profile for Tablestore operations
aliyun configure --profile tablestore-ops

# Use the profile
aliyun otsutil --profile tablestore-ops list_instance -r cn-hangzhou

Authentication Modes

RAM Role Assumption Example

aliyun configure --mode RamRoleArn --profile role-user

# Follow prompts:
# Access Key Id []: <AccessKey ID>
# Access Key Secret []: <AccessKey Secret>
# Sts Region []: cn-hangzhou
# Ram Role Arn []: acs:ram::<account-id>:role/<role-name>
# Role Session Name []: tablestore-session
# Expired Seconds []: 900

Configuration Options

Using otsutil

First Run

On the first run, aliyun otsutil automatically downloads the Tablestore CLI binary:

aliyun otsutil help

The binary is downloaded to ~/.aliyun/ and managed automatically.

Configure Instance Endpoint

Before running table operations, configure the instance endpoint:

aliyun otsutil config --endpoint https://<instance>.cn-hangzhou.ots.aliyuncs.com --instance <instance>

Endpoint Format

Public Network

https://<instance_name>.<region_id>.ots.aliyuncs.com

Example: https://myinstance.cn-hangzhou.ots.aliyuncs.com

VPC Network

https://<instance_name>.<region_id>.vpc.tablestore.aliyuncs.com

Example: https://myinstance.cn-hangzhou.vpc.tablestore.aliyuncs.com

Common Regions

Troubleshooting

otsutil command not found

Symptom: aliyun otsutil returns "ERROR: 'otsutil' is not a valid command or product"

Cause: You have an outdated version of Aliyun CLI (< 3.3.0). The Homebrew version is often outdated.

Solution: 1. Check your version: aliyun version 2. If version is below 3.3.0, download the latest version from CDN:

   # Remove old version (if installed via homebrew)
   brew uninstall aliyun-cli 2>/dev/null
   
   # Download latest from CDN
   curl -L -o aliyun-cli.tgz https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz
   tar -xzf aliyun-cli.tgz
   sudo mv aliyun /usr/local/bin/
   
   # Verify
   aliyun version  # Should show 3.3.0+
   aliyun otsutil help  # Should work now

Command not found: aliyun

Ensure the aliyun binary is in your PATH:

# Check if aliyun is in PATH
which aliyun

# If not found, add to PATH
export PATH=$PATH:/usr/local/bin

Authentication failed

1. Verify credentials with:

   aliyun sts GetCallerIdentity

2. Re-configure if needed:

   aliyun configure

3. Check RAM user has AliyunOTSReadOnlyAccess permission

otsutil download failed

If the Tablestore CLI binary fails to download:

1. Check network connectivity 2. Try running with verbose output:

   aliyun otsutil help

3. The binary is stored in ~/.aliyun/ts - check if it exists

Connection timeout

• Check your network connection
• Verify the endpoint URL is correct
• Ensure the instance exists in the specified region

Profile not found

# List available profiles
aliyun configure list

# Create a new profile
aliyun configure --profile <name>

Verification

Test your installation and configuration:

# Verify Aliyun CLI installation
aliyun version

# Verify credentials
aliyun sts GetCallerIdentity

# Verify otsutil (will auto-download Tablestore CLI if needed)
aliyun otsutil help

# List instances in a region
aliyun otsutil list_instance -r cn-hangzhou

If configured correctly, you'll see a list of instances (or empty array if none exist).

Supported Platforms

The aliyun otsutil command supports the following platforms:

References

• Aliyun CLI GitHub
• Aliyun CLI Documentation
• Tablestore Product Page
• Official Documentation

Tablestore Read-Only Operations - RAM Policies

This document describes the RAM (Resource Access Management) permissions required for Tablestore read-only operations via aliyun otsutil.

Minimum Required Permissions

Read-Only Operations Policy

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ots:GetInstance",
        "ots:ListInstance",
        "ots:ListTable",
        "ots:DescribeTable"
      ],
      "Resource": "acs:ots:*:*:instance/*"
    }
  ]
}

Permission Details

Permission-to-Command Mapping

Permission Descriptions

Managed Policies

Alibaba Cloud provides managed policies for Tablestore:

AliyunOTSFullAccess

Full access to all Tablestore operations (more than needed for read-only).

{
  "Version": "1",
  "Statement": [
    {
      "Action": "ots:*",
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}

Use case: Not recommended for read-only workflows

AliyunOTSReadOnlyAccess (Recommended)

Read-only access to Tablestore resources.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ots:BatchGet*",
        "ots:Describe*",
        "ots:Get*",
        "ots:List*"
      ],
      "Resource": "*"
    }
  ]
}

Use case: Read-only query workflows (recommended for this skill)

Custom Policy Examples

Instance + Table Read-Only

For users who only need to query instances and table schemas:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ots:GetInstance",
        "ots:ListInstance",
        "ots:ListTable",
        "ots:DescribeTable"
      ],
      "Resource": "acs:ots:*:*:instance/*"
    }
  ]
}

Region-Specific Access

Limit operations to specific regions:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ots:GetInstance",
        "ots:ListInstance",
        "ots:ListTable",
        "ots:DescribeTable"
      ],
      "Resource": "acs:ots:cn-hangzhou:*:instance/*"
    }
  ]
}

Specific Instance Read-Only Access

Limit access to specific instances:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ots:GetInstance",
        "ots:ListTable",
        "ots:DescribeTable"
      ],
      "Resource": [
        "acs:ots:cn-hangzhou:*:instance/prod-instance",
        "acs:ots:cn-hangzhou:*:instance/staging-instance"
      ]
    }
  ]
}

Resource Format

Instance Resource ARN

acs:ots:<region>:<account-id>:instance/<instance-name>

Components:

• acs - Alibaba Cloud Service prefix
• ots - Service name (Tablestore)
• <region> - Region ID (e.g., cn-hangzhou) or * for all regions
• <account-id> - Alibaba Cloud account ID or *
• instance/<instance-name> - Instance name or * for all instances

Examples:

• acs:ots:*:*:instance/* - All instances in all regions
• acs:ots:cn-hangzhou:*:instance/* - All instances in cn-hangzhou
• acs:ots:cn-hangzhou:*:instance/myinstance - Specific instance

Applying Policies

Via RAM Console

1. Log in to RAM Console 2. Navigate to Identities > Users 3. Select the target user 4. Click Add Permissions 5. Select or create the policy 6. Click OK to apply

Via Aliyun CLI

# Attach managed policy
aliyun ram attach-policy-to-user \
  --policy-name AliyunOTSFullAccess \
  --policy-type System \
  --user-name <username> \
  --user-agent AlibabaCloud-Agent-Skills

# Create custom policy
aliyun ram create-policy \
  --policy-name OTSInstanceManagement \
  --policy-document '{"Version":"1","Statement":[{"Effect":"Allow","Action":["ots:CreateInstance","ots:GetInstance","ots:ListInstance"],"Resource":"acs:ots:*:*:instance/*"}]}' \
  --user-agent AlibabaCloud-Agent-Skills

Security Best Practices

1. Principle of Least Privilege: Only grant permissions that are actually needed 2. Use RAM Users: Never use root account credentials for daily operations 3. Separate Environments: Use different RAM users/roles for dev/staging/production 4. Regular Audits: Review and remove unused permissions periodically 5. Use STS: For temporary access, use Security Token Service instead of long-term credentials 6. Enable MFA: Require multi-factor authentication for sensitive operations

Troubleshooting Permission Issues

Error: "Permission Denied"

1. Check RAM user has required policy attached 2. Verify policy includes the specific action (e.g., ots:ListTable, ots:DescribeTable) 3. Verify resource pattern matches the target instance

Error: "Access Denied"

1. Confirm AccessKey belongs to the correct RAM user 2. Verify AccessKey is active (not disabled) 3. Check for deny policies that might override allow policies

Debug Command

Use aliyun CLI to check current permissions:

aliyun ram list-policies-for-user --user-name <username> --user-agent AlibabaCloud-Agent-Skills

Reference Links

• RAM Documentation
• Tablestore Authorization
• RAM Console
• Instance Operations Doc
• Data Table Operations Doc

Tablestore CLI - Related APIs Reference (Read-Only)

Complete reference for Tablestore CLI read-only commands for instance and data table operations via aliyun otsutil.

Note: All commands are executed using aliyun otsutil <command> format. Credentials are managed via aliyun configure.

Instance Read Commands

config

Configure instance endpoint for table operations. Note: Credentials are handled by Aliyun CLI (aliyun configure), not this command.

Syntax:

aliyun otsutil config [--endpoint <endpoint>] [--instance <instanceName>]

Parameters:

Endpoint Format:

Examples:

# Configure instance endpoint
aliyun otsutil config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance

Response:

{
  "Endpoint": "https://myinstance.cn-hangzhou.ots.aliyuncs.com",
  "AccessKeyId": "LTAI5t***",
  "AccessKeySecret": "7NR2***",
  "AccessKeySecretToken": "",
  "Instance": "myinstance"
}

---

describe_instance

Get detailed information about a specific instance.

Syntax:

aliyun otsutil describe_instance -r <regionId> -n <instanceName>

Parameters:

Example:

aliyun otsutil describe_instance -r cn-hangzhou -n myinstance

Response:

{
  "ClusterType": "ssd",
  "CreateTime": "2024-07-18 09:15:10",
  "Description": "First instance created by CLI.",
  "InstanceName": "myinstance",
  "Network": "NORMAL",
  "Quota": {
    "EntityQuota": 64
  },
  "ReadCapacity": 5000,
  "Status": 1,
  "TagInfos": {},
  "UserId": "1379************",
  "WriteCapacity": 5000
}

Response Fields:

---

list_instance

List all instances in a specified region.

Syntax:

aliyun otsutil list_instance -r <regionId>

Parameters:

Example:

aliyun otsutil list_instance -r cn-hangzhou

Response:

[
  "myinstance",
  "another-instance",
  "test-instance"
]

Notes:

• Returns an empty array [] if no instances exist in the region
• Only lists instances owned by the authenticated account

---

Data Table Read Commands

use

Select a data table for subsequent operations.

Syntax:

aliyun otsutil use --wc -t <tableName>

Parameters:

Example:

aliyun otsutil use -t mytable

---

list

List table names under the current instance.

Syntax:

aliyun otsutil list [options]

Parameters:

Examples:

# List tables of the current type
aliyun otsutil list

# List all tables
aliyun otsutil list -a

# List only data tables
aliyun otsutil list -w

# List only timeseries tables
aliyun otsutil list -t

---

desc

View detailed table information including primary keys, TTL, max versions, and throughput.

Syntax:

aliyun otsutil desc [-t <tableName>] [-f <format>] [-o <outputPath>]

Parameters:

Examples:

# Describe the currently selected table
aliyun otsutil desc

# Describe a specific table
aliyun otsutil desc -t mytable

# Output in table format
aliyun otsutil desc -t mytable -f table

# Save table info to file
aliyun otsutil desc -t mytable -o /tmp/table_meta.json

Response:

{
  "Name": "mytable",
  "Meta": {
    "Pk": [
      { "C": "uid", "T": "string", "Opt": "none" },
      { "C": "pid", "T": "integer", "Opt": "none" }
    ]
  },
  "Option": {
    "TTL": -1,
    "Version": 1
  },
  "CU": {
    "Read": 0,
    "Write": 0
  }
}

Response Fields:

---

Other Useful Commands

help

Display help information for commands.

Syntax:

aliyun otsutil help
aliyun otsutil help <command>

Example:

aliyun otsutil help desc

quit / exit

Not applicable for aliyun otsutil - commands are executed directly without entering an interactive session.

---

API Mapping

Error Codes

Region Reference

Tablestore Read-Only Operations - Verification Methods

This document provides verification steps for each Tablestore CLI read-only operation via aliyun otsutil.

Pre-requisite: Version Check

CRITICAL: Before running any otsutil commands, verify you have Aliyun CLI version 3.3.0 or later.

# Check version (MUST be 3.3.0+)
aliyun version

# Expected output: 3.3.0 or higher (e.g., 3.3.3)
# If version is lower (e.g., 3.0.x), otsutil will NOT work!

# Verify otsutil is available
aliyun otsutil help

# If you see "ERROR: 'otsutil' is not a valid command", 
# download the latest version from CDN (see cli-installation-guide.md)

Task 1: Configure Instance Verification

After running aliyun otsutil config, verify the configuration was applied correctly.

Verification Steps

1. Check config response:

The aliyun otsutil config command returns current configuration:

{
  "Endpoint": "https://myinstance.cn-hangzhou.ots.aliyuncs.com",
  "AccessKeyId": "LTAI5t***",
  "AccessKeySecret": "7NR2***",
  "AccessKeySecretToken": "",
  "Instance": "myinstance"
}

2. Success Criteria:

• Endpoint matches the configured endpoint URL
• Instance matches the configured instance name
• AccessKeyId shows the configured key (masked)

3. Test connection by listing tables:

aliyun otsutil list

• If configuration is correct and instance exists, returns list of tables (or empty list)
• If configuration is wrong, returns authentication or connection error

Common Issues

---

Task 2: Describe Instance Verification

After running aliyun otsutil describe_instance, verify the response contains expected information.

Verification Steps

1. Check response completeness:

aliyun otsutil describe_instance -r cn-hangzhou -n myinstance

2. Expected Response Fields:

3. Success Criteria:

• Response is valid JSON
• All required fields are present
• Status is 1 (Running)

Status Code Reference

---

Task 3: List Instances Verification

After running aliyun otsutil list_instance, verify the response is correct.

Verification Steps

1. Run list command:

aliyun otsutil list_instance -r cn-hangzhou

2. Expected Response:

[
  "instance1",
  "instance2"
]

Or empty array if no instances:

[]

3. Success Criteria:

• Response is a valid JSON array
• Known instances appear in the list
• No duplicate entries

4. Cross-verify with describe:

For each instance in the list, you can verify with:

aliyun otsutil describe_instance -r <regionId> -n <instanceName>

Common Issues

---

Task 4: List Tables Verification

After running aliyun otsutil list, verify the response is correct.

Verification Steps

1. Ensure instance is configured:

aliyun otsutil config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance

2. Run list command:

# List all data tables
aliyun otsutil list -w

# List all tables (data + timeseries)
aliyun otsutil list -a

3. Success Criteria:

• Command returns without error
• Known table names appear in the output
• Empty output is valid if no tables exist

Common Issues

---

Task 5: Describe Table Verification

After running aliyun otsutil desc, verify the response contains expected table schema.

Verification Steps

1. Describe a specific table:

aliyun otsutil desc -t mytable

2. Expected Response Structure:

{
  "Name": "mytable",
  "Meta": {
    "Pk": [
      { "C": "uid", "T": "string", "Opt": "none" },
      { "C": "pid", "T": "integer", "Opt": "none" }
    ]
  },
  "Option": {
    "TTL": -1,
    "Version": 1
  },
  "CU": {
    "Read": 0,
    "Write": 0
  }
}

3. Success Criteria:

• Response is valid JSON
• Name matches the requested table
• Meta.Pk contains primary key definitions
• Option.TTL and Option.Version are present

4. Export to file for comparison:

aliyun otsutil desc -t mytable -o /tmp/table_meta.json

Common Issues

---

End-to-End Verification Workflow

Complete verification workflow for read-only operations:

# Step 0: Verify Aliyun CLI version (MUST be 3.3.0+)
aliyun version
# If version < 3.3.0, download latest from CDN first!

# Step 1: Verify otsutil is available
aliyun otsutil help

# Step 2: Verify Aliyun CLI credentials are configured
aliyun sts GetCallerIdentity

# Step 3: List instances in a region
aliyun otsutil list_instance -r cn-hangzhou
# Expected: ["myinstance", ...]

# Step 4: Get instance details
aliyun otsutil describe_instance -r cn-hangzhou -n myinstance
# Expected: Status = 1

# Step 5: Configure instance endpoint
aliyun otsutil config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance

# Step 6: List data tables
aliyun otsutil list -w
# Expected: list of table names

# Step 7: Describe a table
aliyun otsutil desc -t mytable
# Expected: table schema with primary keys, TTL, versions

# Step 8: Export table info to file (optional)
aliyun otsutil desc -t mytable -o /tmp/table_meta.json

Automated Verification Script

For automated verification, you can use the following pattern:

#!/bin/bash
# Verification script example

INSTANCE_NAME="test-instance"
REGION="cn-hangzhou"

# Check if instance exists
aliyun otsutil list_instance -r $REGION | grep -q "$INSTANCE_NAME"

if [ $? -eq 0 ]; then
    echo "✅ Instance $INSTANCE_NAME exists in $REGION"
else
    echo "❌ Instance $INSTANCE_NAME not found in $REGION"
    exit 1
fi

Troubleshooting Verification Failures

Authentication Issues

# Verify credentials
aliyun sts GetCallerIdentity

# Re-configure if needed
aliyun configure

Network Issues

1. Check if endpoint is reachable:

• For public endpoint: ensure internet access
• For VPC endpoint: ensure VPC configuration is correct

2. Verify endpoint format matches network type:

• Public: https://<instance>.<region>.ots.aliyuncs.com
• VPC: https://<instance>.<region>.vpc.tablestore.aliyuncs.com

Permission Issues

If verification commands fail with permission errors:

1. Check RAM user has AliyunOTSReadOnlyAccess policy 2. Or verify specific permissions exist:

• ots:GetInstance for describe_instance
• ots:ListInstance for list_instance
• ots:ListTable for list
• ots:DescribeTable for desc