API 시작 가이드

요약

이 시작 가이드에서는 Teleport API Go 클라이언트를 사용하여 Teleport Auth 서비스에 연결합니다. Teleport Auth 서비스는 클라이언트 도구가 백엔드 리소스를 관리할 수 있게 해주는 gRPC API를 제공합니다.

이 시작 가이드에서는 Teleport API Go 클라이언트를 사용하여 Teleport Auth 서비스에 연결합니다.

진행할 단계:

간단한 역할 기반 인증 방법을 사용하여 API 사용자 생성
해당 사용자의 자격 증명 생성
Teleport의 API와 상호작용할 Go 클라이언트 생성 및 연결

작동 방식#

Teleport Auth 서비스는 클라이언트 도구가 백엔드 리소스를 관리할 수 있게 해주는 gRPC API를 제공합니다. tctl, Teleport Kubernetes 오퍼레이터, Teleport Terraform 프로바이더는 이 API를 사용하며, API 리소스를 관리하거나 Teleport 감사 이벤트를 구독하는 커스텀 도구를 작성할 수 있습니다.

Teleport API 클라이언트는 TLS 자격 증명을 사용하여 Teleport에 인증합니다. 이 가이드에서는 tsh로 로그인한 후 Auth 서비스가 제공하는 TLS 자격 증명을 로드하는 방법을 보여줍니다.

사전 요구 사항#

Go [teleport.golang]+ 및 Go 개발 환경 설치
실행 중인 Teleport 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.
tctl and tsh clients.
Installing `tctl` and `tsh` clients
1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:
```
$ TELEPORT_DOMAIN=teleport.example.com:443
$ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
```
2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.

Warning

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```

Teleport cluster에 연결할 수 있는지 확인하려면 tsh login으로 로그인한 다음, 현재 자격 증명으로 tctl 명령을 실행할 수 있는지 확인합니다.

예를 들어, teleport.example.com에 cluster 내 Teleport Proxy Service의 도메인 이름을, email@example.com에 Teleport 사용자 이름을 지정하여 다음 명령을 실행합니다:

$ tsh login --proxy=teleport.example.com --user=email@example.com
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

cluster에 연결하여 tctl status 명령을 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 이후의 tctl 명령을 실행할 수 있습니다. 자체 Teleport cluster를 호스팅하는 경우, 전체 권한을 얻기 위해 Teleport Auth Service를 호스팅하는 컴퓨터에서 tctl 명령을 실행할 수도 있습니다.

1/3단계. 사용자 생성#

프로덕션 보안 모범 사례

Teleport를 프로덕션 환경에서 실행할 때는 보안 사고를 방지하기 위해 다음 모범 사례를 준수해야 합니다:

꼭 필요한 경우가 아니면 프로덕션 환경에서 sudo 사용을 피하십시오.
새로운 non-root 사용자를 생성하고, Teleport를 테스트할 때는 테스트 인스턴스를 사용하십시오.
필요한 경우가 아니면 Teleport의 서비스를 non-root 사용자로 실행하십시오. root 접근이 필요한 것은 SSH Service뿐입니다. Teleport가 1024보다 작은 번호의 포트(예: 443)에서 수신 대기하도록 하려면 root 권한(또는 CAP_NET_BIND_SERVICE 기능)이 필요하다는 점에 유의하십시오.
최소 권한의 원칙을 따르십시오. 더 제한적인 역할로 충분한 경우 사용자에게 허용 범위가 넓은 역할을 부여하지 마십시오. 예를 들어, 모든 클러스터 리소스에 접근하고 편집할 수 있는 권한을 부여하는 내장 access,editor 역할을 사용자에게 할당하지 마십시오. 대신 각 사용자에게 필요한 최소한의 권한으로 역할을 정의하고, 일시적으로 상승된 권한을 제공하기 위해 Access Request를 구성하십시오.
Teleport 리소스(예: 새 데이터베이스나 애플리케이션)를 등록할 때는 초대 토큰을 파일에 저장해야 합니다. 토큰을 명령줄에 직접 입력하면, 악의적인 사용자가 침해된 시스템에서 history 명령을 실행하여 이를 볼 수 있습니다.

이러한 사례가 문서에서 사용된 예시에 반드시 반영되어 있는 것은 아니라는 점에 유의하십시오. 문서의 예시는 주로 시연 및 개발 환경을 위한 것입니다.

팁: API 클라이언트의 커스텀 역할 정의에 대해 자세히 알아보려면 API 권한 부여를 읽으세요.

내장 역할 editor를 가진 사용자 api-admin을 생성합니다:

$ tctl users add api-admin --roles=editor

2/3단계. 클라이언트 자격 증명 생성#

tsh로 새로 생성된 사용자로 로그인합니다.

# tsh 프로파일 생성
$ tsh login --user=api-admin --proxy=tele.example.com

프로파일 자격 증명 로더는 다음 단계에서 현재 프로파일의 자격 증명을 자동으로 가져옵니다.

3/3단계. Go 프로젝트 생성#

새 Go 모듈을 설정하고 client 패키지를 임포트합니다:

$ mkdir client-demo && cd client-demo
$ go mod init client-demo
$ go get github.com/gravitational/teleport/api/client

API 버전: 호환성을 보장하려면 클러스터에서 실행 중인 Teleport의 주요 버전과 일치하는 Teleport API 라이브러리 버전을 사용해야 합니다.

특정 git 태그에 대해 go.mod 파일에 적합한 의사 버전을 찾으려면 teleport 저장소에서 다음 명령을 실행합니다:
$ go list -f '{}' -m "github.com/gravitational/teleport/api@$(git rev-parse v12.1.0)"
v0.0.0-20230307032901-49a6de744a3a

필요에 따라 Addrs 문자열을 수정하여 main.go 파일을 생성합니다:

package main

import (
	"context"
	"log"

	"github.com/gravitational/teleport/api/client"
)

func main() {
	ctx := context.Background()

	clt, err := client.New(ctx, client.Config{
		Addrs: []string{
			// Teleport Cloud 고객은 <tenantname>.teleport.sh 사용
			"tele.example.com:443",
			"tele.example.com:3025",
			"tele.example.com:3024",
			"tele.example.com:3080",
 		},
		Credentials: []client.Credentials{
			client.LoadProfile("", ""),
		},
	})

	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}

	defer clt.Close()
	resp, err := clt.Ping(ctx)
	if err != nil {
		log.Fatalf("failed to ping server: %v", err)
	}

	log.Printf("Example success!")
	log.Printf("Example server response: %v", resp)
	log.Printf("Server version: %s", resp.ServerVersion)
}

이제 프로그램을 실행하고 클라이언트를 Teleport Auth 서비스에 연결하여 서버 버전을 가져올 수 있습니다.

$ go run main.go

다음 단계#

pkg.go.dev에 대해 알아보기
클라이언트 사용법 알아보기
자격 증명 작업 방법 알아보기
API 및 API 클라이언트에 대한 심층적인 개요는 API 아키텍처를 읽으세요.
API 클라이언트의 커스텀 역할 정의에 대해 자세히 알아보려면 API 권한 부여를 읽으세요.
프로그래밍 방식으로 Teleport API 작업에 대한 자세한 내용은 client pkg.go 참조 문서를 검토하세요.
API를 최대한 활용하려면 관리 매뉴얼을 숙지하세요.

API 시작 가이드

Teleport v18.9

원문 보기

번역일: 2026-04-04

요약

이 시작 가이드에서는 Teleport API Go 클라이언트를 사용하여 Teleport Auth 서비스에 연결합니다.

진행할 단계:

간단한 역할 기반 인증 방법을 사용하여 API 사용자 생성
해당 사용자의 자격 증명 생성
Teleport의 API와 상호작용할 Go 클라이언트 생성 및 연결

작동 방식#

사전 요구 사항#

Go [teleport.golang]+ 및 Go 개발 환경 설치
실행 중인 Teleport 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.
tctl and tsh clients.
Installing `tctl` and `tsh` clients
1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:
```
$ TELEPORT_DOMAIN=teleport.example.com:443
$ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
```
2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.

Warning

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```

Teleport cluster에 연결할 수 있는지 확인하려면 tsh login으로 로그인한 다음, 현재 자격 증명으로 tctl 명령을 실행할 수 있는지 확인합니다.

예를 들어, teleport.example.com에 cluster 내 Teleport Proxy Service의 도메인 이름을, email@example.com에 Teleport 사용자 이름을 지정하여 다음 명령을 실행합니다:

$ tsh login --proxy=teleport.example.com --user=email@example.com
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

1/3단계. 사용자 생성#

프로덕션 보안 모범 사례

Teleport를 프로덕션 환경에서 실행할 때는 보안 사고를 방지하기 위해 다음 모범 사례를 준수해야 합니다:

꼭 필요한 경우가 아니면 프로덕션 환경에서 sudo 사용을 피하십시오.
새로운 non-root 사용자를 생성하고, Teleport를 테스트할 때는 테스트 인스턴스를 사용하십시오.
필요한 경우가 아니면 Teleport의 서비스를 non-root 사용자로 실행하십시오. root 접근이 필요한 것은 SSH Service뿐입니다. Teleport가 1024보다 작은 번호의 포트(예: 443)에서 수신 대기하도록 하려면 root 권한(또는 CAP_NET_BIND_SERVICE 기능)이 필요하다는 점에 유의하십시오.
최소 권한의 원칙을 따르십시오. 더 제한적인 역할로 충분한 경우 사용자에게 허용 범위가 넓은 역할을 부여하지 마십시오. 예를 들어, 모든 클러스터 리소스에 접근하고 편집할 수 있는 권한을 부여하는 내장 access,editor 역할을 사용자에게 할당하지 마십시오. 대신 각 사용자에게 필요한 최소한의 권한으로 역할을 정의하고, 일시적으로 상승된 권한을 제공하기 위해 Access Request를 구성하십시오.
Teleport 리소스(예: 새 데이터베이스나 애플리케이션)를 등록할 때는 초대 토큰을 파일에 저장해야 합니다. 토큰을 명령줄에 직접 입력하면, 악의적인 사용자가 침해된 시스템에서 history 명령을 실행하여 이를 볼 수 있습니다.

팁: API 클라이언트의 커스텀 역할 정의에 대해 자세히 알아보려면 API 권한 부여를 읽으세요.

내장 역할 editor를 가진 사용자 api-admin을 생성합니다:

$ tctl users add api-admin --roles=editor

2/3단계. 클라이언트 자격 증명 생성#

tsh로 새로 생성된 사용자로 로그인합니다.

# tsh 프로파일 생성
$ tsh login --user=api-admin --proxy=tele.example.com

프로파일 자격 증명 로더는 다음 단계에서 현재 프로파일의 자격 증명을 자동으로 가져옵니다.

3/3단계. Go 프로젝트 생성#

새 Go 모듈을 설정하고 client 패키지를 임포트합니다:

$ mkdir client-demo && cd client-demo
$ go mod init client-demo
$ go get github.com/gravitational/teleport/api/client

API 버전: 호환성을 보장하려면 클러스터에서 실행 중인 Teleport의 주요 버전과 일치하는 Teleport API 라이브러리 버전을 사용해야 합니다.

특정 git 태그에 대해 go.mod 파일에 적합한 의사 버전을 찾으려면 teleport 저장소에서 다음 명령을 실행합니다:
$ go list -f '{}' -m "github.com/gravitational/teleport/api@$(git rev-parse v12.1.0)"
v0.0.0-20230307032901-49a6de744a3a

필요에 따라 Addrs 문자열을 수정하여 main.go 파일을 생성합니다:

package main

import (
	"context"
	"log"

	"github.com/gravitational/teleport/api/client"
)

func main() {
	ctx := context.Background()

	clt, err := client.New(ctx, client.Config{
		Addrs: []string{
			// Teleport Cloud 고객은 <tenantname>.teleport.sh 사용
			"tele.example.com:443",
			"tele.example.com:3025",
			"tele.example.com:3024",
			"tele.example.com:3080",
 		},
		Credentials: []client.Credentials{
			client.LoadProfile("", ""),
		},
	})

	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}

	defer clt.Close()
	resp, err := clt.Ping(ctx)
	if err != nil {
		log.Fatalf("failed to ping server: %v", err)
	}

	log.Printf("Example success!")
	log.Printf("Example server response: %v", resp)
	log.Printf("Server version: %s", resp.ServerVersion)
}

이제 프로그램을 실행하고 클라이언트를 Teleport Auth 서비스에 연결하여 서버 버전을 가져올 수 있습니다.

$ go run main.go

다음 단계#

pkg.go.dev에 대해 알아보기
클라이언트 사용법 알아보기
자격 증명 작업 방법 알아보기
API 및 API 클라이언트에 대한 심층적인 개요는 API 아키텍처를 읽으세요.
API 클라이언트의 커스텀 역할 정의에 대해 자세히 알아보려면 API 권한 부여를 읽으세요.
프로그래밍 방식으로 Teleport API 작업에 대한 자세한 내용은 client pkg.go 참조 문서를 검토하세요.
API를 최대한 활용하려면 관리 매뉴얼을 숙지하세요.