IaC/Container

도커 이미지 복사 자동화: buildx imagetools vs skopeo 실전 비교

Somaz 2025. 10. 1. 08:32
728x90
반응형

Overview

CI/CD 환경이나 사내 레지스트리를 운영하다 보면, 외부 Docker Hub, GCR, ghcr.io 등에서 사용하는 이미지를 내부 레지스트리(Harbor, Nexus 등)로 복사해 관리할 필요가 생긴다.

 

 

특히 다음과 같은 상황에서 유용하다.

  • 외부 이미지의 pull 제한 우회 (Docker Hub Rate Limit)
  • 인터넷이 제한된 환경(사내망)에서 외부 의존성 제거
  • 이미지 신뢰도 확보 및 보안 감사 용이성

 

 

이런 목적에 사용되는 대표적인 툴은 다음 두 가지이다.

 

 

 

 

 

 

 

 

 

 

`docker buildx imagetools create`

 

예시

docker buildx imagetools create \
  --tag harbor.somaz.link/library/node:latest \
  node:latest

 

 

다양한 이미지 복사 예시

# Python 이미지 복사
docker buildx imagetools create \
  --tag harbor.example.com/library/python:3.14-slim \
  python:3.14-slim

# Alpine 이미지 복사
docker buildx imagetools create \
  --tag harbor.example.com/library/alpine:3.23 \
  alpine:3.23

# Golang 이미지 복사
docker buildx imagetools create \
  --tag harbor.example.com/library/golang:1.26-alpine \
  golang:1.26-alpine

 

 

 

 

특징

  • Docker CLI 기반, 멀티플랫폼 이미지 통째로 복사 가능
  • manifest list를 그대로 가져옴
  • Docker Hub pull limit 회피 불가 (로그인 필요)

 

 

장점

  • Docker 설치만으로 사용 가능
  • buildx 활성화하면 곧바로 사용 가능

 

 

단점

  • layer-level 캐시 재활용은 불가
  • 일부 프록시 이미지에서 실패 사례 있음

 

 

사설 레지스트리(HTTP) 사용 시 설정

Harbor 등 사설 레지스트리를 HTTP(비 TLS) 로 운영하는 경우, 기본 buildx builder로는 push가 실패한다. 이때 `buildkitd.toml` 설정과 함께 별도 builder를 생성해야 한다.

# /tmp/buildkitd.toml
[registry."harbor.example.com"]
  http = true
  insecure = true
 
docker buildx create --name insecure-builder \
  --driver docker-container \
  --config /tmp/buildkitd.toml \
  --driver-opt env.DOCKER_CONFIG=/root/.docker \
  --use

이 설정은 imagetools create 뿐만 아니라, `docker buildx build --push` 시에도 동일하게 적용된다.

 

 

 

 

 

 

 

 

 

 

`skopeo copy`: 더 정교한 복사

 

 

예시

docker buildx imagetools create \
  --tag harbor.somaz.link/library/node:latest \
  node:latest
 
 
 
 

특징

  • 이미지의 메타데이터, 레이어별로 세밀하게 복사 가능
  • `--src-creds`, `--dest-creds`, `--all` 옵션 지원
  • OCI, dir, docker-archive 등 다양한 스토리지 형식도 복사 가능

 

 

장점

  • 인증, 사설 레지스트리, 미러 복사에 최적화
  • Docker 없이도 사용 가능

 

 

단점

  • 학습 난이도 약간 있음
  • Docker Desktop 사용자에겐 생소할 수 있음

 

 

 

오프라인 복사 (로컬 디렉토리 경유)

레지스트리가 일시적으로 접근 불가하거나, 네트워크가 분리된 환경에서는 로컬 디렉토리에 먼저 저장한 뒤 나중에 push하는 패턴이 유용하다.

# skopeo 설치 (Mac)
brew install skopeo

# 1) 외부 이미지를 로컬 디렉토리에 멀티아키텍처로 저장
skopeo copy --all docker://python:3.14-slim dir:///tmp/python-3.14-slim
skopeo copy --all docker://alpine:3.23 dir:///tmp/alpine-3.23
skopeo copy --all docker://golang:1.26-alpine dir:///tmp/golang-1.26-alpine

# 2) 사설 레지스트리 로그인
skopeo login harbor.example.com --tls-verify=false -u admin

# 3) 레지스트리 정상화 후 push
skopeo copy --all --dest-tls-verify=false \
  dir:///tmp/python-3.14-slim docker://harbor.example.com/library/python:3.14-slim

skopeo copy --all --dest-tls-verify=false \
  dir:///tmp/alpine-3.23 docker://harbor.example.com/library/alpine:3.23

skopeo copy --all --dest-tls-verify=false \
  dir:///tmp/golang-1.26-alpine docker://harbor.example.com/library/golang:1.26-alpine

`dir://` 포맷은 OCI 레이아웃으로 저장되므로, USB나 파일 전송을 통한 에어갭(Air-gap) 환경 배포에도 활용 가능하다.

 

 

 

 

 

 

 

 

buildx vs skopeo 요약 비교

항목 buildx imagetools skopeo
설치 난이도 낮음 (Docker만 필요) 약간 있음 (별도 설치)
지원 플랫폼 Docker registry 기반만 다양한 이미지 형식
인증 옵션 약함 (Docker config 기준) 매우 강력 (--creds)
복사 정밀도 단순한 전체 복사 레이어 단위 복사 가능
멀티플랫폼 이미지 지원 지원 (--all)

 

 

 

어떤 툴을 선택해야 할까?

상황 추천 툴
간단한 Docker 이미지 복사 자동화 docker buildx imagetools
프라이빗 레지스트리 간 복사 / 인증 필요 / 고급 컨트롤 skopeo
OCI 아카이브 또는 디스크 백업/복원 등도 필요 skopeo
HTTP 사설 레지스트리 사용 시 둘 다 가능 (buildx: buildkitd.toml / skopeo: --tls-verify=false)
오프라인/에어갭 환경 배포 skopeo (dir:// 활용)

 

 

 

 

 

실전 스크립트 예제

 

buildx 기반 자동 복사 스크립트

#!/bin/bash
images=(
  "alpine:latest"
  "node:latest"
  "refinedev/node:18"
  "gcr.io/kaniko-project/executor:v1.23.0-debug"
)

for image in "${images[@]}"; do
  docker buildx imagetools create \
    --tag "harbor.somaz.link/library/${image,,}" \
    "$image"
done

 

 

 

skopeo 기반 자동 복사 스크립트 (로그인 필요)

#!/bin/bash

SRC_USER="docker_user"
SRC_PASS="docker_password"
DST_USER="harbor_user"
DST_PASS="harbor_password"

images=(
  "docker://alpine:latest"
  "docker://node:latest"
  "docker://refinedev/node:18"
  "docker://gcr.io/kaniko-project/executor:v1.23.0-debug"
)

for image in "${images[@]}"; do
  name=$(basename "$image")
  skopeo copy \
    --src-creds "$SRC_USER:$SRC_PASS" \
    --dest-creds "$DST_USER:$DST_PASS" \
    "$image" \
    "docker://harbor.somaz.link/library/$name"
done
  • 참고: basename을 그대로 쓰면 `executor:v1.23.0-debug` 같은 이름이 보존된다.

 

 

 

 

 

 

 

 

 

 

마무리

외부 이미지 의존성이 늘어나는 현대의 개발·운영 환경에서, 이미지 복사 자동화는 단순한 편의성을 넘어서 보안성, 가용성, 속도 개선까지 영향을 미치는 중요한 인프라 구성 요소이다.

 

 

 

이번 글에서 소개한 `docker buildx imagetools` 와 `skopeo` 는 각각의 강점이 뚜렷하며, 상황에 따라 선택적으로 사용할 수 있다.

  • 간단한 복사 자동화나 멀티플랫폼 이미지 통째 복사에는 `buildx imagetools`
  • 인증 정보 제어, 복사 대상 형식 다양성, 고급 커스텀 작업이 필요할 땐 `skopeo`

 

 

CI/CD 파이프라인 안에 이미지 복사 작업을 넣고 싶다면, 위에서 소개한 예제 스크립트를 참고해 자신만의 자동화 방식을 구성해보세요.

이미지 복사도 결국 신뢰성과 유연성이 핵심이다.

 

 


내부 레지스트리를 제대로 활용하려면, 이런 기초 도구에 대한 이해는 필수이다.

 

 

 

 

 

 

 

 

Reference

https://docs.docker.com/buildx/working-with-buildx/#imagetools

https://github.com/containers/skopeo

https://github.com/containers/skopeo/blob/main/docs/skopeo.1.md

https://goharbor.io/docs/2.13.0/

728x90
반응형

'IaC > Container' 카테고리의 다른 글

Docker 이미지 최적화 실전 가이드  (0) 2026.02.10
Dockerfile 빌드 원칙 & Layer  (4) 2024.07.22
Docker Compose: 컨테이너화된 애플리케이션 구성 및 실행 가이드  (0) 2024.05.02
Dockerfile 보안 설정(Hadolint)  (0) 2024.02.25
Dockerfile이란?  (0) 2023.04.28

'IaC/Container'의 다른글

  • 현재글도커 이미지 복사 자동화: buildx imagetools vs skopeo 실전 비교

관련글

댓글

티스토리툴바