pyinfra — 에이전트 없는 인프라 자동화, 순수 Python으로

• 서버 자동화 작업을 Python 코드로 작성하고 SSH로 병렬 실행해, 에이전트 없이 명령을 멱등적으로 수행함
• pyinfra는 동일 워크로드에서 Ansible보다 6배 빠름을 내세우며, gevent와 SSH 기반 동시 실행을 사용함
• --dry 옵션으로 적용 전 호스트별 변경 diff를 확인하고, 실제 실행 시 결과가 병렬 스트리밍으로 돌아옴
• 대상 호스트에는 shell과 SSH만 필요하며, 데몬·상태 파일·컨트롤 플레인이 없음
• YAML로 제어 흐름을 인코딩하지 않고 Python의 루프와 조건문을 그대로 쓰는 코드 중심 구성을 강조함

핵심 기능과 실행 흐름

• 수천 대 서버 자동화

  • pyinfra는 Python-native, agentless 자동화 도구이며 SSH로 명령을 실행함
  • 명령 실행은 동시성, 멱등성, 속도를 강조하며, 동일 워크로드에서 Ansible보다 6배 빠름을 내세움
  • 설치 명령은 $ uv tool install pyinfra임
  • 표기된 기본 조건은 MIT license, Python 3.10 이상, no agents, zero config임

• 배포 코드 예시

  • apt, files, systemd 작업을 Python 코드로 불러와 패키지 설치, 템플릿 배치, 서비스 재로드를 수행함
  • 예시 코드는 nginx와 certbot 패키지를 설치하고, templates/nginx.conf.j2를 /etc/nginx/sites-enabled/api로 배치함
  • 마지막 단계에서 systemd.service("nginx", reloaded=True)로 nginx 서비스를 재로드함
  from pyinfra.operations import apt, files, systemd apt.packages( packages=["nginx", "certbot"], update=True, ) files.template( src="templates/nginx.conf.j2", dest="/etc/nginx/sites-enabled/api", ) systemd.service("nginx", reloaded=True)

• 인벤토리와 실행 결과

  • 인벤토리 예시는 web-01.prod부터 web-23.prod까지의 웹 호스트와 db-01.prod, db-02.prod 데이터베이스 호스트를 구성함
  • $ pyinfra inventory.py deploy.py --limit web 명령은 web 대상만 제한해 실행함
  • 실행 출력은 인벤토리 로딩, 동시 fact 수집, deploy.py 실행, 요약 순서로 진행됨
  • 예시 요약은 23개 호스트 성공, 18개 변경, 실패 0개, 총 2.1초를 기록함

• 변경 전 확인

  • --dry는 pyinfra가 수행할 모든 작업의 호스트별 diff를 먼저 확인하게 함
  • 실제 실행에서는 결과가 병렬로 스트리밍되어 각 호스트의 변경 수와 실행 시간이 표시됨
  • 예시 실행은 24개 호스트 중 18개 변경, 6개 무변경, 실패 0개, 총 2.1초를 기록함

특징, Ansible 비교, 원칙

• pyinfra를 선택하는 여섯 가지 이유

  • Just Python: YAML과 Jinja-in-YAML 없이 실제 제어 흐름을 Python으로 작성함
  • Concurrent SSH: gevent와 SSH 기반으로 동시 실행하며, 동일 워크로드에서 Ansible보다 6배 빠름
  • Diff before apply: --dry로 모든 변경을 미리 보고, 멱등 작업은 재실행 시 no-op이 됨
  • 0 agents: 호스트에는 shell과 SSH만 필요하며, 데몬·상태 파일·컨트롤 플레인이 없음
  • Scale-ready: 1개 호스트부터 10,000개 호스트까지 동작하고, 병렬 실행과 실시간 스트리밍 출력을 지원함
  • Hackable: 10줄로 커스텀 작업을 만들 수 있고, shell과 통신하는 docker, lxc, k8s에 연결할 수 있음

• Ansible과 pyinfra 코드 비교

  • Ansible 예시는 playbook.yml 16줄로 nginx 설치, 템플릿 렌더링, 핸들러 기반 서비스 재로드를 구성함
  • pyinfra 예시는 deploy.py 8줄로 같은 흐름을 Python 코드로 작성함
  • pyinfra 예시는 files.template 결과의 cfg.will_change가 참일 때만 systemd.service("nginx", reloaded=True)를 실행함
  from pyinfra.operations import apt, files, systemd apt.packages(["nginx"], update=True) cfg = files.template( src="nginx.conf.j2", dest="/etc/nginx/sites-enabled/api", ) if cfg.will_change: systemd.service("nginx", reloaded=True)

• 선언문

  • Code > config: 루프는 루프 그대로이며, 제어 흐름을 YAML에 인코딩하지 않음
  • Show, then do: diff를 먼저 보고, 그다음 적용해 예기치 않은 변경을 피함
  • Stay out of the way: 에이전트, 상태 파일, 컨트롤 플레인 없이 SSH로 바로 실행함
  • Read like english: 작업은 apt.packages, files.template, systemd.service처럼 명사와 동사 형태로 읽힘

• 시작 명령

  • 설치 명령은 $ uv tool install pyinfra임
  • 5분 quickstart를 읽고 첫 호스트를 배포하라는 안내가 제공됨