Cloud SQL 인증 프록시를 사용하여 연결

MySQL   |  PostgreSQL   |  SQL Server

이 페이지에서는 Cloud SQL 인증 프록시를 사용하여 Cloud SQL 인스턴스에 연결하는 방법을 설명합니다.

Cloud SQL 인증 프록시의 작동 방식에 대한 자세한 내용은 Cloud SQL 인증 프록시 정보를 참조하세요.

개요

Cloud SQL 인스턴스에 연결할 때는 Cloud SQL 인증 프록시를 사용하는 것이 좋습니다. Cloud SQL 인증 프록시

• 공개 및 비공개 IP 엔드포인트와 연동
• 사용자 또는 서비스 계정의 사용자 인증 정보를 사용한 연결 검증
• Cloud SQL 인스턴스에 대해 승인된 SSL/TLS 레이어에서 연결을 래핑

일부 Google Cloud 서비스 및 애플리케이션은 Cloud SQL 인증 프록시를 사용하여 다음을 포함해 암호화 및 승인을 사용하는 공개 IP 경로에 대한 연결을 제공합니다.

• App Engine 표준 환경
• App Engine 가변형 환경
• Cloud Functions
• Cloud Run

Google Kubernetes Engine에서 실행되는 애플리케이션은 Cloud SQL 인증 프록시를 사용하여 연결할 수 있습니다.

참고: Google Kubernetes Engine에서 연결할 경우 포드를 애플리케이션과 공유하는 추가 컨테이너와 같이 sidecar 패턴에서 Cloud SQL 인증 프록시를 실행하는 것이 좋습니다. 또한 관련된 빠른 시작을 참조하세요.

기본적인 사용 방법은 빠른 시작: Cloud SQL 인증 프록시 사용을 참조하세요.

로컬 머신 또는 Compute Engine에서 psql 클라이언트를 사용하여 Cloud SQL 인증 프록시 유무와 관계없이 연결할 수 있습니다.

시작하기 전에

Cloud SQL 인스턴스에 연결하려면 먼저 다음을 수행하세요.

1. • 사용자나 서비스 계정의 경우 계정에 Cloud SQL 클라이언트 역할이 있는지 확인합니다. 이 역할에는 주 구성원이 프로젝트의 모든 Cloud SQL 인스턴스에 연결하도록 승인하는 cloudsql.instances.connect 권한이 포함됩니다.

     IAM 페이지로 이동

   • 원하는 경우 특정 Cloud SQL 인스턴스 하나만 연결할 수 있는 권한을 계정에 부여하는 IAM 조건을 IAM 정책 바인딩에 포함할 수 있습니다.

2. Cloud SQL Admin API 사용 설정

   API 사용 설정

3. gcloud CLI를 설치하고 초기화합니다.
4. 선택사항입니다. Cloud SQL 인증 프록시 Docker 클라이언트를 설치합니다.

Cloud SQL 인증 프록시 다운로드

Linux 64비트

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

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

2. Cloud SQL 인증 프록시 실행 파일을 만듭니다.

   chmod +x cloud-sql-proxy
   

Linux 32비트

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

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

2. curl 명령어를 찾을 수 없으면 sudo apt install curl을 실행하고 다운로드 명령어를 반복합니다.
3. Cloud SQL 인증 프록시 실행 파일을 만듭니다.

   chmod +x cloud-sql-proxy
   

macOS 64비트

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

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

2. Cloud SQL 인증 프록시 실행 파일을 만듭니다.

   chmod +x cloud-sql-proxy
   

Mac M1

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

     curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.10.1/cloud-sql-proxy.darwin.arm64
     

2. Cloud SQL 인증 프록시 실행 파일을 만듭니다.

     chmod +x cloud-sql-proxy
     

Windows 64비트

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

Windows 32비트

https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.10.1/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.10.1

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

기타 OS

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

Cloud SQL 인증 프록시 시작

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

경고: 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

1. INSTANCE_CONNECTION_NAME을 복사합니다. Google Cloud 콘솔의 인스턴스에 대한 개요 페이지에서 확인하거나 다음 명령어를 실행하여 확인할 수 있습니다.

       gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'

   .

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

2. 인스턴스에 공개 및 비공개 IP가 모두 구성되어 있고 Cloud SQL 인증 프록시에서 비공개 IP 주소를 사용하도록 하려는 경우 Cloud SQL 인증 프록시를 시작할 때 다음 옵션을 제공해야 합니다.

   --private-ip

3. 서비스 계정을 사용하여 Cloud SQL 인증 프록시를 인증하는 경우 서비스 계정을 만들 때 생성된 비공개 키 파일의 클라이언트 머신 내 위치를 기록해 둡니다.
4. Cloud SQL 인증 프록시를 시작합니다.

   가능한 Cloud SQL 인증 프록시 호출 문자열은 다음과 같습니다.

   • Cloud SDK 인증 사용:

     ./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
     

     지정된 포트는 로컬 데이터베이스 서버 등에서 이미 사용하지 않는 포트여야 합니다.
   • 서비스 계정 사용 및 명시적으로 인스턴스 연결 이름 포함(프로덕션 환경에 권장):

     ./cloud-sql-proxy \
     --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
     
     

   Cloud SQL 인증 프록시 옵션에 대한 자세한 내용은 Cloud SQL 인증 프록시 인증 옵션과 인스턴스 지정 옵션을 참조하세요.

Unix 소켓

참고: Cloud SQL 인증 프록시는 현재 Windows에서 Unix 소켓을 지원하지 않으므로 Linux 및 macOS 플랫폼에서만 이 옵션을 사용할 수 있습니다.

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

참고: PostgreSQL 표준의 경우 소켓 경로에 `.s.PGSQL.5432` 서픽스가 필요합니다. 일부 라이브러리는 이 서픽스를 자동으로 적용하지만 다른 라이브러리에서는 소켓 경로(예: )를 직접 지정해야 합니다.

  /cloudsql/INSTANCE_CONNECTION_NAME/.s.PGSQL.5432
  

Unix 소켓을 만들고 사용하려면 대상 디렉터리가 있어야 하며 Cloud SQL 인증 프록시와 애플리케이션 모두 디렉터리에 대한 읽기 및 쓰기 액세스 권한이 있어야 합니다.

1. 명시적 인스턴스 지정을 사용하는 경우 INSTANCE_CONNECTION_NAME을 복사합니다. Google Cloud 콘솔의 인스턴스 개요 페이지에서 또는 다음 명령어를 실행하여 이를 확인할 수 있습니다.

   gcloud sql instances describe INSTANCE_NAME  --format='value(connectionName)'

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

2. Cloud SQL 인증 프록시 소켓이 위치할 디렉터리를 만듭니다.

   sudo mkdir /cloudsql; sudo chmod 777 /cloudsql

3. 서비스 계정을 사용하여 Cloud SQL 인증 프록시를 인증하는 경우 서비스 계정을 만들 때 생성된 비공개 키 파일의 클라이언트 머신 내 위치를 기록해 둡니다.
4. 새 Cloud Shell 터미널 창을 열고 Cloud SQL 인증 프록시를 시작합니다.

   가능한 Cloud SQL 인증 프록시 호출 문자열은 다음과 같습니다.

   • 서비스 계정 사용 및 명시적으로 인스턴스 연결 이름 포함(프로덕션 환경에 권장):

     ./cloud-sql-proxy --unix-socket /cloudsql
     --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

   • Cloud SDK 인증과 자동 인스턴스 검색 사용:

     ./cloud-sql-proxy --unix-socket /cloudsql &

   자체 Cloud Shell 터미널에서 Cloud SQL 인증 프록시를 시작하여 출력을 다른 프로그램의 출력과 별도로 모니터링할 수 있습니다.

   Cloud SQL 인증 프록시 옵션에 대한 자세한 내용은 Cloud SQL 인증 프록시 인증 옵션과 인스턴스 지정 옵션을 참조하세요.

참고: Unix 소켓을 사용하여 Cloud SQL 인증 프록시로 Cloud SQL에 연결할 경우 소켓 파일 이름 길이가 시스템 제한을 초과하지 않는지 확인합니다. 시스템에 따라 다르지만 이는 일반적으로 91~108자입니다. Linux에서 길이는 일반적으로 108자로 정의되며 다음 명령어를 사용하여 확인할 수 있습니다.

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

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입니다.

참고: Cloud SQL 인증 프록시는 Windows에서 Unix 도메인 소켓의 리슨을 지원하지 않습니다.

언어와 환경에 따라 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:5432:5432 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.10.1 \\
  --address 0.0.0.0 --port 5432 \\
  --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.10.1 --unix-socket=/cloudsql \\
  --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 행을 포함하지 마세요.

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

-v /mnt/stateful_partition/cloudsql:/cloudsql

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

psql 클라이언트에 연결합니다.

Debian/Ubuntu

패키지 관리자에서 psql 클라이언트를 설치합니다.

sudo apt-get update
sudo apt-get install postgresql-client

CentOS/RHEL

패키지 관리자에서 psql 클라이언트를 설치합니다.

sudo yum install postgresql

openSUSE

패키지 관리자에서 psql 클라이언트를 설치합니다.

sudo zypper install postgresql

기타 플랫폼

1. PostgreSQL 다운로드 페이지에서 플랫폼에 맞는 PostgreSQL Core Distribution을 다운로드합니다.
   Core Distribution에는 psql 클라이언트가 포함되어 있습니다.
2. 다운로드 페이지의 안내에 따라 PostgreSQL 데이터베이스를 설치합니다.

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

TCP 소켓

1. psql 클라이언트를 시작합니다.

   psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
   

   sslmode 매개변수가 disable로 설정되어 있더라도 Cloud SQL 인증 프록시는 암호화된 연결을 제공합니다.

   TCP 소켓을 사용하여 연결하면 127.0.0.1을 통해 Cloud SQL 인증 프록시에 액세스합니다.

2. 메시지가 표시되면 비밀번호를 입력합니다.
3. psql 프롬프트가 표시됩니다.

Unix 소켓 사용

1. psql 클라이언트를 시작합니다.

   psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"
   

   sslmode 매개변수가 disable로 설정되어 있더라도 Cloud SQL 인증 프록시는 암호화된 연결을 제공합니다.

2. 비밀번호를 입력합니다.
3. psql 프롬프트가 표시됩니다.

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

애플리케이션과 연결

Unix 또는 TCP 소켓에 연결할 수 있게 해주는 모든 언어에서 Cloud SQL 인증 프록시에 연결할 수 있습니다. 다음은 애플리케이션에서 어떻게 함께 작동하는지 이해하는 데 도움이 되는 GitHub 전체 예시의 몇 가지 코드 스니펫입니다.

TCP로 연결

Cloud SQL 인증 프록시 호출 문:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

import os
import ssl

import sqlalchemy

def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of Postgres."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_host = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=db_host,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

참고:

• CLOUD_SQL_CONNECTION_NAME은 <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>으로 표현되어야 합니다.
• 인수 ipTypes=PRIVATE을 사용하면 SocketFactory가 인스턴스의 연결된 비공개 IP와 강제로 연결됩니다.
• pom.xml 파일에 대한 JDBC 소켓 팩토리 버전 요구사항은 여기를 참조하세요.

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");

  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"

    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Go

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

C#

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

tcp: &tcp
  adapter: postgresql
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("INSTANCE_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 5432 }%>

PHP

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseTcp
{
    public static function initTcpDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)

            // Connect using TCP
            $dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $instanceHost);

            // Connect to the database
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Unix 소켓으로 연결

Cloud SQL 인증 프록시 호출 문:

./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &

Python

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

import os

import sqlalchemy

def connect_unix_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a Unix socket connection pool for a Cloud SQL instance of Postgres."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_user = os.environ["DB_USER"]  # e.g. 'my-database-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-database-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    unix_socket_path = os.environ[
        "INSTANCE_UNIX_SOCKET"
    ]  # e.g. '/cloudsql/project:region:instance'

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@/<db_name>
        #                         ?unix_sock=<INSTANCE_UNIX_SOCKET>/.s.PGSQL.5432
        # Note: Some drivers require the `unix_sock` query parameter to use a different key.
        # For example, 'psycopg2' uses the path set to `host` in order to connect successfully.
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            database=db_name,
            query={"unix_sock": f"{unix_socket_path}/.s.PGSQL.5432"},
        ),
        # ...
    )
    return pool

Java

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class ConnectorConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String INSTANCE_CONNECTION_NAME =
      System.getenv("INSTANCE_CONNECTION_NAME");
  private static final String INSTANCE_UNIX_SOCKET = System.getenv("INSTANCE_UNIX_SOCKET");
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql:///<DB_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&
    // socketFactory=com.google.cloud.sql.postgres.SocketFactory&user=<DB_USER>&password=<DB_PASS>
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql:///%s", DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", _postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"

    config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.postgres.SocketFactory");
    config.addDataSourceProperty("cloudSqlInstance", INSTANCE_CONNECTION_NAME);

    // Unix sockets are not natively supported in Java, so it is necessary to use the Cloud SQL
    // Java Connector to connect. When setting INSTANCE_UNIX_SOCKET, the connector will
    // call an external package that will enable Unix socket connections.
    // Note: For Java users, the Cloud SQL Java Connector can provide authenticated connections
    // which is usually preferable to using the Cloud SQL Proxy with Unix sockets.
    // See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.
    if (INSTANCE_UNIX_SOCKET != null) {
      config.addDataSourceProperty("unixSocketPath", INSTANCE_UNIX_SOCKET);
    }

    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

const Knex = require('knex');

// createUnixSocketPool initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
const createUnixSocketPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  return Knex({
    client: 'pg',
    connection: {
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
      host: process.env.INSTANCE_UNIX_SOCKET, // e.g. '/cloudsql/project:region:instance'
    },
    // ... Specify additional properties here.
    ...config,
  });
};

C#

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlUnix
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlUnixSocketConnectionString()
        {
            // Equivalent connection string:
            // "Server=<INSTANCE_UNIX_SOCKET>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,

                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_UNIX_SOCKET"), // e.g. '/cloudsql/project:region:instance'
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Go

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectUnixSocket initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
func connectUnixSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_unix.go: %s environment variable not set.\n", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser         = mustGetenv("DB_USER")              // e.g. 'my-db-user'
		dbPwd          = mustGetenv("DB_PASS")              // e.g. 'my-db-password'
		unixSocketPath = mustGetenv("INSTANCE_UNIX_SOCKET") // e.g. '/cloudsql/project:region:instance'
		dbName         = mustGetenv("DB_NAME")              // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("user=%s password=%s database=%s host=%s",
		dbUser, dbPwd, dbName, unixSocketPath)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

Ruby

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

unix: &unix
  adapter: postgresql
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  # Specify the Unix socket path as host
  host: "<%= ENV["INSTANCE_UNIX_SOCKET"] %>"

PHP

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseUnix
{
    public static function initUnixDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceUnixSocket = getenv('INSTANCE_UNIX_SOCKET'); // e.g. '/cloudsql/project:region:instance'

            // Connect using UNIX sockets
            $dsn = sprintf(
                'pgsql:dbname=%s;host=%s',
                $dbName,
                $instanceUnixSocket
            );

            // Connect to the database.
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, ' .
                        'and $instanceUnixSocket (for UNIX socket mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

추가 주제

Cloud SQL 인증 프록시 명령줄 인수

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

./cloud-sql-proxy --help

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

Cloud SQL 인증 프록시 인증 옵션

Cloud SQL 인증 프록시를 인증하는 경우 Google 사용자 인증 정보를 사용하여 애플리케이션을 대신해 Google Cloud에 액세스하도록 설정합니다. 이는 데이터베이스 사용자 인증과는 별개입니다. IAM 사용자 데이터베이스 인증은 Cloud SQL 인증 프록시와 통합됩니다.

이러한 모든 옵션은 INSTANCE_CONNECTION_NAME을 연결 문자열로 사용하여 Cloud SQL 인스턴스를 식별합니다. Google Cloud 콘솔의 인스턴스 개요 페이지에서 또는 다음 명령어를 실행하여 INSTANCE_CONNECTION_NAME을 확인할 수 있습니다.

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME

예를 들면 다음과 같습니다. gcloud sql instances describe --project myproject myinstance

이러한 옵션 중 일부는 계정의 RSA 비공개 키가 포함된 JSON 사용자 인증 정보 파일을 사용합니다. 서비스 계정의 JSON 사용자 인증 정보 파일을 만드는 방법은 서비스 계정 만들기를 참조하세요.

Cloud SQL 인증 프록시는 환경에 따라 다양한 인증 방법 대안을 제공합니다. Cloud SQL 인증 프록시는 다음의 각 항목을 다음 순서대로 확인하여 첫 번째로 발견된 항목으로 인증을 시도합니다.

1. credentials-file 플래그로 제공된 사용자 인증 정보

   서비스 계정을 사용하여 연결된 JSON 파일을 만들어 다운로드하고 Cloud SQL 인증 프록시를 시작할 때 --credentials-file 플래그를 해당 파일 경로로 설정합니다. 서비스 계정에는 Cloud SQL 인스턴스를 사용하는 데 필요한 권한이 있어야 합니다.

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

   ./cloud-sql-proxy --credentials-file PATH_TO_KEY_FILE \
   INSTANCE_CONNECTION_NAME
     

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

   Cloud SQL에서 지원하는 역할에 대한 자세한 내용은 Cloud SQL의 IAM 역할을 참조하세요.

2. 액세스 토큰으로 제공된 사용자 인증 정보

   액세스 토큰을 만들고 --token 플래그와 함께 cloud-sql-proxy 명령어를 호출하여 OAuth 2.0 액세스 토큰으로 설정합니다. 예를 들면 다음과 같습니다.

   ./cloud-sql-proxy --token ACCESS_TOKEN \
   INSTANCE_CONNECTION_NAME
     

3. 환경 변수로 제공된 사용자 인증 정보

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

4. 인증된 gcloud CLI 클라이언트의 사용자 인증 정보

   gcloud CLI를 설치하고 개인 계정으로 인증한 경우 Cloud SQL 인증 프록시에서 동일한 계정 사용자 인증 정보를 사용할 수 있습니다. 이 방법은 특히 개발 환경을 준비하고 실행하는 데 유용합니다.

   Cloud SQL 인증 프록시에서 gcloud CLI 사용자 인증 정보를 사용하도록 사용 설정하려면 다음 명령어를 사용하여 gcloud CLI를 인증합니다.

   gcloud auth application-default login

5. Compute Engine 인스턴스와 관련된 사용자 인증 정보

   Compute Engine 인스턴스에서 Cloud SQL에 연결하는 경우 Cloud SQL 인증 프록시는 Compute Engine 인스턴스와 연결된 서비스 계정을 사용할 수 있습니다. 서비스 계정에 Cloud SQL 인스턴스를 사용하는 데 필요한 권한이 있으면 Cloud SQL 인증 프록시가 성공적으로 인증됩니다.

   Compute Engine 인스턴스가 Cloud SQL 인스턴스와 동일한 프로젝트에 있으면 Compute Engine 인스턴스의 기본 서비스 계정에는 Cloud SQL 인증 프록시를 인증하는 데 필요한 권한이 있습니다. 두 인스턴스가 서로 다른 프로젝트에 있는 경우 Compute Engine 인스턴스의 서비스 계정을 Cloud SQL 인스턴스가 포함된 프로젝트에 추가해야 합니다.

6. 환경의 기본 서비스 계정

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

서비스 계정 만들기

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

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

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

1. Google Cloud 콘솔에서 서비스 계정 페이지로 이동합니다.

   서비스 계정으로 이동

2. Cloud SQL 인스턴스가 포함된 프로젝트를 선택합니다.
3. 서비스 계정 만들기를 클릭합니다.
4. 서비스 계정 이름 필드에 서비스 계정의 설명이 포함된 이름을 입력합니다.
5. 서비스 계정 ID를 고유하고 인식할 수 있는 값으로 변경한 후 만들고 계속하기를 클릭합니다.
6. 역할 선택 필드를 클릭하고 다음 역할 중 하나를 선택합니다.
   • Cloud SQL > Cloud SQL 클라이언트
   • Cloud SQL > Cloud SQL 편집자
   • Cloud SQL > Cloud SQL 관리자
   참고: 필요한 권한이 있는 서비스 계정을 만들려면 resourcemanager.projects.setIamPolicy 권한이 있어야 합니다. 이 권한은 프로젝트 소유자, 프로젝트 IAM 관리자, 조직 관리자 역할에 포함되어 있습니다.
   Cloud SQL Admin API도 사용 설정해야 합니다. 기존 프로젝트 역할(뷰어, 편집자, 소유자)을 사용하는 경우 서비스 계정에 최소한 편집자 역할이 있어야 합니다.
7. 완료를 클릭하여 서비스 계정 만들기를 마칩니다.
8. 새 서비스 계정의 작업 메뉴를 클릭한 후 키 관리를 선택합니다.
9. 키 추가 드롭다운 메뉴를 클릭한 후 새 키 만들기를 클릭합니다.
10. 키 유형이 JSON인지 확인한 후 만들기를 클릭합니다.

    비공개 키 파일이 머신에 다운로드됩니다. 파일을 다른 위치로 이동할 수 있습니다. 키 파일을 안전하게 보관하세요.

비공개 IP로 Cloud SQL 인증 프록시 사용

비공개 IP를 사용하여 Cloud SQL 인스턴스에 연결하려면 Cloud SQL 인증 프록시가 인스턴스와 동일한 VPC 네트워크에 액세스할 수 있는 리소스에 있어야 합니다.

Cloud SQL 인증 프록시는 IP를 사용하여 Cloud SQL 인스턴스와의 연결을 설정합니다. 기본적으로 Cloud SQL 인증 프록시는 공개 IPv4 주소를 사용하여 연결을 시도합니다.

Cloud SQL 인스턴스에 비공개 IP만 있거나 인스턴스에 공개 및 비공개 IP가 모두 구성되어 있고 Cloud SQL 인증 프록시가 비공개 IP 주소를 사용하도록 하려면 Cloud SQL 인증 프록시를 시작할 때 다음 옵션을 제공해야 합니다.

--private-ip

Private Service Connect가 사용 설정된 인스턴스에서 Cloud SQL 인증 프록시 사용

Cloud SQL 인증 프록시를 사용하여 Private Service Connect가 사용 설정된 Cloud SQL 인스턴스에 연결할 수 있습니다.

Cloud SQL 인증 프록시는 승인된 네트워크나 SSL 구성 없이도 이 인스턴스에 안전하게 액세스할 수 있는 커넥터입니다.

Cloud SQL 인증 프록시 클라이언트 연결을 허용하려면 사용자가 인스턴스에 제공된 권장 DNS 이름과 일치하는 DNS 레코드를 설정해야 합니다. DNS 레코드는 DNS 리소스와 도메인 이름 간의 매핑입니다.

Cloud SQL 인증 프록시를 사용하여 Private Service Connect가 사용 설정된 인스턴스에 연결하는 방법에 대한 자세한 내용은 Cloud SQL 인증 프록시를 사용하여 연결을 참조하세요.

별도의 프로세스에서 Cloud SQL 인증 프록시 실행

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

Linux

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

./cloud-sql-proxy INSTANCE_CONNECTION_NAME
  --credentials-file PATH_TO_KEY_FILE &

Windows

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

Start-Process --filepath "cloud-sql-proxy.exe"
  --ArgumentList "
  --credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"

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

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

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

다음 명령어로 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:5432:5432 \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.10.1 \
      --address 0.0.0.0 \
      --credentials-file /path/to/service-account-key.json \
      INSTANCE_CONNECTION_NAME

Unix 소켓

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

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

v /mnt/stateful_partition/cloudsql:/cloudsql

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

서비스로 Cloud SQL 인증 프록시 실행

Cloud SQL 인증 프록시를 백그라운드 서비스로 실행은 로컬 개발 및 프로덕션 워크로드를 위한 옵션입니다. 개발 단계에서 Cloud SQL 인스턴스에 액세스해야 하는 경우에는 백그라운드에서 서비스를 시작하고 완료 후에 중지하면 됩니다.

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

참고: Cloud SQL 인증 프록시를 서비스로 실행하는 경우 보안 연결을 사용하여 Cloud SQL 인스턴스와 통신하지만 애플리케이션에서 Cloud SQL 인증 프록시로의 연결은 암호화되지 않습니다. 따라서 신뢰할 수 있는 사용자만 Cloud SQL 인증 프록시에서 리슨하는 주소와 포트에 액세스할 수 있어야 합니다.

Cloud SQL 인증 프록시 사용 시행

ConnectorEnforcement를 사용하여 Cloud SQL에서 Cloud SQL 인증 프록시를 사용 설정합니다.

gcloud

다음 명령어는 Cloud SQL 커넥터를 사용합니다.

    gcloud sql instances patch INSTANCE_NAME \
    --connector-enforcement REQUIRED
  

적용을 중지하려면 다음 코드 줄을 사용합니다. --connector-enforcement NOT_REQUIRED 이 업데이트는 다시 시작을 트리거하지 않습니다.

REST v1

다음 명령어는 Cloud SQL 커넥터를 사용합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• project-id: 프로젝트 ID
• instance-id: 인스턴스 ID입니다.

HTTP 메서드 및 URL:

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

JSON 요청 본문:

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

시행을 중지하려면 대신 "connectorEnforcement": "NOT_REQUIRED"를 사용합니다. 이 업데이트는 다시 시작을 트리거하지 않습니다.

REST v1beta4

다음 명령어는 Cloud SQL 커넥터를 사용합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• project-id: 프로젝트 ID
• instance-id: 인스턴스 ID입니다.

HTTP 메서드 및 URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

JSON 요청 본문:

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

시행을 중지하려면 대신 "connectorEnforcement": "NOT_REQUIRED"를 사용합니다. 이 업데이트는 다시 시작을 트리거하지 않습니다.

Cloud SQL 인증 프록시 작업에 대한 팁

Cloud SQL 인증 프록시 호출하기

모든 프록시 호출 샘플은 백그라운드에서 Cloud SQL 인증 프록시를 시작하므로 프롬프트가 반환됩니다. 출력이 다른 프로그램의 출력과 섞이지 않도록 Cloud SQL 인증 프록시에 Cloud Shell 터미널을 예약합니다. 또한 Cloud SQL 인증 프록시의 출력을 사용해 연결 문제를 진단할 수 있으므로 로그 파일로 캡처하는 것이 유용합니다. 백그라운드에서 Cloud SQL 인증 프록시를 시작하지 않으면 출력이 리디렉션되지 않는 한 stdout으로 이동합니다.

/cloudsql을 Cloud SQL 인증 프록시 소켓의 디렉터리로 사용할 필요는 없습니다. (이 디렉토리 이름은 App Engine 연결 문자열과의 차이를 최소화하기 위해 선택되었습니다.) 그러나 디렉터리 이름을 변경하는 경우에는 전체 길이를 최소로 유지해야 하는데, 이는 운영체제의 길이 제한이 적용되는 더 긴 문자열에 통합되기 때문입니다. 시스템에 따라 다르지만 이는 일반적으로 91~108자입니다. Linux에서 길이는 일반적으로 108자로 정의되며 다음 명령어를 사용하여 확인할 수 있습니다.

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Cloud SQL 인증 프록시를 사용하여 여러 인스턴스에 연결

하나의 로컬 Cloud SQL 인증 프록시 클라이언트를 사용하여 여러 Cloud SQL 인스턴스에 연결할 수 있습니다. Unix 소켓과 TCP 중에 무엇을 사용하는지에 따라 연결 방법이 달라집니다.

Unix 소켓

Cloud SQL 인증 프록시를 여러 인스턴스에 연결하려면 공백으로 구분된 목록으로 각 인스턴스 연결 이름을 Cloud SQL 인증 프록시에 인수로 제공합니다. Cloud SQL 인증 프록시는 시작되면 각 인스턴스에 연결됩니다.

지정된 디렉터리에서 소켓을 사용하여 각 인스턴스에 연결합니다.

예를 들면 다음과 같습니다.

      ./cloud-sql-proxy --unix-socket /cloudsql \
      myProject:us-central1:myInstance myProject:us-central1:myInstance2 &
      psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2
  

TCP 소켓

TCP를 사용하여 연결하는 경우 Cloud SQL 인증 프록시가 각 Cloud SQL 인스턴스를 리슨할 수 있도록 머신에 포트를 지정합니다. 여러 Cloud SQL 인스턴스에 연결할 때 지정된 각 포트는 고유해야 하며 머신에서 사용할 수 있어야 합니다.

예를 들면 다음과 같습니다.

    # Start the Cloud SQL Auth Proxy to connect to two different Cloud SQL instances
    # Give the Cloud SQL Auth Proxy a unique port on your machine to use for each Cloud SQL instance.

    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" \
    "myProject:us-central1:myInstance2?port=1234"

    # Connect to "myInstance" using port 5432 on your machine:
    psql -U myUser -h 127.0.0.1  --port 5432

    # Connect to "myInstance2" using port 1234 on your machine:
    psql -U myUser -h 127.0.0.1  --port 1234
  

Cloud SQL 인증 프록시 호출 및 psql 클라이언트 연결 문자열

예를 들어 myProject 프로젝트의 us-central1에 위치한 myInstance 인스턴스, PostgreSQL 사용자 myUser에 대한 명령어에서 Cloud SQL 인증 프록시 호출과 연결 문자열을 사용할 수 있습니다.

gcloud CLI 사용자 인증 정보로 자동 인스턴스 검색 사용:

    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
 

gcloud CLI 사용자 인증 정보로 프로젝트 검색 사용:

    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

인스턴스가 명시적으로 지정된 Compute Engine 인스턴스의 경우:

    ./cloud-sql-proxy --unix-socket /cloudsql myProject:us-central1:myInstance &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

Unix에서 TCP를 사용하는 경우:

    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" &
    psql -U myUser -h 127.0.0.1

Windows의 경우(명령줄 프롬프트):

    cloud-sql-proxy.exe "myProject:us-central1:myInstance?port=5432"
    psql -U myUser -h 127.0.0.1

참고: 5432는 psql 클라이언트에 사용되는 기본 포트입니다. 다른 포트 번호를 사용하는 경우 psql 클라이언트를 시작할 때 --port 매개변수를 사용하여 포트 번호를 지정해야 합니다.

Cloud SQL 인증 프록시 옵션 및 연결 문자열에 대한 자세한 내용은 Cloud SQL 인증 프록시 GitHub 페이지를 참조하세요.

Cloud SQL 인증 프록시 연결 문제 해결

Cloud SQL 인증 프록시 Docker 이미지는 특정 버전의 Cloud SQL 인증 프록시를 기반으로 합니다. Cloud SQL 인증 프록시의 새 버전이 출시되면 새 버전의 Cloud SQL 인증 프록시 Docker 이미지를 가져와서 환경을 최신 상태로 유지합니다. Cloud SQL 인증 프록시 GitHub 출시 페이지를 확인하여 현재 버전의 Cloud SQL 인증 프록시를 볼 수 있습니다.

Cloud SQL 인증 프록시를 사용하여 Cloud SQL 인스턴스에 연결하는 데 문제가 있는 경우 다음과 같이 문제의 원인을 찾을 수 있습니다.

• Cloud SQL 인증 프록시 출력을 확인합니다.

  Cloud SQL 인증 프록시 출력은 문제의 원인과 해결 방법을 파악하는 데 도움이 됩니다. 출력을 파일로 보내거나 Cloud SQL 인증 프록시를 시작한 Cloud Shell 터미널을 확인하세요.

• 403 notAuthorized 오류가 발생한 경우 서비스 계정을 사용하여 Cloud SQL 인증 프록시를 인증하려면 서비스 계정에 올바른 권한이 있는지 확인합니다.

  IAM 페이지에서 ID를 검색하여 서비스 계정을 확인할 수 있습니다. 이렇게 하려면 cloudsql.instances.connect 권한이 있어야 합니다. Cloud SQL Admin, Client, Editor 사전 정의된 역할에는 이 권한이 있습니다.

• App Engine에서 연결할 때 403 notAuthorized 오류가 발생하면 app.yaml 값 cloud_sql_instances에 인스턴스 연결 이름 또는 철자가 잘못되었는지 확인합니다. 인스턴스 연결 이름은 항상 PROJECT:REGION:INSTANCE 형식입니다.

  또한 App Engine 서비스 계정(예: $[e-mail])에 Cloud SQL 클라이언트 IAM 역할이 있는지 확인합니다.

  App Engine 서비스가 한 프로젝트(A 프로젝트)에 있고 데이터베이스가 다른 프로젝트(B 프로젝트)에 있는 경우 이 오류는 App Engine 서비스 계정에 데이터베이스가 있는 프로젝트(B 프로젝트)의 Cloud SQL 클라이언트 IAM 역할이 부여되지 않았음을 의미합니다.

• Cloud SQL Admin API를 사용 설정해야 합니다.

  그렇지 않은 경우 Cloud SQL 인증 프록시 로그에 Error 403: Access Not Configured와 같은 출력이 표시됩니다.

• 인스턴스 목록에 여러 인스턴스를 포함하는 경우 공백 없이 쉼표로 구분해야 합니다. TCP를 사용하는 경우 인스턴스마다 다른 포트를 지정해야 합니다.

• UNIX 소켓을 사용하여 연결하는 경우 Cloud SQL 인증 프록시를 시작할 때 지정한 디렉터리를 나열하여 소켓이 생성되었는지 확인합니다.

• 아웃바운드 방화벽 정책이 있으면 대상 Cloud SQL 인스턴스에서 포트 3307에 연결할 수 있는지 확인합니다.

  참고: Cloud SQL Auth 프록시는 3307을 사용하여 Cloud SQL Auth 프록시 서버에 연결합니다. 포트 5432은 직접 TCP 연결의 PostgreSQL 프로토콜에 대한 기본 포트입니다(Cloud SQL 인증 프록시 사용 안 함).

• Google Cloud 콘솔의 작업 > 로깅 > 로그 탐색기 섹션 아래의 로그를 조사하여 Cloud SQL Auth 프록시가 올바르게 시작했는지 확인할 수 있습니다. 성공한 작업은 다음과 같이 표시됩니다.

  2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/5432 for $PROJECT_ID:$REGION:$INSTANCE_NAME
  2021/06/14 15:47:56 Ready for new connections
  

• 할당량 문제: Cloud SQL Admin API 할당량이 위반되면 Cloud SQL Auth 프록시가 시작될 때 다음 오류 메시지가 표시됩니다.

  There was a problem when parsing a instance configuration but ignoring due
  to the configuration. Error: googleapi: Error 429: Quota exceeded for quota
  metric 'Queries' and limit 'Queries per minute per user' of service
  'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID.,
  rateLimitExceeded
  

  애플리케이션이 프록시에 연결된 후 프록시가 다음 오류를 보고합니다.

  failed to refresh the ephemeral certificate for $INSTANCE_CONNECTION_NAME:
  googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit
  'Queries per minute per user' of service 'sqladmin.googleapis.com' for
  consumer 'project_number:$PROJECT_ID., rateLimitExceeded
  

  해결 방법: 할당량 문제의 원인을 식별합니다. 예를 들어 애플리케이션이 커넥터를 오용하고 있고 불필요하게 새 연결을 만들고 있을 수 있습니다. 또는 지원팀에 연락하여 Cloud SQL Admin API 할당량 증가를 요청합니다. 시작 시 할당량 오류가 표시되면 애플리케이션을 다시 배포하여 프록시를 다시 시작해야 합니다. 시작 후 할당량 오류가 표시되면 재배포가 불필요합니다.

다음 단계

• Cloud SQL 인증 프록시 자세히 알아보기
• Identity and Access Management(IAM) 자세히 알아보기
• 서비스 계정 자세히 알아보기
• Cloud SQL 인스턴스의 두 가지 액세스 제어 수준 알아보기
• 사용자 및 데이터베이스 만들기
• 애플리케이션에서 인스턴스로 연결하는 방법 알아보기
• psql 클라이언트 알아보기
• 지원 옵션 알아보기