이 문서는 데이터베이스 상태 검사 관리 방법을 설명합니다. Teleport 18에서 사용 가능한 데이터베이스 상태 검사는 Teleport Database Service 인스턴스에서 Teleport 클러스터에 등록된 데이터베이스로의 연결을 모니터링하는 데 사용됩니다.

상태 검사로 데이터베이스 연결을 모니터링하는 이유는 무엇인가요?

• 관찰 가능성: 사용자가 데이터베이스에 연결을 시도하기 전에 네트워킹 문제를 발견합니다. 비정상 데이터베이스는 Teleport 웹 UI에서 강조 표시되며 Teleport 클러스터의 API를 통해 프로그래밍 방식으로 발견할 수 있습니다.
• 고가용성: 여러 Teleport Database Service 인스턴스를 배포하여 동일한 등록 데이터베이스에 대한 연결을 프록시할 수 있습니다. Teleport는 데이터베이스 엔드포인트에 도달할 수 없는 인스턴스보다 도달할 수 있는 Database Service 인스턴스를 통해 사용자 연결을 우선적으로 라우팅합니다.

동작 원리#

사용자가 Teleport를 통해 데이터베이스에 연결하면 연결이 Teleport Database Service를 통해 라우팅됩니다. Database Service는 연결을 프록시하기 위해 데이터베이스의 엔드포인트에 도달할 수 있어야 합니다.

Teleport Database Service 인스턴스는 전역 health_check_config 리소스의 레이블 선택기와 일치하는 데이터베이스에 대해 정기적인 상태 검사를 수행합니다. 데이터베이스와 일치하는 health_check_config가 없으면 해당 데이터베이스에 대한 상태 검사가 활성화되지 않습니다.

상태 검사를 수행하기 위해 Teleport Database Service 인스턴스는 데이터베이스의 엔드포인트에 TCP 연결을 설정하고 연결 성공 여부를 보고하려고 합니다.

데이터베이스가 등록되면 처음에는 "unknown" 상태가 됩니다. 상태 검사가 비활성화되면 상태는 "unknown"으로 유지됩니다. 상태 검사가 활성화되면 첫 번째 상태 검사 결과가 데이터베이스의 상태를 결정합니다: "healthy" 또는 "unhealthy".

데이터베이스에 대한 첫 번째 상태 검사 후에는 연속으로 통과하거나 실패하는 상태 검사 수가 구성 가능한 임계값에 도달할 때만 상태가 변경됩니다.

구성#

Teleport의 health_check_config 리소스는 어떤 데이터베이스에 상태 검사가 활성화되는지와 이러한 검사에 사용될 설정을 결정합니다:

kind: health_check_config
version: v1
metadata:
  name: example
  description: 상태 검사 구성 예시
spec:
  # interval은 각 상태 검사 사이의 시간입니다. 기본값 30s.
  interval: 30s
  # timeout은 상태 검사 연결 설정 타임아웃입니다. 기본값 5s.
  timeout: 5s
  # healthy_threshold는 대상의 상태가 "healthy"가 되는 연속 통과 상태 검사 수입니다. 기본값 2.
  healthy_threshold: 2
  # unhealthy_threshold는 대상의 상태가 "unhealthy"가 되는 연속 실패 상태 검사 수입니다. 기본값 1.
  unhealthy_threshold: 1
  # match는 이러한 설정이 적용되는 데이터베이스를 선택하는 데 사용됩니다.
  # 데이터베이스는 레이블 선택기로 매칭되며 적어도 하나의 레이블 선택기가 설정되어야 합니다.
  # 동일한 데이터베이스와 여러 `health_check_config`가 일치하면
  # 일치하는 상태 검사 구성이 이름으로 정렬되며 첫 번째 구성만 적용됩니다.
  match:
    # db_labels는 데이터베이스 레이블과 매칭됩니다. 빈 값은 무시됩니다.
    # db_labels_expression도 설정된 경우 매칭 결과는 두 값의 논리 AND입니다.
    db_labels:
      - name: env
        values:
          - dev
          - staging
    # db_labels_expression은 데이터베이스를 매칭하기 위한 레이블 술어 표현식입니다.
    # 빈 값은 무시됩니다.
    # db_labels도 설정된 경우 매칭 결과는 두 값의 논리 AND입니다.
    db_labels_expression: 'labels["owner"] == "database-team"'

클러스터에 여러 health_check_config가 있을 수 있으며 각 구성은 다양한 데이터베이스 세트에 대해 다른 설정을 제공할 수 있습니다. 동일한 데이터베이스와 두 개 이상의 health_check_config가 일치하면 일치하는 상태 검사 구성이 이름으로 오름차순으로 정렬되며 첫 번째 구성만 적용됩니다(예: 이름 "00-my-config"은 "10-my-config"보다 높은 우선순위를 가짐).

구성 관리#

클러스터에서 health_check_config 리소스를 관리하기 위해 tctl을 사용합니다.

기본 사전 설정 health_check_config는 Teleport 18부터 생성됩니다. 기본 구성은 모든 등록된 데이터베이스에 대한 TCP 상태 검사를 활성화합니다.

tctl로 기본 구성을 확인해 보십시오:

$ tctl get health_check_config/default
kind: health_check_config
metadata:
  description: Enables all health checks by default
  labels:
    teleport.internal/resource-type: preset
  name: default
  namespace: default
spec:
  match:
    db_labels:
    - name: '*'
      values:
      - '*'
version: v1

tctl create로 직접 상태 검사 구성을 만들 수 있습니다:

$ tctl create health_check_config.yaml

또는 tctl edit로 기존 구성을 대화형으로 업데이트합니다:

$ tctl edit health_check_config/example

상태 검사 구성을 삭제하려면 실행합니다:

$ tctl rm health_check_config/example

구성이 생성, 업데이트 또는 삭제되면 모든 Teleport Database Service 인스턴스가 프록시하는 각 등록 데이터베이스에 대해 어떤 상태 검사 구성이 일치하고 적용되는지 재평가합니다.

대상 상태#

대상 상태 정보는 Teleport Database Service 인스턴스가 프록시하는 각 데이터베이스에 대한 db_server 하트비트 객체에서 보고됩니다. 정보 중에는 상태 필드가 있습니다. 세 가지 상태가 있습니다:

• "unknown": 이 데이터베이스에 대한 상태 검사가 비활성화되었거나 아직 초기화 중입니다
• "healthy": Teleport 서비스가 데이터베이스의 엔드포인트에 도달할 수 있습니다.
• "unhealthy": Teleport 서비스가 데이터베이스의 엔드포인트에 도달할 수 없습니다.

tctl을 사용하여 예를 들어 db_server.status.target_health에서 대상 상태 정보를 볼 수 있습니다:

$ tctl get db_server/example-postgres-db | yq -y .status
target_health:
  # address는 데이터베이스 주소입니다.
  address: "localhost:5432",
  # message는 사용자를 위한 추가 정보입니다.
  message: "1 health check failed"
  # protocol은 상태 검사 연결 프로토콜입니다(예: "TCP").
  protocol: "TCP",
  # status는 상태 값으로 "unknown", "healthy" 또는 "unhealthy" 중 하나입니다.
  status: "unhealthy",
  # transition_reason은 마지막 전환에 대한 고유한 이유입니다: "initialized", "disabled", "threshold_reached" 또는 "internal_error" 중 하나.
  transition_reason: "threshold_reached",
  # transition_timestamp는 마지막 상태 전환이 발생한 시간입니다.
  transition_timestamp: "2025-06-09T22:40:24.147753Z",
  # transition_error는 "unhealthy"로 전환될 때 관찰된 상태 검사 오류를 보여줍니다.
  transition_error: "dial tcp 127.0.0.1:5432: connect: connection refused",

문제 해결#

Teleport 웹 UI는 비정상 데이터베이스를 강조 표시합니다. 강조 표시된 데이터베이스를 클릭하면 상태 검사 실패 세부 정보 또는 기타 경고를 볼 수 있습니다:

이 AWS RDS 데이터베이스 예시에서 상태 검사 오류는 연결 다이얼 타임아웃으로, 이는 일반적으로 AWS 보안 그룹이 데이터베이스에 대한 연결을 차단하는 경우 발생합니다.

tctl을 사용하여 영향받은 Teleport Database Service에 대한 자세한 정보를 볼 수 있습니다. 예를 들어, 스크린샷의 영향받은 Teleport Database Service 인스턴스는 Teleport AWS RDS 등록 마법사를 사용하여 배포되었으며, teleport.dev/awsoidc-agent 레이블로 표시됩니다:

$ tctl get db_service/22c8ecba-69fc-4c15-b94e-e8815236b9f0
kind: db_service
metadata:
  expires: "2025-06-29T03:55:52Z"
  labels:
    teleport.dev/awsoidc-agent: "true"
  name: 22c8ecba-69fc-4c15-b94e-e8815236b9f0
  revision: 089129ef-52e2-4a8f-8451-c1e91879c14e
spec:
  hostname: ip-192-168-0-107.ca-central-1.compute.internal
  resources:
  - aws: {}
    labels:
      account-id: "111111111111"
      region: ca-central-1
      vpc-id: vpc-abc123abc123abc12
version: v1

일반적인 문제 해결 단계는 Database Service 문제 해결 가이드를 참조하십시오.

FAQ#

MySQL 상태 검사가 비활성화된 이유는 무엇인가요?#

MySQL은 데이터베이스에 연결하려는 각 원격 호스트에 대한 연결 오류를 추적합니다. 각 TCP 상태 검사는 연결 오류로 계산되며 결국 sum_connect_errors >= max_connect_errors에 도달하면 MySQL이 호스트를 차단합니다. 결과적으로 TCP 상태 검사는 결국 MySQL 데이터베이스가 Teleport를 차단하게 합니다.

TCP 상태 검사를 다시 활성화하려면:

• 데이터베이스에서 max_connect_errors를 최대값으로 설정하여 자동 호스트 차단을 효과적으로 비활성화합니다.
• Teleport Database Service 인스턴스에 환경 변수 TELEPORT_ENABLE_MYSQL_DB_HEALTH_CHECKS=1을 설정합니다.

데이터베이스 상태 검사를 비활성화하는 방법은?#

클러스터의 health_check_config 리소스를 업데이트하여 특정 데이터베이스만 매칭하도록 하여 데이터베이스 상태 검사를 비활성화할 수 있습니다.

예를 들어, "healthcheck": "enabled" 레이블이 있는 데이터베이스만 매칭하도록 기본 사전 설정 구성을 업데이트합니다:

$ tctl create <

$ tctl db ls --query 'health.status == "unhealthy"'