Docker 이미지를 빌드한 후 실제 서비스 환경에서 사용하려면 이미지를 저장하고 배포할 공간이 필요합니다.
일반적으로 Docker 이미지는 다음과 같은 Registry에 저장합니다.
- Docker Hub
- Amazon ECR
- Google Container Registry
- GitHub Container Registry
- Private Docker Registry
Docker Buildx에서는 빌드한 이미지를 바로 Registry에 업로드할 수 있는 기능을 제공합니다.
이때 사용하는 옵션이 바로 **--push**입니다.
docker buildx build --push는 이미지를 빌드한 후 자동으로 Docker Registry에 업로드하는 옵션입니다.
특히 멀티 플랫폼 이미지를 생성할 때 가장 많이 사용하는 방식입니다.
예:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t username/app:v1 \
--push .빌드 후 자동으로 Registry에 저장됩니다.
이번 글에서는 Docker Buildx Build –push의 개념부터 기본 사용법, Docker Hub Push, 멀티 플랫폼 이미지 업로드, CI/CD 활용 방법까지 자세히 알아보겠습니다.
Docker Buildx Build –push란 무엇인가?
--push 옵션은 빌드 결과 이미지를 Registry로 바로 업로드하는 기능입니다.
기본 형식:
docker buildx build \
-t 이미지명 \
--push .동작 과정:
Dockerfile
↓
Docker Buildx Build
↓
Docker Image 생성
↓
Registry Push빌드와 업로드를 한 번에 처리합니다.
Docker Buildx Build –push는 언제 사용하는가?
다음과 같은 환경에서 사용합니다.
- 운영 서버 배포
- CI/CD 자동화
- 멀티 플랫폼 이미지 생성
- Docker Hub 관리
- Private Registry 운영
특히 Kubernetes 환경에서는 Registry 저장이 필수적이기 때문에 자주 사용됩니다.
Docker Registry 로그인하기
Push 전에 Registry 인증이 필요합니다.
Docker Hub:
docker login입력:
Username:
Password:로그인이 완료되면 이미지를 Push할 수 있습니다.
Docker Buildx Build –push 기본 사용법
예:
docker buildx build \
-t username/app:v1 \
--push .과정:
- Dockerfile 읽기
- 이미지 빌드
- Registry 업로드
까지 자동으로 진행됩니다.
Docker Hub에 이미지 Push하기
예:
docker buildx build \
-t myaccount/web:v1 \
--push .Docker Hub 저장 위치:
docker.io/myaccount/web:v1다른 서버에서도:
docker pull myaccount/web:v1사용할 수 있습니다.
멀티 플랫폼 이미지 Push하기
Buildx –push의 가장 중요한 활용 사례입니다.
예:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:latest \
--push .생성 구조:
company/app:latest
├── linux/amd64
└── linux/arm64Registry에는 Manifest가 함께 저장됩니다.
Push 후 이미지 확인하기
업로드 확인:
docker buildx imagetools inspect company/app:latest결과:
Platforms:
linux/amd64
linux/arm64정상적으로 여러 플랫폼 이미지가 등록된 것을 확인할 수 있습니다.
Docker Buildx Build –push와 –load 차이
두 옵션은 저장 위치가 다릅니다.
–push
저장 위치:
Docker Registry예:
docker buildx build \
--push .사용:
- 운영 배포
- Kubernetes
- CI/CD
–load
저장 위치:
Local Docker Engine예:
docker buildx build \
--load .사용:
- 로컬 테스트
- 개발 환경
Docker Buildx Build –push CI/CD 활용
CI/CD에서는 일반적으로 다음 형태로 사용합니다.
docker buildx build \
--platform linux/amd64 \
-t company/app:${VERSION} \
--push .장점:
- 자동 이미지 생성
- 자동 Registry 저장
- 배포 시스템 연동 가능
Docker Buildx Build –push Private Registry 사용
Private Registry도 동일하게 사용할 수 있습니다.
로그인:
docker login registry.company.com빌드:
docker buildx build \
-t registry.company.com/app:v1 \
--push .사내 Docker Registry에 저장됩니다.
Linux 서버 문제 해결
CI/CD 서버에서 이미지 빌드를 완료했지만 다른 서버에서 이미지를 찾을 수 없었습니다.
기존 명령:
docker buildx build \
-t company/app:v1 .문제:
Unable to find image확인 결과 이미지는 Build Cache에만 존재하고 Registry에는 업로드되지 않았습니다.
해결:
docker buildx build \
-t company/app:v1 \
--push .Push 완료:
pushed company/app:v1다른 서버:
docker pull company/app:v1정상적으로 이미지를 사용할 수 있게 되었습니다.
Docker Buildx Build –push 사용 시 주의사항
첫 번째는 Registry 로그인이 필요합니다.
두 번째는 이미지 Tag에 Registry 주소가 정확해야 합니다.
세 번째는 멀티 플랫폼 빌드에서는 일반적으로 --push가 필요합니다.
네 번째는 Push 전 이미지 이름과 버전을 확인해야 합니다.
Best Practice
Docker Buildx Build –push 사용 방법:
- 운영 이미지는 버전 Tag 사용
- Push 전 Registry 로그인 확인
- 멀티 플랫폼은 –push 활용
- CI/CD 자동화를 구성
- Push 후 imagetools inspect 확인
- Private Registry 권한 관리
자주 묻는 질문
–push 옵션은 무엇인가요?
빌드한 Docker 이미지를 Registry에 자동 업로드하는 옵션입니다.
–push와 docker push 차이는 무엇인가요?
docker push는 이미 생성된 이미지를 업로드하고, --push는 빌드 과정에서 바로 업로드합니다.
멀티 플랫폼 이미지도 Push할 수 있나요?
가능합니다.
오히려 멀티 플랫폼 빌드에서는 가장 일반적인 방식입니다.
Push한 이미지는 어디서 사용할 수 있나요?
Registry 접근 권한이 있는 모든 Docker 환경에서 사용할 수 있습니다.
마무리
Docker Buildx Build –push는 Docker 이미지 배포 과정에서 가장 중요한 기능 중 하나입니다.
빌드와 동시에 Registry에 이미지를 저장할 수 있어 CI/CD 자동화와 Kubernetes 배포 환경에서 필수적으로 사용됩니다.
특히 멀티 플랫폼 이미지를 운영한다면 --platform과 --push를 함께 활용하여 AMD64와 ARM64 환경을 모두 지원하는 안정적인 Docker 이미지 배포 구조를 만들 수 있습니다.