26M25a

Young-Kyoo Kim·2026년 3월 25일

Bitbucket을 활용하여 GitOps 방식으로 Ansible 프로젝트를 구성하는 것은 코드를 통해 인프라를 관리하는 가장 표준적인 방법입니다. 처음부터 끝까지, 디렉토리 구조를 잡고 AWX와 연결하는 절차를 단계별로 안내해 드릴게요.

1단계: Bitbucket 리포지토리 생성 및 로컬 복제

가장 먼저 코드를 저장할 공간을 만들고 컴퓨터로 가져와야 합니다.

Bitbucket 웹 접속: 새 리포지토리(Repository)를 생성합니다. (예: ansible-gitops-infra)

로컬로 클론(Clone): 터미널에서 아래 명령어를 실행합니다.

git clone https://bitbucket.org/your-workspace/ansible-gitops-infra.git
cd ansible-gitops-infra

2단계: 표준 디렉토리 구조 생성 (Skeleton)

이제 AWX가 인식하기 좋은 구조로 폴더를 만듭니다. 터미널에서 한 번에 생성하려면 아래 명령어를 참고하세요.

# 주요 폴더 생성
mkdir -p roles collections playbooks group_vars host_vars

필수 파일 생성 (비어있어도 일단 생성)

touch ansible.cfg
touch collections/requirements.yml
touch roles/requirements.yml
touch playbooks/site.yml

3단계: 핵심 설정 파일 작성

AWX가 프로젝트를 가져갔을 때 "어떻게 작동해야 할지" 알려주는 가이드라인입니다.

1) `ansible.cfg` (Ansible 설정)

AWX 내부에서 실행될 때 역할을 찾는 경로 등을 지정합니다.

[defaults]
roles_path = ./roles
collections_path = ./collections
host_key_checking = False

2) `collections/requirements.yml` (의존성 관리)

클라우드(AWS, Azure 등)나 특정 벤더의 모듈이 필요할 때 정의합니다.

---
collections:
  - name: community.general
  - name: ansible.posix

3) `playbooks/site.yml` (메인 실행 파일)

가장 간단한 테스트용 플레이북을 하나 만들어 둡니다.

---
- name: GitOps Connection Test
  hosts: all
  tasks:
    - name: Print Hello Message
      debug:
        msg: "GitOps is working with Bitbucket!"

4단계: Bitbucket에 푸시 (Push)

작성한 구조를 원격 저장소에 반영합니다.

git add .
git commit -m "Initial Ansible structure for GitOps"
git push origin master

5단계: AWX에서 프로젝트 등록 (GitOps 연결)

이제 AWX 웹 UI로 이동하여 이 저장소를 바라보게 설정합니다.

Credentials 등록: Bitbucket에 접근할 수 있는 SSH Key 또는 ID/PW를 AWX의 Credentials 메뉴에서 등록합니다. (Type: Source Control)
Project 생성:
- Name: Bitbucket Infra Project
- SCM Type: Git
- SCM URL: Bitbucket 리포지토리 주소
- SCM Credential: 1번에서 만든 인증 정보 선택
- Options: Update Revision on Launch 체크 (실행할 때마다 최신 코드를 가져옵니다. GitOps의 핵심!)
Sync 실행: 프로젝트 목록에서 구름 모양 아이콘(Sync)을 눌러 성공적으로 코드를 가져오는지 확인합니다.

전체 구조 요약 표

디렉토리/파일	역할	비고
`playbooks/`	실제 실행할 `.yml` 파일들	AWX Job Template에서 선택할 대상
`roles/`	직접 만든 재사용 가능한 역할	기능별로 폴더 분리
`group_vars/`	서버 그룹별 변수 (DB용, Web용 등)	인벤토리 그룹명과 파일명 일치 필요
`requirements.yml`	외부 라이브러리 자동 다운로드 목록	AWX가 Sync 시 자동 설치
`ansible.cfg`	프로젝트별 개별 설정값	우선순위가 높음

이제 Bitbucket의 코드를 수정하고 push만 하면, AWX에서 버튼 클릭 한 번(또는 웹훅 설정 시 자동)으로 변경 사항이 인프라에 반영되는 GitOps 체계가 완성되었습니다.

다음 단계로, Bitbucket에 코드가 푸시될 때 AWX가 자동으로 실행되도록 하는 '웹훅(Webhook)' 연동 방법을 알아볼까요?

===

Bitbucket 리포지토리에 디렉토리 구조를 잡고 AWX 프로젝트와 연결까지 마치셨다면, 이제 실제로 Playbook(YAML)을 AWX에 등록하고 실행하는 단계입니다.

AWX에서는 단순히 파일을 올리는 것이 아니라, 'Job Template(작업 템플릿)'이라는 것을 만들어 실행 환경을 구성해야 합니다. 그 절차를 상세히 안내해 드립니다.

1단계: Bitbucket에 Playbook 업로드 (Push)

가장 먼저 실행할 YAML 파일을 Bitbucket에 올립니다.

로컬의 playbooks/ 폴더에 test_playbook.yml 파일을 작성합니다.
git add, commit, push를 통해 Bitbucket으로 전송합니다.
- 중요: AWX는 Git의 특정 브랜치(보통 master/main)에 올라온 파일만 인식합니다.

2단계: AWX 프로젝트 동기화 (Sync)

Bitbucket에 새 파일이 올라갔다는 것을 AWX가 알게 해야 합니다.

AWX 메뉴에서 Projects로 이동합니다.
이전에 만든 프로젝트 옆의 구름 모양 아이콘(Sync)을 클릭합니다.
'Status'가 Successful이 되면 AWX가 최신 코드를 성공적으로 가져온 것입니다.

3단계: 인벤토리(Inventory) 준비

Playbook을 실행할 대상 서버(대상체)가 정의되어 있어야 합니다.

Inventories 메뉴에서 Add -> Add inventory를 클릭합니다.
이름을 정하고 저장한 뒤, Hosts 탭에서 대상 서버의 IP 주소나 호스트명을 추가합니다.
- (참고: 이미 인벤토리가 있다면 이 단계는 건너뜁니다.)

4단계: 작업 템플릿(Job Template) 생성 (등록의 핵심)

이제 "어떤 인벤토리에 어떤 플레이북을 실행할지" 정의하는 템플릿을 만듭니다. 이 과정이 AWX에 Playbook을 등록하는 과정입니다.

Templates 메뉴에서 Add -> Add job template을 클릭합니다.
아래 주요 항목들을 설정합니다:
- Name: 템플릿 이름 (예: Web Server Deploy)
- Job Type: Run (실행)
- Inventory: 3단계에서 만든 인벤토리 선택
- Project: Bitbucket과 연동된 프로젝트 선택
- Playbook: (매우 중요) 프로젝트를 선택하면, Bitbucket 내부의 .yml 파일들이 드롭다운 목록에 나타납니다. 실행할 파일을 선택하세요.
- Credentials: 서버에 접속할 때 사용할 SSH 키나 암호 정보를 선택합니다.
하단의 Save를 클릭합니다.

5단계: Playbook 실행 및 결과 확인

만든 템플릿 목록 우측의 로켓 모양 아이콘(Launch)을 클릭합니다.
즉시 작업(Job) 화면으로 전환되며, 실시간으로 터미널 로그가 출력됩니다.
- Changed: 설정이 성공적으로 변경됨
- Ok: 이미 설정되어 있어 변경 필요 없음
- Failed: 오류 발생 (로그를 통해 원인 파악 가능)

💡 실무 꿀팁: 수정 후 재실행할 때

만약 Bitbucket에서 Playbook 코드를 수정했다면, 매번 프로젝트 Sync를 누를 필요 없이 템플릿 설정에서 아래 옵션을 체크해 두면 편리합니다.

Job Template 설정 내 'Update Revision on Launch': 이 옵션을 체크하면, 로켓 아이콘을 누를 때마다 AWX가 자동으로 Bitbucket에서 최신 코드를 가져온 뒤 실행합니다. (완전한 GitOps 흐름)

이제 기본적인 등록과 실행이 가능해졌습니다! 혹시 실행 중에 권한 문제(Permission Denied)나 파일을 찾지 못하는 오류가 발생한다면 말씀해 주세요. 바로 해결책을 찾아드리겠습니다.

Young-Kyoo Kim

engineer

이전 포스트

26M24e

다음 포스트

26M25a

1단계: Bitbucket 리포지토리 생성 및 로컬 복제

2단계: 표준 디렉토리 구조 생성 (Skeleton)

필수 파일 생성 (비어있어도 일단 생성)

3단계: 핵심 설정 파일 작성

1) `ansible.cfg` (Ansible 설정)

2) `collections/requirements.yml` (의존성 관리)

3) `playbooks/site.yml` (메인 실행 파일)

4단계: Bitbucket에 푸시 (Push)

5단계: AWX에서 프로젝트 등록 (GitOps 연결)

전체 구조 요약 표

1단계: Bitbucket에 Playbook 업로드 (Push)

2단계: AWX 프로젝트 동기화 (Sync)

3단계: 인벤토리(Inventory) 준비

4단계: 작업 템플릿(Job Template) 생성 (등록의 핵심)

5단계: Playbook 실행 및 결과 확인

💡 실무 꿀팁: 수정 후 재실행할 때

26M24e

26M25b

0개의 댓글

26M25a

1단계: Bitbucket 리포지토리 생성 및 로컬 복제

2단계: 표준 디렉토리 구조 생성 (Skeleton)

필수 파일 생성 (비어있어도 일단 생성)

3단계: 핵심 설정 파일 작성

1) ansible.cfg (Ansible 설정)

2) collections/requirements.yml (의존성 관리)

3) playbooks/site.yml (메인 실행 파일)

4단계: Bitbucket에 푸시 (Push)

5단계: AWX에서 프로젝트 등록 (GitOps 연결)

전체 구조 요약 표

1단계: Bitbucket에 Playbook 업로드 (Push)

2단계: AWX 프로젝트 동기화 (Sync)

3단계: 인벤토리(Inventory) 준비

4단계: 작업 템플릿(Job Template) 생성 (등록의 핵심)

5단계: Playbook 실행 및 결과 확인

💡 실무 꿀팁: 수정 후 재실행할 때

26M24e

26M25b

0개의 댓글

1) `ansible.cfg` (Ansible 설정)

2) `collections/requirements.yml` (의존성 관리)

3) `playbooks/site.yml` (메인 실행 파일)