Ansible 플레이북에서 SSH 연결 실패 문제 해결

Ansible은 관리 노드와 통신하기 위해 보안 셸(SSH) 프로토콜에 전적으로 의존합니다. Ansible 플레이북이 연결 오류와 함께 실패하면, 거의 항상 제어 머신과 대상 호스트 간의 표준 SSH 설정에 근본적인 문제가 있음을 나타냅니다. 이러한 실패를 체계적으로 진단하는 방법을 이해하는 것은 안정적인 자동화를 유지하는 데 중요합니다.

이 가이드는 Ansible 플레이북을 실행할 때 발생하는 가장 일반적인 SSH 연결 실패를 진단하고 해결하기 위한 단계별 방법론을 제공하여 구성 관리가 원활하게 실행되도록 보장합니다.

1단계: 상세 수준 활성화 및 초기 확인

Ansible 문제 해결에 있어 가장 중요한 단일 도구는 출력 상세 수준을 높이는 것입니다. SSH 오류는 종종 가려지지만, 최대 상세 수준은 Ansible이 사용하는 정확한 매개변수와 기본 OpenSSH 클라이언트에서 반환된 특정 오류 메시지를 보여줍니다.

상세 수준 플래그 사용

세 개 또는 네 개의 상세 수준 플래그(-v, -vv, -vvv, -vvvv)를 사용하여 테스트 명령 또는 플레이북을 실행하십시오. 대부분의 연결 문제는 -vvv에서 제공하는 출력을 검토하여 해결됩니다.

# 인벤토리에 정의된 'webserver' 호스트에 대한 연결 테스트
ansible webserver -m ansible.builtin.ping -vvv

# 최대 디버깅으로 플레이북 실행
ansible-playbook site.yml -i inventory.ini -vvvv

인벤토리 및 호스트 상태 확인

대상으로 지정하는 호스트가 올바르게 정의되어 있고 접근 가능한지 확인하십시오.

호스트 이름이 정확한가요? 인벤토리 파일(/etc/ansible/hosts 또는 사용자 지정 인벤토리)의 철자를 다시 확인하십시오.
대상이 작동 중인가요? 관리 노드가 켜져 있고 네트워크에서 접근 가능한지 확인하십시오.
인벤토리 변수가 정확한가요? ansible_host(IP 주소 또는 호스트 이름) 및 ansible_user(원격 사용자 이름)와 같은 필수 변수가 대상 그룹 또는 호스트에 대해 올바르게 설정되어 있는지 확인하십시오.

# 인벤토리 예시 스니펫
[webservers]
web1 ansible_host=192.168.1.100 ansible_user=deploy_user ansible_port=22

2단계: 기본적인 수동 연결 확인

Ansible이 연결할 수 없는 경우, 첫 번째 단계는 Ansible이 사용하도록 구성된 것과 정확히 동일한 사용자, 키 및 포트를 사용하여 표준 SSH가 수동으로 작동하는지 확인하는 것이어야 합니다.

수동 SSH 테스트

특정 사용자(ansible_user)와 특정 개인 키(ansible_ssh_private_key_file)를 사용하는 경우, 해당 연결을 수동으로 재현하십시오.

# 표준 SSH 테스트 (기본 포트 및 키를 사용하는 경우)
ssh <ansible_user>@<ansible_host>

# 기본값이 아닌 개인 키 및 포트를 사용하여 테스트
ssh -i /path/to/private/key -p 2222 [email protected]

수동 SSH 테스트가 실패하면 문제는 Ansible이 아니라 환경적인 것입니다. Ansible을 진행하기 전에 핵심 SSH 문제를 해결하십시오.

3단계: 인증 실패 진단

인증 실패는 Ansible 연결 문제의 가장 흔한 원인입니다. 이는 일반적으로 Authentication failed 또는 Permission denied 오류로 나타납니다.

3.1 키 권한 및 위치

Ansible이 SSH 키를 사용하는 경우, 개인 키 파일이 제어 머신에서 올바르고 제한적인 권한을 가지고 있는지 확인하십시오. SSH는 너무 관대한 권한을 가진 키를 종종 거부합니다.

# 개인 키 파일에 올바른 권한 설정
chmod 600 /path/to/private/key

또한 SSH 에이전트를 사용하는 경우 키가 추가되었는지 확인하십시오.

# 필요한 경우 에이전트 시작
eval "$(ssh-agent -s)"
# 에이전트에 키 추가
ssh-add /path/to/private/key

3.2 암호 프롬프트 실패 (시간 초과/암호 누락)

설정에서 암호를 요구하는 경우(프로덕션 환경에서는 권장되지 않지만 랩에서는 일반적), Ansible에 암호를 제공해야 합니다. 연결이 멈추거나 시간 초과되는 경우, Ansible은 제공되지 않은 암호를 기다리고 있을 가능성이 높습니다.

--ask-pass 또는 -k 플래그를 사용하여 SSH 연결 암호를 요청하십시오.

ansible webserver -m ansible.builtin.ping -k

3.3 원격 권한 있는 키

개인 키에 해당하는 공개 키가 관리 노드의 ~/.ssh/authorized_keys 파일에 올바르게 설치되어 있는지, 그리고 원격 측의 파일 및 디렉터리 권한이 올바른지(700은 .ssh용, 600은 authorized_keys용) 확인하십시오.

4단계: 호스트 키 오류 해결

Ansible은 원격 서버의 디지털 지문을 저장하는 known_hosts 파일을 존중합니다. 관리 노드의 호스트 키가 변경되면(예: 재구축 또는 IP 재할당으로 인해), SSH 연결 시도는 중간자 공격처럼 보이는 경고와 함께 실패합니다.

`Host key verification failed` 오류

이 오류가 발생하면 충돌하는 키 항목을 업데이트하거나 제거해야 합니다.

오류 출력에 언급된 ~/.ssh/known_hosts의 줄 번호를 식별하십시오.
ssh-keygen을 사용하여 항목을 제거하십시오.

# <hostname_or_ip>를 실제 실패한 호스트로 교체하십시오.
ssh-keygen -R <hostname_or_ip>

⚠️ 보안 경고: 호스트 확인 비활성화

임시 테스트 또는 호스트 불안정성이 예상되는 고도로 통제된 랩 환경에서는 Ansible이 호스트 키 확인을 무시하도록 구성할 수 있습니다. 이는 MITM 공격에 노출되므로 프로덕션 환경에서는 강력히 권장되지 않습니다.

ansible.cfg (또는 임시 환경 변수)에서:
ini [defaults] host_key_checking = False

5단계: 네트워크, 방화벽 및 원격 환경 문제

때때로 SSH는 연결되지만, 연결이 중단되거나 대상 머신의 네트워크 구성 또는 제한으로 인해 실패합니다.

5.1 방화벽 차단

프롬프트 없이 연결 시간이 초과되면 방화벽이 연결 시도를 차단하고 있을 가능성이 높습니다. 세 가지 지점에서 방화벽을 확인하십시오:

로컬 (제어 머신): 포트 22 (또는 사용자 지정 포트)의 아웃바운드 트래픽이 허용되는지 확인하십시오.
네트워크 경로: 중간 네트워크 ACL 또는 기업 방화벽이 트래픽을 차단하지 않는지 확인하십시오.
원격 (관리 노드): 원격 호스트의 방화벽(firewalld, ufw 등)이 SSH (일반적으로 포트 22)를 열고 올바른 네트워크 인터페이스에 대해 구성되어 있는지 확인하십시오.

5.2 Python 인터프리터 오류

Ansible은 모듈을 실행하기 위해 관리 노드에 Python 인터프리터가 필요합니다. 엄밀히 말하면 SSH 실패는 아니지만, Ansible의 초기 연결 단계는 Python 스크립트 실행인 팩트 수집을 포함합니다. 대상 머신이 Python 3가 없는 최소 설치인 경우, 설정 단계에서 연결이 실패할 수 있습니다.

대상이 Python 3를 사용하지만 인터프리터 경로가 표준이 아닌 경우(예: python3 대신 python3.8), 인벤토리에서 올바른 경로를 지정하십시오:

[target_host]
ansible_python_interpreter=/usr/bin/python3.8

5.3 SELinux 또는 AppArmor 컨텍스트

드문 경우지만, SELinux(RHEL/CentOS/Fedora) 또는 AppArmor(Ubuntu/Debian)와 같이 지나치게 엄격한 보안 모듈이 SSH 세션 중 원격 사용자의 셸 프로필 또는 디렉터리 권한이 올바르게 접근되는 것을 방해할 수 있습니다. SSH 또는 사용자의 홈 디렉터리 접근과 관련된 AVC 거부(denial)에 대해 원격 호스트의 감사 로그(/var/log/audit/audit.log 또는 이에 상응하는 파일)를 확인하십시오.

일반적인 연결 오류 및 해결책 요약

오류 메시지	예상 원인	조치 가능한 해결책
`Permission denied (publickey).`	키가 인식되지 않거나 키 권한이 잘못됨.	개인 키에 `chmod 600`을 적용하고, 원격 호스트의 공개 키를 확인하십시오.
`Host key verification failed.`	호스트 키가 변경되었거나 known_hosts 파일이 손상됨.	`ssh-keygen -R hostname`을 사용하여 이전 항목을 제거하십시오.
`Connection timed out.`	방화벽 차단 또는 호스트가 다운/접근 불가능함.	수동 연결(`ping`, `ssh`)을 확인하고, 대상 호스트의 방화벽 규칙을 확인하십시오.
연결이 멈추거나 지연됨.	제공되지 않은 암호 입력을 기다리는 중.	`-k`와 함께 실행하거나 키 기반 인증을 구성하십시오.

결론

Ansible에서 SSH 연결 문제를 해결하는 것은 주로 기본 SSH 클라이언트 구성을 디버깅하는 체계적인 과정입니다. 기본적인 수동 연결 확인부터 시작하여 상세 수준을 높이고(-vvv), 인증, 호스트 키 및 네트워크 경로를 체계적으로 확인하면 대부분의 연결 실패를 신속하게 격리하고 해결하여 자동화 워크플로가 중단 없이 진행될 수 있도록 합니다.