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

문제 해결

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

이 단계를 사용하여 teleport 프로세스에 대한 가시성을 높이고 Auth Service, Proxy Service 및 Application Service, Database Service와 같은 Teleport 에이전트 서비스를 문제 해결할 수 있습니다.

전제 조건

실행 중인 Teleport 클러스터 버전 17.0.0-dev 이상. Teleport를 시작하려면 가입하여 무료 평가판을 이용하거나 데모 환경 설정 방법을 확인하십시오.
tctl 관리자 도구와 tsh 클라이언트 도구.

tctl 및 tsh 다운로드 방법에 대한 지침은 설치를 방문하십시오.

연결이 가능한지 확인하기 위해 tsh login 으로 로그인한 다음, 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
클러스터  teleport.example.com
버전  17.0.0-dev
CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
클러스터에 연결할 수 있고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 후속 tctl 명령어를 실행할 수 있습니다.
자신의 Teleport 클러스터를 호스팅하는 경우, Teleport Auth Service를 호스팅하는 컴퓨터에서 전체 권한으로 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 )에 텔레포트 구성이 배치되어 있지 않은 경우, -c/--config 플래그를 사용하여 CLI 명령에 그 위치를 지정해야 합니다.

문제를 진단하려면 -d 플래그를 전달하여 자세한 로깅이 활성화된 상태로 teleport 프로세스를 실행할 수 있습니다. 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] Discovery 요청 채널이 열림: 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 프로그램은 goroutine 이라는 추상화를 사용하여 CPU 스레드에 작업을 할당합니다. 실행 중인 teleport 프로세스의 goroutine 덤프를 생성하려면 USR1 신호를 보내야 합니다.

이는 막힌 것처럼 보이는 teleport 프로세스를 문제 해결하는 데 특히 유용합니다. 왜냐하면 어떤 goroutine이 차단되었는지와 그 이유를 알 수 있기 때문입니다. 예를 들어, goroutine은 종종 채널을 사용하여 통신하며, goroutine 덤프는 goroutine이 채널에서 송신하거나 수신을 대기하고 있는지를 나타냅니다.

goroutine 덤프를 생성하려면, teleport 프로세스에 USR1 신호를 보내십시오:

kill -USR1 $(pidof teleport)

Teleport는 디버그 정보를 stderr 에 출력합니다. 로그에서 다음과 같은 내용이 표시됩니다:

INFO [PROC:1]    Got signal "user defined signal 1", logging diagnostic info to stderr. service/signals.go:99
Runtime stats
goroutines: 64
OS threads: 10
GOMAXPROCS: 2
num CPU: 2
...
goroutines: 84
...
Goroutines
goroutine 1 [running]:
runtime/pprof.writeGoroutineStacks(0x3c2ffc0, 0xc0001a8010, 0xc001011a38, 0x4bcfb3)
	/usr/local/go/src/runtime/pprof/pprof.go:693 +0x9f
...

자세한 로깅을 활성화하지 않고도 goroutine 덤프를 출력할 수 있습니다.

3/3단계. 도움 요청

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

Teleport 버전 수집

조사 중인 teleport 프로세스의 버전을 결정하십시오.

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

Teleport Auth Service, Proxy Service 및 클라이언트 도구의 버전도 수집하여 버전 호환성 문제를 확인할 수 있습니다.

Auth Service와 Proxy Service의 버전을 보려면 다음 명령을 실행하십시오:

tctl status
Cluster  mytenant.teleport.shVersion  16.4.3Host CA  never updatedUser CA  never updatedJwt CA   never updatedCA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

클라이언트 도구의 버전을 가져옵니다:

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

질문하기

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

도움이 필요하시면 커뮤니티 포럼에서 문의해 주십시오. GitHub에 이슈를 열어주셔도 됩니다.

엔터프라이즈 기능에 대한 더 많은 정보는 Teleport 영업 팀에 문의해 주십시오. Teleport Enterprise의 무료 체험판에도 등록할 수 있습니다.

추가 읽기

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

추가적인 Teleport 지원 소스는 Teleport 지원 및 교육 센터를 참조하시기 바랍니다.

일반적인 문제

`teleport.cluster.local`

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

첫째, Teleport는 Auth 및 Proxy 서비스에 발급된 인증서 내에서 (DNS Subject Alternative Name으로서) 이 값을 사용합니다. Teleport 클라이언트는 클러스터의 인증 기관 사본을 이미 가지고 있는 한 서비스 주소와 관계없이 TLS 핸드쉐이크 중에 서비스의 인증서를 검증하기 위해 이 값을 사용할 수 있습니다. 이는 클라이언트가 Auth 서비스에 연결할 수 있는 여러 가지 방법이 존재하기 때문에 중요합니다. 이들은 항상 동일한 주소를 통해 이루어지지 않습니다.

둘째, 이 값은 클라이언트가 Teleport API에 대한 gRPC 또는 HTTP 요청을 할 때 URL의 일부로 사용됩니다. 이는 Teleport API 클라이언트가 요청을 하기 위해 Auth 서비스에 연결을 여는 특별한 논리를 사용하기 때문입니다. 일반 클라이언트가 단일 주소에 연결하는 것과는 다릅니다. 이 특별한 논리는 클라이언트가 Auth 서비스 목록에 연결하거나 Proxy 서비스를 통해 Auth 서비스에 터널을 통해 연결할 수 있도록 지원하는 데 필요합니다. 이는 Auth 서비스에 대한 요청의 URL을 표시하는 로그 메시지에 teleport.cluster.local 이 나타나며, 잘못 구성되었다는 것을 명시적으로 나타내지 않음을 의미합니다.

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

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

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

Cloudflare 뒤에 Teleport를 배포할 때, 그의 프록시("오렌지 클라우딩")를 사용하든지 또는 터널(cloudflared )을 사용하든지 상관없이 Teleport 버전 15.1 이상에서 작동해야 합니다. 더 자세한 내용은 TLS Routing FAQ를 참조하십시오.

Teleport 원문 보기