Shell 접속
때로는 로그만으로 문제를 파악하기 어려울 때가 있습니다. 이럴 때 Shell 접속 기능을 사용하면 Pod나 Container 내부에서 직접 명령을 실행하여 심층적인 디버깅을 할 수 있습니다.
로그에서 보이지 않는 정보들이 있습니다. 환경 변수, 파일 시스템, 네트워크 연결 상태 등을 직접 확인해야 할 때 Shell 접속이 필요합니다. 마치 서버에 SSH로 접속하는 것과 같습니다.
기능 개요
KIWI의 Shell 접속 기능은 실제로 kubectl exec나 docker exec 명령을 사용합니다.
- Kubernetes:
kubectl exec -it <pod> -- <command>와 동일한 방식으로 실행합니다 . - Docker/Podman:
docker exec -it <container> <command>와 동일한 방식으로 실행합니다 .
Execute 탭 접근
- [서비스 관리] → 서비스 선택
- Operate 단계 클릭
- Execute 탭 선택
명령 실행 방법
Step 1: 대상 선택
- Kubernetes: Pod 드롭다운에서 대상 Pod 선택
- Docker/Podman: 컨테이너 드롭다운에서 대상 컨테이너 선택
Step 2: 명령어 입력
- 명령어 입력 필드에 실행할 명령 입력
- Execute 버튼 클릭 또는 Enter
- 결과가 하단 영역에 표시됨
Step 3: 결과 확인
- 명령 실행 결과가 출력 영역에 표시
- 에러 발생 시 에러 메시지 표시
- 여러 명령 연속 실행 가능
자주 사용하는 명령어
실무에서 자주 사용하는 명령어들을 정리했습니다. 필요한 명령어를 복사해서 사용하세요.
Linux 명령어에 익숙하지 않다면 먼저 읽기 전용 명령어(cat, ls, ps 등)부터 시작하세요. 시스템을 변경하지 않으므로 안전합니다.
시스템 정보
기본적인 시스템 상태를 확인하는 명령어입니다.
# OS 정보 확인
cat /etc/os-release
# 호스트명 확인
hostname
# 현재 시간 확인
date
# 서버 가동 시간 확인
uptime
프로세스 확인
# 전체 프로세스 목록
ps aux
# 특정 프로세스 검색
ps aux | grep java
# 프로세스 트리
pstree
# 메모리 사용량 순 정렬
ps aux --sort=-%mem | head -10
# CPU 사용량 순 정렬
ps aux --sort=-%cpu | head -10
리소스 모니터링
# 메모리 사용량
free -m
# 디스크 사용량
df -h
# 디렉토리 크기
du -sh /app/*
# 네트워크 통계
netstat -tlnp
# 또는
ss -tlnp
네트워크 확인
# 네트워크 인터페이스
ip addr
# 또는
ifconfig
# DNS 확인
cat /etc/resolv.conf
nslookup google.com
# 포트 연결 테스트
nc -zv <host> <port>
# HTTP 요청 테스트
curl -v http://localhost:8080/health
wget -qO- http://localhost:8080/api/status
파일 시스템
# 파일 목록
ls -la /app/
# 파일 내용 확인
cat /app/config/application.yml
# 파일 검색
find /app -name "*.log"
# 파일 끝부분 (로그 확인)
tail -100 /var/log/app.log
# 실시간 로그 (Follow)
tail -f /var/log/app.log
환경 변수
# 전체 환경 변수
env
# 특정 환경 변수 검색
env | grep -i database
# 환경 변수 값 확인
echo $DATABASE_URL
echo $NODE_ENV
Java 애플리케이션
# JVM 메모리 상태
jstat -gc <pid>
# 힙 덤프
jmap -dump:format=b,file=/tmp/heap.hprof <pid>
# 스레드 덤프
jstack <pid>
# GC 로그 확인
tail -100 /var/log/gc.log
Node.js 애플리케이션
# Node.js 버전
node --version
# npm 패키지 목록
npm list --depth=0
# 환경 확인
node -e "console.log(process.env)"
Python 애플리케이션
# Python 버전
python --version
# 설치된 패키지
pip list
# 패키지 상세 정보
pip show <package>
디버깅 시나리오
실제 문제 상황에서 어떻게 디버깅하는지 단계별로 알아보겠습니다.
시나리오 1: 메모리 부족 진단
Container가 OOM(Out of Memory)으로 계속 재시작되는 상황입니다.
증상: Container가 갑자기 종료되고 "OOMKilled" 상태가 됩니다.
진단 명령:
# 현재 메모리 사용량 확인
free -m
# 메모리를 많이 사용하는 프로세스 Top 5
ps aux --sort=-%mem | head -5
결과 분석: 어떤 프로세스가 메모리를 많이 사용하는지 확인합니다.
대응 방법:
- 메모리 limit을 증가시킵니다 .
- 또는 메모리 누수가 있다면 코드를 수정합니다 .
애플리케이션의 평균 메모리 사용량의 1.5~2배 정도로 limit을 설정하면 안정적입니다.
시나리오 2: 네트워크 연결 문제
- 증상: DB 연결 실패
- 명령 실행:
nc -zv database-host 5432
nslookup database-host - 결과 분석: DNS 해석 또는 포트 연결 확인
- 대응: 네트워크 정책, 서비스 엔드포인트 확인
시나리오 3: 설정 파일 확인
- 증상: 애플리케이션 동작 이상
- 명령 실행:
cat /app/config/application.yml
env | grep -i config - 결과 분석: 설정 값 확인
- 대응: ConfigMap/환경 변수 수정
시나리오 4: 디스크 공간 부족
- 증상: 로그 파일 쓰기 실패
- 명령 실행:
df -h
du -sh /var/log/*
ls -la /var/log/*.log - 결과 분석: 어떤 파일/디렉토리가 공간 차지
- 대응: 로그 정리, 볼륨 크기 증가
주의사항
Production 환경에서 명령 실행 시 주의하세요:
- 데이터 변경 명령 (rm, mv, truncate) 신중히 사용
- 리소스 영향 명령 (fork bomb, 무한 루프) 금지
- 민감 정보가 출력될 수 있으므로 화면 공유 주의
피해야 할 명령
rm -rf /- 시스템 전체 삭제:(){ :|:& };:- Fork bomb (리소스 고갈)kill -9 1- PID 1 종료 (컨테이너 종료)chmod -R 777 /- 보안 취약dd if=/dev/zero of=/dev/sda- 디스크 파괴
안전한 사용법
- 읽기 전용 명령 먼저:
cat,ls,ps등으로 상황 파악 - 테스트 환경에서 먼저: 위험한 명령은 개발 환경에서 테스트
- 백업 확인: 중요 파일 수정 전 백업 상태 확인
- 동료 검토: 중요한 작업은 다른 팀원과 함께
권한
권한 안내: Shell 접속 기능에 접근할 수 없다면 기관 관리자에게 권한을 요청하세요. 권한이 없는 경우 Execute 탭이 비활성화됩니다.
감사 로그
모든 명령 실행은 감사 로그에 기록됩니다:
- 실행 시간: 명령 실행 시각
- 실행자: 명령 실행한 사용자
- 대상: Pod/컨테이너 이름
- 명령어: 실행된 명령
- 결과: 성공/실패
문제 해결
- "command not found": 해당 명령이 컨테이너에 없습니다. 다른 명령을 사용하거나 패키지를 설치하세요.
- "Permission denied": 권한이 부족합니다. root로 실행 필요 시 --user root 옵션을 사용하세요.
- 응답 없음: 명령 실행 시간이 초과되었습니다. 간단한 명령으로 재시도하세요.
- 연결 실패: Pod/컨테이너 상태가 불량합니다. 상태 확인 후 재시도하세요.
Shell이 없는 컨테이너
일부 최소화된 이미지(distroless 등)에는 shell이 없습니다:
# /bin/sh가 없는 경우
# 에러: executable file not found
# 대안: 이미지에 포함된 바이너리 직접 실행