Ansible과 함께하는 머신 및 워크로드 아이덴티티

요약

Ansible은 SSH를 통해 Linux 호스트 집합을 관리하는 일반적인 도구입니다. 이 가이드에서는 머신 및 워크로드 아이덴티티 에이전트 tbot을 자격 증명과 OpenSSH 설정을 생성하도록 설정하고, Ansible이 Teleport Proxy Service를 통해 SSH 노드에 연결하도록 설정합니다.

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

이 가이드에서는 머신 및 워크로드 아이덴티티 에이전트 tbot을 자격 증명과 OpenSSH 설정을 생성하도록 설정하고, Ansible이 Teleport Proxy Service를 통해 SSH 노드에 연결하도록 설정합니다.

사전 조건#

Ansible AWX 사용 중이신가요?

Ansible AWX 또는 Ansible Automation Platform에서 Ansible 작업을 실행 중인 경우 전용 가이드를 참조하세요.

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

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 tctl and tsh clients.
Installing `tctl` and `tsh` clients
1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and 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')"
```
2. Follow the instructions for your platform to install tctl and tsh clients:

ssh OpenSSH 도구
ansible >= [ansible.min_version]
선택 사항: JSON 출력 처리를 위한 jq
Ansible을 실행할 머신에 tbot이 이미 설치되고 설정되어 있어야 합니다. 자세한 내용은 배포 가이드를 참조하세요.
위 가이드를 따랐다면 --destination-dir=/opt/machine-id 플래그를 참고하세요. 이 플래그는 Ansible이 사용할 SSH 인증서와 OpenSSH 설정이 기록되는 디렉터리를 정의합니다.

특히 Ansible 설정에서 /opt/machine-id/ssh_config 파일을 사용하여 Ansible이 Teleport 노드에 연결하는 방법을 정의합니다.

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단계/4단계. RBAC 설정#

Ansible은 tbot이 생성한 자격 증명을 사용하여 SSH 노드에 연결하므로, 먼저 Teleport가 봇 접근을 허용하도록 설정해야 합니다. 이는 필요한 권한을 부여하는 역할을 만들고 해당 역할을 봇에 할당하는 방식으로 수행됩니다.

이 예시에서는 사용자 이름 으로 모든 SSH 노드에 대한 접근을 허용합니다. SSH 노드 전체에서 사용 가능하고 노드를 관리할 적절한 권한이 있는 사용자 이름으로 설정하세요.

다음 내용으로 role.yaml 파일을 만듭니다:

kind: role
version: v6
metadata:
  name: example-role
spec:
  allow:
    # 'root' 사용자로 로그인 허용.
    logins: ['']
    # 모든 노드에 대한 연결 허용. Ansible이 접근해야 하는
    # 노드에만 일치하도록 이 레이블을 조정하세요.
    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 사용자가 읽을 수 있도록 하세요.

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

services:
- type: identity
  destination:
    type: directory
    # 이 가이드에서는 /opt/machine-id를 대상 디렉터리로 사용합니다.
    # 필요에 따라 커스터마이즈할 수 있습니다. 여러 출력은 동일한
    # 대상을 공유할 수 없습니다.
    path: /opt/machine-id

tbot을 백그라운드 서비스로 실행 중인 경우 재시작하세요. 원샷 모드로 실행 중이라면 Ansible 플레이북을 실행하기 전에 실행해야 합니다.

이제 /opt/machine-id에서 다음 파일들을 볼 수 있습니다:

ssh_config: Ansible 또는 OpenSSH에서 올바른 자격 증명으로 Teleport Proxy Service를 사용하도록 설정할 때 사용할 수 있습니다.
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이 됩니다.

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

# tsh 환경을 소스로 현재 Teleport 클러스터 이름을 가져옵니다.
$ eval "$( tsh env )"
# 레이블 기반으로 노드를 필터링하도록 `tsh ls` 명령을 수정할 수 있습니다.
$ tsh ls --format=json | jq --arg cluster $TELEPORT_CLUSTER -r '.[].spec.hostname + "." + $cluster' > hosts

노드가 보이지 않나요?

When the Teleport Auth Service receives a request to list Teleport-connected resources (e.g., to display resources in the Web UI or via tsh ls), it only returns the resources that the current user is authorized to view.

For each resource in the user's Teleport cluster, the Auth Service applies the following checks in order and, if one check fails, hides the resource from the user:

None of the user's roles contain a deny rule that matches the resource's labels.
At least one of the user's roles contains an allow rule that matches the resource's labels.

If you are not seeing resources when expected, make sure that your user's roles include the appropriate allow and deny rules as documented in the Access Controls Reference.

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

마지막으로 간단한 Ansible 플레이북 playbook.yaml을 만들어 봅니다. 아래 예시 플레이북은 모든 호스트에서 hostname을 실행합니다.

- hosts: all
  remote_user:  name="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 @node-name.example.com

ssh가 작동하면 상세 모드로 플레이북을 실행해보세요:

$ ansible-playbook -vvv playbook.yaml

호스트 이름에 대문자가 포함된 경우(예: MYHOSTNAME), Teleport의 내부 호스트 이름 매칭은 기본적으로 대소문자를 구분하므로 이 오류가 발생할 수 있습니다.

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

모든 서버에서 auth_service가 실행 중인 /etc/teleport.yaml 설정 파일을 편집한 후 각 서버에서 Teleport를 재시작합니다.

auth_service:
  case_insensitive_routing: true

tctl edit cluster_networking_config를 실행하여 다음 스펙을 추가한 후 저장하고 종료합니다.

spec:
  case_insensitive_routing: true

다음 단계#

사용 가능한 모든 설정 옵션을 확인하려면 설정 레퍼런스를 읽으세요.
Ansible AWX 또는 Ansible Automation Platform을 사용한다면 전용 Ansible AWX 가이드를 읽으세요.

Ansible과 함께하는 머신 및 워크로드 아이덴티티

원문 보기

번역일: 2026-05-14

요약

사전 조건#

Ansible AWX 사용 중이신가요?

Ansible AWX 또는 Ansible Automation Platform에서 Ansible 작업을 실행 중인 경우 전용 가이드를 참조하세요.

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

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 tctl and tsh clients.
Installing `tctl` and `tsh` clients
1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and 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')"
```
2. Follow the instructions for your platform to install tctl and tsh clients:

ssh OpenSSH 도구
ansible >= [ansible.min_version]
선택 사항: JSON 출력 처리를 위한 jq
Ansible을 실행할 머신에 tbot이 이미 설치되고 설정되어 있어야 합니다. 자세한 내용은 배포 가이드를 참조하세요.
위 가이드를 따랐다면 --destination-dir=/opt/machine-id 플래그를 참고하세요. 이 플래그는 Ansible이 사용할 SSH 인증서와 OpenSSH 설정이 기록되는 디렉터리를 정의합니다.

특히 Ansible 설정에서 /opt/machine-id/ssh_config 파일을 사용하여 Ansible이 Teleport 노드에 연결하는 방법을 정의합니다.

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=)

1단계/4단계. RBAC 설정#

다음 내용으로 role.yaml 파일을 만듭니다:

kind: role
version: v6
metadata:
  name: example-role
spec:
  allow:
    # 'root' 사용자로 로그인 허용.
    logins: ['']
    # 모든 노드에 대한 연결 허용. Ansible이 접근해야 하는
    # 노드에만 일치하도록 이 레이블을 조정하세요.
    node_labels:
      '*': '*'

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

tctl create -f ./role.yaml을 사용하여 역할을 만듭니다.

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

2단계/4단계. `tbot` 출력 서비스 설정#

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

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

services:
- type: identity
  destination:
    type: directory
    # 이 가이드에서는 /opt/machine-id를 대상 디렉터리로 사용합니다.
    # 필요에 따라 커스터마이즈할 수 있습니다. 여러 출력은 동일한
    # 대상을 공유할 수 없습니다.
    path: /opt/machine-id

tbot을 백그라운드 서비스로 실행 중인 경우 재시작하세요. 원샷 모드로 실행 중이라면 Ansible 플레이북을 실행하기 전에 실행해야 합니다.

이제 /opt/machine-id에서 다음 파일들을 볼 수 있습니다:

ssh_config: Ansible 또는 OpenSSH에서 올바른 자격 증명으로 Teleport Proxy Service를 사용하도록 설정할 때 사용할 수 있습니다.
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

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

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

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

# tsh 환경을 소스로 현재 Teleport 클러스터 이름을 가져옵니다.
$ eval "$( tsh env )"
# 레이블 기반으로 노드를 필터링하도록 `tsh ls` 명령을 수정할 수 있습니다.
$ tsh ls --format=json | jq --arg cluster $TELEPORT_CLUSTER -r '.[].spec.hostname + "." + $cluster' > hosts

노드가 보이지 않나요?

For each resource in the user's Teleport cluster, the Auth Service applies the following checks in order and, if one check fails, hides the resource from the user:

None of the user's roles contain a deny rule that matches the resource's labels.
At least one of the user's roles contains an allow rule that matches the resource's labels.

If you are not seeing resources when expected, make sure that your user's roles include the appropriate allow and deny rules as documented in the Access Controls Reference.

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

마지막으로 간단한 Ansible 플레이북 playbook.yaml을 만들어 봅니다. 아래 예시 플레이북은 모든 호스트에서 hostname을 실행합니다.

- hosts: all
  remote_user:  name="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 @node-name.example.com

ssh가 작동하면 상세 모드로 플레이북을 실행해보세요:

$ ansible-playbook -vvv playbook.yaml

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

모든 서버에서 auth_service가 실행 중인 /etc/teleport.yaml 설정 파일을 편집한 후 각 서버에서 Teleport를 재시작합니다.

auth_service:
  case_insensitive_routing: true

tctl edit cluster_networking_config를 실행하여 다음 스펙을 추가한 후 저장하고 종료합니다.

spec:
  case_insensitive_routing: true

다음 단계#

사용 가능한 모든 설정 옵션을 확인하려면 설정 레퍼런스를 읽으세요.
Ansible AWX 또는 Ansible Automation Platform을 사용한다면 전용 Ansible AWX 가이드를 읽으세요.

Ansible과 함께하는 머신 및 워크로드 아이덴티티

사전 조건#

1단계/4단계. RBAC 설정#

2단계/4단계. tbot 출력 서비스 설정#

3단계/4단계. Ansible 설정#

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

문제 해결#

다음 단계#

사전 조건#

1단계/4단계. RBAC 설정#

2단계/4단계. tbot 출력 서비스 설정#

3단계/4단계. Ansible 설정#

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

문제 해결#

다음 단계#

2단계/4단계. `tbot` 출력 서비스 설정#

2단계/4단계. `tbot` 출력 서비스 설정#