ansible-directory-structure

Ansible에서 inventory, playbooks, roles를 포함한 디렉토리 구조는 가독성과 재사용성, 유지보수 용이성, 환경 분리, 역할 명확화 등을 위해 표준적인 구조로 구성하는 것이 좋습니다. 아래에 실무에서 가장 널리 쓰이는 디렉토리 구조 예시와 각 구성요소의 역할을 설명드릴게요.

📁 Best Practice 디렉토리 구조⚑

ansible-project/
├── inventories/
│   ├── production/
│   │   ├── hosts.yml
│   │   └── group_vars/
│   │       ├── all.yml
│   │       ├── web.yml
│   │       └── db.yml
│   └── staging/
│       ├── hosts.yml
│       └── group_vars/
├── playbooks/
│   ├── site.yml
│   ├── web.yml
│   ├── db.yml
│   └── k3s-cluster.yml
├── roles/
│   ├── common/
│   │   ├── tasks/
│   │   └── templates/
│   ├── k3s/
│   ├── helm/
│   ├── argocd/
│   └── app/
├── files/
│   └── custom-configs/
├── templates/
│   └── nginx.conf.j2
├── group_vars/
│   └── all.yml
├── ansible.cfg
└── requirements.yml

🧩 각 구성요소 설명⚑

1. inventories/⚑

• 환경별 인벤토리 정의 (예: production, staging)

• 각 환경별 hosts.yml + group_vars/ 구조로 나눠 유지보수 용이

• 🔑 SSH 정보, 변수 설정, 호스트 그룹화 등을 설정

ansible-playbook -i inventories/production/hosts.yml playbooks/site.yml

2. playbooks/⚑

• 실제 실행될 플레이북 YAML 파일 위치

• 보통 역할(role)을 묶는 상위 단위의 orchestration 역할 수행

• 예: web.yml, k3s-cluster.yml, deploy-app.yml

- name: Web setup
  hosts: web
  roles:
    - common
    - nginx

3. roles/⚑

• Ansible의 핵심 재사용 단위

• 각 역할(role)은 독립적인 기능 단위 (예: k3s, helm, argocd)

• 하위 디렉토리로 분리:

roles/helm/
├── tasks/main.yml
├── defaults/main.yml
├── files/
├── templates/
├── handlers/main.yml
└── vars/main.yml

• 다른 프로젝트에서도 재사용 가능

4. group_vars/, host_vars/⚑

• 그룹 또는 개별 호스트 단위 변수 설정

• group_vars/all.yml: 모든 환경에 공통 적용되는 변수

예: group_vars/web.yml

nginx_port: 80

5. files/, templates/⚑

• files/: 그대로 복사할 파일들

• templates/: Jinja2 문법 사용하여 변수를 동적으로 넣을 수 있는 템플릿

6. ansible.cfg⚑

• Ansible 실행에 대한 설정을 정의

• 예: 기본 inventory, ssh args, roles_path 등

[defaults]
inventory = inventories/production/hosts.yml
roles_path = roles

✅ 운영 기준 요약⚑

🧠 TIP⚑

• 로컬에서 관리하다가 클라우드로 확장할 계획이라면 이 구조는 그대로 확장 가능

• 역할만 추가하고, inventory만 클라우드에 맞게 늘리면 됨