Compute Engine에서 연결

이 페이지에서는 Compute Engine 인스턴스에 설치된 sqlcmd 클라이언트를 사용하여 Cloud SQL에 연결하는 방법을 설명합니다.

비공개 IP, 공개 IP, Cloud SQL 인증 프록시 또는 Cloud SQL 인증 프록시 Docker 이미지를 사용할 수 있습니다.

Cloud SQL에 연결된 Compute Engine 샘플 웹 애플리케이션을 실행하는 방법에 대한 단계별 안내는 빠른 시작: Compute Engine에서 연결을 참조하세요.

시작하기 전에

이 태스크에는 Compute Engine 인스턴스를 설정하는 방법에 대한 안내가 포함되어 있지 않습니다. Compute Engine 인스턴스 만들기 및 구성에 도움이 필요한 경우 Compute Engine 문서를 참조하세요.

Compute Engine VM에 Cloud SQL Admin API를 사용하여 연결할 scope가 적합한지 확인합니다.

다음 액세스 범위 중 하나를 갖도록 서비스 계정을 구성합니다.

https://www.googleapis.com/auth/sqlservice.admin
https://www.googleapis.com/auth/cloud-platform

비공개 IP

비공개 IP를 사용하여 Compute Engine 인스턴스에서 Cloud SQL에 연결하려면 비공개 서비스 액세스가 사용 환경에 맞게 설정되어 있고 Cloud SQL 인스턴스가 비공개 IP를 사용할 수 있도록 구성되어 있어야 합니다. Compute Engine 인스턴스는 Cloud SQL 인스턴스와 같은 리전과 비공개로 연결할 수 있도록 구성된 네트워크에 있어야 합니다. 자세히 알아보기

1. 비공개 IP를 사용하도록 인스턴스 구성

비공개 IP 연결 구성의 안내를 따릅니다.

2. Compute Engine 인스턴스와의 Cloud Shell 터미널 연결을 엽니다.

인스턴스의 운영체제에 따라 적절한 안내를 사용합니다.

Linux의 경우 Linux VM에 연결을 참조하세요.
Windows의 경우 Windows VM에 연결을 참조하세요.

Compute Engine 인스턴스가 RHEL 또는 CentOS 공개 이미지를 실행할 경우 SELinux가 프록시 연결을 차단할 수 있습니다. 이 경우에는 SELinux 기능이 연결을 허용하도록 구성해야 합니다.

RHEL과 관련한 SELinux에 대한 자세한 내용은 RHEL 문서를 참조하세요. CentOS용 SELinux에 대한 자세한 내용은 CentOS 문서를 참조하세요.

3. 아직 설치되어 있지 않다면 Compute Engine 인스턴스에 sqlcmd 클라이언트를 설치합니다.

기타 플랫폼

SQL Server 설치에 대한 방문 페이지와 SQL Server 다운로드 페이지를 참조하세요.

4. sqlcmd 클라이언트와 연결합니다.

sqlcmd -S CLOUD_SQL_PRIVATE_IP_ADDRESS -U USERNAME

Cloud SQL 인스턴스 페이지에서 또는 다음 gcloud 명령어를 실행하여 비공개 IP 주소를 찾을 수 있습니다.

gcloud sql instances list

공개 IP

공개 IP를 사용하여 연결하려면 다음 안내를 따르세요.

1. 아직 Compute Engine 인스턴스에 고정 IPv4 IP 주소가 없으면 지금 추가합니다.

IPv6을 사용하여 Compute Engine에 연결할 수는 없습니다. 고정 IP 주소를 추가하는 방법에 대한 자세한 내용은 Compute Engine 문서의 새 고정 외부 IP 주소 예약을 참조하세요.

2. Compute Engine 인스턴스의 고정 IP 주소를 Cloud SQL 인스턴스에 연결할 수 있는 네트워크로 승인합니다.

자세한 내용은 공개 IP 연결을 통한 액세스 구성을 참조하세요.

3. Compute Engine 인스턴스와의 Cloud Shell 터미널 연결을 엽니다.

인스턴스의 운영체제에 따라 적절한 안내를 사용합니다.

Linux의 경우 Linux VM에 연결을 참조하세요.
Windows의 경우 Windows VM에 연결을 참조하세요.

RHEL과 관련한 SELinux에 대한 자세한 내용은 RHEL 문서를 참조하세요. CentOS용 SELinux에 대한 자세한 내용은 CentOS 문서를 참조하세요.

4. 아직 설치되어 있지 않다면 Compute Engine 인스턴스에 sqlcmd 클라이언트를 설치합니다.

Debian/Ubuntu

Debian/Ubuntu의 경우 해당 SQL Server 명령줄 도구를 설치합니다.

CentOS/RHEL

CentOS/RHEL의 경우 해당 SQL Server 명령줄 도구를 설치합니다.

openSUSE

openSUSE의 경우 해당 SQL Server 명령줄 도구를 설치합니다.

기타 플랫폼

SQL Server 설치에 대한 방문 페이지와 SQL Server 다운로드 페이지를 참조하세요.

5. sqlcmd 클라이언트와 연결합니다.

sqlcmd -S CLOUD_SQL_PUBLIC_IP_ADDR -U USERNAME

공개 IP 주소는 Cloud SQL 인스턴스 페이지에서 또는 다음 gcloud 명령어를 실행하여 찾을 수 있습니다.

gcloud sql instances list

SSL을 사용하여 연결하는 방법의 예시는 SSL로 연결하기를 참조하세요.

6. sqlcmd 프롬프트가 표시됩니다.

Cloud SQL 인증 프록시

Compute Engine에서 Cloud SQL 인증 프록시를 사용하여 연결하려면 다음 안내를 따르세요.

1. Cloud SQL Admin API를 사용 설정합니다.

Enable the API

2. 서비스 계정 만들기.

Compute Engine에서 연결하는 경우 VM에 Cloud SQL Admin API를 사용하여 연결할 수 있는 적절한 scope가 있는지 확인합니다.

다음 액세스 범위 중 하나를 갖도록 서비스 계정을 구성합니다.

https://www.googleapis.com/auth/sqlservice.admin
https://www.googleapis.com/auth/cloud-platform

Google Cloud 콘솔에서 서비스 계정 페이지로 이동합니다.
서비스 계정으로 이동
Cloud SQL 인스턴스가 포함된 프로젝트를 선택합니다.
서비스 계정 만들기를 클릭합니다.
서비스 계정 이름 필드에 서비스 계정의 설명이 포함된 이름을 입력합니다.
서비스 계정 ID를 고유하고 인식할 수 있는 값으로 변경한 후 만들고 계속하기를 클릭합니다.
역할 선택 필드를 클릭하고 다음 역할 중 하나를 선택합니다.
- Cloud SQL > Cloud SQL 클라이언트
- Cloud SQL > Cloud SQL 편집자
- Cloud SQL > Cloud SQL 관리자
완료를 클릭하여 서비스 계정 만들기를 마칩니다.
새 서비스 계정의 작업 메뉴를 클릭한 후 키 관리를 선택합니다.
키 추가 드롭다운 메뉴를 클릭한 후 새 키 만들기를 클릭합니다.
키 유형이 JSON인지 확인한 후 만들기를 클릭합니다.
비공개 키 파일이 머신에 다운로드됩니다. 파일을 다른 위치로 이동할 수 있습니다. 키 파일을 안전하게 보관하세요.

Compute Engine 인스턴스가 Cloud SQL 인스턴스와 다른 프로젝트에 있는 경우, Cloud SQL 인스턴스가 포함된 프로젝트에서 서비스 계정에 적절한 권한이 있는지 확인합니다.

Google Cloud 콘솔에서 Compute Engine 인스턴스 목록으로 이동합니다.
Compute Engine 인스턴스 목록으로 이동
필요한 경우 Compute Engine 인스턴스와 연결된 프로젝트를 선택합니다.
Compute Engine 인스턴스를 선택하여 속성을 표시합니다.
Compute Engine 인스턴스 속성에서 서비스 계정의 이름을 복사합니다.
Google Cloud 콘솔에서 IAM 및 관리자 프로젝트 페이지로 이동합니다.
IAM 및 관리자 프로젝트 페이지로 이동
Cloud SQL 인스턴스가 포함된 프로젝트를 선택합니다.
서비스 계정 이름을 검색합니다.
이미 서비스 계정이 있고 이 계정의 역할에 cloudsql.instances.connect 권한이 포함되어 있으면 4단계를 진행합니다.

Cloud SQL Client, Cloud SQL Editor, Cloud SQL Admin 역할은 모두 기존 Editor 및 Owner 프로젝트 역할과 마찬가지로 필요한 권한을 제공합니다.
그렇지 않은 경우 추가를 클릭하여 서비스 계정을 추가합니다.
주 구성원 추가 대화상자에서 서비스 계정 이름을 지정하고 cloudsql.instances.connect 권한이 있는 역할을 선택합니다. 뷰어를 제외하고 사전 정의된 모든 Cloud SQL 역할을 선택할 수 있습니다.

또는 프로젝트 > 편집자를 선택하여 기본 편집자 역할을 사용할 수 있지만 편집자 역할에는 Google Cloud 전반에 대한 권한이 포함됩니다.

이러한 역할이 표시되지 않으면 Google Cloud 사용자에게 resourcemanager.projects.setIamPolicy 권한이 없는 것일 수 있습니다. Google Cloud 콘솔의 IAM 페이지로 이동하고 사용자 ID를 검색하여 권한을 확인할 수 있습니다.
추가를 클릭합니다.
이제 지정한 역할을 포함한 서비스 계정이 나열된 것을 볼 수 있습니다.

3. Compute Engine 인스턴스와의 터미널 연결을 엽니다.

인스턴스의 운영체제에 따라 적절한 안내를 사용합니다.

Linux의 경우, Linux 인스턴스에 연결을 참조하세요.
Windows의 경우, Windows 인스턴스에 연결을 참조하세요.

RHEL과 관련한 SELinux에 대한 자세한 내용은 RHEL 문서를 참조하세요. CentOS용 SELinux에 대한 자세한 내용은 CentOS 문서를 참조하세요.

4. 아직 설치되어 있지 않다면 Compute Engine 인스턴스에 sqlcmd 클라이언트를 설치합니다.

Debian/Ubuntu

Debian/Ubuntu의 경우 해당 SQL Server 명령줄 도구를 설치합니다.

CentOS/RHEL

CentOS/RHEL의 경우 해당 SQL Server 명령줄 도구를 설치합니다.

openSUSE

openSUSE의 경우 해당 SQL Server 명령줄 도구를 설치합니다.

기타 플랫폼

SQL Server 설치에 대한 방문 페이지와 SQL Server 다운로드 페이지를 참조하세요.

5. Compute Engine 인스턴스에 Cloud SQL 인증 프록시를 설치합니다.

Linux 64비트

Cloud SQL 인증 프록시를 다운로드합니다.

curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.12.0/cloud-sql-proxy.linux.amd64

Cloud SQL 인증 프록시 실행 파일을 만듭니다.
```
chmod +x cloud-sql-proxy
```

Linux 32비트

Cloud SQL 인증 프록시를 다운로드합니다.

curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.12.0/cloud-sql-proxy.linux.386

curl 명령어를 찾을 수 없으면 sudo apt install curl을 실행하고 다운로드 명령어를 반복합니다.
Cloud SQL 인증 프록시 실행 파일을 만듭니다.
```
chmod +x cloud-sql-proxy
```

Windows 64비트

https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.12.0/cloud-sql-proxy.x64.exe를 마우스 오른쪽 버튼으로 클릭하고 다른 이름으로 링크 저장을 선택하여 Cloud SQL 인증 프록시를 다운로드합니다. 파일 이름을 cloud-sql-proxy.exe로 바꿉니다.

Windows 32비트

https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.12.0/cloud-sql-proxy.x86.exe를 마우스 오른쪽 버튼으로 클릭하고 다른 이름으로 링크 저장을 선택하여 Cloud SQL 인증 프록시를 다운로드합니다. 파일 이름을 cloud-sql-proxy.exe로 바꿉니다.

Cloud SQL 인증 프록시 Docker 이미지

Cloud SQL 인증 프록시에는 distroless, alpine, buster와 같은 서로 다른 컨테이너 이미지가 있습니다. 기본 Cloud SQL 인증 프록시 컨테이너 이미지는 셸이 없는 distroless를 사용합니다. 셸 또는 관련 도구가 필요하면 alpine 또는 buster를 기반으로 이미지를 다운로드합니다. 자세한 내용은 Cloud SQL 인증 프록시 컨테이너 이미지를 참조하세요.

다음 명령어로 Docker를 사용하여 최신 이미지를 로컬 머신으로 가져올 수 있습니다.

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.12.0

참고: Cloud SQL 인증 프록시는 gcr.io 도메인을 지원하지만 Artifact Registry에서 이미지를 제공하는 저장소를 사용합니다. 자세한 내용은 Container Registry에서 전환을 참조하세요.

기타 OS

여기에 포함되지 않은 다른 운영체제의 경우 소스에서 Cloud SQL 인증 프록시를 컴파일하면 됩니다.

6. Cloud SQL 인증 프록시를 시작합니다.

TCP 소켓 또는 Cloud SQL 인증 프록시 Docker 이미지를 사용하여 Cloud SQL 인증 프록시를 시작할 수 있습니다. Cloud SQL 인증 프록시 바이너리는 명령줄에 지정된 Cloud SQL 인스턴스 하나 이상에 연결하고 로컬 연결을 TCP 소켓으로 엽니다. 애플리케이션 코드나 데이터베이스 관리 클라이언트 도구와 같은 다른 애플리케이션과 서비스는 TCP 소켓 연결을 통해 Cloud SQL 인스턴스에 연결할 수 있습니다.

TCP 소켓

TCP 연결의 경우 Cloud SQL 인증 프록시는 기본적으로 localhost(127.0.0.1)에서 리슨합니다. 따라서 인스턴스에 --port PORT_NUMBER를 지정하면 로컬 연결은 127.0.0.1:PORT_NUMBER에서 이루어집니다.

또는 로컬 연결에 다른 주소를 지정할 수 있습니다. 예를 들어 Cloud SQL 인증 프록시가 0.0.0.0:1234에서 로컬 연결을 리슨하도록 하는 방법은 다음과 같습니다.

./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME

INSTANCE_CONNECTION_NAME을 복사합니다. Google Cloud 콘솔의 인스턴스에 대한 개요 페이지에서 확인하거나 다음 명령어를 실행하여 확인할 수 있습니다.
```
    gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
```
예를 들면 myproject:myregion:myinstance입니다.
인스턴스에 공개 및 비공개 IP가 모두 구성되어 있고 Cloud SQL 인증 프록시에서 비공개 IP 주소를 사용하게 하려면 Cloud SQL 인증 프록시를 시작할 때 다음 옵션을 제공해야 합니다.
```
--private-ip
```
서비스 계정을 사용하여 Cloud SQL 인증 프록시를 인증하는 경우 서비스 계정을 만들 때 생성된 비공개 키 파일의 클라이언트 머신 내 위치를 기록해 둡니다.
Cloud SQL 인증 프록시를 시작합니다.
가능한 Cloud SQL 인증 프록시 호출 문자열은 다음과 같습니다.
- Cloud SDK 인증 사용:
```
./cloud-sql-proxy --port 1433 INSTANCE_CONNECTION_NAME
```
  지정된 포트는 로컬 데이터베이스 서버 등에서 이미 사용하지 않는 포트여야 합니다.
- 서비스 계정 사용 및 명시적으로 인스턴스 연결 이름 포함(프로덕션 환경에 권장):
```
./cloud-sql-proxy \
--credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
```
Cloud SQL 인증 프록시 옵션에 대한 자세한 내용은 Cloud SQL 인증 프록시 인증 옵션을 참조하세요.

Docker

Docker 컨테이너에서 Cloud SQL 인증 프록시를 실행하려면 Google Container Registry에서 제공하는 Cloud SQL 인증 프록시 Docker 이미지를 사용합니다.

다음 명령어로 TCP 소켓이나 Unix 소켓을 사용하여 Cloud SQL 인증 프록시를 시작할 수 있습니다. 이 옵션은 INSTANCE_CONNECTION_NAME을 연결 문자열로 사용하여 Cloud SQL 인스턴스를 식별합니다. Google Cloud 콘솔의 인스턴스 개요 페이지에서 또는 다음 명령어를 실행하여 INSTANCE_CONNECTION_NAME을 확인할 수 있습니다.

gcloud sql instances describe INSTANCE_NAME

예를 들면 myproject:myregion:myinstance입니다.

언어와 환경에 따라 TCP 소켓이나 Unix 소켓을 사용하여 Cloud SQL 인증 프록시를 시작할 수 있습니다. 자바 프로그래밍 언어로 작성된 애플리케이션이나 Windows 환경에서는 Unix 소켓이 지원되지 않습니다.

TCP 소켓 사용

docker run -d \\
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\
  -p 127.0.0.1:1433:1433 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.12.0 \\
  --address 0.0.0.0 --port 1433 \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Compute Engine 인스턴스에서 제공되는 사용자 인증 정보를 사용하는 경우에는 --credentials-file 매개변수와 -v PATH_TO_KEY_FILE:/path/to/service-account-key.json 행을 포함하지 마세요.

Cloud SQL 인증 프록시가 로컬 호스트 외부에 노출되지 않도록 항상 -p에 127.0.0.1 프리픽스를 지정합니다. 인스턴스 매개변수의 '0.0.0.0'은 Docker 컨테이너 외부에서 포트에 액세스할 수 있도록 하는 데 필요합니다.

Unix 소켓 사용

docker run -d -v /cloudsql:/cloudsql \\
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.12.0 --unix-socket=/cloudsql \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

컨테이너 최적화 이미지를 사용하는 경우 /cloudsql 대신 쓰기 가능한 디렉터리를 사용합니다. 예를 들면 다음과 같습니다.

-v /mnt/stateful_partition/cloudsql:/cloudsql

여러 개의 인스턴스를 쉼표로 구분하여 지정할 수 있습니다. 또한 Compute Engine 메타데이터를 사용하여 연결할 인스턴스를 동적으로 결정할 수 있습니다. Cloud SQL 인증 프록시 매개변수에 대해 자세히 알아보세요.

7. sqlcmd 세션을 시작합니다.

사용하는 연결 문자열은 TCP 소켓 또는 Docker 중에 무엇을 사용하여 Cloud SQL 인증 프록시를 시작했는지에 따라 다릅니다.

TCP 소켓

sqlcmd 클라이언트를 시작합니다.
```
sqlcmd -S tcp:127.0.0.1,1433 -U USERNAME -P PASSWORD
```
TCP 소켓을 사용하여 연결하면 127.0.0.1을 통해 Cloud SQL 인증 프록시에 액세스합니다.
메시지가 표시되면 비밀번호를 입력합니다.
sqlcmd 프롬프트가 표시됩니다.

도움이 필요하신가요? 프록시 문제를 해결하는 데 도움이 필요하면 Cloud SQL 인증 프록시 연결 문제 해결 또는 Cloud SQL 지원 페이지를 참조하세요.

다음 단계

Cloud SQL 인증 프록시의 연결 문제 해결 도움말 보기
사용자 및 데이터베이스 만들기
비공개 IP 자세히 알아보기
애플리케이션에서 인스턴스에 연결하는 옵션 알아보기
지원 옵션 알아보기