문제 해결
이 가이드에서는 Teleport 클러스터에서 발생하는 문제 또는 예상치 못한 동작을 해결하는 방법을 설명합니다. 이 단계들을 사용하여 teleport 프로세스에 대한 더 많은 가시성을 확보하고 Auth Service, Proxy Service, Application Service 및 Database Service와 같은 Teleport 에이전트 서비스를 문제 해결할 수 있습니다.
이 가이드에서는 Teleport 클러스터에서 발생하는 문제 또는 예상치 못한 동작을 해결하는 방법을 설명합니다.
이 단계들을 사용하여 teleport 프로세스에 대한 더 많은 가시성을 확보하고 Auth Service, Proxy Service, Application Service 및 Database Service와 같은 Teleport 에이전트 서비스를 문제 해결할 수 있습니다.
작동 방식#
Teleport 프로세스는 내부 작업에 대한 데이터를 수집하는 데 사용할 수 있는 여러 방법을 노출합니다:
- Debug Service: Teleport 프로세스 내에서 실행되며 사용자가 인스턴스를 재시작하지 않고도 Teleport 인스턴스의 로그 수준을 변경할 수 있게 하는 서비스.
- 상세 로깅: 구성 파일을 사용하여 Teleport 프로세스의 로그 수준을 변경할 수 있습니다.
- 디버그 덤프: Teleport는 Go 프로그램입니다. Go 런타임은 goroutine이라는 추상화를 사용하여 CPU 스레드 내에서 작업을 스케줄링하며, 실행 중인 각 goroutine에 대한 정보가 담긴 파일을 생성할 수 있습니다.
추가 정보는 Teleport 팀이나 커뮤니티에 도움을 요청할 수 있습니다.
사전 요구사항#
-
A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.
-
The
tctlandtshclients.Installing `tctl` and `tsh` clients
-
Determine the version of your Teleport cluster. The
tctlandtshclients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at/v1/webapi/findand use a JSON query tool to obtain your cluster version. Replace with the web address of your Teleport Proxy Service:$ TELEPORT_DOMAIN= $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" -
Follow the instructions for your platform to install
tctlandtshclients:
-
To check that you can connect to your Teleport cluster, sign in with tsh login, then
verify that you can run tctl commands using your current credentials.
For example, run the following command, assigning to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:
$ tsh login --proxy= --user=
$ tctl status
# Cluster (=teleport.url=)
# Version (=teleport.version=)
# CA pin (=presets.ca_pin=)
If you can connect to the cluster and run the tctl status command, you can use your
current credentials to run subsequent tctl commands from your workstation.
If you host your own Teleport cluster, you can also run tctl commands on the computer that
hosts the Teleport Auth Service for full permissions.
1단계/3단계: 상세 로깅 활성화#
Teleport에서 로그 수준을 변경하려면 다음 방법 중 하나를 사용할 수 있습니다:
- Debug Service: 인스턴스를 재시작하지 않고 즉석에서 로그 수준을 조정할 수 있어 문제 해결 세션에 이상적입니다.
- 구성 업데이트: Teleport 구성 파일을 업데이트하고 인스턴스를 재시작하는 방법입니다.
Debug Service 방법:
Teleport Debug Service는 관리자가 인스턴스를 재시작하지 않고도 로그 수준을 동적으로 관리할 수 있게 합니다. 기본적으로 활성화된 이 서비스는 로컬 전용 접근을 보장하며 동일한 인스턴스 내부에서 사용해야 합니다.
인스턴스 로그 수준을 변경하려면 teleport debug set-log-level 명령을 사용합니다.
Linux 서버에서 다음 명령을 실행합니다:
$ teleport debug set-log-level DEBUG
Changed log level from "INFO" to "DEBUG".
Kubernetes에서 Teleport 클러스터를 실행하는 경우 kubectl을 사용합니다:
$ kubectl -n teleport exec my-pod -- teleport debug set-log-level DEBUG
Changed log level from "INFO" to "DEBUG".
현재 수준을 확인하려면 teleport debug get-log-level을 사용할 수 있습니다.
문제 해결 후에는 불필요한 로그 생성을 방지하기 위해 로그 수준을 다시 원래대로 돌리는 것을 잊지 마세요.
구성 업데이트 방법:
문제를 진단하기 위해 -d 플래그를 전달하여 teleport 프로세스를 상세 로깅 활성화 상태로 실행하도록 구성할 수 있습니다. teleport는 stderr에 로그를 씁니다.
또는 Teleport 구성 파일에서 로그 수준을 설정할 수 있습니다:
teleport:
log:
severity: DEBUG
Kubernetes에서 teleport-cluster Helm 차트로 클러스터를 실행하는 경우 값 파일을 다음과 같이 편집하고 릴리즈를 업데이트합니다:
log:
level: DEBUG
수정된 로그 수준을 적용하려면 teleport 프로세스를 재시작합니다.
디버그 로그는 로그를 발생시킨 코드의 파일과 줄 번호를 포함하므로 teleport 프로세스가 문제에 부딪히기 전에 무엇을 하고 있었는지 조사(또는 보고)할 수 있습니다. 다음은 예시입니다:
DEBU [NODE:PROX] Agent connected to proxy: [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] Changing state connecting -> connected. leaseID:4 target:tele.example.com:11106 reversetunnel/agent.go:210
DEBU [NODE:PROX] Discovery request channel opened: teleport-discovery. leaseID:4 target:tele.example.com:11106 reversetunnel/agent.go:526
DEBU [NODE:PROX] handleDiscovery requests channel. leaseID:4 target:tele.example.com:11106 reversetunnel/agent.go:544
DEBU [NODE:PROX] Pool is closing agent. leaseID:2 target:tele.example.com:11106 reversetunnel/agentpool.go:238
DEBU [NODE:PROX] Pool is closing agent. leaseID:3 target:tele.example.com:11106 reversetunnel/agentpool.go:238
경고: 상세 로깅을 활성화한 상태로 프로덕션에서 Teleport를 실행하는 것은 권장하지 않습니다. 많은 양의 데이터가 생성됩니다.
2단계/3단계: 디버그 덤프 생성#
teleport 바이너리는 Go 프로그램입니다. Go 프로그램은 goroutine이라는 추상화를 사용하여 CPU 스레드에 작업을 할당합니다. teleport 프로세스가 실행 중인 머신에 접근할 수 있는 경우 USR1 신호를 전송하여 프로세스의 goroutine 덤프를 얻을 수 있습니다.
이는 goroutine이 차단된 위치와 이유를 볼 수 있어 멈춘 것처럼 보이는 teleport 프로세스를 문제 해결하는 데 특히 유용합니다. 예를 들어 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
또는 Kubernetes에서 다음을 사용합니다:
$ kubectl -n teleport exec my-pod -- teleport version
버전 호환성 문제를 배제하기 위해 Teleport Auth Service, Proxy Service 및 클라이언트 도구의 버전도 수집할 수 있습니다.
Auth Service와 Proxy Service의 버전을 확인하려면 다음 명령을 실행합니다:
$ tctl status
Cluster mytenant.teleport.sh
Version (=cloud.version=)
Host CA never updated
User CA never updated
Jwt CA never updated
CA pin (=presets.ca_pin=)
클라이언트 도구의 버전을 확인합니다:
$ tctl version
Teleport v9.0.4 git: go1.18
$ tsh version
Teleport v9.0.4 git: go1.18
질문하기#
상용 Teleport 에디션 (Cloud, Enterprise, Team):
질문이 있거나 도움이 필요하면 Teleport 지원 포털을 통해 요청을 제출하세요.
Teleport Community Edition:
도움이 필요하면 커뮤니티 포럼에 질문하세요. GitHub에서 이슈를 열 수도 있습니다.
Enterprise 기능에 대한 자세한 내용은 Teleport 영업팀에 문의하세요. Teleport Enterprise의 무료 체험에 가입할 수도 있습니다.
추가 자료#
이 가이드는 teleport 프로세스의 문제를 조사하는 방법을 보여주었습니다. Teleport 클러스터에서 보다 일반적인 상태 및 성능 데이터를 모니터링하는 방법은 Teleport 진단 가이드를 참조하세요.
Teleport 지원의 추가 소스는 Teleport 지원 및 교육 센터를 참조하세요.
일반적인 문제#
teleport.cluster.local#
Teleport의 로그와 오류에서 teleport.cluster.local에 대한 참조를 자주 볼 수 있습니다. 이는 Teleport 내에서 두 가지 목적으로 사용되는 특수 값으로, 로그에서 이를 보더라도 반드시 잘못된 것이 있다는 표시는 아닙니다.
첫째, Teleport는 Auth Service와 Proxy Service에 발행된 인증서(DNS Subject Alternative Name으로)에 이 값을 사용합니다. 그러면 Teleport 클라이언트는 서비스 주소에 관계없이 클러스터의 인증 기관 사본을 이미 갖고 있는 경우 TLS 핸드셰이크 중에 서비스의 인증서를 검증하는 데 이 값을 사용할 수 있습니다. 이는 클라이언트가 Auth Service에 연결하는 방법이 여러 가지 있는 경우가 많고 항상 동일한 주소를 통하는 것이 아니기 때문에 중요합니다.
둘째, 이 값은 Teleport API에 gRPC 또는 HTTP 요청을 할 때 URL의 일부로 클라이언트에서 사용됩니다. 이는 Teleport API 클라이언트가 일반적인 클라이언트처럼 단일 주소에 연결하는 대신 Auth Service에 대한 연결을 열기 위한 특수 로직을 사용하기 때문입니다. 이 특수 로직은 클라이언트가 Auth Service 인스턴스 목록에 연결하거나 Proxy Service를 통한 터널을 통해 Auth Service에 연결하는 것을 지원할 수 있도록 필요합니다. 이는 teleport.cluster.local이 Auth Service에 대한 요청의 URL을 보여주는 로그 메시지에 나타나며 뭔가 잘못 구성되었다는 것을 명시적으로 나타내는 것이 아님을 의미합니다.
ssh: overflow reading version string 및/또는 502: Bad Gateway 오류#
You must ensure that your reverse proxy is communicating with Teleport using HTTPS. When running Teleport in Kubernetes and using nginx as an ingress, this requires adding an annotation to the chart values:
annotations:
ingress:
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
Deploying Teleport behind Cloudflare, whether using its proxy ("orange-clouding") or tunnels
(cloudflared) should work. See the TLS Routing FAQ for more details.
