Docker 배포

빌드된 컨테이너 이미지를 Docker 또는 Podman 런타임에 배포하는 방법을 안내합니다. KIOPS의 Docker 배포는 docker-compose 기반으로 동작하며, 단일 서비스부터 여러 컨테이너가 결합된 멀티 서비스 스택까지 동일한 흐름으로 배포할 수 있습니다.

왜 이 가이드를 읽어야 하는가

이 가이드를 따라가면 K8s 클러스터 없이도 단일 서버에 docker-compose 기반으로 서비스를 배포하고, 배포 직전 자동 백업으로 안전망을 확보할 수 있습니다. 비개발 운영팀은 "이미지 버전 선택 → 연결 방식 선택 → 배포 버튼" 3단계만 따라가면 되며, 세부 설정이 필요할 때만 docker-compose 편집 모드를 사용합니다.

Docker 배포와 Kubernetes 배포 비교

Docker 배포

• 복잡도: 간단함
• 확장성: 제한적
• 고가용성: 수동 구성 필요
• 추천 환경: 개발, 테스트, 소규모

Kubernetes 배포

• 복잡도: 복잡함
• 확장성: 자동 확장 지원
• 고가용성: 기본 지원
• 추천 환경: 스테이징, 프로덕션

---

시작하기 전에: 알아둘 용어

본문에 들어가기 전에 자주 등장하는 용어를 한 줄씩 정리합니다. 본문에서 처음 등장할 때 "(용어 사전 참고)" 안내를 함께 표시합니다.

용어	정의
컨테이너	앱 하나를 격리해서 실행하는 격리 박스.
이미지	컨테이너를 만들기 위한 스냅샷(틀).
Docker Compose	여러 컨테이너의 실행 정의를 한 YAML 파일로 묶어 한 번에 띄우는 도구.
볼륨	컨테이너 재시작 후에도 유지되는 데이터 저장 공간.
환경 변수	컨테이너 실행 시 주입되는 설정값(예: DATABASE_URL).
자동 백업	배포 직전 현재 컨테이너/볼륨 상태를 보관하는 KIOPS 기능.

사전 요구사항

배포를 시작하기 전에 다음을 확인하세요:

• Docker/Podman 런타임 등록: [런타임 환경] 페이지에 Docker 또는 Podman 런타임이 등록되어 있어야 합니다.
• 이미지 빌드 완료: 배포할 이미지가 레지스트리에 푸시되어 있어야 합니다.
• docker-compose.yml 정의: 서비스의 배포 구성은 docker-compose.yml에서 관리됩니다. 단일 컨테이너든 멀티 컨테이너든 동일하게 적용됩니다.

---

Step 1: 배포 단계로 이동

1. [서비스 관리] 페이지로 이동합니다.
2. 배포할 서비스를 선택합니다.
3. 파이프라인에서 배포 단계를 클릭합니다.

---

Step 2: Docker 배포 선택

1. 배포 유형에서 Docker를 선택합니다.
2. 배포 대상 런타임을 선택합니다.

• Docker: Docker Engine 기반입니다. 가장 일반적이며 넓은 호환성을 가집니다.
• Podman: Rootless 컨테이너 런타임입니다. 보안이 강화되어 있고 데몬 없이 동작합니다.
  • Docker와 호환되는 컨테이너 런타임이지만 데몬 없이 동작하며 rootless 모드를 지원합니다. 보안이 중요한 환경에서 권장됩니다.

---

Step 3: 배포 옵션 입력

Docker 배포 모달에서 사용자가 입력하는 항목은 이미지 버전 하나뿐입니다. 실제 UI 라벨은 이미지 버전이며, 본 문서에서는 의미를 명확히 하기 위해 이미지 태그/버전을 혼용합니다. 아래 표의 "배포 전 자동 백업"은 입력 항목이 아니라 배포 시 자동으로 수행되는 동작을 설명합니다. (이미지, 자동 백업 참고)

항목	설명
이미지 버전 (입력)	배포할 컨테이너 이미지의 태그(버전)를 선택합니다. 빌드 이력에 등록된 이미지 목록에서 선택할 수 있습니다. (목록에 없는 버전을 직접 입력할 수는 없으며, 먼저 빌드를 실행해야 합니다.)
배포 전 자동 백업 (자동 수행)	사용자가 켜고 끄는 토글이 아니라, 배포 직전에 KIOPS가 현재 컨테이너/볼륨 백업을 자동으로 수행합니다. 백업은 배포 대상 서버의 로컬 디렉터리(/var/backups/k8scontrol/...)에 저장됩니다.

배포 전 자동 백업은 배포 대상 서버의 로컬 디렉터리(/var/backups/k8scontrol/...)에 저장되며, [백업 관리] 의 외부 저장소(오브젝트 스토리지 등)로 자동 업로드되지는 않습니다. 또한 이 백업은 배포를 막지 않습니다 — 백업이 실패해도 배포는 중단되지 않고 계속 진행되며 로그에 경고만 남습니다. 사용자가 켜고 끄는 토글은 없습니다.

배포 모달에서 입력하는 값은 이미지 버전 하나뿐입니다. 컨테이너 이름, 포트 매핑, 볼륨 마운트, 환경 변수, 네트워크 설정은 모두 docker-compose.yml 편집 모드에서 처리합니다. 자세한 내용은 docker-compose.yml 편집을 참고하세요.

---

Step 4: 배포 실행

1. 이미지 버전을 검토합니다.
2. 배포 버튼을 클릭합니다.
3. 연결 방식 선택 모달에서 VPN 또는 직접 SSH 를 선택합니다. 배포는 대상 서버로의 SSH 연결이 필요하므로 매번 이 모달이 나타납니다. 대상 IP를 커버하는 VPN이 없으면 이 단계는 자동으로 직접 SSH 로 건너뜁니다.
4. 백엔드가 docker-compose pull 및 docker-compose up -d를 실행하여 스택을 갱신합니다.
5. 배포 진행 로그가 실시간으로 표시됩니다. 로그가 정상적으로 끝나면 아래 Step 5: 컨테이너 상태 확인에서 컨테이너가 Running 인지 확인하세요. 로그 중간에 오류가 보이거나 컨테이너가 뜨지 않으면 이 페이지 하단의 문제 해결 항목과 운영 모달 로그 조회 탭에서 원인을 확인하세요.

서비스가 멀티 서비스로 등록된 경우, docker-compose.yml의 여러 서비스가 한 번의 배포로 함께 갱신됩니다. 단일 서비스든 멀티 서비스든 사용 흐름은 동일합니다.

---

docker-compose.yml 편집

컨테이너 이름, 포트 매핑, 볼륨, 환경 변수, 네트워크 등 모든 세부 설정은 docker-compose.yml에서 관리됩니다. KIOPS의 Compose 편집 모드에서 직접 편집할 수 있습니다. (Docker Compose, 볼륨, 환경 변수 참고)

편집 가능한 항목

services:
  api:
    image: harbor.company.com/library/app:latest
    container_name: my-web-app
    restart: unless-stopped
    ports:
      - "8080:80"
      - "8443:443"
    volumes:
      - app-data:/app/data
      - ./config:/app/config:ro
    environment:
      NODE_ENV: production
      DATABASE_URL: ${DATABASE_URL}
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

volumes:
  app-data:

항목	docker-compose 키
컨테이너 이름	container_name
재시작 정책	restart (no / on-failure / always / unless-stopped)
포트 매핑	ports
볼륨 마운트	volumes
환경 변수	environment 또는 env_file
네트워크 설정	networks

민감 정보 주의

비밀번호나 API 키 같은 민감 정보는 docker-compose.yml에 평문으로 입력하지 말고, .env 파일이나 Secret으로 분리하세요.

---

Step 5: 컨테이너 상태 확인

운영 모달에서 컨테이너 상태를 확인합니다. Docker 운영 모달은 개요 / 컨테이너 목록 / 로그 조회 / 명령 실행 / 도메인 설정 탭으로 구성됩니다(로그 조회·명령 실행 탭은 해당 권한이 있을 때만 표시됩니다). 도메인 대상 DAST 스캔은 [보안 분석] 페이지로 이관되어 운영 모달에는 더 이상 없습니다.

1. [서비스 관리] 페이지에서 서비스의 운영 카드를 클릭합니다.
2. 운영 모달에서 컨테이너 목록 탭을 선택하면 다음 정보를 확인할 수 있습니다.

• 상태: Running / Stopped / Error
• 포트: 매핑된 포트 정보
• 생성 시간: 컨테이너 생성 시점
• 리소스: CPU / Memory 사용량

컨테이너 제어

운영 모달의 컨테이너 목록 탭에서 각 컨테이너를 재시작·중지·삭제할 수 있습니다. 권한이 있을 때만 표시됩니다. docker-compose 기반 재배포는 운영 모달이 아니라 파이프라인 배포 단계에서 수행합니다(Docker 배포 모달 또는 Compose 편집 모드).

---

문제 해결

컨테이너 시작 실패

• 포트 충돌: docker-compose.yml에서 호스트 포트를 다른 값으로 변경합니다.
• 이미지 없음: 레지스트리에 해당 태그가 존재하는지, 인증 정보가 올바른지 확인합니다.
• 권한 문제: 볼륨 마운트 경로의 권한을 확인합니다.

컨테이너 크래시 (재시작 반복)

• 환경 변수 누락: 필수 환경 변수가 설정되었는지 확인합니다.
• 의존성 문제: 로그에서 오류 메시지를 확인합니다.
• 메모리 부족: 리소스 제한을 조정하거나 애플리케이션을 최적화합니다.

외부에서 접근 불가

• 포트 미매핑: docker-compose.yml의 ports 설정을 확인합니다.
• 방화벽 차단: 호스트 방화벽에서 해당 포트를 허용합니다.
• 컨테이너 내부 오류: 로그를 확인하고 애플리케이션 상태를 점검합니다.

운영 모달의 로그 조회 탭에서 실시간 로그를 확인할 수 있습니다.

자주 하는 실수

• latest 태그 사용: 이미지 버전에 latest 를 사용하면 배포 시점마다 다른 이미지가 내려오면서 롤백 기준이 사라지고, 같은 시점이라도 두 노드가 서로 다른 이미지를 받는 사태가 생길 수 있습니다. 운영 환경에서는 빌드 ID/커밋 해시가 포함된 고정 태그(예: main-abc123, v1.2.3)를 사용하세요.
• Compose YAML 들여쓰기: docker-compose.yml은 YAML 문법을 사용하므로 들여쓰기는 공백 2칸, 탭 키 금지입니다. 한 칸이라도 어긋나거나 탭이 섞이면 yaml: line N: did not find expected key 같은 오류로 배포 전체가 실패합니다. KIOPS의 Compose 편집기는 들여쓰기 오류를 미리 표시해 주므로 저장 전 빨간 줄이 없는지 확인하세요.

---

다음에 할 일

Docker 배포가 정상적으로 완료됐다면, 다음 동선을 권장합니다.

1. 자동 백업 확인: 배포 전 자동 백업은 배포 대상 서버의 로컬 디렉터리(/var/backups/k8scontrol/...)에 저장되며 배포 실패를 막지 않습니다. 지속적인 보관이 필요하면 [백업 관리] 페이지에서 별도의 백업 정책을 함께 구성하세요.
2. compose 편집 가이드 익히기: 컨테이너 이름·포트·볼륨 같은 세부 설정은 compose 편집 모드에서 처리합니다. 자주 쓰는 옵션을 미리 한 번 살펴보세요.
3. 운영 모달 활용: 운영 모달의 로그 조회 / 명령 실행 / 컨테이너 목록 탭으로 컨테이너 상태를 점검하고 문제 발생 시 빠르게 대응할 수 있도록 익혀두세요.

---

관련 가이드

• K8s 배포 - Kubernetes 클러스터 배포
• 롤백 - 이전 버전으로 복원
• 운영 관리 - 컨테이너 모니터링