셀프 호스팅 앱 업데이트 전에 컨테이너 UID/GID와 볼륨 소유권을 고정하는 방법

에바 왕

IceWhale author

에바 왕 는 기술 작가 그리고 이자 ZimaSpace의 상주 장인입니다. 평생을 기술에 열정을 가진 사람으로서 홈랩과 오픈소스 소프트웨어에 열정을 가지고 있으며,복잡한 기술 개념을 쉽게 이해할 수 있는 실습 가이드로 번역하는 데 전문성을 가지고 있습니다.에바는 셀프 호스팅이 어렵지 않고 재미있어야 한다고 믿습니다. 그녀의 튜토리얼을 통해 커뮤니티가 하드웨어 설정의 신비를 풀도록돕고 있습니다. 첫 NAS 구축부터 Docker 컨테이너 마스터링까지.

How to Lock Container UID/GID and Volume Ownership Before Self-Hosted App Updates - Zima Store Online

배포 시 숫자형 사용자 계약을 고정하고 컨테이너를 교체하기 전에 볼륨 소유권을 검증하면 셀프 호스팅 앱 업데이트로 인해 루트 소유 파일이 생성될 가능성을 줄일 수 있습니다.

예방을 위해서는 이미지 내부 사용자 이름을 안정적인 저장소 식별자로 취급하지 않아야 합니다. 영구 데이터를 기록하는 유효 UID와 GID를 기록하고, 이를 호스트 디렉터리 또는 이름 있는 볼륨에 매핑하며, PUID/PGID 또는 사용자 네임스페이스 설정을 유지해야 합니다. 또한 전체 배포 전에 새 이미지가 작은 쓰기 가능 경로에서 제대로 작동하는지 테스트하세요. 이렇게 하면 이미지 업데이트로 인해 구성 파일, 업로드 파일, 데이터베이스 또는 미디어 메타데이터의 숫자형 소유자가 아무런 표시 없이 변경되는 일을 방지할 수 있습니다.

업데이트 전에 숫자형 UID와 GID 기록하기

모든 쓰기 가능 마운트에서 실행 중인 프로세스 사용자, 기본 그룹, 보조 그룹, 대표 파일의 숫자형 소유권을 기록하세요. 해당 소유권 기준 정보와 함께 이미지 다이제스트 또는 버전도 저장하세요.

Docker의 이미지 빌드 지침에 따르면, 명시적 ID를 사용하면 재빌드에 따른 변동을 방지할 수 있습니다. 자동으로 할당되는 이미지 사용자는 재빌드할 때마다 서로 다른 숫자형 ID를 받을 수 있기 때문입니다.

app 또는 media 같은 이름만 기록하지 말고 숫자도 기록하세요. 새 이미지가 같은 사용자 이름을 재사용하면서 UID를 변경할 수 있으며, 호스트 파일은 숫자형 소유권을 저장합니다.

배포 계약에서 런타임 사용자 고정하기

이미지가 비루트 계정으로 직접 실행되는 것을 지원한다면 Compose 또는 런타임 구성에서 의도한 사용자와 그룹을 명시적으로 지정하세요. 이미지에 루트 초기화 단계가 필요한 경우에는 이후 실제로 영구 데이터를 기록하는 프로세스가 무엇인지 문서화하세요.

Open Container 이미지 사양은 User를 런타임 기본값으로 정의합니다. 따라서 배포에서 의도적으로 재정의하거나 검증하지 않으면 이미지 변경으로 런타임 ID가 달라질 수 있습니다.

지원되는 초기화 모델이 필요한 이미지에 임의의 비루트 UID를 강제로 지정하지 마세요. 영구 파일 소유자를 예측 가능하게 유지하면서 계약은 애플리케이션의 문서화된 설계를 따라야 합니다.

PUID와 PGID를 호스트 소유권에 맞추기

PUID 및 PGID 변수를 제공하는 이미지의 경우, 버전 관리되는 Compose 또는 환경 구성에서 해당 값을 고정하고 호스트 측 볼륨 디렉터리가 이에 해당하는 서비스 계정의 소유인지 확인하세요.

LinuxServer는 PUID가 컨테이너의 쓰기를 매핑한다고 설명합니다. 따라서 매핑된 볼륨에 생성된 파일을 컨테이너 외부에서도 관리할 수 있습니다.

업데이트 전에 구성된 ID를 호스트의 id 명령 결과 및 기존 파일 소유권과 비교하세요. 해당 ID가 다른 사람이나 서비스에 속한 서버에서 1000 같은 예시 값을 무작정 사용하지 마세요.

-15% OFF

ZimaBoard 2 - 당신의 큰 아이디어를 위한 미니 홈 서버

Single board computer zimaboard2

사용자 네임스페이스와 루트리스 매핑 고려하기

루트리스 Docker 또는 Podman에서는 컨테이너 내부에서 프로세스가 루트로 보이더라도 호스트에서는 비루트 UID로 매핑될 수 있습니다. 소유권 변경을 해석하기 전에 네임스페이스 모드와 보조 UID/GID 구성을 기록하세요.

Podman의 런타임 옵션에 따르면 keep-id는 사용자 매핑을 유지합니다. 따라서 컨테이너가 호스트에 마운트된 파일에 예측 가능하게 접근할 수 있습니다.

컨테이너 내부에서 루트처럼 보이는 소유자를 바로 “수정”하지 말고, 먼저 호스트 측 숫자형 ID를 확인하세요. 네임스페이스 내부의 루트와 호스트의 루트가 항상 같은 ID인 것은 아닙니다.

테스트 볼륨에서 새 이미지 사전 점검하기

프로덕션 컨테이너를 교체하기 전에 의도한 UID/GID와 프로덕션 권한을 모방한 임시 디렉터리를 사용해 새 이미지를 실행하세요. 시작 초기화 과정에서 파일과 디렉터리를 하나씩 생성하게 한 다음 호스트 측 소유권을 확인하세요.

Red Hat의 루트리스 볼륨 디버깅 가이드는 호스트 소유권이 컨테이너 내부에 표시되는 사용자 이름이 아니라 UID 매핑을 따른다는 점을 보여 줍니다.

카나리 테스트에서 예상하지 못한 루트 소유 또는 재매핑 파일이 생성되면 배포를 중단하고 이미지 사용자, 엔트리포인트, 네임스페이스 및 마운트 설정을 비교하세요. 전체 사진 또는 데이터베이스 트리에 영향을 주는 재귀적 시작 마이그레이션이 완료된 뒤 변경을 발견하는 것보다 훨씬 안전합니다.

보조 그룹과 쓰기 가능 경로 확인하기

일부 앱은 기본 서비스 UID와 함께 공유 미디어, 다운로드 또는 장치 그룹을 통한 접근 권한이 필요합니다. 해당 그룹 ID를 기록하고 구성 디렉터리뿐 아니라 모든 쓰기 가능 경로를 테스트하세요.

Kubernetes는 명시적인 runAsUser 및 runAsGroup 제어 기능을 사용합니다. 이는 단순한 Docker Compose 배포가 아닌 환경에서도 동일한 Linux 소유권 원칙이 적용된다는 점을 보여 줍니다.

새 이미지가 모든 영구 경로에서 예상한 호스트 소유권으로 파일을 생성하고 컨테이너를 한 번 재생성한 뒤에도 정상 작동한다면 업데이트 정책이 완성된 것입니다. 배포 과정에서 이미 루트 소유 데이터가 생성된 경우에는 이미지 업데이트 후 루트 소유 파일에 관한 관련 ZimaSpace 문서에서 복구 방법을 확인할 수 있습니다.