Docker 이미지를 관리하다 보면 이미지 이름과 Tag만으로는 부족한 경우가 있습니다.
예:
- 어떤 팀에서 만든 이미지인지
- 어떤 버전으로 빌드했는지
- 어떤 환경에서 생성되었는지
- 배포 목적이 무엇인지
같은 추가 정보가 필요할 수 있습니다.
Docker는 이러한 정보를 이미지 내부에 저장할 수 있도록 Label(라벨) 기능을 제공합니다.
Docker Buildx Build에서는 --label 옵션을 사용하여 이미지에 메타데이터를 추가할 수 있습니다.
예:
docker buildx build \
--label version=1.0 \
--label author=dev-team \
-t app:v1 .생성된 이미지에 원하는 정보를 저장할 수 있습니다.
이번 글에서는 Docker Buildx Build –label의 개념부터 기본 사용법, 이미지 정보 확인 방법, CI/CD 활용, 운영 환경 관리 방법까지 자세히 알아보겠습니다.
Docker Buildx Build –label이란 무엇인가?
--label은 Docker 이미지에 사용자 정의 메타데이터를 추가하는 옵션입니다.
기본 형식:
docker buildx build \
--label 키=값 .예:
docker buildx build \
--label app=backend \
-t api:v1 .이미지 내부에 추가 정보가 저장됩니다.
Docker Label이란 무엇인가?
Docker Label은 이미지에 저장되는 Key-Value 형태의 정보입니다.
예:
version = 1.0
environment = production
team = backend특징:
- 이미지 설명 정보 저장
- 검색 및 관리 가능
- 실행 환경 정보 기록
- 자동화 시스템 활용 가능
Docker Buildx Build –label을 사용하는 이유
이미지가 많아지면 다음 문제가 발생합니다.
이 이미지가 어디서 만들어졌는가?
누가 관리하는가?
어떤 버전인가?
운영용인가 테스트용인가?Label을 추가하면 이미지 정보를 쉽게 구분할 수 있습니다.
Docker Buildx Build –label 기본 사용법
예:
docker buildx build \
--label maintainer=team-a \
-t app:v1 .이미지에 관리 정보를 추가합니다.
여러 Label 추가하기
여러 개의 Label을 사용할 수 있습니다.
예:
docker buildx build \
--label version=1.0 \
--label environment=production \
--label owner=backend \
-t app:v1 .여러 정보를 동시에 저장할 수 있습니다.
Docker Image Label 확인하기
빌드 후 확인:
docker inspect app:v1결과:
{
"Labels": {
"version": "1.0",
"environment": "production"
}
}저장된 Label 정보를 확인할 수 있습니다.
Docker Buildx Build –label과 Dockerfile LABEL 차이
두 방법 모두 Label을 추가합니다.
Dockerfile LABEL
Dockerfile:
LABEL version="1.0"Buildx –label
빌드:
docker buildx build \
--label version=1.0 .차이:
Dockerfile LABEL
= 이미지 내부 고정
--label
= 빌드 시 동적 추가Docker Buildx Build –label 실무 활용 예제
빌드 버전 기록
빌드:
docker buildx build \
--label build.version=2026.07.28 \
-t app:v1 .확인:
docker inspect app:v1결과:
build.version=2026.07.28빌드 기록을 관리할 수 있습니다.
CI/CD 자동화 활용
CI 환경:
docker buildx build \
--label git.commit=${COMMIT_SHA} \
--label build.number=${BUILD_NUMBER} \
-t company/app:v1 \
--push .저장 정보:
Commit 정보
Build 번호
배포 정보자동으로 추적할 수 있습니다.
Docker 이미지 관리 자동화
Label을 기준으로 이미지를 검색할 수 있습니다.
예:
docker images --filter label=environment=production운영 이미지만 찾을 수 있습니다.
Linux 서버 문제 해결
운영 서버에 비슷한 이름의 이미지가 여러 개 존재했습니다.
기존:
docker images문제:
어떤 이미지가 운영 버전인지 구분 어려움Label 추가:
docker buildx build \
--label environment=production \
--label version=2.0 \
-t app:v2 .확인:
docker inspect app:v2결과:
environment=production
version=2.0이미지 목적을 쉽게 확인할 수 있었습니다.
Docker Buildx Build –label 사용 시 주의사항
첫 번째는 Label에는 민감 정보를 저장하면 안 됩니다.
두 번째는 Label은 검색과 관리 목적이지 보안 저장소가 아닙니다.
세 번째는 팀에서 Label 규칙을 통일하는 것이 좋습니다.
네 번째는 너무 많은 Label은 관리 복잡성을 증가시킬 수 있습니다.
Best Practice
Docker Buildx Build –label 활용 방법:
- 버전 정보 기록
- Git Commit 정보 저장
- 운영 환경 구분
- 담당 팀 정보 추가
- CI/CD 자동화 연동
- Label 규칙 표준화
자주 묻는 질문
Docker Buildx Build –label은 무엇인가요?
Docker 이미지에 메타데이터 정보를 추가하는 옵션입니다.
Label과 Tag 차이는 무엇인가요?
Tag는 이미지 이름과 버전을 구분하고, Label은 이미지 내부 설명 정보를 저장합니다.
Label 정보를 어떻게 확인하나요?
docker inspect 명령으로 확인할 수 있습니다.
Label에 비밀번호를 저장해도 되나요?
아닙니다.
Label은 공개될 수 있으므로 민감 정보 저장용으로 사용하면 안 됩니다.
마무리
Docker Buildx Build –label은 Docker 이미지 관리와 추적성을 높여주는 유용한 기능입니다.
이미지 이름이나 Tag만으로 부족한 정보를 추가할 수 있으며, 버전 관리, CI/CD 자동화, 운영 환경 구분 등 다양한 상황에서 활용할 수 있습니다.
특히 대규모 Docker 환경에서는 Label 규칙을 정하고 활용하면 수많은 이미지를 더욱 체계적으로 관리할 수 있습니다.