연결 문제 디버깅

소개

일반적으로 연결 문제는 다음 세 가지 영역 중 하나에 해당합니다.

연결 - 네트워크를 통해 인스턴스에 연결할 수 있나요?
승인 - 인스턴스에 연결할 권한이 있나요?
인증 - 데이터베이스가 사용자의 데이터베이스 사용자 인증 정보를 받아들이나요?

이러한 각 영역은 조사를 위해 더 다양한 경로로 세분할 수 있습니다. 다음 섹션에는 문제를 더 구체적으로 파악하기 위해 스스로 물어볼 수 있는 질문의 예시가 있습니다.

연결 문제 체크리스트

연결 중

비공개 IP

프로젝트에 Service Networking API를 사용 설정했나요?
공유 VPC를 사용하고 있나요?
사용자 계정 또는 서비스 계정에 비공개 서비스 액세스 연결을 관리하는 데 필요한 IAM 권한이 있나요?
프로젝트에 비공개 서비스 액세스 연결이 구성되어 있나요?
비공개 연결에 IP 주소 범위를 할당했나요?
할당된 IP 주소 범위에 mysql 인스턴스를 만들려는 모든 리전에 대해 /24 공간이 하나 이상 포함되었나요?
mysql 인스턴스에 대해 할당된 IP 주소 범위를 지정하는 경우 이 범위에서 mysql 인스턴스를 만들려는 모든 범위에 대해 /24 공간이 하나 이상 범위에 포함되나요?
비공개 연결이 만들어졌나요?
비공개 연결이 변경된 경우 vpc-peerings가 업데이트되었나요?
VPC 로그에 오류가 표시되나요?
소스 머신의 IP가 RFC 1918 이외의 주소인가요?

공개 IP

소스 IP가 승인된 네트워크로 등록되었나요?
SSL/TLS 인증서가 요구되나요?
사용자 계정 또는 서비스 계정에 Cloud SQL 인스턴스에 연결하는 데 필요한 IAM 권한이 있나요?

승인

Cloud SQL 인증 프록시

Cloud SQL 인증 프록시가 최신 상태인가요?
Cloud SQL 인증 프록시가 실행 중인가요?
인스턴스 연결 이름이 Cloud SQL 인증 프록시 연결 명령어에 올바르게 구성되어 있나요?
Cloud SQL 인증 프록시 출력을 확인하셨나요? 출력을 파일로 보내거나 Cloud SQL 인증 프록시를 시작한 Cloud Shell 터미널을 확인하세요.
사용자 계정 또는 서비스 계정에 Cloud SQL 인스턴스에 연결하는 데 필요한 IAM 권한이 있나요?
프로젝트에 Cloud SQL Admin API를 사용 설정했나요?
아웃바운드 방화벽 정책이 있으면 대상 Cloud SQL 인스턴스에서 포트 3307에 연결할 수 있는지 확인합니다.
UNIX 도메인 소켓을 사용하여 연결하는 경우에는 Cloud SQL 인증 프록시를 시작할 때 -dir로 지정된 디렉터리를 나열하여 소켓이 생성되었는지 확인하세요.

Cloud SQL 커넥터 및 언어별 코드

연결 문자열이 올바르게 작성되었나요?
사용 중인 프로그래밍 언어의 샘플 코드와 코드를 비교해 보았나요?
샘플 코드가 없는 런타임 또는 프레임워크를 사용하고 있나요?

그렇다면 커뮤니티에서 관련 참고 자료를 찾아보았나요?

자체 관리형 SSL/TLS 인증서

클라이언트 인증서가 소스 머신에 설치되어 있나요?
클라이언트 인증서가 연결 인수에 올바르게 입력되었나요?
클라이언트 인증서가 여전히 유효한가요?
SSL을 사용하여 연결할 때 오류가 발생하나요?
서버 인증서가 여전히 유효한가요?

승인된 네트워크

소스 IP 주소가 포함되어 있나요?
RFC 1918 이외의 IP 주소를 사용하고 있나요?
지원되지 않는 IP 주소를 사용하고 있나요?

연결 실패

연결 권한이 있나요?
연결 한도 오류가 표시되나요?
애플리케이션이 올바르게 연결을 종료하나요?

인증하는 중

기본 데이터베이스 인증(사용자 이름/비밀번호)

access denied 오류가 표시되나요?
사용자 이름 및 비밀번호가 정확한가요?

IAM 데이터베이스 인증

인스턴스에 cloudsql.iam_authentication 플래그를 사용 설정했나요?
계정에 정책 binding을 추가했나요?
-enable_iam_login 또는 Oauth 2.0 토큰을 데이터베이스 비밀번호로 사용하여 Cloud SQL 인증 프록시를 사용하고 있나요?
서비스 계정을 사용하는 경우 단축한 이메일 이름을 사용하고 있나요?
PostgreSQL의 IAM 데이터베이스 인증에 대해 자세히 알아보세요.

오류 메시지

특정 API 오류 메시지는 오류 메시지 참조 페이지를 참조하세요.

추가 연결 문제 해결

다른 연결 문제는 문제 해결 페이지의 연결 섹션을 참조하세요.

일반적인 연결 문제

애플리케이션이 연결을 올바르게 종료하는지 확인

'Aborted connection nnnn to db:'가 포함된 오류가 표시되는 경우 이는 일반적으로 애플리케이션이 연결을 올바르게 중지하지 않았음을 의미합니다. 네트워크 문제로 인해 이 오류가 발생할 수도 있습니다. 이 오류는 Cloud SQL 인스턴스에 문제가 있음을 의미하지 않습니다. 또한 문제의 원인을 추적하기 위해 패킷을 검사하려면 tcpdump를 실행하는 것이 좋습니다.

연결 관리 권장사항의 예시는 데이터베이스 연결 관리를 참조하세요.

인증서가 만료되었는지 확인

인스턴스가 SSL을 사용하도록 구성된 경우 Google Cloud 콘솔의 Cloud SQL 인스턴스 페이지로 이동하여 인스턴스를 엽니다. 인스턴스의 연결 페이지를 열고 보안 탭을 선택한 후 서버 인증서가 유효한지 확인합니다. 만료된 경우 새 인증서를 추가하고 새 인증서로 순환시켜야 합니다.

연결 권한이 있는지 확인

연결이 실패하면 연결이 승인되었는지 확인합니다.

예를 들어 온프레미스 환경에서 mysql 클라이언트를 사용해 연결하는 등 IP 주소를 사용하여 연결하는 데 문제가 있는 경우 연결 시 사용하는 IP 주소에 Cloud SQL 인스턴스 연결이 승인되었는지 확인합니다.
비공개 IP 주소를 사용하는 Cloud SQL 인스턴스에 대한 연결은 RFC 1918 주소 범위에서 자동으로 승인됩니다. 이에 따라 모든 비공개 클라이언트가 Cloud SQL 인증 프록시를 통하지 않고 데이터베이스에 액세스할 수 있습니다. RFC 1918 이외의 주소 범위는 승인된 네트워크로 구성해야 합니다.
Cloud SQL은 기본적으로 VPC에서 RFC 1918 이외의 서브넷 경로를 학습하지 않습니다. RFC 1918 이외의 경로를 내보내려면 네트워크 피어링을 Cloud SQL로 업데이트해야 합니다. 예를 들면 다음과 같습니다.
```
gcloud compute networks peerings update cloudsql-mysql-googleapis-com \
--network=NETWORK \
--export-subnet-routes-with-public-ip \
--project=PROJECT_ID
```
현재 IP 주소
gcloud sql connect 명령어를 사용하여 인스턴스에 연결합니다. 이 명령어는 잠시 동안 IP 주소를 승인합니다. gcloud CLI와 mysql 클라이언트가 설치된 환경에서 이 명령어를 실행할 수 있습니다. Cloud Shell에서도 이 명령어를 실행할 수 있습니다. Cloud Shell은 Google Cloud 콘솔에서 제공되며 gcloud CLI와 mysql 클라이언트가 사전 설치되어 있습니다. Cloud Shell에서는 Cloud SQL에 연결하는 데 사용할 수 있는 Compute Engine 인스턴스를 제공합니다.
일시적으로 모든 IP 주소를 인스턴스에 연결합니다. IPv4의 경우 0.0.0.0/0을 승인합니다(IPv6의 경우 ::/0 승인).
참고: 모든 IP 주소를 승인하면 연결을 시도하는 모든 클라이언트에서 데이터베이스를 사용할 수 있습니다. 데이터베이스에 민감한 데이터나 독점 데이터가 있는 경우에는 이 방법으로 연결 문제를 조사하지 마세요.

연결 방법 확인

연결 시 다음과 같은 오류 메시지가 표시되는 경우

ERROR 1045 (28000): Access denied for user 'root'@'1.2.3.4' (using password: NO)

비밀번호를 제공하고 있는지 확인하세요.

연결 시 다음과 같은 오류 메시지가 표시되는 경우

ERROR 1045 (28000): Access denied for user 'root'@'1.2.3.4' (using password: YES)

올바른 비밀번호를 사용하고 있는지와 인스턴스가 요구할 경우 SSL을 통해 연결하고 있는지 확인합니다.

연결 시작 방법 결정

데이터베이스에 연결하고 다음 명령어를 실행하여 현재의 연결에 대한 정보를 확인할 수 있습니다.

SHOW PROCESSLIST;

1.2.3.4와 같은 IP 주소가 표시된 연결은 IP를 사용하여 연결됩니다. cloudsqlproxy~1.2.3.4가 표시된 연결은 Cloud SQL 인증 프록시를 사용하거나 App Engine에서 시작된 것입니다. localhost에서의 연결은 일부 내부 Cloud SQL 프로세스가 사용할 수 있습니다.

연결 한도

Cloud SQL 인스턴스에 대한 QPS 한도는 없습니다. 그러나 연결, 크기, App Engine별 한도가 설정되어 있습니다. 할당량 및 한도를 참조하세요.

데이터베이스 연결은 서버 및 연결 애플리케이션의 리소스를 사용합니다. 항상 연결 관리 권장사항을 참고하여 애플리케이션의 사용 공간을 최소화하고 Cloud SQL 연결 한도를 초과할 가능성을 줄이세요. 자세한 내용은 데이터베이스 연결 관리를 참조하세요.

연결 및 스레드 표시

'too many connections' 오류 메시지가 표시되거나 인스턴스에서 발생하는 상황을 확인하려면 SHOW PROCESSLIST를 사용하여 연결 수와 스레드 수를 표시하면 됩니다.

MySQL 클라이언트에서 다음을 실행합니다.

mysql> SHOW PROCESSLIST;

다음과 비슷한 출력이 표시됩니다.

+----+-----------+--------------+-----------+---------+------+-------+----------------------+
| Id | User      | Host         | db        | Command | Time | State | Info                 |
+----+-----------+--------------+-----------+---------+------+-------+----------------------+
|  3 | user-name | client-IP    | NULL      | Query   |    0 | NULL  | SHOW processlist     |
|  5 | user-name | client-IP    | guestbook | Sleep   |    1 |       | SELECT * from titles |
| 17 | user-name | client-IP    | employees | Query   |    0 | NULL  | SHOW processlist     |
+----+-----------+--------------+-----------+---------+------+-------+----------------------+
3 rows in set (0.09 sec)

PROCESSLIST에서 반환된 열을 해석하는 방법에 대한 자세한 내용은 MySQL 참조를 확인하세요.

스레드 수를 가져오려면 다음을 사용하면 됩니다.

mysql> SHOW STATUS WHERE Variable_name = 'Threads_connected';

다음과 비슷한 출력이 표시됩니다.

+-------------------+-------+
| Variable_name     | Value |
+-------------------+-------+
| Threads_connected | 7     |
+-------------------+-------+
1 row in set (0.08 sec)

연결 시간 초과(Compute Engine에서)

Compute Engine 인스턴스와의 연결은 10분 동안 비활성 상태이면 시간 초과되어 Compute Engine 인스턴스와 Cloud SQL 인스턴스 간의 오랫동안 사용되지 않은 연결에 영향을 줄 수 있습니다. 자세한 내용은 Compute Engine 문서의 네트워킹 및 방화벽을 참조하세요.

오랫동안 사용되지 않은 연결을 유지하려면 TCP 연결 유지를 설정하면 됩니다. 다음 명령어는 TCP 연결 유지 값을 1분으로 설정하고 인스턴스 재부팅 시 구성을 영구 유지합니다.

현재 tcp_keepalive_time 값을 표시합니다.

cat /proc/sys/net/ipv4/tcp_keepalive_time

tcp_keepalive_time을 60초로 설정하고 재부팅할 때도 영구적이게 설정합니다.

echo 'net.ipv4.tcp_keepalive_time = 60' | sudo tee -a /etc/sysctl.conf

변경사항을 적용합니다.

sudo /sbin/sysctl --load=/etc/sysctl.conf

tcp_keepalive_time 값을 표시하여 변경사항이 적용되었는지 확인합니다.

cat /proc/sys/net/ipv4/tcp_keepalive_time

IPv6로 연결

연결 시 다음 오류 메시지 중 하나가 표시되는 경우

Can't connect to MySQL server on '2001:1234::4321' (10051)
Can't connect to MySQL server on '2001:1234::4321' (101)

인스턴스의 IPv6 주소로 연결을 시도하고 있지만 워크스테이션에서 IPv6를 사용하지 못할 가능성이 높습니다. ipv6.google.com으로 이동하여 워크스테이션에서 IPv6가 작동하는지 확인할 수 있습니다. 이 페이지가 로드되지 않으면 IPv6를 사용할 수 없는 것입니다. IPv4 주소 또는 Cloud SQL 인스턴스에 대신 연결합니다. 먼저 IPv4 주소를 인스턴스에 추가해야 할 수도 있습니다.

연결 디버깅 도구

tcpdump

tcpdump는 패킷을 캡처하는 도구입니다. 연결 문제를 디버깅할 때 호스트와 Cloud SQL 인스턴스 사이의 패킷을 캡처하고 검사하려면 tcpdump를 실행하는 것이 좋습니다.

로컬 IP 주소 찾기

호스트의 로컬 주소를 모르는 경우 ip -br address show 명령어를 실행합니다. Linux에서는 네트워크 인터페이스, 인터페이스 상태, 로컬 IP, MAC 주소가 표시됩니다. 예를 들면 eth0 UP 10.128.0.7/32 fe80::4001:aff:fe80:7/64입니다.

또는 ipconfig 또는 ifconfig를 실행하여 네트워크 인터페이스의 상태를 확인할 수 있습니다.

연결 테스트로 테스트

연결 테스트는 네트워크의 엔드포인트 간 연결을 확인할 수 있게 해주는 진단 도구입니다. 구성을 분석하고 경우에 따라 런타임 확인을 수행합니다. 이제 Cloud SQL이 지원됩니다. 이 안내에 따라 Cloud SQL 인스턴스로 테스트를 실행합니다.

연결 테스트

mysql 클라이언트를 사용하여 로컬 환경에서 연결하는 기능을 테스트할 수 있습니다. 자세한 내용은 IP 주소를 사용하여 mysql 클라이언트 연결과 Cloud SQL 인증 프록시를 사용하여 mysql 클라이언트 연결을 참조하세요.

애플리케이션의 IP 주소 확인

애플리케이션을 실행하는 컴퓨터의 IP 주소를 확인하여 그 주소에서 Cloud SQL 인스턴스에 액세스하도록 승인하려면 다음 방법 중 하나를 사용하세요.

컴퓨터가 프록시 또는 방화벽 뒤에 있으면 컴퓨터에 로그인하고 내 IP 확인 사이트에서 IP 주소를 확인합니다.
컴퓨터가 프록시 또는 방화벽을 사용하고 있는 경우 컴퓨터에 로그인해서 whatismyipaddress.com과 같은 도구나 서비스로 실제 IP 주소를 확인합니다.

로컬 포트 열기

호스트가 어떤 포트에서 리슨 중인지 확인하려면 ss -tunlp4 명령어를 실행합니다. 그러면 어느 포트가 개방되어 수신 대기 중인지 확인할 수 있습니다. 예를 들어 MySQL 데이터베이스가 실행 중이면 포트 3306에서 리슨해야 합니다. SSH의 경우 포트 22가 표시됩니다. 예를 들어 PostgreSQL 데이터베이스가 실행 중이면 포트 5432에서 리슨해야 합니다. SSH의 경우 포트 22가 표시됩니다.

모든 로컬 포트 활동

netstat 명령어를 사용하여 모든 로컬 포트 활동을 확인합니다. 예를 들어 netstat -lt은 현재 활성 포트를 모두 표시합니다.

telnet을 사용하여 Cloud SQL 인스턴스에 연결

TCP를 사용하여 Cloud SQL 인스턴스에 연결할 수 있는지 확인하려면 telnet 명령어를 실행합니다. Telnet은 제공된 IP 주소와 포트로 연결을 시도합니다.

예를 들어 Cloud SQL 인스턴스가 MySQL 데이터베이스를 실행하는 경우 포트 3306에서 telnet으로 연결할 수 있습니다(예시: telnet 35.193.198.159 3306). 예를 들어 Cloud SQL 인스턴스가 PostgreSQL 데이터베이스를 실행하는 경우 포트 5432에서 telnet으로 연결할 수 있습니다(예시: telnet 35.193.198.159 5432).

성공하면 다음이 표시됩니다.

Trying 35.193.198.159...

Connected to 35.193.198.159..

실패하면 연결 시도를 강제 종료할 때까지 telnet이 중지됩니다.

Trying 35.193.198.159...

^C..

클라이언트 인증

클라이언트 인증은 pg_hba.conf라는 구성 파일로 제어됩니다(HBA는 호스트 기반 인증(host-based authentication)을 의미함).

소스 데이터베이스에 있는 pg_hba.conf 파일의 복제 연결 섹션이 Cloud SQL VPC의 IP 주소 범위의 연결을 수락하도록 업데이트되었는지 확인하세요.

Cloud Logging

Cloud SQL 및 Cloud SQL은 Cloud Logging을 사용합니다. 자세한 내용은 Cloud Logging 문서를 참조하고 Cloud SQL 샘플 쿼리를 검토하세요.

로그 보기

Cloud SQL 인스턴스와 Cloud VPN 또는 Compute Engine 인스턴스와 같은 다른 Google Cloud 인스턴스의 로그를 볼 수 있습니다. Cloud SQL 인스턴스 로그 항목의 로그를 보려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 Cloud Logging 페이지로 이동합니다.

Cloud Logging으로 이동
페이지 상단에서 기존 Cloud SQL 프로젝트를 선택합니다.
쿼리 빌더에서 다음을 추가합니다.

리소스: Cloud SQL Database를 선택합니다. 대화상자에서 Cloud SQL 인스턴스를 선택합니다.
로그 이름: Cloud SQL 섹션으로 스크롤하고 인스턴스에 적합한 로그 파일을 선택합니다. 예를 들면 다음과 같습니다.
- cloudsql.googlapis.com/mysql-general.log
- cloudsql.googleapis.com/mysql.err
- cloudsql.googleapis.com/postgres.log
심각도: 로그 수준을 선택합니다.
기간: 미리 설정을 선택하거나 커스텀 범위를 만듭니다.

gcloud

gcloud logging 명령어를 사용하여 로그 항목을 볼 수 있습니다. 아래 예시에서 PROJECT_ID를 바꿉니다. limit 플래그는 반환할 최대 항목 수를 나타내는 선택적 매개변수입니다.

gcloud logging read "projects/PROJECT_ID/logs/cloudsql.googleapis.com/mysql-general.log" \
--limit=10

gcloud logging read "projects/PROJECT_ID/logs/cloudsql.googleapis.com/postgres.log" \
--limit=10

비공개 IP 주소

비공개 IP 주소를 사용하는 Cloud SQL 인스턴스에 대한 연결은 RFC 1918 주소 범위에서 자동으로 승인됩니다. RFC 1918 이외의 주소 범위는 Cloud SQL에서 승인된 네트워크로 구성해야 합니다. 또한 RFC 1918 이외의 경로를 내보내려면 네트워크 피어링을 Cloud SQL로 업데이트해야 합니다. 예를 들면 다음과 같습니다.

gcloud compute networks peerings update cloudsql-mysql-googleapis-com 

--network=NETWORK 

--export-subnet-routes-with-public-ip 

--project=PROJECT_ID

VPN 문제 해결

Cloud VPN 문제 해결 페이지를 참조하세요.