이미지 레지스트리 사용 구성하기

원문 보기 위키 갱신 2026.10.11

Calico가 퍼블릭 또는 프라이빗 컨테이너 레지스트리에서 이미지를 가져오도록 구성하는 방법을 다뤄요. 에어갭(air-gapped) 클러스터나 대역폭·보안 제약이 있는 환경에서 특히 유용해요. 레지스트리 지정, 이미지 경로, Windows 이미지 복사까지 단계별로 안내해요.

출처: 문서

본문

큰 그림

퍼블릭 또는 프라이빗 레지스트리에서 이미지를 가져오도록 Calico를 구성해요.

이런 점이 좋아요

많은 배포에서 서드파티 프라이빗 저장소로 클러스터에 Calico를 설치하는 것이 불가능해요. Calico는 다음과 같은 퍼블릭·프라이빗 레지스트리 옵션을 제공하고, 어떤 조합으로든 사용할 수 있어요.

에어갭 클러스터, 대역폭이나 보안 제약이 있는 클러스터 같은 용도라면 레지스트리에서 설치
Calico 이미지를 레지스트리의 하위 경로로 가져왔다면 레지스트리의 이미지 경로에서 설치
레지스트리 다이제스트로 이미지 설치

개념

컨테이너 이미지 레지스트리(흔히 레지스트리라고 불려요)는 컨테이너 이미지를 푸시하고, 풀하고, 저장할 수 있는 서비스예요. Kubernetes에서 레지스트리는 공개적으로 접근할 수 없을 때 프라이빗으로 간주해요.

프라이빗 레지스트리에는 **이미지 풀 시크릿(image pull secret)**이 필요해요. 이미지 풀 시크릿은 이미지 레지스트리에 대한 인증을 제공해요. 이를 통해 특정 이미지에 대한 접근을 제어하거나 더 높은 풀 레이트 제한(DockerHub 같은)을 받을 수 있어요.

**이미지 경로(image path)**는 Calico 설치에 필요한 이미지를 담고 있는 레지스트리 안의 디렉터리예요.

시작하기 전에

필요 사항

Calico가 오퍼레이터로 관리되고 있어야 해요
레지스트리에 대한 풀 접근을 구성해야 해요
사용자 인증이 필요한 프라이빗 레지스트리를 사용한다면, tigera-operator 네임스페이스에 레지스트리용 이미지 풀 시크릿이 구성되어 있는지 확인하세요. REGISTRY_PULL_SECRET 환경 변수를 시크릿 이름으로 설정해요. 도움이 필요하면 Installation 리소스 레퍼런스의 imagePullSecrets와 registry 필드를 참고하세요.
Calico for Windows 이미지를 관리할 때는 Crane 명령을 사용하세요. 이 이미지들에는 docker pull 명령이 실행 환경의 OS와 버전에 따라 동작하지 않을 수 있어요.

방법

다음 예시는 퍼블릭·프라이빗 레지스트리의 경로 형식인 $REGISTRY/를 보여 줘요. 이미지 경로를 사용한다면 $REGISTRY/$IMAGE_PATH/ 형식으로 바꾸세요.

Calico 이미지를 자신의 레지스트리로 푸시하기

자신의 레지스트리에서 이미지를 설치하려면 먼저 Tigera 레지스트리에서 이미지를 풀하고, 자신의 레지스트리 이름으로 리태그한 다음, 새로 태그한 이미지를 자신의 레지스트리로 푸시해야 해요. Calico for Windows 이미지(node-windows와 cni-windows)에는 풀+리태그+푸시 대신 crane cp 명령을 사용하세요.

다음 명령으로 필요한 Calico 이미지를 풀해요.

docker pull quay.io/tigera/operator:v1.44.0
docker pull quay.io/calico/calico:v3.33.0
docker pull quay.io/calico/node:v3.33.0
docker pull quay.io/calico/whisker:v3.33.0
docker pull quay.io/calico/envoy-gateway:v3.33.0
docker pull quay.io/calico/envoy-proxy:v3.33.0
docker pull quay.io/calico/envoy-ratelimit:v3.33.0

이미지를 자신의 레지스트리 이름 $REGISTRY로 리태그해요.

docker tag quay.io/tigera/operator:v1.44.0 $REGISTRY/tigera/operator:v1.44.0
docker tag quay.io/calico/calico:v3.33.0 $REGISTRY/calico/calico:v3.33.0
docker tag quay.io/calico/node:v3.33.0 $REGISTRY/calico/node:v3.33.0
docker tag quay.io/calico/whisker:v3.33.0 $REGISTRY/calico/whisker:v3.33.0
docker tag quay.io/calico/envoy-gateway:v3.33.0 $REGISTRY/calico/envoy-gateway:v3.33.0
docker tag quay.io/calico/envoy-proxy:v3.33.0 $REGISTRY/calico/envoy-proxy:v3.33.0
docker tag quay.io/calico/envoy-ratelimit:v3.33.0 $REGISTRY/calico/envoy-ratelimit:v3.33.0

이미지를 자신의 레지스트리로 푸시해요.

docker push $REGISTRY/tigera/operator:v1.44.0
docker push $REGISTRY/calico/calico:v3.33.0
docker push $REGISTRY/calico/node:v3.33.0
docker push $REGISTRY/calico/whisker:v3.33.0
docker push $REGISTRY/calico/envoy-gateway:v3.33.0
docker push $REGISTRY/calico/envoy-proxy:v3.33.0
docker push $REGISTRY/calico/envoy-ratelimit:v3.33.0

crane cp를 사용해 Windows 이미지를 자신의 프라이빗 레지스트리로 복사해요.

Linux + Windows 하이브리드 클러스터라면 다음 Windows 이미지에 crane cp를 사용해 프라이빗 레지스트리로 복사해요.

crane cp quay.io/calico/node-windows:v3.33.0 $REGISTRY/calico/node-windows:v3.33.0
crane cp quay.io/calico/cni-windows:v3.33.0 $REGISTRY/calico/cni-windows:v3.33.0

자신의 레지스트리 이미지로 오퍼레이터 실행하기

tigera-operator.yaml을 적용하기 전에 레지스트리 참조를 자신의 커스텀 레지스트리로 수정해요.

OpenShift인 경우

모든 매니페스트를 먼저 내려받은 다음 다음을 수정해요.

sed -ie "s?quay.io?$REGISTRY?g" manifests/02-tigera-operator.yaml

그 외 모든 플랫폼인 경우

sed -ie "s?quay.io?$REGISTRY?g" tigera-operator.yaml

다음으로, 프라이빗 레지스트리에 사용자 인증을 적용한다면 자신의 registry용 이미지 풀 시크릿을 tigera-pull-secret 시크릿에 추가해요.

sed -ie "/serviceAccountName: tigera-operator/a \      imagePullSecrets:\n\      - name: $REGISTRY_PULL_SECRET"  tigera-operator.yaml

오퍼레이터가 이미지를 사용하도록 구성하기

Installation 리소스의 spec.registry 필드를 자신의 커스텀 레지스트리 이름으로 설정해요. 예를 들면 다음과 같아요.

apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
  name: default
spec:
  variant: Calico
  imagePullSecrets:
    - name: tigera-pull-secret
  registry: myregistry.com

더 알아보기 (Learn more)

핵심 흐름은 "Tigera 레지스트리에서 풀 → $REGISTRY로 리태그 → 푸시"예요. Windows 이미지는 docker 대신 crane cp로 복사해야 한다는 점을 잊지 마세요. 다이제스트 기반 설치가 필요하면 ImageSet 문서를 함께 확인해 보세요.