Ansible 일반 오류: 플레이북 실행 실패 문제 해결

Ansible 일반 오류는 보통 최악의 타이밍에 나타납니다. 플레이북이 롤아웃 중간에 실패하거나, 호스트에 연결할 수 없거나, 변수가 빈 값으로 렌더링됩니다. 가장 빠른 해결 방법은 실패 메시지를 읽고 올바른 범주에 매칭하는 것부터 시작합니다.

이 가이드는 추측 없이 플레이북 실행 실패를 문제 해결하는 방법을 보여줍니다. 일반적인 증상, 가능한 원인, 그리고 먼저 실행해야 할 실용적인 확인 사항을 살펴보겠습니다.

Ansible 오류 메시지 이해하기

Ansible은 일반적으로 실패한 계층을 찾을 수 있는 충분한 정보를 제공합니다. 다음을 확인하세요:

작업 이름: 실패한 작업입니다.
사용된 모듈: 오류를 발생시킨 모듈 또는 액션입니다.
반환 코드 또는 상태: 시스템 반환 코드, HTTP 상태 또는 모듈별 상태입니다.
오류 메시지: msg, stderr 또는 exception 뒤에 오는 텍스트입니다.
줄 번호: 가능한 경우 플레이북 또는 역할 파일 위치입니다.

stderr와 stdout에 특히 주의하세요. 예를 들어, Ansible 작업이 일반 모듈 메시지와 함께 실패할 수 있지만, stderr에는 Permission denied 또는 No such file or directory라고 표시될 수 있습니다.

일반적인 오류 범주 및 해결 방법

1. 연결 및 인증 오류

이러한 오류는 Ansible이 대상 호스트에 연결을 설정하거나 성공적으로 인증할 수 없을 때 발생합니다.

증상:

Failed to connect to host [...]
Permission denied [...]
Authentication failed for user [...]

원인 및 해결 방법:

SSH 또는 WinRM 자격 증명 오류: SSH의 경우 개인 키가 컨트롤 노드에 있고 공개 키가 대상에 승인되었는지 확인하세요. Windows의 경우 WinRM 구성, 사용자 이름, 비밀번호 및 권한을 확인하세요.

# 예시: 플레이북에서 사용자 및 키 파일 지정
- name: 웹 서버 구성
  hosts: webservers
  become: yes
  vars:
    ansible_user: ubuntu
    ansible_ssh_private_key_file: /path/to/your/private_key.pem
  tasks:
    - name: Nginx 설치
      apt: 
        name: nginx
        state: present

방화벽 문제: SSH 또는 WinRM이 Ansible 컨트롤 노드에서 연결 가능한지 확인하세요.
잘못된 인벤토리 호스트: 호스트 이름 또는 IP 주소가 컨트롤 노드에서 확인되는지 확인하세요.
SSH 에이전트 키 누락: ssh-agent에 의존하는 경우 플레이북을 실행하기 전에 키가 로드되었는지 확인하세요.

2. 모듈 오류 및 잘못된 구성

이러한 오류는 잘못된 모듈 사용, 누락된 매개변수 또는 대상 시스템의 호환되지 않는 구성으로 인해 발생합니다.

증상:

Invalid parameter [...] for module [...]
Failed to set parameter [...]
Error installing package 또는 Failed to create directory와 같은 모듈별 오류

원인 및 해결 방법:

잘못된 모듈 매개변수: 모듈 문서를 확인하고 필수 값과 데이터 유형을 확인하세요. 예를 들어, copy 모듈은 컨트롤 노드의 소스와 대상 호스트의 대상을 필요로 합니다.
```
- name: 구성 파일 복사
  copy:
    src: /etc/ansible/files/my_app.conf
    dest: /etc/my_app.conf
    owner: root
    group: root
    mode: '0644'
```
누락된 종속성: 패키지 모듈은 작동하는 리포지토리가 필요합니다. 클라우드 및 네트워크 모듈은 컨트롤 노드에 Python 라이브러리 또는 컬렉션이 필요할 수 있습니다.
멱등성 문제: 사용자 지정 명령은 실행할 때마다 변경 또는 실패를 보고할 수 있습니다. 기본 결과가 실제와 일치하지 않는 경우 changed_when 및 failed_when을 사용하세요.
권한 부족: 작업에 상승된 권한이 필요한 경우 become: yes를 추가하고 원격 사용자가 sudo를 사용할 수 있는지 확인하세요.

3. 구문 오류 및 플레이북 구조

YAML 구문 또는 플레이북의 전체 구조 오류로 인해 실행이 차단될 수 있습니다.

증상:

Syntax Error while loading YAML [...]
ERROR! unexpected indentation in [...]
ERROR! couldn't resolve module/action [...]

원인 및 해결 방법:

YAML 들여쓰기: 탭이 아닌 공백을 사용하세요. 실제 실행 전에 ansible-playbook --syntax-check your_playbook.yml을 실행하세요.
오타 및 누락된 콜론: 콜론이나 따옴표가 누락되면 전체 플레이가 중단될 수 있습니다.
잘못된 모듈 이름: 필요한 경우 ansible.builtin.copy 또는 community.general.ufw와 같은 정규화된 컬렉션 이름을 사용하세요.
잘못된 Jinja2 구문: 잘못된 필터, 누락된 중괄호 및 템플릿의 정의되지 않은 변수는 호스트에 도달하기 전에 작업을 중단시킬 수 있습니다.

4. 변수 및 데이터 문제

잘못 정의되거나 사용된 변수는 예기치 않은 동작이나 작업 실패로 이어질 수 있습니다.

증상:

Variable not defined [...]
Template error [...]
예기치 않은 값으로 실패하는 작업

원인 및 해결 방법:

정의되지 않은 변수: 인벤토리 파일, vars, vars_files, include_vars, 역할 기본값 및 그룹 변수를 확인하세요. debug를 사용하여 Ansible이 보는 값을 확인하세요.
```
- name: 변수 값 디버그
  debug:
    var: my_application_version
```
변수 우선 순위: 추가 변수의 값이 group_vars의 값을 재정의할 수 있습니다. 최종 값이 어디서 오는지 추적하세요.
잘못된 데이터 유형: 숫자 모듈 매개변수의 경우 {{ my_var | int }}와 같이 필요할 때 값을 캐스트하세요.

5. 역할 실행 오류

Ansible 역할을 사용할 때 변수 범위, 핸들러 및 종속성과 관련하여 문제가 발생할 수 있습니다.

증상:

역할 내 작업이 실행되지 않습니다.
역할 내 변수에 예기치 않은 값이 있습니다.
핸들러가 트리거되지 않습니다.

원인 및 해결 방법:

잘못된 역할 포함: 역할이 roles: 아래에 나열되었거나 올바른 경로로 가져왔는지 확인하세요.
변수 범위 지정: 기본값은 defaults/main.yml에, 역할별 변수는 vars/main.yml에, 환경 재정의는 인벤토리에 넣으세요.

핸들러 문제: 핸들러는 작업이 changed를 보고하고 notify를 사용할 때만 실행됩니다.

- name: Nginx 구성
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify: Nginx 재시작

handlers:
  - name: Nginx 재시작
    service:
      name: nginx
      state: restarted

역할 종속성: 역할이 다른 역할에 종속된 경우 meta/main.yml을 확인하고 종속성이 설치되었는지 확인하세요.

6. Ansible Vault 오류

Ansible Vault 문제는 종종 암호화/복호화 실패 또는 잘못된 Vault 비밀번호 처리와 관련됩니다.

증상:

Decryption failed [...]
Encrypted data contains invalid characters.

원인 및 해결 방법:

잘못된 Vault 비밀번호: 올바른 비밀번호 프롬프트 또는 비밀번호 파일을 사용하세요.
```
ansible-playbook -i inventory.ini --ask-vault-pass my_playbook.yml
```
잘못된 암호화: 파일이 ansible-vault encrypt로 암호화되었거나 ansible-vault edit로 편집되었는지 확인하세요.
느슨한 비밀번호 파일 권한: Vault 비밀번호 파일에 대한 액세스를 제한하세요.

문제 해결을 위한 모범 사례

일반 출력이 너무 부족할 때는 -vvv로 실행하세요.
실제 실행 전에 ansible-playbook --syntax-check를 사용하세요.
모듈이 지원하는 경우 --check 모드를 사용하세요.
모든 것을 결합하기 전에 하나의 역할 또는 작업 그룹을 테스트하세요.
플레이북, 인벤토리 및 역할 변경 사항을 버전 관리에 유지하세요.
실패한 실행을 알려진 양호한 실행과 비교할 수 있도록 CI 로그를 저장하세요.

전문가의 도움이 필요할 때

플레이북이 프로덕션 네트워킹을 변경하거나, 시크릿을 순환하거나, 한 번에 많은 호스트를 수정하거나, 배포 중간에 실패하는 경우 시니어 플랫폼 엔지니어의 도움을 받으세요. 실패 모드를 이해하기 전까지 파괴적인 작업을 계속 재실행하지 마세요.

결론

Ansible 문제 해결은 실패한 작업, 모듈 출력 및 인벤토리 대상부터 시작하세요. 그런 다음 문제를 연결, 모듈 사용, YAML 구문, 변수, 역할 또는 Vault로 좁히세요. 이 프로세스를 통해 실제 오류가 이미 출력에 있는 동안 자동화의 관련 없는 부분을 변경하는 것을 방지할 수 있습니다.