Cloud SQL 프록시로 승인

이 페이지에서는 Cloud SQL 프록시 연결을 승인하는 방법을 설명합니다. 프록시를 사용하여 Cloud SQL 인스턴스에 연결하는 방법에 대한 자세한 방법은 연결 개요를 참조하세요. 프록시 작동 방식에 대한 자세한 내용과 프록시를 사용하는 작업에 대한 팁은 Cloud SQL 프록시 정보를 참조하세요.

Cloud SQL 프록시는 Cloud SQL로 인증을 처리하므로, Cloud SQL 인스턴스의 보안 액세스를 위해 허용 IP 주소를 관리하거나 SSL 연결을 구성할 필요가 없습니다.

시작하기 전에

Cloud SQL 프록시 설치

Cloud SQL 프록시는 무료 다운로드로 배포되며, 32비트 및 64비트 Linux, macOS, Windows 플랫폼에서 사용 가능한 사전 컴파일된 실행 파일입니다.

Linux 64비트

  1. 프록시를 다운로드합니다.
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. 프록시를 실행 가능하도록 합니다.
    chmod +x cloud_sql_proxy
    

Linux 32비트

  1. 프록시를 다운로드합니다.
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. 프록시를 실행 가능하도록 합니다.
    chmod +x cloud_sql_proxy
    

macOS 64비트

  1. 프록시를 다운로드합니다.
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. 프록시를 실행 가능하도록 합니다.
    chmod +x cloud_sql_proxy
    

macOS 32비트

  1. 프록시를 다운로드합니다.
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. 프록시를 실행 가능하도록 합니다.
    chmod +x cloud_sql_proxy
    

Windows 64비트

https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe를 마우스 오른쪽 버튼으로 클릭하고 다른 이름으로 링크 저장을 선택하여 프록시를 다운로드합니다. 파일 이름을 cloud_sql_proxy.exe로 바꿉니다.

Windows 32비트

https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe를 마우스 오른쪽 버튼으로 클릭하고 다른 이름으로 링크 저장을 선택하여 프록시를 다운로드합니다. 파일 이름을 cloud_sql_proxy.exe로 바꿉니다.
사용 중인 운영체제가 여기에 포함되어 있지 않으면 소스에서 프록시를 컴파일할 수도 있습니다.

API 사용 설정 및 권한 설정

Cloud SQL 프록시는 사용자 또는 서비스 계정의 IAM 권한을 사용하여 Cloud SQL 인스턴스에 대한 연결을 인증합니다.

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

    API 사용 설정

  2. 사용자 또는 서비스 계정에 필요한 IAM 역할을 하나 이상 추가합니다.

    • Cloud SQL Client(권장)
    • Cloud SQL Editor
    • Cloud SQL Admin

    또는 다음 IAM 권한을 수동으로 할당할 수도 있습니다.

    • cloudsql.instances.connect
    • cloudsql.instances.get

IAM 역할을 서비스 계정에 추가하는 방법에 대한 자세한 방법은 서비스 계정에 역할 부여를 참조하세요.

Cloud SQL이 지원하는 역할에 대한 자세한 내용은 Cloud SQL의 프로젝트 액세스 제어를 참조하세요.

Cloud SQL 프록시의 사용자 인증 정보 사용

Cloud SQL 프록시를 시작하려면 먼저 프록시가 연결을 인증하는 데 사용할 수 있는 사용자 또는 서비스 계정의 사용자 인증 정보를 제공해야 합니다. 사용할 사용자 인증 정보를 지정하는 방법에는 여러 가지 옵션이 있으며, 프록시는 각 옵션을 다음 순서대로 확인합니다.

이러한 모든 옵션은 INSTANCE_CONNECTION_NAME을 연결 문자열로 사용하여 Cloud SQL 인스턴스를 식별합니다. 연결 문자열은 PROJECT_ID:REGION:INSTANCE_ID 형식입니다. 인스턴스 개요 페이지에서 인스턴스 연결 문자열을 확인할 수 있습니다.

이러한 옵션 중 일부는 계정의 RSA 비공개 키가 포함된 JSON 사용자 인증 정보 파일을 사용합니다. 서비스 계정의 JSON 사용자 인증 정보 파일을 만드는 방법은 서비스 계정 만들기를 참조하세요. 새 사용자 인증 정보 파일을 만들어야 하는 경우 Cloud Console에서 프로젝트의 서비스 계정 페이지로 이동하고 서비스 계정의 작업을 클릭하고 키 만들기를 선택하여 서비스 계정의 JSON 사용자 인증 정보 파일을 다운로드합니다.

명령줄의 사용자 인증 정보 파일

이 옵션을 사용하려면 -credential_file 플래그를 JSON 사용자 인증 정보 파일의 경로와 파일 이름으로 설정하여 cloud_sql_proxy 명령어를 호출합니다. 경로는 절대적이거나 현재 작업 디렉터리를 기준으로 할 수 있습니다. 예를 들면 다음과 같습니다.

./cloud_sql_proxy -credential_file=PATH_TO_KEY_FILE -instances=INSTANCE_CONNECTION_NAME

명령줄의 액세스 토큰

액세스 토큰은 일반적으로 사용자 계정을 대신하여 액세스를 승인하는 데 사용됩니다. OAuth 2.0 액세스 토큰을 만들고 사용하는 방법에 대한 자세한 내용은 요청 승인을 참조하세요.

이 옵션을 사용하려면 -token 플래그를 OAuth 2.0 액세스 토큰으로 설정하여 cloud_sql_proxy 주석을 호출합니다. 예를 들면 다음과 같습니다.

./cloud_sql_proxy -token=ACCESS_TOKEN -instances=INSTANCE_CONNECTION_NAME

환경 변수의 사용자 인증 정보 파일

이 옵션은 -credential_file 명령줄 인수를 사용하는 대신 GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 JSON 사용자 인증 정보 파일을 지정한다는 점을 제외하면 -credential_file 플래그를 사용하는 것과 유사합니다.

Cloud SDK 사용자 인증 정보

gcloud 명령줄 도구를 설치하고 개인 계정으로 인증하면 Cloud SQL 프록시는 동일한 계정 사용자 인증 정보를 사용할 수 있습니다. 이 방법은 특히 개발 환경을 준비하고 실행하는 데 유용합니다. 프로덕션 환경의 경우 다른 방법 중 하나를 사용하여 인증합니다.

Cloud SDK를 인증하려면 gcloud auth login 명령어를 사용하여 계정을 선택하고 로그인합니다. gcloud auth list 명령어를 사용하여 현재 Cloud SDK에 대해 인증된 계정을 확인할 수 있습니다.

gcloud auth login에 선택된 계정이 없는 경우 프록시는 gcloud application-default login에 선택된 계정을 확인합니다.

환경의 기본 서비스 계정

프록시가 위에 설명한 위치에서 사용자 인증 정보를 찾을 수 없는 경우 서버 간 프로덕션 애플리케이션 인증 설정에 설명된 로직을 따릅니다. 일부 환경(예: Compute Engine, App Engine 등)은 애플리케이션이 기본적으로 인증하는 데 사용할 수 있는 기본 서비스 계정을 제공합니다. 기본 서비스 계정을 사용하는 경우 API 사용 설정 및 권한 설정에 설명된 권한이 있어야 합니다.

Google Cloud의 인증 방식에 대한 자세한 내용은 인증 개요를 참조하세요.

Cloud SQL 프록시 실행

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

Cloud SQL 프록시 명령줄 사용의 예시는 다음과 같습니다.

TCP 구성

TCP로 Cloud SQL 인스턴스에 연결하려면 -instances 명령줄 인수를 사용하여 쉼표로 구분된 연결 문자열 목록을 지정합니다. 이 예시에서 보여준 것처럼 각 연결 문자열 뒤에 TCP 포트 번호가 있습니다.

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER

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

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

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234

여러 인스턴스에 연결하려면 -instances 인수에 쉼표로 구분된 인스턴스 연결 이름 목록을 지정하여 Cloud SQL 프록시를 사용할 수 있습니다. 다음 예시와 같이 각 인스턴스에는 고유한 포트 번호가 있어야 합니다.

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME_1=tcp:5432,INSTANCE_CONNECTION_NAME_2=tcp:5433

Unix 소켓 구성

또한 Cloud SQL 프록시는 폴더를 사용하여 동일한 호스트에서 실행되는 두 프로세스 간의 통신을 관리하는 Posix 표준 메커니즘인 Unix 소켓에서 리슨할 수 있습니다. Unix 소켓을 사용할 때의 장점은 보안이 향상되고 지연 시간이 짧다는 것입니다. 하지만 외부 머신에서는 Unix 소켓에 액세스할 수 없습니다.

Unix 소켓을 만들고 사용하려면 대상 디렉터리가 있어야 하며 프록시와 애플리케이션 모두 해당 디렉터리에 대한 읽기 및 쓰기 액세스 권한이 있어야 합니다. 새 디렉터리를 만들고 필요한 권한을 설정하려면 다음 명령어를 사용하세요.

sudo mkdir ~/cloudsql
sudo chmod a+rw ~/cloudsql

프록시를 시작할 때 두 가지 옵션으로 소켓 디렉터리를 지정할 수 있습니다. 한 가지 옵션은 다음과 같이 -dir 명령줄 인수를 사용하는 것입니다.

./cloud_sql_proxy -dir=PATH_TO_TARGET_FOLDER -instances=INSTANCE_CONNECTION_NAME

다른 옵션으로는 소켓 디렉터리를 연결 문자열 인수에 추가할 수 있습니다.

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=unix:/PATH_TO_TARGET_FOLDER

공개 IP 또는 비공개 IP 선택

Cloud SQL 인스턴스는 기본적으로 공개 IP 연결을 사용하지만 비공개 IP 연결을 지원하도록 인스턴스를 구성할 수도 있습니다. 비공개 IP는 VPC 네트워크에서 호스팅되는 내부 IP 주소를 사용하므로 동일한 VPC 네트워크 내의 다른 리소스에서만 액세스할 수 있습니다. 비공개 IP 사용의 이점은 IP 트래픽이 인터넷에 노출되지 않으므로 더 안전하고, 일부 경우 비공개 IP가 공개 IP보다 지연 시간이 짧기 때문에 성능이 향상된다는 것입니다.

비공개 IP를 사용하도록 Cloud SQL 인스턴스를 구성하려면 비공개 IP 구성을 참조하세요.

프록시의 -ip_address_types 명령줄 플래그는 Cloud SQL 인스턴스에 연결할 때 사용되는 기본 IP 순서를 지정합니다. 기본 설정은 -ip_address_types=PUBLIC,PRIVATE입니다. 즉, 인스턴스가 공개 IP를 사용 설정하면 프록시가 공개 IP로 먼저 연결을 시도합니다. 그런 다음 인스턴스가 비공개 IP를 사용 설정하면 프록시가 비공개 IP로 연결을 시도합니다. 프록시가 비공개 IP로만 연결을 시도하도록 지정하려면 다음 예시와 같이 -ip_address_types=PRIVATE 플래그를 사용합니다.

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:5432 -ip_address_types=PRIVATE

기타 명령줄 인수

위의 예시는 가장 일반적인 사용 사례를 다루지만 Cloud SQL 프록시에는 명령줄 인수로 설정할 수 있는 다른 구성 옵션도 있습니다. 명령줄 인수에 대한 도움말은 -help 플래그를 사용하여 최신 문서를 참조하세요.

./cloud_sql_proxy -help

Cloud SQL 프록시 명령줄 옵션을 사용 방법에 대한 추가 예시는 Cloud SQL 프록시 GitHub 저장소의 README를 참조하세요.

추가 정보

별도의 프로세스에서 프록시 실행

별도의 터미널 프로세스에서 Cloud SQL 프록시를 실행하면 콘솔 출력이 다른 프로그램의 출력과 혼합되지 않습니다. 아래의 구문을 사용하여 별도 프로세스에서 프록시를 호출합니다.

Linux

Linux 또는 macOS에서는 명령줄에서 후행 &를 사용하여 별도의 프로세스에서 프록시를 실행합니다.

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE &

Windows

Windows PowerShell에서 Start-Process 명령어를 사용하여 별도의 프로세스에서 프록시를 실행합니다.

Start-Process -filepath "cloud_sql_proxy.exe"
  -ArgumentList "-instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE"

Docker 컨테이너에서 Cloud SQL 프록시 실행

Docker 컨테이너에서 Cloud SQL 프록시를 실행하려면 Google Container Registry에서 제공되는 프록시 Docker 이미지를 사용합니다. 이 gcloud 명령어를 사용하여 프록시 Docker 이미지를 설치할 수 있습니다.

docker pull gcr.io/cloudsql-docker/gce-proxy:1.16

다음 명령어를 통해 TCP 소켓 또는 Unix 소켓을 사용하여 프록시를 시작할 수 있습니다.

TCP 소켓

docker run -d \
  -v PATH_TO_KEY_FILE:/config \
  -p 127.0.0.1:5432:5432 \
  gcr.io/cloudsql-docker/gce-proxy:1.16 /cloud_sql_proxy \
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:5432 \
  -credential_file=/config

Unix 소켓

docker run -d \
  -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
  -v PATH_TO_KEY_FILE:/config \
  gcr.io/cloudsql-docker/gce-proxy:1.16 /cloud_sql_proxy -dir=/cloudsql \
  -instances=INSTANCE_CONNECTION_NAME
  -credential_file=/config/PATH_TO_KEY_FILE

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

-v /mnt/stateful_partition/cloudsql:/cloudsql

Compute Engine 인스턴스에서 제공되는 사용자 인증 정보를 사용하는 경우에는 credential_file 매개변수와 -v PATH_TO_KEY_FILE:/config</span> 행을 포함하지 마세요.

서비스로 Cloud SQL 프록시 실행

프록시를 백그라운드 서비스로 실행하면 로컬 개발 및 테스트에 편리합니다. Cloud SQL 인스턴스에 액세스해야 하는 경우 백그라운드에서 서비스를 시작하고, 완료되면 중지할 수 있습니다.

Windows

Cloud SQL 프록시는 현재 Windows 서비스로 실행하기 위한 기본 지원을 제공하지 않지만 타사 서비스 관리자를 사용하면 서비스로 실행할 수 있습니다. 예를 들어 NSSM을 사용하여 프록시를 Windows 서비스로 구성할 수 있습니다. 그러면 NSSM이 프록시를 모니터링하고 프록시가 응답을 중지하면 자동으로 다시 시작합니다. 자세한 내용은 NSSM 문서를 참조하세요.

다음 단계