# rds-connectivity

Part of **RDS**

# ApsaraDB RDS Database Connectivity Troubleshooting Guide

## Problem Index

| Problem | Symptom | Severity | Solution Summary |
|--------|--------|---------|------------------|
| IP Not in Whitelist When Connecting from ECS | `ERROR 1045 (HY000): #28000ip not in whitelist` or `ERROR 2801 (HY000): #RDS00ip not in whitelist, client ip is XXX` | High | Add the ECS instance's actual egress IP to the RDS IP whitelist |
| Using Public IP Instead of Private IP for Internal Connection | Connection succeeds but uses public bandwidth; higher latency and cost | Medium | Use the private (internal) endpoint of the RDS instance when connecting from ECS in the same region and VPC |
| Misconfigured Network Type (Classic vs VPC) | Connection fails even with correct IP in whitelist | High | Ensure both ECS and RDS are in the same network type (preferably VPC) and properly linked |

## Problem Details

### Problem 1: IP Address Not in RDS Whitelist When Connecting from ECS

**Symptoms**
- Error message: `ERROR 1045 (HY000): #28000ip not in whitelist`
- Error message: `ERROR 2801 (HY000): #RDS00ip not in whitelist, client ip is XXX`
- Behavior: Connection attempt from an ECS instance to an RDS instance over the internal network fails immediately
- Context: Occurs when the ECS instance’s outbound IP is not included in the RDS instance’s IP whitelist

**Root Cause**
The ApsaraDB RDS service enforces IP-based access control via a whitelist. When an ECS instance connects to RDS over the internal network, RDS checks the source IP against its whitelist. If the ECS instance uses a NAT gateway, proxy, or resides in a different network environment, the observed client IP may differ from the expected private IP. Additionally, users may mistakenly add the public IP of the ECS instance instead of the actual egress IP used for internal traffic.

**Solution**
1. Identify the actual IP address used by the ECS instance when connecting to RDS:
   - Log into the ECS instance and run the following command to check the source IP seen by RDS:
     ```bash
     telnet <rds-private-endpoint> 3306
     ```
     (Use `nc` or `mysql` client if `telnet` is unavailable)
   - Alternatively, check the exact IP reported in the error message (`client ip is XXX`)

2. Add the correct IP address to the RDS instance’s IP whitelist:
   - In the ApsaraDB RDS console, navigate to your RDS instance
   - Go to **Security Controls** > **Whitelist Settings**
   - Edit the appropriate whitelist group (e.g., `default` or a custom group)
   - Add the ECS instance’s private IP address (or CIDR block like `192.168.0.0/24` if multiple ECS instances share a subnet)
   - Click **OK** to save

3. If the ECS and RDS are in the same VPC, ensure you are using the **private endpoint** of the RDS instance (not the public endpoint)

**Verification**
- From the ECS instance, attempt to connect to the RDS instance using the MySQL client:
  ```bash
  mysql -h <rds-private-endpoint> -u <username> -p
  ```
- Expected behavior: Connection succeeds without IP whitelist errors
- Confirm in RDS logs (if enabled) that the connection is accepted from the whitelisted IP

---

### Problem 2: Using Public Endpoint Instead of Private Endpoint for Internal Connections

**Symptoms**
- Connection to RDS succeeds but incurs public network charges
- Higher latency compared to expected internal network performance
- No explicit error, but inefficient resource usage

**Root Cause**
Users may inadvertently use the public endpoint of the RDS instance when connecting from an ECS instance in the same region. Even if both resources are in the same VPC, using the public endpoint forces traffic through the internet, bypassing the faster and free internal network.

**Solution**
1. Obtain the private (internal) endpoint of the RDS instance:
   - In the ApsaraDB RDS console, go to the instance’s **Basic Information** page
   - Locate the **Internal Endpoint** field (typically ends with `.privatelink.aliyuncs.com` or similar)

2. Update your application or connection string to use the private endpoint:
   ```python
   # Example in Python (MySQLdb)
   conn = MySQLdb.connect(
       host='rm-xxxxxx.mysql.rds.aliyuncs.com',  # ← must be internal endpoint
       user='myuser',
       passwd='mypass',
       db='mydb'
   )
   ```

3. Ensure the ECS instance and RDS instance are in the same region and VPC (for VPC-type instances)

**Verification**
- Run a network trace from ECS to confirm traffic stays internal:
  ```bash
  traceroute <rds-private-endpoint>
  ```
- Expected: Hops remain within private IP ranges (e.g., 10.x.x.x, 172.16–31.x.x, 192.168.x.x)
- Monitor network metrics in CloudMonitor to confirm no public outbound traffic is generated

---

### Problem 3: Network Type Mismatch Between ECS and RDS

**Symptoms**
- Connection fails even after adding the correct IP to the whitelist
- Error may include timeout or “host unreachable” in addition to whitelist errors
- Applies primarily to older deployments using Classic network

**Root Cause**
ApsaraDB RDS supports two network types: **Classic Network** and **VPC**. ECS instances in VPC cannot directly communicate with RDS instances in Classic Network over the internal network unless properly bridged. Similarly, Classic Network ECS instances cannot access VPC RDS instances without additional configuration.

**Solution**
1. Check the network type of both ECS and RDS instances:
   - In ECS console: Instance details → **Network Attributes** → **Network Type**
   - In RDS console: Instance details → **Basic Information** → **Network Type**

2. If both are in **VPC**:
   - Ensure they are in the **same VPC and zone**
   - Confirm security group rules allow outbound (ECS) and inbound (RDS) traffic on port 3306

3. If one is in **Classic** and the other in **VPC**:
   - Migrate the Classic instance to VPC (recommended), or
   - Use public endpoints with proper whitelisting (not recommended for production due to cost and latency)

4. For mixed environments requiring internal access, consider using **ClassicLink** (if supported and enabled)

**Verification**
- After aligning network types, test connectivity using the private endpoint
- Use `telnet` or `nc` to verify port 3306 is reachable:
  ```bash
  nc -zv <rds-private-endpoint> 3306
  ```
- Expected output: `Connection to ... 3306 port [tcp/mysql] succeeded!`

## FAQ

**Q: How do I find the correct IP address to add to the RDS whitelist when connecting from ECS?**  
A: Use the private IP address of the ECS instance if both ECS and RDS are in the same VPC. If the ECS uses a NAT or proxy, check the actual source IP reported in the RDS error message (`client ip is XXX`) or capture outbound traffic from the ECS instance.

**Q: Can I use 0.0.0.0/0 in the RDS whitelist for testing?**  
A: Yes, adding `0.0.0.0/0` allows all IPv4 addresses to connect, but this poses a severe security risk. Only use it temporarily for diagnostics, and remove it immediately after testing. Never use it in production.

**Q: Why does my ECS instance show a different IP when connecting to RDS than its assigned private IP?**  
A: This can occur if the ECS instance routes traffic through a proxy, NAT gateway, or if it’s part of a Kubernetes cluster with SNAT rules. The RDS service sees the egress IP after NAT translation, not the pod or instance IP. Always use the IP reported in the error message.

**Q: Do I need to restart the RDS instance after updating the IP whitelist?**  
A: No. Changes to the IP whitelist take effect immediately without requiring a restart or downtime.

**Q: How can I verify that my connection is using the internal network?**  
A: Connect using the RDS internal endpoint and run `traceroute` or `mtr` from the ECS instance. Internal connections will not traverse public internet hops and will show low latency (<1 ms). Additionally, CloudMonitor should show zero public network outbound traffic for the ECS instance during the connection.