프라이빗 레지스트리에서 이미지 가져오기

프라이빗 레지스트리에서 이미지 가져오기 (Pull an Image from a Private Registry)

이 페이지에서는 Secret을 사용해 프라이빗 컨테이너 이미지 레지스트리나 저장소에서 이미지를 가져오는 Pod를 만드는 방법을 보여드려요. 사용 중인 프라이빗 레지스트리는 다양해요. 이 작업에서는 예시 레지스트리로 Docker Hub를 사용해요.

출처: 문서

본문

시작하기 전에 (Before you begin)

쿠버네티스 클러스터가 필요하고, kubectl 명령줄 도구가 클러스터와 통신하도록 구성돼 있어야 해요. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 두 개 이상 있는 클러스터에서 실행하는 것을 권장해요. 아직 클러스터가 없다면 minikube로 만들거나 다음 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있어요.

  • iximiuz Labs
  • Killercoda
  • KodeKloud

이 실습을 하려면 docker 명령줄 도구와, 비밀번호를 알고 있는 Docker ID가 필요해요.

다른 프라이빗 컨테이너 레지스트리를 사용한다면, 그 레지스트리의 명령줄 도구와 레지스트리에 대한 로그인 정보가 필요해요.

참고: 이 항목은 쿠버네티스 자체가 아닌 서드파티 프로젝트나 제품을 링크해요. 자세한 내용을 보세요.

Docker Hub에 로그인하기 (Log in to Docker Hub)

노트북에서 프라이빗 이미지를 가져오려면 레지스트리로 인증해야 해요. docker 도구를 사용해 Docker Hub에 로그인하세요. 자세한 내용은 Docker ID 계정의 로그인 섹션을 참고하세요.

docker login

프롬프트가 나오면 Docker ID와 사용하려는 자격 증명(액세스 토큰 또는 Docker ID 비밀번호)을 입력하세요.

로그인 과정은 인증 토큰을 담은 config.json 파일을 만들거나 업데이트해요. 쿠버네티스가 이 파일을 어떻게 해석하는지 알아보세요.

config.json 파일을 확인해 보죠.

cat ~/.docker/config.json

출력은 다음과 비슷한 섹션을 포함해요.

{
    "auths": {
        "https://index.docker.io/v1/": {
            "auth": "c3R...zE2"
        }
    }
}

참고: Docker 자격 증명 저장소(credentials store)를 사용하면 그 auth 항목 대신 저장소 이름을 값으로 하는 credsStore 항목이 보여요. 그 경우 시크릿을 직접 만들 수 있어요. "명령줄에서 자격 증명을 제공해 Secret 생성하기"를 참고하세요.

기존 자격 증명 기반으로 Secret 생성하기 (Create a Secret based on existing credentials)

쿠버네티스 클러스터는 kubernetes.io/dockerconfigjson 유형의 Secret을 사용해 컨테이너 레지스트리로 인증하고 프라이빗 이미지를 가져와요.

이미 docker login을 실행했다면 그 자격 증명을 쿠버네티스에 복사할 수 있어요.

kubectl create secret generic regcred \
    --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
    --type=kubernetes.io/dockerconfigjson

더 많은 제어가 필요하다면(예: 새 시크릿에 네임스페이스나 라벨 설정) 저장 전에 Secret을 커스터마이즈할 수 있어요. 반드시 다음을 확인하세요.

  • 데이터 항목의 이름을 .dockerconfigjson으로 설정
  • Docker 구성 파일을 base64로 인코딩한 뒤 그 문자열을 data[".dockerconfigjson"] 필드의 값으로 끊기지 않게 붙여넣기
  • type을 kubernetes.io/dockerconfigjson으로 설정

예시:

apiVersion: v1
kind: Secret
metadata:
  name: myregistrykey
  namespace: awesomeapps
data:
  .dockerconfigjson: UmVhbGx5IHJlYWxseSByZWVlZWVlZWVlZWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGx5eXl5eXl5eXl5eXl5eXl5eXl5eSBsbGxsbGxsbGxsbGxsbGxsbG9vb29vb29vb29vb29vb29vb29vb29vb29vb25ubm5ubm5ubm5ubm5ubm5ubm5ubm5ubmdnZ2dnZ2dnZ2dnZ2dnZ2dnZ2cgYXV0aCBrZXlzCg==
type: kubernetes.io/dockerconfigjson

error: no objects passed to create 오류 메시지가 나오면 base64로 인코딩된 문자열이 유효하지 않다는 뜻일 수 있어요. Secret "myregistrykey" is invalid: data[.dockerconfigjson]: invalid value ... 같은 오류 메시지가 나온다면, data의 base64 문자열이 성공적으로 디코딩됐지만 .docker/config.json 파일로 파싱할 수 없었다는 뜻이에요.

명령줄에서 자격 증명을 제공해 Secret 생성하기 (Create a Secret by providing credentials on the command line)

regcred라는 이름으로 이 Secret을 생성해요.

kubectl create secret docker-registry regcred --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email>

여기서:

  • <your-registry-server>는 프라이빗 Docker 레지스트리 FQDN이에요. DockerHub에서는 https://index.docker.io/v1/을 사용하세요.
  • <your-name>은 Docker 사용자 이름이에요.
  • <your-pword>는 Docker 비밀번호예요.
  • <your-email>은 Docker 이메일이에요.

Docker 자격 증명을 regcred라는 Secret으로 클러스터에 성공적으로 설정했어요.

참고: 명령줄에 시크릿을 입력하면 셸 히스토리에 보호되지 않은 채 저장될 수 있고, kubectl이 실행되는 동안 다른 사용자가 그 시크릿을 볼 수도 있어요.

regcred Secret 검사하기 (Inspecting the Secret regcred)

생성한 regcred Secret의 내용을 이해하려면 먼저 YAML 형식으로 Secret을 확인해 보세요.

kubectl get secret regcred --output=yaml

출력은 다음과 비슷해요.

apiVersion: v1
kind: Secret
metadata:
  ...
  name: regcred
  ...
data:
  .dockerconfigjson: eyJodH...GV4L ... J0QUl6RTIifX0=
type: kubernetes.io/dockerconfigjson

.dockerconfigjson 필드의 값은 Docker 자격 증명의 base64 표현이에요.

.dockerconfigjson 필드에 무엇이 있는지 이해하려면 시크릿 데이터를 읽을 수 있는 형식으로 변환해 보세요.

kubectl get secret regcred --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode

출력은 다음과 비슷해요.

{"auths":{"your.private.registry.example.com":{"username":"janedoe","password":"xxxxxxxxxxx","email":"[email protected]","auth":"c3R...zE2"}}}

auth 필드에 무엇이 있는지 이해하려면 base64로 인코딩된 데이터를 읽을 수 있는 형식으로 변환해 보세요.

echo "c3R...zE2" | base64 --decode

출력은 :으로 연결된 사용자 이름과 비밀번호로, 다음과 비슷해요.

janedoe:xxxxxxxxxxx

Secret 데이터가 로컬 ~/.docker/config.json 파일과 비슷한 인증 토큰을 포함한다는 점을 알아두세요. Docker 자격 증명을 클러스터의 regcred라는 Secret으로 성공적으로 설정했어요.

Secret을 사용하는 Pod 생성하기 (Create a Pod that uses your Secret)

regcred의 Docker 자격 증명이 필요한 예시 Pod의 매니페스트는 다음과 같아요.

apiVersion: v1
kind: Pod
metadata:
  name: private-reg
spec:
  containers:
  - name: private-reg-container
    image: <your-private-image>
  imagePullSecrets:
  - name: regcred

pods/private-reg-pod.yaml — 위 파일을 컴퓨터에 다운로드하세요.

curl -L -o my-private-reg-pod.yaml https://k8s.io/examples/pods/private-reg-pod.yaml

my-private-reg-pod.yaml 파일에서 <your-private-image>를 프라이빗 레지스트리의 이미지 경로로 바꾸세요. 예를 들어:

your.private.registry.example.com/janedoe/jdoe-private:v1

프라이빗 레지스트리에서 이미지를 가져오려면 쿠버네티스에 자격 증명이 필요해요. 구성 파일의 imagePullSecrets 필드는 쿠버네티스가 regcred라는 Secret에서 자격 증명을 가져와야 한다고 지정해요.

Secret을 사용하는 Pod를 만들고 Pod가 실행 중인지 확인해 보세요.

kubectl apply -f my-private-reg-pod.yaml
kubectl get pod private-reg

참고: Pod(또는 Deployment, 또는 여러분이 사용하는 파드 템플릿이 있는 다른 객체)에 이미지 풀 시크릿을 사용하려면, 적절한 Secret이 올바른 네임스페이스에 존재하는지 확인해야 해요. 사용해야 할 네임스페이스는 Pod를 정의한 것과 같은 네임스페이스예요.

또한 Pod가 ImagePullBackOff 상태로 시작하지 못하는 경우 Pod 이벤트를 확인해 보세요.

kubectl describe pod private-reg

그런 다음 FailedToRetrieveImagePullSecret 이유로 이벤트가 보이면, 쿠버네티스가 이름(이 예시에서는 regcred)이 있는 Secret을 찾을 수 없다는 뜻이에요. 지정한 Secret이 존재하고 이름 철자가 올바른지 확인하세요.

Events:
  ...  Reason                           ...  Message
       ------                                -------
  ...  FailedToRetrieveImagePullSecret  ...  Unable to retrieve some image pull secrets (<regcred>); attempting to pull the image may not succeed.

여러 레지스트리의 이미지 사용하기 (Using images from multiple registries)

Pod는 여러 컨테이너를 가질 수 있고, 각 컨테이너 이미지는 다른 레지스트리에서 올 수 있어요. 한 Pod에 여러 imagePullSecrets를 사용할 수 있고, 각각 여러 자격 증명을 포함할 수 있어요.

레지스트리와 일치하는 각 자격 증명으로 이미지 풀을 시도해요. 레지스트리와 일치하는 자격 증명이 없으면, 인가 없이 또는 커스텀 런타임 specific 구성으로 이미지 풀을 시도해요.

다음 단계 (What's next)

  • Secrets에 대해 자세히 배우거나 Secret의 API 참조 읽기
  • 프라이빗 레지스트리 사용에 대해 자세히 배우기
  • 서비스어카운트에 이미지 풀 시크릿 추가하기에 대해 배우기
  • kubectl create secret docker-registry 보기
  • Pod의 컨테이너 정의에 있는 imagePullSecrets 필드 보기

더 알아보기 (Learn more)