Alibabacloud Tair Devtoolset

Tair DevToolset — Full-Lifecycle Tair Development Assistant

This Skill provides operational capabilities and development guidelines for Alibaba Cloud Tair (Redis OSS-Compatible) database, covering architecture selection, data structure design, instance creation, connection management, performance monitoring, error troubleshooting, and backup & recovery.

Note: This Skill executes real cloud operations via aliyun CLI. Restore operations are high-risk and will overwrite current data. Ensure the RAM account has the required permissions before use.

Supported Capabilities

Part I — Cross-Cutting Concerns

1. Prerequisites

1.1 CLI Installation & Version

Aliyun CLI >= 3.3.3 required. Run aliyun version to verify. If not installed or version too low, see references/cli-installation-guide.md for installation instructions.

# Enable automatic plugin installation (required for r-kvstore plugin)
aliyun configure set --auto-plugin-install true

# Update existing plugins to latest version
aliyun plugin update

# Verify jq is installed (required for JSON parsing in scripts)
jq --version

1.2 Authentication

All credential configurations follow existing aliyun CLI settings.

Security Rules:

• NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
• NEVER ask the user to input AK/SK directly in the conversation or command line
• NEVER use aliyun configure set with literal credential values
• ONLY use aliyun configure list to check credential status

aliyun configure list

If no valid profile exists, STOP here. Configure credentials outside of this session, then return.

1.3 AI-Mode Configuration

[MUST] Enable AI-Mode at the start of any workflow (before any CLI invocation):

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset"

[MUST] Disable AI-Mode at EVERY exit point — before delivering the final response for ANY reason (success, failure, error, user cancellation, etc.). AI-mode MUST NOT remain enabled after the skill stops running.

aliyun configure ai-mode disable

2. Security & Compliance

2.1 User-Agent Requirement

Every aliyun CLI command invocation must include:

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

2.2 RAM Permissions

This Skill requires R-KVStore RAM permissions for instance management, backup, and recovery operations. See references/ram-policies.md for the full permission table and policy document.

[MUST] Permission Failure Handling: When any command fails due to permission errors:

1. Read references/ram-policies.md to get the full list of required permissions
2. Use ram-permission-diagnose skill to guide the user through requesting permissions
3. Pause and wait until the user confirms that the required permissions have been granted

3. Parameter Confirmation Rule

Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, passwords, resource specifications) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Part II — Capabilities

4. Architecture Selection

Choose the right Tair architecture based on data volume, throughput requirements, and read/write ratio.

When to Use

• Deciding between Standard and Cluster architecture
• Determining whether read/write splitting is needed
• Selecting edition type (Memory-optimized, Persistent memory, Disk-based)
• Evaluating Tair vs Open Source Redis for a new project

Key Guidance

Key Concepts:

Architecture Comparison:

Selection Decision Tree:

Data volume > single-node capacity?
├── Yes → Cluster architecture
│   └── Read-heavy? → Enable read/write splitting
└── No → Standard architecture
    └── Read-heavy? → Enable read/write splitting

References

• references/architecture-selection/arch-selection.md — Architecture selection decision guide
• references/architecture-selection/arch-compare-oss-redis.md — Tair vs Open Source Redis comparison and edition selection

5. Data Structure Design

Choose the appropriate data structure based on your access patterns and business requirements.

When to Use

• Selecting data structures for a new feature or application
• Choosing between Redis native and Tair extended data structures
• Migrating data models and evaluating structure alternatives

Key Guidance

Redis Data Structures:

Tair Data Structures:

References

• references/data-structure-design/data-structure-design.md — Detailed data structure use case descriptions
• Redis Data Types
• Tair Extended Data Structures

6. Instance Creation

Create and configure Tair instances on Alibaba Cloud, including whitelist configuration and public endpoint allocation.

When to Use

• Creating a new Tair instance for testing, development, or production
• Configuring network access (whitelist, public endpoint) for an instance
• Setting up a Tair benchmark or PoC environment

6.1 Choosing Instance Specifications

Required Parameters:

Optional Parameters (with defaults):

Common Specifications (Standard Architecture):

6.2 Automated Workflow (Script)

For quick end-to-end instance creation with public network access, use the all-in-one script:

Execution Constraints:

• MUST use scripts/create-and-connect-test.sh for this workflow — do NOT bypass the script to directly call individual aliyun r-kvstore commands
• DO NOT write or concatenate aliyun CLI commands to replace script functionality
• Model's responsibility: collect parameters → set environment variables → run script

export VPC_ID="<user-confirmed VPC_ID>"
export VSWITCH_ID="<user-confirmed VSWITCH_ID>"

# Optional parameters
export REGION_ID="cn-hangzhou"
export ZONE_ID="cn-hangzhou-h"
export INSTANCE_TYPE="tair_rdb"
export INSTANCE_CLASS="tair.rdb.1g"
# For NAT environment, manually set public IP
# export MY_PUBLIC_IP="your-public-ip"

bash scripts/create-and-connect-test.sh

The script will automatically complete: Create instance → Wait for ready → Configure whitelist → Allocate public endpoint → Get public connection info.

6.3 Manual CLI Steps

For custom requirements (PrePaid subscription, no public endpoint, custom security groups, etc.), use manual CLI steps:

Step 1 — Create instance:

aliyun r-kvstore create-tair-instance \
  --biz-region-id "$REGION_ID" --zone-id "$ZONE_ID" \
  --vpc-id "$VPC_ID" --vswitch-id "$VSWITCH_ID" \
  --instance-type "$INSTANCE_TYPE" --instance-class "$INSTANCE_CLASS" \
  --password "$PASSWORD" --charge-type "$CHARGE_TYPE" \
  --shard-type "MASTER_SLAVE" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

Step 2 — Wait for instance ready (poll until InstanceStatus is Normal):

aliyun r-kvstore describe-instance-attribute \
  --instance-id "$INSTANCE_ID" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

Step 3 — Configure whitelist:

aliyun r-kvstore modify-security-ips \
  --instance-id "$INSTANCE_ID" --security-ips "$MY_PUBLIC_IP" \
  --security-ip-group-name "default" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

Step 4 — Allocate public endpoint:

aliyun r-kvstore allocate-instance-public-connection \
  --instance-id "$INSTANCE_ID" \
  --connection-string-prefix "${INSTANCE_ID}pub" --port "6379" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

6.4 Success Verification

aliyun r-kvstore describe-instance-attribute \
  --instance-id "$INSTANCE_ID" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

Confirm InstanceStatus is Normal and public endpoint is allocated. For the full 3-step verification (instance status, whitelist, public endpoint), see references/verification-method.md.

References

• references/instance-creation/connect-create-instance.md — End-to-end instance creation and connection guide with redis-cli examples
• references/related-commands.md — Complete CLI command and parameter reference
• references/verification-method.md — Detailed success verification steps
• references/acceptance-criteria.md — CLI command correctness standards

7. Connection Management

Connect to Tair instances using various Redis-compatible clients in standalone, proxy, cluster, or TLS modes.

When to Use

• Connecting to a Tair instance from application code
• Choosing the right client library and connection mode
• Configuring TLS/SSL encryption for secure connections
• Troubleshooting connection issues

Key Guidance

Connection Modes:

Authentication Format:

• Default account: password only
• Custom account: <user>:<password>
• redis-cli: use REDISCLI_AUTH environment variable — export REDISCLI_AUTH='InstanceID:Password'

Supported Clients: Jedis, Lettuce, Redisson (Java); redis-py (Python); Predis, phpredis (PHP); StackExchange.Redis (.NET); go-redis (Go); node-redis (Node.js); Spring Data Redis

References

• references/connection-management/connect-standalone-or-proxy.md — Standalone/proxy connection examples in Java, Python, PHP, .NET, Go, Spring Data Redis
• references/connection-management/connect-cluster.md — Cluster connection examples (JedisCluster, RedisCluster, LettuceCluster, go-redis cluster, redis-cli)
• references/connection-management/connect-with-tls.md — TLS/SSL connection examples for all client types (Proxy + Direct)

8. Performance Monitoring

Intelligent performance monitoring and diagnostics via the Tair AI Assistant (DAS API).

When to Use

• Diagnosing slow queries or performance degradation
• Analyzing memory usage and identifying big keys / hotspot keys
• Tuning instance parameters and connection settings
• Monitoring instance health and resource utilization

Key Guidance

For intelligent diagnostics, install and use the alibabacloud-tair-ai-assistant skill:

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-tair-ai-assistant --agent <your-agent-platform>

The AI Assistant provides natural language based diagnostics covering: instance management, performance analysis, slow queries, memory analysis, big key / hotspot key detection, parameter tuning, and connection troubleshooting.

References

• references/performance-monitoring/perf-monitoring.md — Performance monitoring reference
• alibabacloud-tair-ai-assistant

9. Error Troubleshooting

Diagnose and resolve common Tair errors across authentication, connection, cluster, memory, proxy, Lua/transactions, and client-specific issues.

When to Use

• Encountering authentication or connection errors
• Resolving cluster-related errors (cross-slot, moved, read-only)
• Handling memory exhaustion or command errors
• Debugging client-specific issues (Jedis, Lettuce, Redisson, go-redis, etc.)

Key Guidance

Common Error Categories:

References

• references/error-troubleshooting/errors-troubleshooting.md — Complete error tables with causes and solutions for all error categories and client libraries
• Common errors and troubleshooting

10. Backup and Recovery

Configure backup policies, create manual backups, restore data from backups, and perform point-in-time recovery (PITR).

When to Use

• Configuring automatic backup policies
• Creating a manual backup before high-risk operations
• Restoring data from a backup set
• Performing point-in-time recovery (PITR) or key-filtered recovery

Key Guidance

Persistence Policies:

Key CLI Operations:

• modify-backup-policy — Modify automatic backup schedule
• create-backup — Create a manual backup
• describe-backups — Query available backup sets
• restore-instance — Restore from backup set or point-in-time
  • Full backup: --backup-id "$BACKUP_ID"
  • PITR: --restore-type 1 --restore-time "2024-01-15T10:30:00Z"
  • Key-filtered PITR: add --filter-key "session:*,user:*"

⚠️ HIGH-RISK OPERATION — restore-instance overwrites current data and cannot be undone. Before executing any restore:

1. Verify current write traffic — Check if the instance has active writes; notify the user if so
2. Create a latest backup — Run create-backup to preserve current data as a rollback point
3. Confirm with the user — Explicitly inform that data will be overwritten and obtain confirmation

References

• references/backup-and-recovery/backup-recovery.md — Complete backup/recovery guide with CLI examples and data protection details
• Data backup and restoration policies

References Index