Kubernetes 개발용 환경 구축 기록 (Docker Registry → K3s 배포 성공기)

환경 목표

• 로컬 리눅스 서버에 개발용 K8s 환경 구축
• 자체 Docker Registry에 이미지를 Push하고 K3s에 배포
• 외부에서 NodePort로 서비스 접근 (/docs 확인)

---

1. Docker Registry 구축

docker run -d \
  --name registry \
  --restart=always \
  -p 5000:5000 \
  -v /opt/registry/data:/var/lib/registry \
  registry:2

📌 5000 포트는 registry 기본 포트
📌 외부 포트 충돌 시 -p 5001:5000처럼 조정 가능

---

2. 이미지 태깅 및 Push

docker tag api-gateway localhost:5000/dev/api-gateway
docker push localhost:5000/dev/api-gateway

확인:

curl http://localhost:5000/v2/_catalog
curl http://localhost:5000/v2/dev/api-gateway/tags/list

---

3. Kubernetes 클러스터 준비 (k3s)

k3s 설치:

curl -sfL https://get.k3s.io | sh -

설치 후 확인:

kubectl get nodes

문제 발생: permission denied on kubeconfig

• 해결: ~/.kube/config로 복사 + 권한 설정

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config
unset KUBECONFIG

---

4. Deployment 및 Service 생성

Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-gateway
  namespace: tekapicker-dev
spec:
  replicas: 1
  selector:
    matchLabels:
      app: api-gateway
  template:
    metadata:
      labels:
        app: api-gateway
    spec:
      containers:
        - name: api-gateway
          image: 192.168.1.111:5000/dev/api-gateway
          ports:
            - containerPort: 3000

Service (NodePort):

apiVersion: v1
kind: Service
metadata:
  name: api-gateway-service
  namespace: tekapicker-dev
spec:
  selector:
    app: api-gateway
  type: NodePort
  ports:
    - port: 80
      targetPort: 3000
      nodePort: 31000

---

문제 발생: Image Pull 실패 (ImagePullBackOff)

원인:

• image: localhost:5000 → 클러스터 노드 입장에서는 localhost가 자기 자신
• insecure registry 허용 안 됨

해결:

🔧 /etc/rancher/k3s/registries.yaml 설정

mirrors:
  "192.168.1.111:5000":
    endpoint:
      - "http://192.168.1.111:5000"

설정 후 반드시 재시작:

sudo systemctl restart k3s
kubectl rollout restart deployment/api-gateway -n tekapicker-dev

---

성공 확인

kubectl get pods -n tekapicker-dev
kubectl get svc -n tekapicker-dev

NAME                          READY   STATUS    RESTARTS   AGE
api-gateway-xxxxxxx-xxxxx     1/1     Running   0          10s

---

🎉 마무리

• Registry 구축부터 K8s 배포까지 완성
• 추후 Ingress + Domain 연결, Helm Chart 자동화로 확장 가능