문제 해결 | Teleport 공식 기술 문서 한국판 by 인포그랩

문제 해결

이 가이드에서는 Teleport 클러스터에서 문제나 예기치 않은 동작을 해결하는 방법을 설명합니다.

이 단계를 사용하여 teleport 프로세스에 대한 가시성을 높이고 인증 서비스, 프록시 서비스 및 응용 프로그램 서비스와 데이터베이스 서비스와 같은 Teleport 에이전트 서비스의 문제를 해결할 수 있습니다.

전제 조건

실행 중인 Teleport 클러스터 버전 이상. Teleport를 시작하려면, 가입하기 위해 무료 평가판에 등록하거나 데모 환경 설정하기를 참조하세요.
tctl 관리 도구와 tsh 클라이언트 도구.

tctl과 tsh 다운로드에 대한 지침은 설치를 방문하세요.

당신의 Teleport 클러스터에 연결할 수 있는지 확인하려면, tsh login으로 로그인한 다음 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
클러스터  teleport.example.com
버전  16.2.0
CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
클러스터에 연결하고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 작업대에서 후속 tctl 명령어를 실행할 수 있습니다. 자신의 Teleport 클러스터를 호스팅하는 경우, Teleport 인증 서비스를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

단계 1/3. 자세한 로깅 활성화

Teleport에서 로그 수준을 변경하려면 다음 방법 중 하나를 사용할 수 있습니다:

디버그 서비스: 인스턴스를 재시작하지 않고도 실시간으로 로그 수준을 조정할 수 있으며, 문제 해결 세션에 이상적입니다.
구성 업데이트: Teleport 구성 파일을 업데이트하고 인스턴스를 재시작하는 것입니다.

Teleport 디버그 서비스는 관리자들이 인스턴스를 재시작하지 않고도 로그 수준을 동적으로 관리할 수 있게 해줍니다. 기본적으로 활성화되며, 로컬 전용 접근만 보장되며 같은 인스턴스 내부에서 소비해야합니다.

인스턴스 로그 수준을 변경하려면 teleport debug set-log-level 명령을 사용하세요:

teleport debug set-log-level DEBUG
로그 수준이 "INFO"에서 "DEBUG"로 변경되었습니다.
kubectl -n teleport exec my-pod -- teleport set-log-level DEBUG
로그 수준이 "INFO"에서 "DEBUG"로 변경되었습니다.

현재 수준을 확실히 모르는 경우, teleport debug get-log-level을 사용해 조회할 수 있습니다.

문제 해결 후에는 불필요한 로그 생성을 피하기 위해 로그 수준을 원래대로 되돌리는 것을 잊지 마세요.

텔레포트 구성 경로 지정하기

기본 경로(/etc/teleport.yaml)에 텔레포트 구성이 없으면, CLI 명령에 -c/--config 플래그를 사용하여 그 위치를 지정해야 합니다.

문제를 진단하기 위해 teleport 프로세스를 자세한 로깅이 활성화된 상태로 실행하도록 구성할 수 있습니다. -d 플래그를 전달하면 됩니다. teleport는 stderr에 로그를 기록합니다.

또는 Teleport 구성 파일에서 로그 수준을 설정할 수 있습니다:

teleport:
  log:
    severity: DEBUG

수정된 로그 수준을 적용하려면 teleport 프로세스를 재시작하세요. 로그는 다음과 유사하게 나타납니다 (이 로그는 클러스터에 서버를 조인한 후, 서버에서 teleport 프로세스를 종료하는 동안 인쇄되었습니다):

디버그 로그는 로그를 생성한 코드의 파일과 행 번호를 포함하므로 teleport 프로세스가 문제에 직면하기 전 무엇을 하고 있었는지 조사(또는 보고)하는 데 유용합니다. 예를 들면 다음과 같습니다:

DEBU [NODE:PROX] 에이전트가 프록시에 연결됨: [aee1241f-0f6f-460e-8149-23c38709e46d.tele.example.com aee1241f-0f6f-460e-8149-23c38709e46d teleport-proxy-us-west-2-6db8db844c-ftmg9.tele.example.com teleport-proxy-us-west-2-6db8db844c-ftmg9 localhost 127.0.0.1 ::1 tele.example.com 100.92.90.42 remote.kube.proxy.teleport.cluster.local]. leaseID:4 target:tele.example.com:11106 reversetunnel/agent.go:414
DEBU [NODE:PROX] 상태 변경 connecting -> connected. leaseID:4 target:tele.example.com:11106 reversetunnel/agent.go:210
DEBU [NODE:PROX] 발견 요청 채널이 열림: teleport-discovery. leaseID:4 target:tele.example.com:11106 reversetunnel/agent.go:526
DEBU [NODE:PROX] handleDiscovery 요청 채널. leaseID:4 target:tele.example.com:11106 reversetunnel/agent.go:544
DEBU [NODE:PROX] 풀에서 에이전트를 닫고 있습니다. leaseID:2 target:tele.example.com:11106 reversetunnel/agentpool.go:238
DEBU [NODE:PROX] 풀에서 에이전트를 닫고 있습니다. leaseID:3 target:tele.example.com:11106 reversetunnel/agentpool.go:238

자세한 로깅이 활성화된 상태에서 Teleport를 프로덕션 환경에서 실행하는 것은 권장되지 않습니다. 이는 상당한 양의 데이터를 생성합니다.

단계 2/3. 디버그 덤프 생성

teleport 바이너리는 Go 프로그램입니다. Go 프로그램은 고루틴이라는 추상화를 사용하여 CPU 스레드에 작업을 할당합니다. 실행 중인 teleport 프로세스에서 고루틴 덤프를 받으려면 USR1 신호를 보냅니다.

이것은 teleport 프로세스가 멈춘 것처럼 보일 때 문제 해결에 특히 유용합니다. 이는 어떤 고루틴이 차단되었는지와 그 이유를 볼 수 있기 때문입니다. 예를 들어, 고루틴은 종종 채널을 사용하여 통신하며, 고루틴 덤프는 고루틴이 채널에서 보내거나 받을 준비가 되었는지를 나타냅니다.

고루틴 덤프를 생성하려면 teleport 프로세스에 USR1 신호를 보내세요:

kill -USR1 $(pidof teleport)

Teleport는 디버그 정보를 stderr에 인쇄합니다. 로그에서 볼 수 있는 내용은 다음과 같습니다:

INFO [PROC:1]    "사용자 정의 신호 1" 신호를 받았습니다. 진단 정보를 stderr에 기록 중입니다. service/signals.go:99
런타입 통계
고루틴: 64
OS 스레드: 10
GOMAXPROCS: 2
CPU 수: 2
...
고루틴: 84
...
고루틴
고루틴 1 [실행 중]:
runtime/pprof.writeGoroutineStacks(0x3c2ffc0, 0xc0001a8010, 0xc001011a38, 0x4bcfb3)
	/usr/local/go/src/runtime/pprof/pprof.go:693 +0x9f
...

자세한 로깅을 활성화하지 않고도 고루틴 덤프를 인쇄할 수 있습니다.

단계 3/3. 도움 요청하기

자세한 로그와 고루틴 덤프를 teleport 바이너리에서 수집한 후, 이 정보를 사용하여 Teleport 커뮤니티 및 지원팀에 도움을 요청할 수 있습니다.

Teleport 버전 수집하기

조사 중인 teleport 프로세스의 버전을 확인하세요.

teleport version
Teleport v8.3.7 git:v8.3.7-0-ga8d066935 go1.17.3

반드시 Teleport 인증 서비스, 프록시 서비스, 클라이언트 도구의 버전도 확인하여 버전 호환성 문제를 확인하세요.

인증 서비스와 프록시 서비스의 버전을 보려면 다음 명령을 실행하세요:

tctl status
클러스터  mytenant.teleport.sh버전  16.1.7Host CA  업데이트되지 않음User CA  업데이트되지 않음Jwt CA   업데이트되지 않음CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

클라이언트 도구의 버전을 가져오세요:

tctl version
Teleport v9.0.4 git: go1.18tsh version
Teleport v9.0.4 git: go1.18

질문하기

질문이 있거나 도움이 필요하시면 Teleport 지원 포털을 통해 요청해 주세요.

도움이 필요하시면 커뮤니티 포럼에서 질문해 주세요. 또한 GitHub에서 이슈를 열 수 있습니다.

커스텀 기능에 대한 추가 정보나 자체 호스팅하는 엔터프라이즈 에디션을 시도하려면 영업팀에 문의해 주세요.

추가 읽기

이 가이드는 teleport 프로세스의 문제를 조사하는 방법을 보여주었습니다. Teleport 클러스터에서 더 일반적인 건강 및 성능 데이터를 모니터링하는 방법을 보려면 Teleport 진단 가이드를 읽어주세요.

Teleport 지원의 추가 출처는 Teleport 지원 및 교육 센터를 참조하세요.

일반적인 문제

`teleport.cluster.local`

teleport.cluster.local에 대한 참조를 로그 및 Teleport의 오류에서 보는 것은 일반적입니다. 이는 Teleport 내에서 두 가지 용도로 사용되는 특별한 값으로, 로그에서 이를 보는 것이 반드시 잘못된 것을 나타내는 것은 아닙니다.

우선, Teleport는 인증 서비스 및 프록시 서비스에 발급된 인증서 내에서 이 값을 사용합니다(도메인 이름 주제 대체 이름으로). Teleport 클라이언트는 클라이언트가 클러스터의 인증 기관에 대한 사본을 이미 갖고 있는 한, 서비스 주소와 관계없이 TLS 핸드셰이크 중에 서비스의 인증서를 검증하는 데 이 값을 사용할 수 있습니다. 이는 클라이언트가 인증 서비스에 연결하는 다양한 방법이 있을 수 있고, 항상 동일한 주소를 통해 연결되는 것은 아니기 때문에 중요합니다.

둘째, 클라이언트는 Teleport API에 대한 gRPC 또는 HTTP 요청을 할 때 URL의 일부로 이 값을 사용합니다. 이는 Teleport API 클라이언트가 요청을 하기 위해 인증 서비스에 연결을 열기 위한 특별한 로직을 사용하므로, 일반 클라이언트가 수행할 수 있는 단일 주소에 연결하는 것이 아닙니다. 이 특별한 로직은 클라이언트가 인증 서비스 목록에 연결할 수 있도록 하거나 프록시 서비스를 통해 인증 서비스에 연결할 수 있도록 합니다. 이는 teleport.cluster.local가 인증 서비스에 대한 요청의 URL를 표시하는 로그 메시지에 나타나며, 무엇인가 잘못 구성되었음을 명시적으로 나타내지 않습니다.

`ssh: overflow reading version string` 및/또는 `502: Bad Gateway` 오류

Teleport 버전 13.0+

TLS 라우팅에 대한 지원은 레이어 7 (HTTP/HTTPS) 로드 밸런서 및 리버스 프록시 뒤에서 Teleport 13.0부터 사용할 수 있습니다. Teleport 클러스터와 Teleport 클라이언트가 최신 상태인지 확인하세요. 문제가 지속되는 경우 GitHub 이슈를 제출해주세요.

리버스 프록시가 HTTPS를 사용하여 Teleport와 통신하고 있는지 확인해야 합니다. Kubernetes에서 Teleport를 실행하고 nginx를 인그레스로 사용하는 경우, 차트 값에 주석을 추가해야 합니다:

annotations:
  ingress:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

Cloudflare 뒤에서 Teleport를 배포할 때, 프록시("orange-clouding") 또는 터널(cloudflared)을 사용할 경우 Teleport 버전 15.1 이상이어야 합니다. 자세한 내용은 TLS 라우팅 FAQ를 참조하세요.

Teleport 버전 13.0 이전

Teleport 버전 13.0 이전에는 레이어 7 (HTTP/HTTPS) 프록시 뒤에서 Teleport의 TLS 라우팅 모드를 사용하는 것이 지원되지 않습니다. 이러한 프록시는 TLS를 자체적으로 종료하고 요청을 업스트림 서비스로 재작성하며, 이 과정에서 요청의 추가 SNI/ALPN 부분을 제거합니다.

이전 버전에서는 ALPN이 올바르게 작동하기 위해 Teleport 프록시 서비스가 TLS를 자체적으로 종료해야 합니다.

일반적으로 이것은 Teleport 버전 13.0 이전에 Teleport의 TLS 라우팅 기능이 다음과 호환되지 않음을 의미합니다:

AWS ALB(Application Load Balancers)
AWS NLB(Network Load Balancers), TLS 리스너 및 공개 ACM(Amazon Certificate Manager) 인증서를 사용하는 경우
nginx, Apache, Caddy, Traefik, HAProxy 및 기타 일반적으로 사용되는 HTTP 리버스 프록시
기본 구성의 Cloudflare 터널

HTTP 프록시 뒤에서 TLS 라우팅 모드로 Teleport를 배포하면 Teleport 웹 UI 경험이 완벽하게 작동하는 것처럼 보이지만, tsh, tctl을 사용하는 것과 클러스터에 원격 Teleport 서비스를 추가하려고 시도할 경우 ssh: overflow reading version string 및 EOF와 같은 오류로 실패할 수 있습니다. 작동하는 Teleport 웹 UI는 항상 올바르게 구성된 Teleport 클러스터의 지표가 아닙니다.

의심스러운 경우, 모든 로드 밸런서/프록시를 제거하고 Teleport 클라이언트 또는 에이전트 프로세스를 Teleport의 웹 포트에 직접 연결하여 문제를 고립시키세요.

Teleport 버전 13.0 이전에 리버스 프록시 뒤에서 Teleport를 사용하려면 다음 중 하나를 수행해야 합니다:

TCP 스트림을 Teleport에 직접 전달하는 레이어 4 (TCP) 프록시를 사용하세요 (이는 TLS 종료를 자체적으로 처리합니다).
구성 파일에 version: v1을 추가하고 proxy_listener_mode: multiplex를 제거하여 Teleport의 TLS 라우팅 모드를 비활성화하세요.

teleport configure --version=v1 --public-addr=teleport.example.com:443를 사용하여 예제 v1 구성 파일을 가져올 수 있습니다 (공개 주소는 자신의 도메인으로 변경하세요).

TLS 라우팅을 비활성화할 경우, 서로 다른 Teleport 서비스 연결에 사용할 기본 포트 목록을 참조하세요.

Teleport 원문 보기