Kubernetes에서 Private Registry 이미지 Pull 시크릿 설정하기

Kubernetes에서 Private Registry 이미지 Pull 시크릿 설정하기

🔐 목적

사설 Docker 레지스트리 (예: 10.10.10.10:5000)에서 Kubernetes Pod가 이미지를 당겨오기 위해 필요한 imagePullSecret 생성과 적용 방법을 설명합니다.

📌 사전 조건

• 사설 레지스트리에 접근 가능한 사용자 계정이 있어야 함
• 사설 레지스트리 주소와 포트 확인 (예: 10.10.10.10:5000)
• Kubernetes 클러스터에 접근할 수 있어야 함

📄 Kubernetes 버전 및 ServiceAccount 연동

Kubernetes 1.6부터 Pod에 직접 imagePullSecrets를 지정할 수 있었으며, Kubernetes 1.9 이후부터는 ServiceAccount에 imagePullSecrets를 연결하는 기능이 안정화되어 널리 사용됩니다.

공식 문서 참조: Pull an Image from a Private Registry | Kubernetes Docs

🔧 ServiceAccount에 시크릿을 연결하고 사용하는 YAML 예시

# 시크릿 생성 (kubectl 명령 또는 별도 YAML 사용)
apiVersion: v1
kind: Secret
metadata:
  name: my-registry-secret
  namespace: my-namespace
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: 
---
# 서비스 어카운트에 연결
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-admin
  namespace: my-namespace
imagePullSecrets:
  - name: my-registry-secret
---
# 해당 서비스 어카운트를 사용하는 Pod
apiVersion: v1
kind: Pod
metadata:
  name: busybox-from-sa
  namespace: my-namespace
spec:
  serviceAccountName: my-admin
  containers:
  - name: busybox
    image: 10.10.10.10:5000/busybox:1.36
    command: ["sh", "-c", "sleep 3600"]
  restartPolicy: Never

🧾 시크릿 생성 명령어

kubectl create secret docker-registry my-registry-secret \
  --docker-server=10.10.10.10:5000 \
  --docker-username=myuser \
  --docker-password='MyP@ssw0rd!' \
  --docker-email=dummy@example.com \
  --namespace=my-namespace

※ --docker-email은 Kubernetes 1.27 기준에서도 생략 불가입니다. 아무 이메일 주소나 입력하면 됩니다.

📄 시크릿 YAML 수동 작성 예시

apiVersion: v1
kind: Secret
metadata:
  name: my-registry-secret
  namespace: my-namespace
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64로 인코딩된 .dockerconfigjson 내용>

생성 명령어:

kubectl apply -f my-registry-secret.yaml

🔧 여러 레지스트리를 하나의 시크릿으로 묶는 예시

{
  "auths": {
    "10.10.10.10:5000": {
      "auth": "<base64-encoded-auth1>"
    },
    "10.10.20.20:5000": {
      "auth": "<base64-encoded-auth2>"
    }
  }
}

하지만 실수를 줄이기 위해 각 레지스트리마다 시크릿을 생성하고 imagePullSecrets 항목에 나열하는 것을 추천합니다.

🚀 Pod 예시 YAML

apiVersion: v1
kind: Pod
metadata:
  name: busybox-test
  namespace: my-namespace
spec:
  serviceAccountName: my-admin
  containers:
  - name: busybox
    image: 10.10.10.10:5000/busybox:1.36
    command: ["sh", "-c", "sleep 3600"]
  imagePullSecrets:
  - name: my-registry-secret
  restartPolicy: Never

🧪 테스트 및 디버깅

• kubectl describe pod <pod-name> -n <namespace> 명령어로 Events 확인
• container runtime이 containerd일 경우 crictl pull로 직접 테스트 가능

에러 사례 1:
unauthorized: authentication required

• 시크릿의 인증 정보가 틀림
• Pod에 imagePullSecrets가 적용되지 않음
• 계정에 이미지 pull 권한이 없음

해결: 시크릿 재생성, 서비스 어카운트/Pod에 제대로 연결되었는지 확인, 레지스트리 권한 체크

에러 사례 2:
illegal base64 data at input byte XX

• 수동으로 작성한 base64 문자열이 깨졌거나 줄바꿈 포함

해결: kubectl create secret docker-registry 명령어로 자동 생성 권장

에러 사례 3:
Error: ErrImagePull / ImagePullBackOff

• 이미지 주소 오타
• 태그가 존재하지 않음
• 시크릿은 있으나 레지스트리 인증 실패

해결: 이미지가 존재하는지 curl로 확인, 태그 확인, 레지스트리 curl 테스트로 인증 확인

⚠️ 유의사항

• 비밀번호에 특수문자 있을 경우 작은따옴표('')로 감싸기
• Pod 생성 후 이미지 풀 에러가 나면 imagePullSecrets가 적용되었는지 반드시 확인
• 시크릿 변경 시에는 기존 Pod 삭제 후 재생성 필요
• registry 주소, 포트, 계정은 환경에 맞게 반드시 교체할 것 (위 예시는 샘플입니다)