Ubuntu 환경 Docker 셋업 및 GCP Artifact Registry 인증 연동

VM 내부 런타임 환경 구축의 필요성

2026.05.24 - [프로젝트/똑똣] - GCP 단일 VM 프로비저닝: 서비스 계정(IAM) 최소 권한 원칙 적용

GCP 단일 VM 프로비저닝: 서비스 계정(IAM) 최소 권한 원칙 적용

이전 글을 통해 보안이 강화된 GCP 깡통 인스턴스(Ubuntu 22.04 LTS)를 준비하고 IAP(Identity-Aware Proxy)를 통해 안전하게 접속하는 것까지 완료했습니다. 이제 이 서버 위에서 Spring Boot 서버와 데이터베이스 프록시, 캐시 메모리를 구동해야 합니다.

애플리케이션과 인프라의 결합도를 낮추고 배포의 일관성을 유지하기 위해 모든 서비스는 컨테이너 형태로 실행할 것입니다. 이번 글에서는 Ubuntu 환경에 공식 저장소를 통해 최신 Docker 엔진을 설치하고, GCP의 프라이빗 이미지 저장소인 Artifact Registry와 연동하여 안전하게 이미지를 내려받을 수 있는 런타임 환경을 셋업해 보겠습니다.

패키지 매니저를 통한 최신 Docker 및 Compose 설치

우분투 기본 저장소에 포함된 docker.io 패키지는 버전이 낮아 최신 기능이나 보안 패치가 누락되어 있을 수 있습니다. 따라서 기존 충돌 가능한 패키지들을 깔끔하게 지우고 Docker 공식 GPG 키와 저장소를 추가하여 설치를 진행합니다.

먼저, 구형 패키지가 있다면 삭제하고 필수 의존성 패키지를 설치합니다.

sudo apt-get remove -y docker docker-engine docker.io containerd runc 2>/dev/null
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

다음으로 Docker 공식 GPG 키를 다운로드하여 시스템에 안전하게 등록합니다.

sudo install -m 0755 -d /etc/apt/keyrings 
curl -fsSL [https://download.docker.com/linux/ubuntu/gpg](https://download.docker.com/linux/ubuntu/gpg) | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

이제 apt 소스 리스트에 Docker 공식 저장소를 추가하고, 최신 버전의 Docker Engine과 Docker Compose 플러그인을 설치합니다.

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] [https://download.docker.com/linux/ubuntu](https://download.docker.com/linux/ubuntu) $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

설치가 완료되면 버전을 확인하여 정상 구동을 검증합니다.

sudo docker version
sudo docker compose version

출력 결과:

Client: Docker Engine - Community
 Version:           29.5.2
...
Docker Compose version v5.1.4

사용자 권한 설정(usermod) 및 sudo 종속성 탈피

Docker 데몬은 기본적으로 root 권한으로 실행되므로, 일반 사용자 계정에서 docker 명령어를 치려면 매번 sudo를 붙여야 하는 번거로움이 있습니다. 이를 해결하기 위해 현재 접속한 사용자를 docker 그룹에 추가합니다.

sudo usermod -aG docker $USER
newgrp docker

명령어 실행 후 터미널 세션을 다시 맺거나 newgrp 명령어를 통해 그룹 변경 사항을 즉시 적용하면, 이후부터는 sudo 없이도 자유롭게 컨테이너를 제어할 수 있습니다.

GCP Artifact Registry 연동을 위한 Docker Credential 설정

로컬이나 GitHub Actions CI 환경에서 빌드된 애플리케이션 이미지는 퍼블릭 Docker Hub가 아닌, 우리 프로젝트의 프라이빗 저장소인 GCP Artifact Registry(AR)에 보관됩니다. 앞서 1편에서 VM의 서비스 계정에 roles/artifactregistry.reader 권한을 부여해 둔 상태입니다.

이제 Docker가 GCP의 저장소(asia-northeast3-docker.pkg.dev)와 통신할 때 해당 서비스 계정의 자격 증명(Credential)을 사용하도록 인증 헬퍼(Credential Helper)를 설정해 주어야 합니다.

gcloud auth configure-docker asia-northeast3-docker.pkg.dev --quiet

출력 결과:

Adding credentials for: asia-northeast3-docker.pkg.dev
Docker configuration file updated.

설정이 잘 되었는지, 그리고 서비스 계정이 레포지토리 목록을 정상적으로 읽어올 수 있는지 확인해 봅니다.

gcloud artifacts repositories list --location=asia-northeast3

출력 결과:

                                                       ARTIFACT_REGISTRY
REPOSITORY     FORMAT  MODE                 DESCRIPTION                    LOCATION         LABELS  ENCRYPTION          CREATE_TIME          UPDATE_TIME          SIZE (MB)
toktot-images  DOCKER  STANDARD_REPOSITORY  toktot backend container images  asia-northeast3          Google-managed key  2026-05-20T02:18:45  2026-05-20T13:55:24  278.678

정상적으로 278MB 크기의 이미지를 보유한 toktot-images 저장소가 조회되는 것을 볼 수 있습니다. 이로써 외부 환경으로부터 안전하게 보호되는 Private Registry에서 컨테이너 이미지를 Pull 해올 완벽한 준비가 끝났습니다.

결론

Ubuntu 패키지 매니저를 활용해 깨끗한 상태의 최신 Docker 런타임을 구성했고, GCP Artifact Registry를 연동하여 안전한 애플리케이션 이미지 배포망을 연결했습니다.

인프라 구성의 모든 기반 작업이 끝났습니다. 다음 마지막 글에서는 GCP Secret Manager를 활용해 보안에 민감한 환경 변수들을 동적으로 가져오고, Docker Compose를 이용해 다중 컨테이너(Spring Boot, Redis, Cloud SQL Proxy)를 오케스트레이션하여 띄우는 과정을 살펴보도록 하겠습니다.