pulp-console/PULP_INTEGRATION.md

실제 Pulp 연동 가이드

이 콘솔은 BFF로서 실제 Pulp 3 서버의 REST API(/pulp/api/v3/)에 붙어 동작한다. 지금까지 본 화면은 PULP_DEMO=true(가짜 인메모리 데이터)였고, 실연동하려면 Pulp 서버 + 환경변수가 필요하다. 이 문서는 그 절차와, 실서버에서 흔히 보정이 필요한 지점을 정리한다.

---

0. 준비물

• Pulp 3 서버 (RPM 플러그인 pulp_rpm 설치; DEB면 pulp_deb)
• Pulp admin 계정(또는 API 권한 계정) — 사용자/비밀번호
• 콘솔이 Pulp 주소에 네트워크 도달 가능할 것
• (선택) Postgres — 배포 감사 로그(deploy_audit) 저장용 DATABASE_URL
• 사내 HTTPS Pulp면 사내 CA(.pem) 또는 검증 끄기 옵션

---

1. (테스트용) Pulp 서버 빠르게 띄우기

실서버가 없으면 컨테이너로 올인원 Pulp를 띄워 테스트할 수 있다(podman/docker 동일).

mkdir -p ~/pulp/{settings,pgsql,storage}
podman run -d --name pulp -p 8080:80 \
  -v ~/pulp/settings:/etc/pulp \
  -v ~/pulp/pgsql:/var/lib/pgsql \
  -v ~/pulp/storage:/var/lib/pulp \
  docker.io/pulp/pulp

# 기동까지 1~2분. admin 비밀번호 설정:
podman exec -it pulp pulpcore-manager reset-admin-password

• API 주소: http://localhost:8080/pulp/api/v3/
• 상태 확인: curl -u admin:<pw> http://localhost:8080/pulp/api/v3/status/

폐쇄망 운영 Pulp는 인프라팀이 구축한 주소/계정을 그대로 쓰면 된다(위 컨테이너는 개발 검증용).

---

2. 화면에 보일 콘텐츠 만들기 (Remote → Repository → Distribution)

대시보드에 저장소가 보이려면 Pulp에 Repository가 있어야 하고, 동기화하려면 Remote가, 배포하려면 Distribution이 있어야 한다. pulp CLI(pip install pulp-cli)로 RPM 예시:

# pulp CLI 설정 (한 번)
pulp config create --base-url http://localhost:8080 --username admin --password <pw>

# 1) Remote (외부 미러 소스 정의) — 검증을 켜려면 gpgkey/tls_validation 설정
pulp rpm remote create --name rocky9-baseos \
  --url https://dl.rockylinux.org/pub/rocky/9/BaseOS/x86_64/os/

# 2) Repository (그릇) + remote 연결
pulp rpm repository create --name rocky9-baseos --remote rocky9-baseos \
  --autopublish      # 동기화 후 자동 publication (배포 단계 단순화에 도움)

# 3) (콘솔에서 동기화해도 되고) CLI 동기화로 첫 스냅샷 생성
pulp rpm repository sync --name rocky9-baseos

# 4) Distribution (운영이 보는 공개 URL) — 배포 확정이 PATCH 할 대상
pulp rpm distribution create --name rocky9-baseos \
  --base-path rocky9-baseos --repository rocky9-baseos

• 이렇게 하면 콘솔 대시보드에 rocky9-baseos가 뜨고, 동기화/버전 목록/배포 확정을 UI에서 시험할 수 있다.
• 배포 확정은 Distribution을 특정 publication으로 교체하므로, distribution이 미리 있어야 한다. --autopublish + distribution을 repository에 연결해두면 우리 콘솔의 역추적(publication→version)이 잘 맞는다.

---

3. 콘솔 환경변수 설정

.env(루트, git 미추적) 또는 실행 환경에 설정. PULP_DEMO는 빼거나 false.

PULP_BASE_URL=http://localhost:8080        # 실제 Pulp 주소
PULP_USERNAME=admin
PULP_PASSWORD=********                      # 비밀번호 (커밋 금지)
PULP_VERIFY_TLS=true                        # 사내 HTTPS+CA면 PULP_CA_FILE 사용
PULP_CA_FILE=/path/boknet-ca.pem            # 사내 self-signed CA 경로(있을 때만)
DATABASE_URL=postgresql://...               # 배포 감사 로그용(없으면 배포는 되나 기록 실패 경고)
# PULP_DEMO 미설정

비밀번호/DATABASE_URL은 코드/깃에 두지 않는다. Coolify 배포 시엔 Environment Variables에 넣는다.

---

4. 실행 & 확인

.venv/Scripts/python.exe -m uvicorn app.main:app --reload    # Windows

확인	기대
GET /healthz	{"ok": true} (앱 생존, Pulp와 무관)
GET /pulp-status	🟢 "Pulp 연결됨" (실패 시 사유 표시)
대시보드 /	실제 저장소 목록·검증 배지·패키지 수
동기화 버튼	sync task 시작 → 진행률 폴링 → 새 버전
버전 페이지	스냅샷 목록 + 현재 배포 버전 배지
배포 확정	publication 생성 → distribution 교체 → 감사 로그

---

5. 실서버 첫 연동 시 보정 체크리스트

스펙/일반적 Pulp 구조 기준으로 구현했으므로, 실제 응답 형태에 따라 아래가 안 맞을 수 있다. 각 항목이 이상하면 해당 코드를 실제 JSON에 맞춰 조정한다.

증상	확인할 Pulp 필드	고칠 곳
검증 배지가 항상 ⚪/⚠️	repository.repo_config의 gpgcheck / repo-gpgcheck 키 형태	app/views.py gpg_status()
패키지 수·증감이 0	version.content_summary.present/added/removed 구조	app/views.py _content_count()
"현재 배포 버전" 배지가 안 뜸	distribution.publication 유무 / publication.repository_version 경로, 또는 distribution이 repository 직접 배포(최신 추종)	app/routes/versions.py _deployed_version_number(), app/routes/deploy.py _distribution_for_repo()
동기화 진행률/완료 안 잡힘	task의 progress_reports[], created_resources[], state	app/views.py task_progress()
배포가 distribution을 못 찾음	repo↔distribution 매핑 규칙	app/routes/deploy.py _distribution_for_repo()

실서버 응답을 한 번 떠보면 빠르다: curl -u admin:<pw> http://<pulp>/pulp/api/v3/repositories/rpm/rpm/ | jq.

---

6. 트러블슈팅

• /pulp-status 연결 실패 → 주소/포트/방화벽, HTTPS면 CA(PULP_CA_FILE) 또는 임시로 PULP_VERIFY_TLS=false.
• 401 Unauthorized → PULP_USERNAME/PULP_PASSWORD 확인.
• 대시보드가 비어 있음 → Pulp에 Repository가 없거나 RPM 플러그인 미설치. §2로 콘텐츠 생성.
• 배포 버튼 비활성 → 해당 저장소가 검증(pass) 상태가 아님(= remote에 gpgkey/tls_validation 미설정 → repo_config에 gpgcheck 없음). 의도된 안전장치.
• "감사 로그 기록 실패" → DATABASE_URL 미설정/접속 불가. 배포 자체는 성공.

---

7. DEB(Ubuntu/Debian) 저장소

현재 라우트는 RPM(/repositories/rpm/rpm/ 등) 경로에 맞춰져 있다. DEB는 rpm/rpm 자리를 deb/apt로 바꾸면 된다 — app/pulp_client.py의 경로를 콘텐츠 타입으로 파라미터화하면 양쪽을 지원할 수 있다(1차 MVP는 RPM 집중).