arillso/action.playbook: Ansible 플레이북 실행 액션

원문 발행 2026. 10. 24. 09:44원문 언어 영어AI 한국어 번역GitHub AI Tools 원문 보기

요약

이 GitHub Action은 GitHub Actions 워크플로우 내에서 Ansible Playbook을 실행할 수 있도록 지원합니다. Ansible Galaxy 통합, 자동 SSH 인증, 그리고 Vault 비밀번호 처리를 포함한 포괄적인 구성 옵션을 제공하여 안전하고 유연한 인프라 구성을 가능하게 합니다.

핵심 포인트

GitHub Actions 환경에서 Ansible Playbook 실행을 지원합니다.
Ansible Galaxy 통합 기능을 통해 역할 및 컬렉션 설치가 용이합니다.
SSH 인증과 Vault 지원으로 보안성이 강화된 배포가 가능합니다.
인벤토리, 태그, 변수 등 다양한 옵션을 제공하여 유연한 제어가 가능합니다.

Action: Ansible Playbook 실행

Galaxy, SSH, Vault 및 권한 상승(privilege escalation)을 위한 포괄적인 구성 옵션을 갖춘 Ansible Playbook을 실행하는 GitHub Action입니다.

기능 (Features)

Ansible Playbook 실행: GitHub Actions 워크플로우에서 Ansible playbook 실행
Galaxy 통합: Ansible Galaxy에서 역할(roles) 및 컬렉션(collections) 설치
SSH 인증: 자동 SSH 키 정규화 및 인증
Vault 지원: Ansible Vault 비밀번호의 안전한 처리
유연한 구성: 인벤토리, 태그, 변수 등에 대한 포괄적인 옵션 제공

입력값 (Inputs)

galaxy_file

Ansible Galaxy 요구사항 파일의 경로를 지정합니다.

galaxy_force

Galaxy 파일에서 역할이나 컬렉션을 강제로 재설치합니다.

galaxy_api_key

Ansible Galaxy 인증에 사용되는 API 키를 설정합니다.

galaxy_api_server_url

상호 작용할 Ansible Galaxy API 서버의 URL을 정의합니다.

galaxy_collections_path

Galaxy 컬렉션이 저장된 디렉토리 경로를 설정합니다.

galaxy_disable_gpg_verify

Ansible Galaxy 작업에 대한 GPG 서명 검증을 비활성화합니다.

galaxy_force_with_deps

Galaxy에서 의존성을 포함하여 컬렉션을 강제로 설치합니다.

galaxy_ignore_certs

Ansible Galaxy 요청에 대해 SSL 인증서 유효성 검사를 무시합니다.

galaxy_ignore_signature_status_codes

Galaxy 서명 검증 중 무시할 HTTP 상태 코드를 나열합니다.

galaxy_keyring

Ansible Galaxy와 함께 사용되는 GPG 키링의 경로를 지정합니다.

galaxy_offline

오프라인 모드를 활성화하여 Ansible Galaxy로의 모든 요청을 방지합니다.

galaxy_pre

Ansible Galaxy에서 프리릴리스(pre-release) 버전 설치를 허용합니다.

galaxy_required_valid_signature_count

Galaxy 콘텐츠에 필요한 유효한 GPG 서명의 개수를 설정합니다.

galaxy_requirements_file

Ansible Galaxy 요구사항 파일의 경로를 정의합니다.

galaxy_signature

Galaxy 콘텐츠에 대해 검증할 특정 GPG 서명을 지정합니다.

galaxy_timeout

Ansible Galaxy 작업에 대한 타임아웃을 초 단위로 설정합니다.

galaxy_upgrade

Galaxy 컬렉션을 최신 버전으로 자동 업그레이드할 수 있게 합니다.

galaxy_no_deps

Ansible Galaxy에서 의존성(dependencies)의 자동 해결을 비활성화합니다.

inventory

필수 항목. Ansible이 사용할 하나 이상의 인벤토리 호스트 파일을 지정합니다.

playbook

필수 항목. 적용할 플레이북 목록입니다.

limit

선택된 호스트를 추가 패턴으로 더욱 제한합니다.

skip_tags

지정된 값을 태그로 가지지 않는 플레이와 태스크만 실행합니다.

start_at_task

이 이름과 일치하는 태스크에서 플레이북을 시작합니다.

extra_vars

플레이북에 추가 변수를 key=value 형식으로 설정합니다.

module_path

지정된 경로를 모듈 라이브러리 경로 목록 앞에 붙입니다.

check

실제 변경을 가하지 않고 어떤 변경이 이루어질지 보여주는 건식 실행(dry run)을 수행합니다.

diff

파일과 템플릿을 변경할 때의 차이점을 보여줍니다.

flush_cache

인벤토리 내 모든 호스트에 대해 사실 캐시(fact cache)를 지웁니다.

force_handlers

태스크가 실패하더라도 모든 핸들러를 실행합니다.

list_hosts

일치하는 호스트 목록을 출력합니다.

사용 가능한 모든 태그를 나열합니다.

list_tasks

실행될 모든 태스크를 나열합니다.

syntax_check

플레이북을 실행하지 않고 구문 검사(syntax check)를 수행합니다.

forks

플레이북 실행 중 사용할 병렬 프로세스 수를 정의합니다.

vault_id

Ansible Vault에 접근할 때 사용할 ID를 지정합니다.

vault_password

사용할 볼트 비밀번호입니다. 이 값은 Github의 Secret에 저장되어야 합니다.

verbose

상세도를 설정하며, 0(최소 출력)부터 4(최대 상세도)까지 범위가 있습니다.

private_key

연결을 위한 SSH 개인 키 내용을 지정합니다. 액션이 임시 파일로 이 키를 작성합니다. 이 값은 Github의 Secret에 저장되어야 합니다.

v1.2.0부터 시작: 이 액션은 SSH 키를 자동으로 정규화합니다 (CRLF를 LF로 변환하고, 트레일링 개행 문자(trailing newlines)를 추가하며, 형식을 검증합니다).

참고: 이전 버전에서 배스천 호스트(bastion host) 또는 ProxyCommand 관련 문제가 발생하면, 해결 방법은 SSH 인증 (SSH Authentication) 섹션을 참조하십시오.

user

연결을 수행할 사용자 이름을 정의합니다.

connection

사용할 연결 유형을 설정합니다 (예: SSH).

timeout

기본 연결 타임아웃 시간을 초 단위로 재정의합니다.

ssh_common_args

모든 SSH 기반 연결 방식(SSH, SCP, SFTP)에 전달할 공통 인수를 지정합니다.

sftp_extra_args

SFTP에만 전달할 추가 인수를 제공합니다.

scp_extra_args

SCP에만 전달할 추가 인수를 제공합니다.

ssh_extra_args

SSH에만 전달할 추가 인수를 제공합니다.

become

권한 상승(privilege escalation)을 활성화하여 다른 사용자로 작업을 실행할 수 있게 합니다.

become_method

권한 상승에 사용할 방법을 지정합니다 (예: sudo).

become_user

권한 상승 시 사칭할 사용자(impersonate)를 설정합니다.

config_file

사용할 ansible.cfg 구성 파일의 경로입니다 (ANSIBLE_CONFIG 설정).

no_color

색상 출력을 비활성화합니다.

output_callback

Ansible 출력용 표준 출력(stdout) 콜백 플러그인을 설정합니다 (예: yaml, json, minimal).

callbacks_enabled

활성화된 콜백 플러그인의 쉼표로 구분된 목록입니다 (예: profile_tasks,timer).

strategy_plugin

사용할 전략 플러그인을 지정합니다 (예: linear, free, mitogen_linear).

gather_subset

수집되는 사실(facts)의 범위를 제한합니다 (예: !all,!min,network).

gather_timeout

사실 수집에 대한 타임아웃 시간입니다 (초 단위, 0-3600, 0 = ansible 기본값).

fact_path

호스트 사실로 로드될 로컬 사실 파일의 경로입니다.

fact_caching

사실 수집에 사용할 캐싱 방법입니다 (예: jsonfile, redis, memory).

fact_caching_timeout

사실 캐시의 타임아웃 시간입니다 (초 단위, 0 = 만료 없음).

poll_interval

비동기 작업(async tasks) 폴링 간격입니다 (초 단위, 0-3600, 0 = ansible 기본값).

max_fail_percentage

플레이북이 중단되기 전에 실패할 수 있는 최대 호스트 비율(0-100)입니다.

any_errors_fatal

모든 작업 오류를 치명적인 것으로 간주하여 전체 플레이를 중단합니다.

ssh_transfer_method

SSH를 통한 파일 전송 방법(예: scp 또는 sftp)입니다.

vault_password_file

볼트 비밀번호를 포함하는 파일의 경로입니다 (vault_password의 대안).

private_key_file

SSH 개인 키가 포함된 파일의 경로입니다 (private_key의 대안).

temp_dir

Ansible 임시 파일을 위한 디렉토리입니다.

고급 설정 (Advanced Configuration)

기본 입력 외에도, 이 액션은 Ansible의 고급 실행 옵션을 노출합니다. 각 입력은 또한 ANSIBLE_<INPUT_NAME_UPPERCASE>라는 이름의 환경 변수에서도 읽을 수 있으므로, 아래 두 형식은 동일하며 — with:를 통해 액션 입력으로 설정하거나 env:를 통해 환경 변수로 설정할 수 있습니다.

주의사항: 액션의 'ANSIBLE_<INPUT_NAME>' 철자를 사용하고, Ansible 자체의 네이티브 변수 이름은 사용하지 마십시오. 몇 가지는 다릅니다: 'strategy_plugin' → 'ANSIBLE_STRATEGY_PLUGIN' (Ansible의 네이티브 변수는 'ANSIBLE_STRATEGY'), 'fact_caching' → 'ANSIBLE_FACT_CACHING' (네이티브: 'ANSIBLE_CACHE_PLUGIN'), 'config_file' → 'ANSIBLE_CONFIG_FILE' (네이티브: 'ANSIBLE_CONFIG').

- name: Deploy with advanced Ansible tuning
  uses: arillso/action.playbook@master
  with:
...

참고: 'fact_caching: jsonfile' 역시 캐시 디렉토리가 필요합니다. 이는 'env: { ANSIBLE_CACHE_PLUGIN_CONNECTION: /tmp/ansible_facts }' 또는 사용자 지정 'config_file'을 통해 설정할 수 있습니다. 전용 입력이 없는 플러그인별 옵션은 항상 'env:'를 통하거나 'config_file'에 의해 참조되는 'ansible.cfg'를 통해 접근 가능합니다.

SSH 인증 (SSH Authentication)

✨ v1.2.0 이상에서 신규 추가됨:

SSH 개인 키는 자동으로 정규화됩니다:

Windows 줄 바꿈(CRLF) → Unix 형식(LF)

누락된 후행 개행 문자가 추가됩니다

형식 검증 (RSA, OpenSSH, EC, DSA)

기본 사용법 (Basic Usage)

- name: Deploy with Ansible
  uses: arillso/[email protected]
  with:
...

GitHub Secrets에 SSH 키 저장하기

🔒 보안 경고: 개인 SSH 키를 절대 리포지토리에 커밋하지 마십시오!

리포지토리의 설정 (Settings) → Secrets and variables → Actions로 이동합니다.
**"New repository secret"**을 클릭합니다.
이름(Name): SSH_PRIVATE_KEY
값(Value): 개인 키 전체를 붙여넣습니다 ( -----BEGIN/END----- 헤더 포함).
**"Add secret"**을 클릭합니다.

키는 적절한 PEM 헤더(-----BEGIN RSA PRIVATE KEY----- 또는 유사)를 가지고 있어야 합니다. 줄 바꿈 및 후행 개행 문자는 v1.2.0 이상에서 자동으로 수정됩니다.

문제 해결 (Troubleshooting)

버전 1.2.0 미만이거나 예외적인 경우, extra_vars를 사용하여 키 파일 경로를 전달하십시오:

- name: Setup SSH Key
  run: |
    echo "${{ secrets.SSH_PRIVATE_KEY }}" > /tmp/ssh_key
...

상세한 SSH 디버깅을 위해서는 액션 입력에 verbose: 4를 설정하십시오.

사용 예시 (Example Usage)

- name: Play Ansible Playbook
  uses: arillso/action.playbook@master
  with:
...

라이선스 (License)

본 프로젝트는 MIT License 하에 있습니다. 전체 라이선스 텍스트는 LICENSE 파일을 참조하십시오.

AI 자동 생성 콘텐츠

원문 바로가기