인포레터에서 최신 DevOps 트렌드를 격주로 만나보세요!
API 시작하기 가이드
이 시작하기 가이드에서는 Teleport API Go 클라이언트를 사용하여 Teleport Auth 서비스에 연결할 것입니다.
다음 단계에 대해 설명하겠습니다:
- 간단한 역할 기반 인증 방법을 사용하여 API 사용자를 생성합니다.
- 해당 사용자를 위한 자격 증명을 생성합니다.
- Teleport API와 상호작용하기 위해 Go 클라이언트를 생성하고 연결합니다.
필수 조건
- Go 1.22+ 및 Go 개발 환경을 설치합니다.
-
실행 중인 Teleport 클러스터 버전 17.0.0-dev 이상. Teleport를 시작하려면 가입하여 무료 평가판을 이용하거나 데모 환경 설정 방법을 확인하십시오.
-
tctl
관리자 도구와tsh
클라이언트 도구.tctl
및tsh
다운로드 방법에 대한 지침은 설치를 방문하십시오.
- 연결이 가능한지 확인하기 위해
tsh login
으로 로그인한 다음, 현재 자격 증명을 사용하여tctl
명령어를 실행할 수 있는지 확인하십시오. 예를 들어:클러스터에 연결할 수 있고tsh login --proxy=teleport.example.com --user=email@example.comtctl status클러스터 teleport.example.com
버전 17.0.0-dev
CA 핀 sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 후속tctl
명령어를 실행할 수 있습니다.
자신의 Teleport 클러스터를 호스팅하는 경우, Teleport Auth Service를 호스팅하는 컴퓨터에서 전체 권한으로tctl
명령어를 실행할 수도 있습니다.
1/3단계. 사용자 생성
Teleport를 운영 환경에서 실행할 때 보안 사고를 피하기 위해 다음의 모범 사례를 준수해야 합니다:
- 필요하지 않는 한 운영 환경에서
sudo
사용을 피하십시오. - 새로운 비루트 사용자를 생성하고 Teleport 실험을 위해 테스트 인스턴스를 사용하십시오.
- 필요하지 않은 한 비루트 사용자로 Teleport의 서비스를 실행하십시오. SSH 서비스만 루트 액세스를 요구합니다. Teleport가 <
1024
(예:443
)로 번호 매겨진 포트에서 수신 대기하도록 하려면 루트 권한(또는CAP_NET_BIND_SERVICE
권한)이 필요합니다. - 최소 권한 원칙을 따르십시오. 더 제한적인 역할로도 충분할 때 사용자에게 허용적인 역할을 부여하지 마십시오.
예를 들어, 클러스터 리소스에 액세스하고 편집할 수 있는 권한을 부여하는 내장된
access,editor
역할을 사용자에게 할당하지 마십시오. 대신 각 사용자에 대해 최소한의 필수 권한을 가진 역할을 정의하고 액세스 요청을 구성하여 일시적으로 상승된 권한을 부여하십시오. - 새로운 데이터베이스나 애플리케이션과 같은 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-demogo mod init client-demogo get github.com/gravitational/teleport/api/client
API 버전
호환성을 보장하기 위해, 클러스터에서 실행 중인 Teleport의 주요 버전과 일치하는 Teleport API 라이브러리 버전을 사용해야 합니다.
특정 git 태그에 대한 go.mod 파일에 적합한 의사 버전을 찾으려면,
teleport
리포지토리에서 다음 명령을 실행하세요:
go list -f '{{.Version}}' -m "github.com/gravitational/teleport/api@$(git rev-parse v12.1.0)"v0.0.0-20230307032901-49a6de744a3a
main.go
라는 파일을 생성하고 필요에 따라 Addrs
문자열을 수정합니다:
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("클라이언트 생성 실패: %v", err)
}
defer clt.Close()
resp, err := clt.Ping(ctx)
if err != nil {
log.Fatalf("서버 핑 실패: %v", err)
}
log.Printf("예제 성공!")
log.Printf("예제 서버 응답: %s", resp)
log.Printf("서버 버전: %s", resp.ServerVersion)
}
이제 프로그램을 실행하고 클라이언트를 Teleport Auth 서버에 연결하여 서버 버전을 가져올 수 있습니다.
go run main.go
다음 단계
- pkg.go.dev에 대해 알아보기
- 클라이언트 사용법에 대해 알아보기
- 자격 증명 작업 방법 알아보기
- Teleport API 아키텍처에 대해 읽고 API 및 API 클라이언트에 대한 심층 개요 확인하기
- API 권한 부여에 대해 읽고 API 클라이언트를 위한 사용자 지정 역할 정의 방법 알아보기
client
pkg.go 참조 문서를 검토하여 Teleport API를 프로그래밍적으로 작업하는 데 대한 더 많은 정보를 얻기- API를 최적으로 사용하기 위해 관리자 매뉴얼에 익숙해지기