Fullmoon System

AWX Git 동기화 실패 해결: 읽기 전용 SSH 명령과 실행환경 점검

AI_Manager

AWX Project를 내부 Git 저장소에 연결했지만 동기화가 실패했다. 로그에는 권한과 저장소 경로를 확인하라는 안내가 있었고, 실제 단서는 그 앞의 fatal: bad argument였다. SSH 키를 새로 만들기 전에 서버가 허용한 Git 명령과 경로 인용 방식을 확인해 해결했다.

사용 기술·서비스: AWX 24.6.1 · Git · OpenSSH · git-shell · K3s · Execution Environment

이 글의 순서

  1. 1. 증상: SSH 접속 이후 Git 저장소를 읽지 못한다
  2. 2. 원인과 수정: 저장소 경로까지 정확하게 인용한다
  3. 3. 호스트에서 성공해도 AWX 실행환경을 따로 확인한다
  4. 4. 수정 후 확인: 성공 상태와 가져온 커밋을 함께 본다

1. 증상: SSH 접속 이후 Git 저장소를 읽지 못한다

AWX는 git ls-remote 단계에서 실패했다. 아래는 실제 작업 로그에서 임시 경로와 접속 문자열을 제외한 오류 발췌다.

fatal: bad argument
fatal: Could not read from remote repository.

이 실습의 Git 계정은 일반 관리 계정과 달리 저장소 읽기만 허용했다. 공개키에 강제 명령을 연결하고 로그인 셸은 git-shell을 사용했다. 따라서 키가 맞는지만 볼 것이 아니라, 인증 후 실행하도록 제한한 명령이 올바른지도 확인해야 했다.

2. 원인과 수정: 저장소 경로까지 정확하게 인용한다

초기 강제 명령의 저장소 인자 형식이 git-shell에서 처리되는 방식과 맞지 않았다. git-upload-pack 뒤의 경로를 작은따옴표로 감싸고, authorized_keys의 command 전체는 큰따옴표로 감쌌다.

restrict,command="git-upload-pack '/srv/git/fullmoon-automation.git'" ssh-ed25519 <AWX_읽기전용_공개키>

git-upload-pack은 clone·fetch에 사용하는 읽기 경로다. 이 공개키에 임의 셸이나 push 권한을 추가하지 않았다. 명령을 제한하는 셸의 동작은 Git 공식 git-shell 문서를 참고했다. 위 키 설정은 예시이며 실제 공개키로 교체하고 해당 계정의 소유권·파일 권한도 유지해야 한다.

설정 후에는 일반 셸 접속 성공을 기준으로 삼지 않는다. 이 계정은 셸 사용을 제한했으므로, AWX가 실제 사용하는 저장소 읽기 동작으로 검증한다.

# 검증된 SSH host key와 읽기 전용 키가 설정된 관리 환경에서 실행
git ls-remote \
  ssh://fmlgit@git.fullmoon.test/srv/git/fullmoon-automation.git \
  refs/heads/main

3. 호스트에서 성공해도 AWX 실행환경을 따로 확인한다

AWX의 실행환경은 플레이북과 연동 도구를 실행하는 컨테이너 이미지다. 관리 VM에서 Git이나 NetBox API에 연결된다고 해서 AWX 컨테이너 안에서도 동일하게 동작하는 것은 아니다. 내부 DNS, SSH host key, HTTPS CA, collection 버전을 별도로 준비했다.

이 실습에서는 awx-ee:24.6.1을 기반으로 netbox.netbox:3.23.0, 공개 CA, 검증한 SSH host key를 포함한 이미지를 만들었다. 이미지를 Docker에서 만들고 K3s의 containerd에도 반입했다. AWX가 사용하는 이미지 이름과 반입된 이름을 일치시켰다.

# 완성한 실행환경 archive를 K3s에서 사용하도록 반입
sudo /usr/local/bin/k3s ctr images import fullmoon-ee-r2.tar
sudo /usr/local/bin/k3s ctr images list

온라인망에서는 준비 구간에서 필요한 의존성을 받아 이미지를 완성한다. 폐쇄망에서는 이미지·Git 데이터·CA·승인한 host key를 함께 반입하고, 작업 중 외부 다운로드에 의존하지 않게 한다. 실습 이미지의 localhost/ 접두부는 이미지 이름일 뿐, 로컬 레지스트리를 별도로 운영한다는 뜻은 아니다.

4. 수정 후 확인: 성공 상태와 가져온 커밋을 함께 본다

강제 명령 수정 후 Project 동기화가 성공했고 scm_revision에 가져온 커밋이 기록됐다. 초기 성공 커밋은 acf6bb6으로 시작했다. 이후 플레이북 수정이 이어졌으므로 이 값을 현재 최신 커밋으로 고정해 사용하지는 않는다.

확인 항목 결과
읽기 전용 SSH 명령 저장소 읽기 성공
AWX Project 동기화 성공
실제 Git 커밋 식별값 확인
후속 NetBox 인벤토리 갱신 성공
대상 온보딩 작업 성공

문제가 재발하면 Git URL·브랜치, SSH 인증, 강제 명령, 실행환경 순으로 점검한다. Could not read from remote repository라는 마지막 문장만 보고 계정 권한을 넓히지 않는 것이 핵심이다.