본문 바로가기
도커&쿠버네티스

[도커&쿠버네티스 스터디 1편] 그게 뭔데 00아. 도커 실습 셋팅해보기(with Windows+WSL2);

홍옹 2025. 4. 20. 13:15

“관제 화면 설계하다가, 컨테이너 우주에 입문한 사연”

 

얼마전에 진행했던 프로젝트에서,

사용자 흐름과 기능 요구사항을 정리하던 중, 막판에 시스템 관제 대시보드 설계가 제 몫으로 넘어왔습니다.
그 순간 처음 듣는 용어들이 쏟아졌죠.

 

“Pod · 컨테이너 · ReplicaSet 지표도 넣어 주세요”

 

 

 

시스템 관제를 위한 화면 설계는 기존에도 많이 해왔던 터라 가벼운 마음으로 설계에 들어갔었습니다.

그런데 왠걸....

생전 처음 보는 인프라 구성도가 떡하니 있더군요..

 

예전 모놀리식 환경에서는
서버별 CPU·메모리만 모니터링해도 충분했습니다.

 

하지만 이번엔 달랐습니다.

 

 

전통형 관제컨테이너 / 쿠버네티스 관제

서버(호스트) 단위 지표 VM → 컨테이너 → Pod → ReplicaSet 단계별 지표
OS 자원만 체크 Pod 상태, 재시작 횟수, 오토스케일링 현황까지

 

 

“컨테이너가 뭔데요? Pod는 또 뭔가요?”

지표를 그리려면 먼저 개념을 이해해야 했습니다.

  • 도커 : 컨테이너 한 개가 어떻게 만들어지고 배포되는지
  • 쿠버네티스 : 그 컨테이너들이 군집(Pod)과 ReplicaSet으로 어떻게 묶이고 관리되는지

기획자 관점으로라도 ‘원리’를 제대로 알아야 관제를 설계할 수 있겠다!

 

그래서 시작한 스터디 – “내 손으로 환경부터 만들어 보기”

왜 Windows + WSL2일까요?

저는 윈도우 사용자입니다.
주변 개발자들은 주로 macOS에서 터미널을 열고 도커를 돌리지만,
가끔 저처럼 Windows 노트북 한 대로 공부를 시작하려는 분들도 계시잖아요?

  • WSL2는 윈도우 안에 가벼운 리눅스를 얹어 주므로,
    도커처럼 리눅스에 최적화된 도구를 별도 VM 없이 쾌적하게 다룰 수 있습니다.
  • “윈도우에서 도커 쓰면 느리다”는 옛말도, WSL2 이후로는 확연히 달라졌습니다.
  • 무엇보다 같은 환경을 공유하면 실습 가이드가 더 명확해집니다.
    macOS만 전제한 자료가 난무하는데, 윈도우 버전이 하나쯤 있어야죠! 😎

첫 실습 과제

  1. AWS EC2에 실습 서버 한 대 띄우기
  2. 그 위에 Docker를 설치해 “Hello from Docker!” 메시지를 확인하기

본 실습은 windows 환경에 WSL2 최신버전이 설치되어 있는 것을 전제로 진행하겠습니다.

AWS EC2 실습 서버 만들기

  1. 키 페어 생성
    • 리전 확인 하기(서울)
    • AWS 콘솔 ▶ EC2 ▶ Key pairs ▶ Create key pair [그림1]
    • 형식: RSA / .pem, 이름은 my-ec2.pem 예시(다운로드 위치 기억!) AWS Documentation
  2. 인스턴스 시작
    • AMI: Ubuntu 22.04 LTS (64‑bit x86)
    • 인스턴스 유형: t3.micro(프리티어)
    • 보안그룹: 인바운드에 TCP 22(SSH)만 열기
  3. 퍼블릭 IPv4 주소를 메모합니다.

[그림1] 키페어 생성

🐣 처음이시라면 “EC2 런치 마법사”의 기본값을 그대로 두고 키페어·보안그룹만 신경 써도 충분합니다.
참고로 저는 스터디 그룹에서 공유해주신 CloudFomation을 통해 공유받은 템플릿을 사용하였습니다.

 

 

WSL 터미널에서 EC2 접속

# (1) 키 파일 이동 & 권한 세팅
mv ~/Downloads/my-ec2.pem ~/.ssh/
chmod 400 ~/.ssh/my-ec2.pem      # 권한 과다 시 SSH가 거절합니다.

# (2) SSH 접속
ssh -i ~/.ssh/my-ec2.pem ubuntu@<퍼블릭_IP>

접속이 안 된다면
  • IP 오타?  • 보안그룹 22번?  • ubuntu 계정 맞나? 한 번 더 체크!

 

 

우분투 업데이트 & Docker Engine 설치

sudo apt update && sudo apt upgrade -y

# Docker 공식 저장소 설정
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
 "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
 https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
 sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
sudo systemctl enable --now docker

 

비‑root 사용자 권한 & 테스트

sudo usermod -aG docker $USER
# 재로그인 후
docker run --rm hello-world
 

“Hello from Docker!” 문구가 보이면 성공 

 

주요 오류 & 해결 방법

1. “No such file or directory” (키 페어 .pem 파일 경로 문제)

증상

  • SSH 명령어 실행 시:→ No such file or directory 에러
  •   
    ssh -i /home/wsl/downloads/mykey.pem ubuntu@<IP>
  • 코드 복사
  • swift

원인

  • 파일 이름이나 경로가 실제와 불일치.
  • 예: 실제 파일명은 knou-key.pem인데 명령에서 mykey.pem을 입력.

해결

  1. **WSL에서 ls**로 정확한 파일명을 확인.
  2. 명령어도 똑같이 맞춤:
  3. bash
    코드 복사
    cd /home/wsl/downloads chmod 400 knou-key.pem ssh -i /home/wsl/downloads/knou-key.pem ubuntu@<IP>
  4. 괄호(<>)나 오타가 없는지 주의.

2. “InvalidClientTokenId” (AWS CLI 자격증명/권한 문제)

증상

  • AWS CLI로 aws cloudformation describe-stacks 또는 aws sts get-caller-identity 실행 시:
  •  
    코드 복사
    An error occurred (InvalidClientTokenId) when calling the ... The security token included in the request is invalid
  • vbnet

원인

  1. Access Key / Secret Key가 잘못되었거나 비활성화
  2. IAM 사용자에 CloudFormation/STS/EC2 권한이 없어 (권한이 너무 제한적)
  3. Region 설정이 잘못(예: p-northeast-2 오타)

해결

  1. IAM에서 적절한 정책(예: AdministratorAccess) 부여
  2. aws configure로 정확한 Access Key / Secret Key / region 입력
  3. ~/.aws/config와 ~/.aws/credentials에서 오타 여부 확인
  4. 시스템 시간 동기화(5분 이상 차이 나면 Token 에러)

 

3. “Could not connect to the endpoint URL” (p-northeast-2 리전 오타)

증상

원인

  • region = p-northeast-2 처럼 맨 앞 ‘a’가 빠짐
  • 올바른 주소는 ap-northeast-2 인데, 오타로 인한 호스트 미존재

해결

  • ~/.aws/config에서로 수정
  • ini
    코드 복사
    [default] region = ap-northeast-2
  • aws configure 재실행 시 리전 제대로 입력하기

4. Permission denied (publickey) (SSH 키 파일 권한 문제)

증상

  • SSH 시도했는데:
    • 또는 “UNPROTECTED PRIVATE KEY FILE!” 경고
  • java
    코드 복사
    Permission denied (publickey)

원인

  1. .pem 파일 권한이 600 이상(읽기/쓰기/실행 등이 열려 있음)
  2. AWS가 “보안상 안전하지 않은 키 파일”로 인식

해결

  1. **chmod 400**으로 파일 권한을 소유자 읽기 전용으로 제한
  2. 다시 ssh -i ...

5. “permission denied while trying to connect to the Docker daemon socket” (Docker 권한 문제)

증상

  • Docker 명령어(docker ps, docker build 등) 실행 시:
  • arduino
    코드 복사
    dial unix /var/run/docker.sock: connect: permission denied

원인

  • 현재 사용자(ubuntu, wsl 등)가 Docker 소켓(/var/run/docker.sock) 접근 권한이 없음
  • Docker는 기본적으로 root나 docker 그룹만 접근 가능

해결

  1. 일단 sudo docker ps 로는 되지만 매번 sudo가 필요
  2. sudo usermod -aG docker <사용자명> 으로 그룹에 추가
  3. 로그아웃/재로그인 후 → 이제 docker ps가 정상 동작

6. usermod 명령 실패 (“Usage: usermod [options] LOGIN”) (계정명 변수 문제)

증상

  • sudo usermod -aG docker $wsl → Usage: usermod [options] LOGIN 에러

원인

  • $wsl이라는 환경변수가 정의되지 않아 빈 문자열이 되어버림.
  • 실제 리눅스 계정명(예: ubuntu) 대신 쓰여서 usermod가 인자를 못 찾음.

해결

  1. 정확한 계정명을 whoami 등으로 확인
  2. sudo usermod -aG docker ubuntu
  3. 비밀번호 묻는다면 sudo passwd ubuntu로 설정

7. 기타

  • “No newline near token” 같은 문법 에러: <IP> 괄호를 써서 Shell이 리다이렉션으로 인식
  • “File not found (Zone.Identifier)”: Windows가 만든 보안 속성 파일, 무시나 삭제해도 됨
  • “SSH 포트 안 열린다”: 보안 그룹 인바운드 규칙에서 SSH(22) 허용 필요

티스토리툴바