PostgreSQL 데이터 소스 구성

PostgreSQL 데이터 소스 구성 (Configure)

이 문서는 PostgreSQL 데이터 소스를 구성하는 방법을 설명하고 모든 구성 옵션을 나열해요. 데이터 소스 관리 일반 정보는 Data source management을 참고하세요.

출처: Configure the PostgreSQL data source

본문

시작하기 전에

데이터 소스를 구성하려면 Organization administrator 역할이 필요해요. YAML(Grafana 프로비저닝) 또는 Terraform으로도 구성할 수 있어요.
Grafana는 OSS와 Enterprise에서 PostgreSQL 데이터 소스를 기본 설치해요. 플러그인을 설치할 필요가 없어요. 업데이트 옵션은 Plugin updates 참고.
PostgreSQL 보안 세부 정보(TLS/SSL을 사용한다면 인증서와 클라이언트 키)를 준비해요.
PostgreSQL 버전을 기록해 두세요. 구성 중에 물어볼 거예요.

참고: 데이터 소스를 추가할 때 지정하는 데이터베이스 사용자는 관련 스키마와 테이블에 대해 SELECT 권한만 가져야 해요. Grafana는 쿼리의 안전성을 검증하지 않으므로 사용자가 DROP TABLE 같은 잠재적으로 유해한 SQL을 실행할 수 있어요. 위험을 제한하려면 권한이 제한된 전용 PostgreSQL 사용자를 만드세요.

예시:

CREATE USER grafanareader WITH PASSWORD 'password';
GRANT USAGE ON SCHEMA schema TO grafanareader;
GRANT SELECT ON schema.table TO grafanareader;

schema와 table을 자신의 스키마와 테이블 이름으로 바꿔요.

PostgreSQL 데이터 소스 추가

왼쪽 메뉴에서 Connections를 클릭해요.
Add new connection을 클릭해요.
검색창에 PostgreSQL을 입력해요.
PostgreSQL data source를 선택해요.
오른쪽 위에서 Add new data source를 클릭해요.

데이터 소스를 구성하는 Settings 탭으로 이동해요.

PostgreSQL 구성 옵션

다음은 PostgreSQL 구성 옵션 목록이에요.

설정	설명
Name	패널과 쿼리에서 데이터 소스를 참조할 때 쓰는 이름. 예: `PostgreSQL-DB-1`
Default	이 특정 PostgreSQL 데이터 소스를 패널과 시각화에서 기본 사전 선택 데이터 소스로 설정하려면 토글

연결(Connection) 섹션:

참고: Grafana Cloud 사용자: Grafana Cloud는 localhost, 127.0.0.1, 또는 프라이빗 IP 범위(10.x, 172.16.x, 192.168.x)의 데이터베이스에 직접 도달할 수 없어요. PostgreSQL 인스턴스가 공개적으로 접근 불가능하다면 Grafana Cloud와 프라이빗 네트워크 사이에 보안 터널을 구축하려면 Private data source connect (PDC)를 설정해야 해요. Docker 기반 PDC 에이전트에서 간헐적 연결 끊김이 발생한다면 바이너리 기반 에이전트로 전환해 보세요. 데이터베이스가 공개적으로 접근 가능하지만 방화벽으로 보호된다면 Grafana Cloud 아웃바운드 IP 주소를 허용 목록에 추가해야 해요. Grafana Cloud는 스택별 고정 IP 주소를 제공하지 않아요. 서비스 수준 IP 범위만 제공해요. 현재 아웃바운드 IP 주소 목록은 Allow Grafana Cloud IP addresses in a firewall 참고.

설정	설명
Host URL	PostgreSQL 인스턴스의 IP 주소/호스트 이름과 선택적 포트. 기본 PostgreSQL 포트는 `5432`. IPv6 주소는 `[::1]:5432` 형식 사용. Unix 소켓으로 연결하려면 소켓 디렉토리 경로 입력(예: `/var/run/postgresql`)
Database name	PostgreSQL 데이터베이스 이름. 이 데이터베이스는 쿼리 편집기에서 쿼리의 기본값으로 사용돼요.

인증(Authentication) 섹션:

설정	설명
Username	PostgreSQL 데이터베이스에 연결하는 데 사용되는 사용자 이름을 입력해요.
Password	PostgreSQL 데이터베이스에 연결하는 데 사용되는 비밀번호를 입력해요. 선택 필드. 비워두면 PostgreSQL 클라이언트 드라이버가 표준 PostgreSQL password file(`.pgpass`)로 비밀번호를 해석해요. 기본이 아닌 비밀번호 파일 위치를 사용하려면 Grafana 서버 프로세스에서 `PGPASSFILE` 환경 변수를 설정해요.
TLS/SSL Mode	서버와 보안 TLS/SSL 연결을 협상할지, 어떻게 협상할지 결정. 각 모드에 대한 지침은 TLS/SSL mode reference 참고. `disable`로 설정하면 TLS/SSL Method와 Auth Details 옵션이 보이지 않아요.
TLS/SSL Method	TLS/SSL 인증서가 구성되는 방식을 결정해요.
- File system path	이 옵션은 Grafana가 실행되는 로컬 파일 시스템의 기존 인증서 경로를 지정해 인증서를 구성할 수 있게 해줘요. 이 파일이 Grafana 프로세스를 실행하는 사용자가 읽을 수 있는지 확인해요.
- Certificate content	이 옵션은 내용을 지정해 인증서를 구성할 수 있게 해줘요. 내용은 Grafana 데이터베이스에 암호화되어 저장돼요. 데이터베이스에 연결할 때 인증서는 Grafana 데이터 경로의 로컬 파일 시스템에 파일로 저장돼요.

TLS/SSL mode reference

보안 요구 사항과 데이터베이스가 호스팅된 위치에 따라 TLS/SSL 모드를 선택해요.

모드	암호화	서버 ID 검증	사용 시점
`disable`	아니요	아니요	로컬 개발 또는 신뢰된 프라이빗 네트워크 전용. 프로덕션에서 사용하지 말 것
`require`	예	아니요	Amazon RDS, Azure Database for PostgreSQL, Google Cloud SQL 같은 클라우드 호스팅 데이터베이스에 권장 최소값. 연결을 암호화하지만 서버 인증서를 검증하지 않음
`verify-ca`	예	CA만	서버 인증서가 신뢰된 CA가 서명했는지 확인해야 하지만 호스트 이름은 검증할 필요가 없을 때 사용
`verify-full`	예	CA + 호스트 이름	가장 안전한 옵션. CA와 서버 호스트 이름이 인증서와 일치하는지 모두 검증. 인증서를 제어할 때 프로덕션에 권장

참고: 대부분의 클라우드 호스팅 PostgreSQL 서비스(Amazon RDS, Azure Database for PostgreSQL, Google Cloud SQL)는 최소 require 모드를 요구해요. TLS/SSL Mode를 disable로 두면 서버가 연결을 거부할 수 있어요. 클라우드 공급자의 문서에서 권장 sslmode 설정을 확인하세요.

TLS/SSL 인증 세부 정보:

TLS/SSL Mode 옵션 require, verify-ca 또는 verify-full과 file system path를 선택하면 다음이 필요해요.

설정	설명
TLS/SSL Root Certificate	루트 인증서 파일 경로를 지정해요.
TLS/SSL Client Certificate	클라이언트 인증서 경로를 지정하고 파일이 Grafana 프로세스를 실행하는 사용자에게 접근 가능한지 확인해요.
TLS/SSL Client Key	클라이언트 키 파일 경로를 지정하고 파일이 Grafana 프로세스를 실행하는 사용자에게 접근 가능한지 확인해요.

TLS/SSL Mode 옵션 require와 TLS/SSL Method certificate content를 선택하면 다음이 필요해요.

설정	설명
TLS/SSL Client Certificate	클라이언트 인증서를 제공해요.
TLS/SSL Client Key	클라이언트 키를 제공해요.

TLS/SSL Mode 옵션 verify-ca 또는 verify-full와 TLS/SSL Method certificate content를 선택하면 다음이 필요해요.

설정	설명
TLS/SSL Client Certificate	클라이언트 인증서를 제공해요.
TLS/SSL Root Certificate	루트 인증서를 제공해요.
TLS/SSL Client Key	클라이언트 키를 제공해요.

PostgreSQL 옵션:

설정	설명
Version	PostgreSQL 서버 버전. 쿼리 빌더에서 사용 가능한 함수를 결정해요. 기본값은 9.3. 데이터 소스를 저장하면 Grafana가 서버 버전을 자동 감지하고 성공적으로 연결할 수 있으면 이 필드를 업데이트해요.
Min time interval	자동 group by 시간 간격의 하한을 정의해요. Grafana는 이 설정을 데이터 쓰기 빈도와 맞추는 것을 권장해요. 예를 들어 데이터가 매분 쓰이면 `1m`으로 설정해요. 형식 예시는 Min time interval 참고.
TimescaleDB	PostgreSQL 확장으로 구축된 시계열 데이터베이스. 활성화하면 Grafana가 `$__timeGroup` 매크로에서 `time_bucket`을 사용하고 쿼리 빌더에 TimescaleDB 특정 집계 함수를 표시해요. 서버가 9.6 이상이고 확장이 설치되어 있으면 Grafana는 저장 시 TimescaleDB를 자동 감지해요. 자세한 내용은 TimescaleDB documentation 참고.

연결 한도(Connection limits):

이 설정은 Grafana가 PostgreSQL 서버에 대한 연결을 관리하는 방식을 제어해요. 데이터베이스를 다른 애플리케이션과 공유하거나 PgBouncer 같은 연결 풀링 소프트웨어를 사용한다면 이 값을 조정하세요.

설정	설명
Max open	데이터베이스에 대한 최대 열린 연결 수. 기본값은 `100`. PostgreSQL 서버의 `max_connections` 한도가 낮거나 여러 Grafana 인스턴스가 같은 데이터베이스에 연결한다면 줄여요.
Auto max idle	최대 유휴 연결 수를 최대 열린 연결 수로 설정하려면 토글. 기본적으로 켜져 있어요.
Max idle	유휴 연결 풀의 최대 연결 수. 기본값은 `100`. PgBouncer나 유사한 연결 풀링 소프트웨어를 사용할 때 불필요한 연결을 잡지 않도록 낮추는 것을 고려해요.
Max lifetime	연결이 재사용될 수 있는 최대 시간(초). 기본값은 `14400`(4시간). 네트워크나 보안 정책이 주기적 재연결을 요구한다면 더 낮은 값을 설정해요.

Private data source connect:

설정	설명
Private data source connect	Grafana Cloud 사용자 전용. Private data source connect(PDC)는 Grafana Cloud 인스턴스(스택)와 프라이빗 네트워크 내에 보안된 데이터 소스 사이에 프라이빗·보안 연결을 구축할 수 있게 해줘요. 드롭다운을 클릭해 PDC URL을 찾아요. 자세한 내용은 Private data source connect (PDC) 참고.

Manage private data source connect를 클릭해 PDC 구성 세부 정보가 있는 PDC 연결 페이지로 이동해요.

Secure SOCKS proxy:

Grafana 인스턴스에 secure SOCKS proxy 기능이 활성화되어 있다면 데이터 소스 설정에 토글이 나타나요. 활성화하면 Grafana는 프라이빗 네트워크의 데이터베이스에 대한 안전한 접근을 위해 SOCKS 프록시로 PostgreSQL 연결을 라우팅해요. 자세한 내용은 Configure a Secure SOCKS5 proxy 참고.

PostgreSQL 연결 설정을 추가한 후 Save & test를 클릭해 데이터 소스 연결을 테스트하고 저장해요.

Min time interval

Min time interval 설정은 $__interval과 $__interval_ms 변수의 하한을 정의해요. 이 옵션은 대시보드 패널의 데이터 소스 설정에서도 구성하거나 재정의할 수 있어요.

이 값은 숫자 다음에 유효한 시간 식별자가 오는 형식이어야 해요.

식별자	설명
`y`	year
`M`	month
`w`	week
`d`	day
`h`	hour
`m`	minute
`s`	second
`ms`	millisecond

데이터 소스 프로비저닝

프로비저닝으로 YAML 파일에서 데이터 소스를 정의·구성할 수 있어요. 프로비저닝과 사용 가능한 구성 옵션에 대한 자세한 내용은 Provision Grafana 참고.

플러그인 ID는 grafana-postgresql-datasource예요. 이 문서의 프로비저닝 예시는 지원되는 별칭으로 남아 있는 type: postgres을 사용해요.

기본 프로비저닝 예시

다음 예시는 비밀번호 인증과 SSL 비활성화로 PostgreSQL 데이터 소스를 프로비저닝해요.

apiVersion: 1

datasources:
  - name: Postgres
    type: postgres
    url: localhost:5432
    user: grafana
    secureJsonData:
      password: 'Password!'
    jsonData:
      database: grafana
      sslmode: 'disable' # disable/require/verify-ca/verify-full
      maxOpenConns: 100
      maxIdleConns: 100
      maxIdleConnsAuto: true
      connMaxLifetime: 14400
      postgresVersion: 903 # 900=9.0 ... 906=9.6, 1000=10, 1100=11, 1200=12, 1300=13, 1400=14, 1500=15
      timescaledb: false

TLS 프로비저닝

다음 예시는 인증서의 파일 시스템 경로를 사용해 verify-full TLS 모드로 PostgreSQL 데이터 소스를 프로비저닝해요.

apiVersion: 1

datasources:
  - name: Postgres-TLS
    type: postgres
    url: db.example.com:5432
    user: grafana
    secureJsonData:
      password: '<PASSWORD>'
    jsonData:
      database: grafana
      sslmode: 'verify-full'
      tlsConfigurationMethod: 'file-path'
      sslRootCertFile: '/etc/grafana/certs/root.crt'
      sslCertFile: '/etc/grafana/certs/client.crt'
      sslKeyFile: '/etc/grafana/certs/client.key'

<PASSWORD>를 데이터베이스 비밀번호로 바꾸고 인증서 경로를 사용자 환경에 맞게 업데이트해요.

TimescaleDB 프로비저닝

다음 예시는 TimescaleDB 지원을 활성화해요.

apiVersion: 1

datasources:
  - name: Postgres-TimescaleDB
    type: postgres
    url: timescale.example.com:5432
    user: grafana
    secureJsonData:
      password: '<PASSWORD>'
    jsonData:
      database: metrics
      sslmode: 'require'
      postgresVersion: 1000
      timescaledb: true

<PASSWORD>를 데이터베이스 비밀번호로 바꿔요.

Unix 소켓 프로비저닝

다음 예시는 TCP 대신 Unix 소켓으로 연결해요.

apiVersion: 1

datasources:
  - name: Postgres-Socket
    type: postgres
    url: /var/run/postgresql
    user: grafana
    secureJsonData:
      password: '<PASSWORD>'
    jsonData:
      database: grafana
      sslmode: 'disable'

<PASSWORD>를 데이터베이스 비밀번호로 바꿔요. Unix 소켓을 사용할 때 url을 소켓 디렉토리 경로로 설정해요. 포트 번호는 포함하지 마세요.

환경 변수 프로비저닝

프로비저닝 파일에서 $__env{} 문법으로 환경 변수를 참조할 수 있어요. 이는 자격 증명을 일반 텍스트 YAML로 저장하는 것을 피할 수 있어요.

apiVersion: 1

datasources:
  - name: Postgres
    type: postgres
    url: $__env{PG_HOST}:$__env{PG_PORT}
    user: $__env{PG_USER}
    secureJsonData:
      password: $__env{PG_PASSWORD}
    jsonData:
      database: $__env{PG_DATABASE}
      sslmode: 'require'

프로비저닝 구성 참조

다음 표는 PostgreSQL 데이터 소스를 프로비저닝할 때 지원되는 모든 jsonData와 secureJsonData 필드를 나열해요.

필드	위치	설명
`database`	`jsonData`	데이터베이스 이름
`sslmode`	`jsonData`	TLS/SSL 모드: `disable`, `require`, `verify-ca`, `verify-full`
`maxOpenConns`	`jsonData`	최대 열린 연결. 기본값: `100`
`maxIdleConns`	`jsonData`	최대 유휴 연결. 기본값: `100`
`maxIdleConnsAuto`	`jsonData`	max idle을 자동으로 max open으로 설정. 기본값: `true`
`connMaxLifetime`	`jsonData`	연결 최대 수명(초). 기본값: `14400`
`postgresVersion`	`jsonData`	쿼리 빌더용 서버 버전 코드. 예: `900`(9.0), `903`(9.3), `1000`(10), `1100`(11), `1200`(12), `1300`(13), `1400`(14), `1500`(15). Grafana는 가능하면 저장 시 이를 자동 감지해요.
`timescaledb`	`jsonData`	TimescaleDB 지원을 활성화. 기본값: `false`
`timeInterval`	`jsonData`	`$__interval`과 `$__interval_ms`의 하한. Min time interval과 동일한 형식(예: `1m`)
`tlsConfigurationMethod`	`jsonData`	TLS 인증서 방법: `file-path` 또는 `file-content`
`sslRootCertFile`	`jsonData`	루트 CA 인증서 경로(`file-path` 방법 사용 시)
`sslCertFile`	`jsonData`	클라이언트 인증서 경로(`file-path` 방법 사용 시)
`sslKeyFile`	`jsonData`	클라이언트 키 경로(`file-path` 방법 사용 시)
`password`	`secureJsonData`	데이터베이스 비밀번호
`tlsCACert`	`secureJsonData`	루트 CA 인증서 내용(`file-content` 방법 사용 시)
`tlsClientCert`	`secureJsonData`	클라이언트 인증서 내용(`file-content` 방법 사용 시)
`tlsClientKey`	`secureJsonData`	클라이언트 키 내용(`file-content` 방법 사용 시)

프로비저닝 문제 해결

프로비저닝할 때 지표 요청 오류나 다른 문제가 발생하면 PostgreSQL 문제 해결 가이드의 Provisioning errors를 참고하세요.

Terraform으로 구성

Terraform과 Grafana Terraform provider로 PostgreSQL 데이터 소스를 구성할 수 있어요. Terraform으로 리소스를 프로비저닝하는 방법은 Grafana as code using Terraform 참고.

Terraform 예시

다음 예시는 기본 PostgreSQL 데이터 소스를 만들어요.

resource "grafana_data_source" "postgres" {
  name = "Postgres"
  type = "postgres"
  url  = "localhost:5432"
  user = "grafana"

  json_data_encoded = jsonencode({
    database         = "grafana"
    sslmode          = "disable"
    maxOpenConns     = 100
    maxIdleConns     = 100
    maxIdleConnsAuto = true
    connMaxLifetime  = 14400
    postgresVersion  = 903
    timescaledb      = false
  })

  secure_json_data_encoded = jsonencode({
    password = "Password!"
  })
}

사용 가능한 모든 구성 옵션은 Grafana provider data source resource documentation을 참고하세요.

다음 단계

PostgreSQL 데이터 소스를 구성한 뒤에는:

쿼리 편집기로 쿼리 작성해 데이터를 탐색·시각화
동적 재사용 대시보드를 위한 템플릿 변수 사용
패널에 PostgreSQL 이벤트를 겹치는 어노테이션 추가
PostgreSQL 데이터 기반 알림 설정(시계열 형식만)
데이터 소스 문제 시 문제 해결

더 알아보기 (Learn more)

PostgreSQL data source overview - 데이터 소스 개요
PostgreSQL query editor - 쿼리 편집기
Private data source connect - PDC 연결
Provisioning - 프로비저닝
Configure the PostgreSQL data source - 원문 문서