이 가이드는 Terraform 사용자를 생성하고 Teleport Auth Service가 해당 사용자에 대한 장기 자격 증명에 서명하도록 하는 방법을 설명합니다. 그러면 Teleport Terraform 프로바이더가 해당 자격 증명을 사용하여 Teleport와 상호 작용할 수 있습니다.

동작 방식#

Teleport 관리자는 Teleport Terraform 프로바이더용 역할과 Terraform 프로바이더 역할을 가장(impersonate)할 수 있는 역할을 정의합니다. Teleport 사용자는 가장자 역할을 가정하고 tctl 명령을 실행하여 Teleport Auth Service가 Terraform 프로바이더용 사용자 인증서에 서명하도록 지시합니다. 그런 다음 프로바이더는 인증서를 로드하여 Teleport 클러스터에 인증하고 Teleport Auth Service 백엔드에서 리소스를 관리합니다.

자격 증명은 완전한 Teleport 관리 접근 권한을 보유하므로 보호하고 교체해야 합니다. 가능한 경우 tbot, CI 또는 클라우드 환경에서 네이티브 머신 및 워크로드 아이덴티티 참여, 또는 로컬 사용을 위한 임시 봇 생성을 사용하는 것이 좋습니다.

어떤 것이 사용 사례에 맞는지 찾으려면 가능한 Terraform 프로바이더 설정 목록을 참조하세요.

장기 자격 증명은 ID 공급자(IdP) 침해 시 Teleport를 보호하는 추가 보안 계층인 관리 작업용 MFA(MFA4A)와 호환되지 않습니다.

사전 요구 사항#

• 실행 중인 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` 파일을 더블 클릭하여 설치를 시작합니다.
 
     

       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
     ```
   

 

• Terraform >= [terraform.version]+

  $ terraform version
  # Terraform v(=terraform.version=)
  

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단계. Terraform용 Teleport 자격 증명 생성하기#

Terraform은 클러스터의 리소스를 관리하기 위해 Teleport 클러스터 인증 기관에서 서명한 ID 파일이 필요합니다. 이 목적으로 로컬 Teleport 사용자를 생성합니다.

1. 임시 파일을 보관할 teleport-terraform이라는 폴더를 생성합니다:

   $ mkdir -p teleport-terraform
   $ cd teleport-terraform
   

2. terraform.yaml이라는 새 파일을 생성하고 편집기에서 엽니다.

3. 다음 내용을 terraform.yaml 파일에 붙여넣어 로컬 Teleport 사용자 및 역할에 대한 설정을 구성합니다:

   kind: user
   metadata:
     name: terraform
   spec:
     roles: ['terraform-provider']
   version: v2
   

16.2부터 Teleport에는 Terraform 프로바이더용 기본 제공 역할인 terraform-provider가 포함됩니다.

```yaml
kind: role
version: v7
metadata:
  name: terraform-provider
spec:
  allow:
    db_labels:
      '*': '*'
    app_labels:
      '*': '*'
    node_labels:
      '*': '*'
    rules:
      - resources:
        - app
        - cluster_auth_preference
        - cluster_networking_config
        - db
        - device
        - github
        - login_rule
        - oidc
        - okta_import_rule
        - role
        - saml
        - session_recording_config
        - token
        - trusted_cluster
        - user
        - access_list
        - node
        verbs: ['list','create','read','update','delete']
```

`tctl create -f ./role.yaml`을 사용하여 역할을 생성하십시오.

이 설정은 Teleport 클러스터에서 리소스를 관리하는 데 필요한 권한으로 terraform이라는 이름의 사용자와 역할을 구성합니다.

1. 다음 명령을 실행하여 terraform 사용자와 역할을 생성합니다:

   $ tctl create terraform.yaml
   

   terraform 사용자는 로그인하여 자격 증명을 얻을 수 없으므로, 다른 사용자가 terraform 계정을 가장하여 인증서를 요청해야 합니다.

2. terraform-impersonator.yaml이라는 새 파일을 생성하고 편집기에서 엽니다.

3. 다음 내용을 terraform-impersonator.yaml 파일에 붙여넣어 Terraform 사용자를 가장할 수 있도록 하는 역할을 구성합니다:

   kind: role
   version: v7
   metadata:
     name: terraform-impersonator
   spec:
     allow:
       # 이 가장 역할은 이 역할이 할당된 모든 사용자가
       # "terraform"이라는 이름의 사용자를 가장하고 해당 사용자의 인증서를
       # 생성할 수 있도록 합니다. 역할 이름도 "terraform"입니다.
       impersonate:
         users: ['terraform']
         roles: ['terraform-provider']
   

4. 다음 명령을 실행하여 terraform-impersonator 역할을 생성합니다:

   $ tctl create terraform-impersonator.yaml
   

인증 공급자에 맞는 적절한 명령을 실행하여 terraform-impersonator 역할을 your Teleport user에게 할당하십시오:

Local User

1. 로컬 사용자의 역할을 쉼표로 구분된 목록으로 가져옵니다:

   $ ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')
   

2. 로컬 사용자를 편집하여 새 역할을 추가합니다:

   $ tctl users update $(tsh status -f json | jq -r '.active.username') \
     --set-roles "${ROLES?},terraform-impersonator"
   

3. Teleport 클러스터에서 로그아웃한 다음 다시 로그인하여 새 역할을 적용합니다.

GitHub

1. 텍스트 편집기에서 github 인증 커넥터를 엽니다:

   $ tctl edit github/github
   

2. github 커넥터를 편집하여 teams_to_roles 섹션에 terraform-impersonator을 추가합니다.

   이 역할에 매핑해야 할 팀은 조직의 역할 기반 액세스 제어(RBAC)를 어떻게 설계했는지에 따라 달라집니다. 다만, 해당 팀은 여러분의 사용자 계정을 포함해야 하며 조직 내에서 가능한 한 가장 작은 팀이어야 합니다.

   다음은 예시입니다:

     teams_to_roles:
       - organization: octocats
         team: admins
         roles:
           - access
   +       - terraform-impersonator
   

3. 편집기에서 파일을 저장하고 닫아 변경 사항을 적용합니다.

4. Teleport 클러스터에서 로그아웃한 다음 다시 로그인하여 새 역할을 적용합니다.

SAML

1. saml 구성 리소스를 가져옵니다:

   $ tctl get --with-secrets saml/mysaml > saml.yaml
   

   --with-secrets 플래그는 spec.signing_key_pair.private_key 값을 saml.yaml 파일에 추가한다는 점에 유의하십시오. 이 키에는 민감한 값이 포함되어 있으므로, 리소스를 업데이트한 직후 saml.yaml 파일을 삭제해야 합니다.

2. saml.yaml을 편집하여 attributes_to_roles 섹션에 terraform-impersonator을 추가합니다.

   이 역할에 매핑해야 할 속성은 조직의 역할 기반 액세스 제어(RBAC)를 어떻게 설계했는지에 따라 달라집니다. 다만, 해당 그룹은 여러분의 사용자 계정을 포함해야 하며 조직 내에서 가능한 한 가장 작은 그룹이어야 합니다.

   다음은 예시입니다:

     attributes_to_roles:
       - name: "groups"
         value: "my-group"
         roles:
           - access
   +       - terraform-impersonator
   

3. 변경 사항을 적용합니다:

   $ tctl create -f saml.yaml
   

4. Teleport 클러스터에서 로그아웃한 다음 다시 로그인하여 새 역할을 적용합니다.

OIDC

1. oidc 구성 리소스를 가져옵니다:

   $ tctl get oidc/myoidc --with-secrets > oidc.yaml
   

   --with-secrets 플래그는 spec.signing_key_pair.private_key 값을 oidc.yaml 파일에 추가한다는 점에 유의하십시오. 이 키에는 민감한 값이 포함되어 있으므로, 리소스를 업데이트한 직후 oidc.yaml 파일을 삭제해야 합니다.

2. oidc.yaml을 편집하여 claims_to_roles 섹션에 terraform-impersonator을 추가합니다.

   이 역할에 매핑해야 할 클레임은 조직의 역할 기반 액세스 제어(RBAC)를 어떻게 설계했는지에 따라 달라집니다. 다만, 해당 그룹은 여러분의 사용자 계정을 포함해야 하며 조직 내에서 가능한 한 가장 작은 그룹이어야 합니다.

   다음은 예시입니다:

     claims_to_roles:
       - name: "groups"
         value: "my-group"
         roles:
           - access
   +       - terraform-impersonator
   

3. 변경 사항을 적용합니다:

   $ tctl create -f oidc.yaml
   

4. Teleport 클러스터에서 로그아웃한 다음 다시 로그인하여 새 역할을 적용합니다.

5. 다음 명령을 실행하여 Terraform 사용자에 대한 서명된 ID 파일을 요청합니다:

   $ tctl auth sign --user=terraform --out=terraform-identity
   

   이 명령을 실행하면 Terraform 사용자의 자격 증명이 포함된 terraform-identity 파일이 생성됩니다.

2/3단계. Terraform 구성 파일 준비하기#

Terraform 구성 파일을 준비하려면:

1. main.tf라는 새 파일을 생성하고 편집기에서 엽니다.

2. 다음 내용을 main.tf 파일에 붙여넣어 Terraform을 사용하여 예제 사용자와 역할을 정의합니다. teleport.example.com:443을 Teleport 프록시 서비스의 호스트와 포트로 교체합니다:

   terraform {
      required_providers {
         teleport = {
            source  = "terraform.releases.teleport.dev/gravitational/teleport"
            version = "~> (=teleport.major_version=).0"
         }
      }
   }
   
   provider "teleport" {
      addr               = 'teleport.example.com:443'
      identity_file_path = "terraform-identity"
   }
   
   # 테스트 역할을 생성해야 합니다. 리소스를 선언하지 않으면 Terraform이
   # Teleport에 연결을 시도하지 않아 설정을 검증할 수 없습니다.
   resource "teleport_role" "test" {
      version = "v7"
      metadata = {
         name        = "test"
         description = "Dummy role to validate Terraform Provider setup"
         labels = {
            test = "yes"
         }
      }
   
      spec = {}
   }
   

3/3단계. 구성 적용하기#

구성을 적용하려면:

1. teleport-terraform 폴더의 내용을 확인합니다:

   $ ls
   # main.tf  terraform-identity  terraform-impersonator.yaml  terraform.yaml
   

2. 다음 명령을 실행하여 Terraform 구성 파일이 포함된 작업 디렉터리를 초기화합니다:

   $ terraform init
   Initializing the backend...
   
   Initializing provider plugins...
   - Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ...
   

3. 다음 명령을 실행하여 구성 파일에 정의된 Terraform 플랜을 실행합니다:

   $ terraform apply
   Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
   + create
   
   Terraform will perform the following actions:
   
   # teleport_role.test will be created
   + resource "teleport_role" "test" {
      + id       = (known after apply)
      + kind     = (known after apply)
      + metadata = {
         + name      = "test"
         + namespace = (known after apply)
           }
      + spec     = {}
      + version  = "v7"
        }
   
   Plan: 1 to add, 0 to change, 0 to destroy.
   

다음 단계#

• 지원되는 Terraform 프로바이더 리소스 전체 목록을 탐색하세요.
• IaC로 사용자 및 역할 관리하는 방법에 대해 알아보세요
• 가장(impersonation)에 대해 자세히 읽어보세요.