Ansible은 SSH를 통해 Linux 호스트 집합을 관리하는 일반적인 도구입니다. 호스트에 연결하려면 인증 방식이 필요합니다. 머신 및 워크로드 아이덴티티를 사용하면 Ansible에 단기 인증서를 제공하여 Teleport에 등록된 SSH 노드에 안전하고 감사 가능한 방식으로 연결할 수 있습니다.

이 가이드에서는 머신 및 워크로드 아이덴티티 에이전트인 tbot을 구성하여 자격 증명과 OpenSSH 설정을 생성한 다음, Teleport 프록시 서비스를 통해 SSH 노드에 연결하도록 Ansible을 구성합니다.

사전 요구사항#

Teleport를 Ansible과 함께 사용하려면 다음 도구가 필요합니다.

• 실행 중인 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
     ```
   

 

• ssh OpenSSH 도구

• ansible >= [ansible.min_version]

• 선택사항: JSON 출력을 처리하기 위한 jq

• Ansible을 실행할 머신에 tbot이 이미 설치 및 구성되어 있어야 합니다. 자세한 내용은 배포 가이드를 참조하세요.

• 위 가이드를 따랐다면, Ansible에서 사용하는 SSH 인증서와 OpenSSH 설정이 기록되는 디렉터리를 정의하는 --destination-dir=/opt/machine-id 플래그를 참고하세요.

  특히, Teleport 노드에 Ansible이 연결하는 방식을 정의하기 위해 Ansible 설정에서 /opt/machine-id/ssh_config 파일을 사용하게 됩니다.

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단계/4단계. RBAC 구성#

Ansible은 tbot이 생성한 자격 증명을 사용하여 SSH 노드에 연결하므로, 먼저 봇에 접근 권한을 부여하도록 Teleport를 구성해야 합니다. 이를 위해 필요한 권한을 부여하는 역할을 생성한 다음, 이 역할을 봇에 할당합니다.

이 예시에서는 root 사용자 이름으로 모든 SSH 노드에 대한 접근 권한이 부여됩니다. SSH 노드 전반에서 사용 가능하고 노드를 관리하는 데 적절한 권한을 가진 사용자 이름으로 설정했는지 확인하세요.

다음 내용으로 role.yaml 파일을 생성합니다:

kind: role
version: v6
metadata:
  name: example-role
spec:
  allow:
    # Allow login to the user 'root'.
    logins: ['root']
    # Allow connection to any node. Adjust these labels to match only nodes
    # that Ansible needs to access.
    node_labels:
      '*': '*'

example-role을 사용 사례와 관련된 설명적인 이름으로 바꾸세요.

프로덕션 환경에서 사용할 때는 라벨을 사용하여 Ansible이 접근해야 하는 호스트로만 이 접근 권한을 제한해야 합니다. 이를 최소 권한의 원칙이라고 하며, 유출된 자격 증명이 초래할 수 있는 피해를 줄여줍니다.

tctl create -f ./role.yaml을 사용하여 역할을 생성합니다.

이제 tctl bots update를 사용하여 봇에 역할을 추가합니다. example은 배포 가이드에서 생성한 봇의 이름으로, example-role은 방금 생성한 역할의 이름으로 바꾸세요:

$ tctl bots update example --add-roles example-role

2단계/4단계. tbot 출력 서비스 구성#

이제 Ansible에 필요한 자격 증명과 SSH 설정을 생성할 출력 서비스로 tbot을 구성해야 합니다. SSH의 경우 identity 서비스 유형을 사용합니다.

출력 서비스는 대상과 함께 구성해야 합니다. 이 예시에서는 directory 대상을 사용합니다. 이렇게 하면 이러한 자격 증명이 디스크의 지정된 디렉터리에 기록됩니다. 이 디렉터리는 tbot이 실행되는 Linux 사용자가 쓸 수 있어야 하며, Ansible이 실행되는 Linux 사용자가 읽을 수 있어야 합니다.

identity 서비스를 추가하도록 tbot 설정을 수정합니다:

services:
- type: identity
  destination:
    type: directory
    # For this guide, /opt/machine-id is used as the destination directory.
    # You may wish to customize this. Multiple outputs cannot share the same
    # destination.
    path: /opt/machine-id

이제 /opt/machine-id 아래에 여러 파일이 생성된 것을 확인할 수 있습니다:

• ssh_config: 연결 시 올바른 자격 증명으로 Teleport 프록시 서비스를 사용하도록 Ansible이나 OpenSSH를 설정하는 데 사용할 수 있습니다.
• known_hosts: Teleport SSH 호스트 CA를 포함하며, SSH 클라이언트가 호스트의 인증서를 검증할 수 있게 해줍니다.
• key-cert.pub: Teleport SSH 사용자 CA로 서명된 SSH 인증서입니다.
• key: SSH 인증서를 사용하는 데 필요한 개인 키입니다.

다음으로, 연결 시 이러한 파일을 사용하도록 Ansible을 구성합니다.

3단계/4단계. Ansible 구성#

모든 Ansible 파일을 모을 ansible이라는 폴더를 생성합니다.

$ mkdir -p ansible
$ cd ansible

ansible.cfg 파일을 생성합니다. tbot이 생성한 설정 파일인 /opt/machine-id/ssh_config로 OpenSSH 클라이언트를 실행하도록 Ansible을 구성합니다. 여기서 example.com은 Teleport 클러스터의 이름입니다.

[defaults]
host_key_checking = True
inventory=./hosts
remote_tmp=/tmp

[ssh_connection]
scp_if_ssh = True
ssh_args = -F /opt/machine-id/ssh_config

그런 다음 hosts라는 인벤토리 파일을 생성할 수 있습니다. 이 파일은 Teleport에 등록된 호스트 이름을 사용하여 호스트를 참조해야 하며, Teleport 클러스터의 이름이 여기에 추가되어야 합니다. 예를 들어, 클러스터 이름이 teleport.example.com이고 호스트 이름이 node1이라면 hosts의 항목은 node1.teleport.example.com이 됩니다.

이 요구사항을 충족하는 모든 노드에 대한 인벤토리 파일은 다음과 같은 스크립트로 생성할 수 있습니다:

# Source tsh env to get the name of the current Teleport cluster.
$ eval "$( tsh env )"
# You can modify the `tsh ls` command to filter nodes based on the label.
$ tsh ls --format=json | jq --arg cluster $TELEPORT_CLUSTER -r '.[].spec.hostname + "." + $cluster' > hosts

4단계/4단계. 플레이북 실행#

이제 간단한 Ansible 플레이북인 playbook.yaml을 만들어 보겠습니다. 아래 예시 플레이북은 모든 호스트에서 hostname을 실행합니다.

- hosts: all
  remote_user: root
  tasks:
    - name: "hostname"
      command: "hostname"

ansible 폴더에서 Ansible 플레이북을 실행합니다:

$ ansible-playbook playbook.yaml

# PLAY [all] *****************************************************************************************************************************************
# TASK [Gathering Facts] *****************************************************************************************************************************
#
# ok: [terminal]
#
# TASK [hostname] ************************************************************************************************************************************
# changed: [terminal]
#
# PLAY RECAP *****************************************************************************************************************************************
# terminal                   : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

이제 준비가 완료되었습니다. 회전, 감사, 그리고 익숙한 모든 접근 제어로 제어할 수 있는 머신 아이덴티티에 연결된 단기 인증서를 머신에 제공했습니다.

문제 해결#

Ansible이 연결할 수 없는 경우, 다음과 같은 오류가 표시될 수 있습니다:

example.host | UNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: ssh: Could not resolve hostname node-name: Name or service not known",
    "unreachable": true
}

ssh_config에서 인벤토리 호스트와 일치하는 패턴을 검토하고 조정할 수 있습니다.

상세 모드로 ssh_config를 사용하여 SSH 연결을 시도하고 오류를 확인해 보세요:

$ ssh -vvv -F /opt/machine-id/ssh_config root@node-name.example.com

ssh가 작동한다면, 상세 모드를 켠 상태로 플레이북을 실행해 보세요:

$ ansible-playbook -vvv playbook.yaml

호스트 이름에 대문자(예: MYHOSTNAME)가 포함되어 있다면, Teleport의 내부 호스트 이름 매칭이 기본적으로 대소문자를 구분한다는 점에 유의하세요. 이로 인해서도 이 오류가 발생할 수 있습니다.

이러한 경우라면, 클러스터 수준에서 대소문자를 구분하지 않는 라우팅을 활성화하여 이 문제를 해결할 수 있습니다.

auth_service:
  case_insensitive_routing: true

spec:
  case_insensitive_routing: true

다음 단계#

• 사용 가능한 모든 구성 옵션을 살펴보려면 구성 참조를 읽어보세요.
• Ansible AWX 또는 Ansible Automation Platform을 사용한다면, 저희의 전용 Ansible AWX 가이드를 읽어보세요.