Docker 런타임 등록
KIOPS 플랫폼에 Docker 또는 Podman 런타임을 등록하면 웹 UI에서 컨테이너를 통합 관리할 수 있습니다. K8s와 마찬가지로 새 런타임 설치(신규) 또는 기존 런타임 연결(임포트) 두 흐름으로 진행되며, Docker와 Podman은 동일한 모달에서 처리됩니다.
왜 Docker 런타임을 등록하나요?
- 컨테이너 상태를 한눈에 확인
- 클릭 한 번으로 컨테이너 재시작 등 운영 작업
- 실시간 로그 확인 및 문제 추적
- 원격 명령 실행으로 컨테이너 내부 점검
Docker와 Podman은 모두 컨테이너 런타임입니다. Podman은 데몬 없이 동작하는 보안 강화 대안이며, KIOPS는 두 가지 모두 지원합니다. 등록 흐름과 모달은 동일합니다.
사전 요구사항
- 대상 장비가 KIOPS에 먼저 등록되어 있어야 합니다.
- 신규 설치의 경우 KIOPS가 SSH로 접속해 Docker 또는 Podman을 설치합니다.
- 임포트의 경우 대상 장비에 Docker 또는 Podman이 이미 설치되어 있어야 합니다.
- SSH 계정은 sudo 권한 또는 Docker 소켓 접근 권한을 보유해야 합니다.
등록 진입점: 런타임 환경 추가
Docker/Podman 런타임도 별도의 "Docker 추가" 버튼이 없으며, K8s와 동일한 공통 진입점에서 시작합니다.
- 좌측 메뉴에서 [런타임 환경] 페이지를 클릭합니다.
- 우측 상단의 런타임 환경 추가 버튼을 클릭해 런타임 환경 추가 모달(AddInfraSelectModal) 을 엽니다.
- 두 가지 흐름 중 하나를 선택합니다.
모달 내부의 환경 유형 항목은 K8s/Docker/Podman을 하나의 Select 드롭다운으로 통합 선택합니다. "타입 라디오"는 사용되지 않습니다.
두 모달의 옵션 텍스트 표기가 다릅니다.
- AddInfraModal (신규 설치): Select 옵션이 raw value 그대로 출력되어
kubernetes/docker/podman(소문자)로 표시됩니다. - ImportInfraModal (임포트): 한글 라벨 "Kubernetes / Docker / Podman" 로 표시됩니다.
신규 설치 흐름
KIOPS가 등록된 장비에 SSH로 접속해 Docker 또는 Podman을 설치합니다.
Step 1: 입력
- 환경 이름: 런타임을 구분할 식별명 (예:
dev-docker,prod-container-host) - 환경 유형 (Select):
Docker또는Podman을 선택합니다. - 서버 장비 (TreeSelect): 등록된 장비를 트리에서 선택합니다.
- 이미 Docker/Podman 런타임이 설치된 장비는 자동으로 disabled 되어 선택할 수 없습니다.
- 설명 (선택): 자유 형식 메모
Step 2: SSH 접속 경로 미리보기
선택한 장비에 부모(점프 서버)가 있는 경우, 모달 하단에 hop 체인이 화살표(gateway → jump → target) 형태로 시각화됩니다. 경로가 의도와 다르면 장비 등록을 먼저 정정합니다.
Step 3: 등록
등록 버튼을 클릭하면 KIOPS가 해당 장비에 SSH로 접속하여 Docker 또는 Podman을 설치하고 런타임을 등록합니다. 진행 상황은 모달에서 실시간으로 확인할 수 있습니다.
기존 연결 (임포트) 흐름
이미 Docker 또는 Podman이 설치된 장비를 런타임으로 등록합니다.
Step 1: 환경 유형 선택
임포트 모달의 환경 유형 Select 옵션에 사용자가 보는 라벨은 "Kubernetes / Docker / Podman" (한글 라벨)으로 표시됩니다. (external_docker, external_podman, external_kubernetes는 백엔드 내부 식별자입니다.)
- Docker: 기존 Docker 호스트 (내부 식별자
external_docker) - Podman: 기존 Podman 호스트 (내부 식별자
external_podman) - Kubernetes: 기존 K8s 클러스터 (K8s 등록 가이드 참고)
Step 2: 접속 경로 입력
- 등록된 장비 선택 또는 SSH hops 직접 입력 중 하나를 사용합니다.
Step 3: 가져오기
- 가져오기 버튼을 클릭하면 KIOPS가 SSH로 접속해
docker version또는podman version을 확인하고, 컨테이너 목록·이미지·네트워크 등을 자동 감지합니다. - 별도의 "테스트 연결" 버튼은 없습니다 (가져오기 시 자동 검증).
Step 4: 등록
검증이 성공하면 런타임 목록에 추가됩니다. Docker와 Podman은 등록 이후에도 동일한 운영 화면(개요/런타임 환경/운영 관리/실시간 모니터링)을 사용합니다.
런타임 기능
등록된 Docker/Podman 런타임에서는 다음 기능을 사용할 수 있습니다.
- 이미지 목록: 해당 호스트에 저장된 컨테이너 이미지 조회
- 컨테이너 관리: 컨테이너 재시작 (목록·상세에서 수행)
- 로그 조회: 컨테이너의 실시간 로그
- 원격 명령 실행: 컨테이너 내부 점검 (대화형 쉘이 아닌 단발 명령 실행)
컨테이너에 문제가 생겼을 때 로그 조회 기능을 사용하면 터미널 접속 없이 바로 원인을 파악할 수 있습니다. 실시간 로그 스트리밍도 지원됩니다.
문제 해결
Docker 접근 불가 (permission denied)
permission denied while trying to connect to Docker
원인: SSH 사용자가 Docker 소켓에 접근할 권한이 없습니다.
해결 방법:
- docker 그룹에 사용자 추가
sudo usermod -aG docker $USER
- 변경사항 적용 (둘 중 하나 선택)
# 방법 1: 현재 세션에서 바로 적용
newgrp docker
# 방법 2: 로그아웃 후 다시 로그인
- 권한이 적용되었는지 확인
docker ps
docker 그룹에 사용자를 추가하면 해당 사용자는 루트 수준의 권한을 얻게 됩니다. 운영 환경에서는 꼭 필요한 사용자에게만 권한을 부여하세요.
Docker 미설치 (command not found)
docker: command not found
원인: 대상 서버에 Docker가 설치되어 있지 않습니다.
신규 설치 흐름으로 진행하면 KIOPS가 자동으로 Docker를 설치합니다. 수동 설치가 필요한 경우 아래 명령을 사용합니다.
# Docker 공식 설치 스크립트 (Ubuntu/Debian/CentOS)
curl -fsSL https://get.docker.com | sh
# 설치 후 Docker 서비스 시작
sudo systemctl start docker
# 부팅 시 자동 시작 설정
sudo systemctl enable docker
# 설치 확인
docker --version
다음 단계
Docker/Podman 런타임 등록이 완료되었습니다! 이제 서비스를 등록하고 배포할 준비가 되었습니다.