레지스트리 사용량을 관리하지 않으면 컨테이너 레지스트리는 시간이 지남에 따라 크기가 커질 수 있습니다. 예를 들어 대량의 이미지나 태그를 추가하면:

• 사용 가능한 태그나 이미지 목록을 가져오는 속도가 느려집니다.
• 서버에서 많은 양의 스토리지 공간을 차지합니다.

불필요한 이미지와 태그를 삭제하고 컨테이너 레지스트리 정리 정책을 설정하여 컨테이너 레지스트리 사용량을 자동으로 관리해야 합니다.

컨테이너 레지스트리 사용량 보기#

히스토리

• GitLab 15.7에서 도입됨

컨테이너 레지스트리 리포지터리의 스토리지 사용량 데이터를 확인합니다.

프로젝트의 경우#

사전 요구 사항:

• GitLab Self-Managed 인스턴스의 경우, 관리자가 컨테이너 레지스트리 메타데이터 데이터베이스를 활성화해야 합니다.
• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있거나 네임스페이스에 대한 Owner 권한이 있어야 합니다.

프로젝트의 스토리지 사용량을 보려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 다음 중 하나를 수행합니다:
   • 전체 스토리지 사용량을 보려면 Settings > Usage quotas를 선택합니다. Namespace entities 아래에서 Container Registry를 선택하여 개별 리포지터리를 봅니다.
   • 리포지터리별 스토리지 사용량을 직접 보려면 Deploy > Container Registry를 선택합니다.

다음을 사용할 수도 있습니다:

• Projects API를 사용하여 프로젝트의 총 컨테이너 레지스트리 스토리지를 가져옵니다. 자세한 내용은 단일 프로젝트 가져오기를 참조하세요.
• 컨테이너 레지스트리 API를 사용하여 특정 리포지터리의 크기 데이터를 가져옵니다. 자세한 내용은 단일 리포지터리 세부 정보 가져오기를 참조하세요.

그룹의 경우#

사전 요구 사항:

• GitLab Self-Managed 인스턴스의 경우, 관리자가 컨테이너 레지스트리 메타데이터 데이터베이스를 활성화해야 합니다.
• 그룹에 대한 Owner 권한이 있어야 합니다.

그룹의 스토리지 사용량을 보려면:

1. 왼쪽 사이드바에서 Settings > Usage quotas를 선택합니다.
2. Storage 탭을 선택합니다.

Groups API를 사용하여 그룹 내 모든 프로젝트의 총 컨테이너 레지스트리 스토리지를 가져올 수도 있습니다.

스토리지 데이터 업데이트#

메타데이터 데이터베이스가 활성화된 후:

• 새 컨테이너 이미지의 경우, 푸시한 직후 크기 데이터를 사용할 수 있습니다.
• 기존 컨테이너 이미지의 경우, 크기 데이터가 백그라운드에서 계산되며 최대 24시간이 걸릴 수 있습니다.

스토리지 데이터 업데이트가 발생하는 시점:

• 컨테이너 이미지를 푸시하거나 삭제하면 즉시.
• 다음을 수행할 때 실시간으로:
  • UI에서 리포지터리 이미지 태그를 봅니다.
  • 컨테이너 레지스트리 API를 사용하여 단일 리포지터리 세부 정보 가져오기를 수행합니다.
• 프로젝트의 컨테이너 리포지터리에서 태그를 푸시하거나 삭제할 때.
• 그룹의 경우 5분마다.

컨테이너 레지스트리 사용량 계산 방법#

컨테이너 레지스트리에 저장된 이미지 레이어는 루트 네임스페이스 수준에서 중복이 제거됩니다.

이미지는 다음 경우에 한 번만 계산됩니다:

• 동일한 리포지터리에서 동일한 이미지에 두 번 이상 태그를 지정하는 경우.
• 동일한 루트 네임스페이스 아래의 서로 다른 리포지터리에서 동일한 이미지에 태그를 지정하는 경우.

이미지 레이어는 다음 경우에 한 번만 계산됩니다:

• 동일한 컨테이너 리포지터리, 프로젝트 또는 그룹의 여러 이미지에서 이미지 레이어를 공유하는 경우.
• 서로 다른 리포지터리에서 이미지 레이어를 공유하는 경우.

태그가 지정된 이미지에서 참조하는 레이어만 계산됩니다. 태그가 없는 이미지와 해당 이미지에서만 참조되는 레이어는 온라인 가비지 컬렉션의 대상입니다. 태그가 없는 이미지 레이어는 해당 기간 동안 참조되지 않은 상태로 남아 있으면 24시간 후에 자동으로 삭제됩니다.

이미지 레이어는 원본(일반적으로 압축된) 형식으로 스토리지 백엔드에 저장됩니다. 즉, 특정 이미지 레이어의 측정된 크기는 해당하는 이미지 매니페스트에 표시된 크기와 일치해야 합니다.

네임스페이스 사용량은 네임스페이스 아래의 컨테이너 리포지터리에서 태그가 푸시되거나 삭제된 후 몇 분 후에 새로 고쳐집니다.

지연된 새로 고침#

매우 큰 네임스페이스(약 1%의 네임스페이스)에서는 최대 정밀도로 실시간으로 컨테이너 레지스트리 사용량을 계산하는 것이 불가능합니다. 이러한 네임스페이스의 관리자가 사용량을 볼 수 있도록 하기 위해 지연된 대체 메커니즘이 있습니다. 자세한 내용은 에픽 9413을 참조하세요.

네임스페이스의 사용량을 정밀하게 계산할 수 없는 경우, GitLab은 지연된 방법으로 대체됩니다. 지연된 방법에서 표시되는 사용량 크기는 네임스페이스의 모든 고유 이미지 레이어의 합계입니다. 태그가 없는 이미지 레이어도 무시되지 않습니다. 결과적으로, 태그를 삭제한 후 표시되는 사용량 크기가 크게 변경되지 않을 수 있습니다. 대신, 크기 값은 다음 경우에만 변경됩니다:

• 자동화된 가비지 컬렉션 프로세스가 실행되어 태그가 없는 이미지 레이어를 삭제하는 경우. 사용자가 태그를 삭제하면 24시간 후에 시작할 가비지 컬렉션 실행이 예약됩니다. 해당 실행 중에 이전에 태그가 지정된 이미지가 분석되고, 다른 태그가 지정된 이미지에서 참조하지 않는 경우 레이어가 삭제됩니다. 레이어가 삭제되면 네임스페이스 사용량이 업데이트됩니다.
• 네임스페이스의 레지스트리 사용량이 GitLab이 최대 정밀도로 측정할 수 있을 만큼 충분히 감소하는 경우. 네임스페이스의 사용량이 감소함에 따라 측정 방식이 자동으로 지연에서 정밀 사용량 측정으로 전환됩니다. 어느 측정 방법이 사용되는지 확인할 수 있는 UI 위치는 없지만, 이슈 386468에서 이를 개선하는 방안을 제안하고 있습니다.

정리 정책#

히스토리

• 필요한 권한이 GitLab 15.0에서 developer에서 maintainer로 변경됨.

정리 정책은 컨테이너 레지스트리에서 태그를 제거하는 데 사용할 수 있는 예약된 Job입니다. 정리 정책이 정의된 프로젝트에서는 정규식 패턴과 일치하는 태그가 제거됩니다. 기본 레이어와 이미지는 그대로 유지됩니다.

태그와 연결되지 않은 기본 레이어와 이미지를 삭제하려면 관리자가 -m 스위치와 함께 가비지 컬렉션을 사용할 수 있습니다.

정리 정책 활성화#

정리 정책 작동 방식#

정리 정책은 컨테이너 레지스트리의 모든 태그를 수집하고 삭제하려는 태그만 남을 때까지 태그를 제외합니다.

정리 정책은 태그 이름을 기반으로 이미지를 검색합니다. 전체 경로 매칭 지원은 이슈 281071에서 추적됩니다.

정리 정책:

1. 목록에서 지정된 리포지터리의 모든 태그를 수집합니다.
2. latest라는 이름의 태그를 제외합니다.
3. name_regex(만료할 태그)를 평가하여 일치하지 않는 이름을 제외합니다.
4. name_regex_keep 값과 일치하는 태그를 제외합니다(보존할 태그).
5. 매니페스트가 없는 태그를 제외합니다(UI의 옵션에는 포함되지 않음).
6. 나머지 태그를 created_date별로 정렬합니다.
7. keep_n 값을 기반으로 N개의 태그를 제외합니다(보존할 태그 수).
8. older_than 값보다 최근의 태그를 제외합니다(만료 간격).
9. 보호된 태그를 제외합니다.
10. 변경 불가능한 태그를 제외합니다.
11. 목록의 나머지 태그를 컨테이너 레지스트리에서 삭제합니다.

정리 정책 워크플로 예시#

정리 정책의 유지 및 제거 규칙 간의 상호 작용은 복잡할 수 있습니다. 예를 들어, 다음 정리 정책 구성이 있는 프로젝트의 경우:

• 가장 최근 것 유지: 이미지 이름당 1개의 태그.
• 다음과 일치하는 태그 유지: production-.*
• 다음보다 오래된 태그 제거: 7일.
• 다음과 일치하는 태그 제거: .*.

다음 태그가 있는 컨테이너 리포지터리의 경우:

• latest, 2시간 전에 게시됨.
• production-v44, 3일 전에 게시됨.
• production-v43, 6일 전에 게시됨.
• production-v42, 11일 전에 게시됨.
• dev-v44, 2일 전에 게시됨.
• dev-v43, 5일 전에 게시됨.
• dev-v42, 10일 전에 게시됨.
• v44, 어제 게시됨.
• v43, 12일 전에 게시됨.
• v42, 20일 전에 게시됨.

이 예시에서 다음 정리 실행 시 삭제될 태그는 dev-v42, v43, v42입니다. 다음 우선순위로 규칙이 적용된다고 해석할 수 있습니다:

1. 유지 규칙이 가장 높은 우선순위를 가집니다. 태그는 어떤 규칙과 일치할 때 유지되어야 합니다.
   • latest 태그는 항상 유지되므로 유지되어야 합니다.
   • production-v44, production-v43, production-v42 태그는 다음과 일치하는 태그 유지 규칙과 일치하므로 유지되어야 합니다.
   • v44 태그는 가장 최근 것이므로 가장 최근 것 유지 규칙과 일치하여 유지되어야 합니다.
2. 제거 규칙은 더 낮은 우선순위를 가지며, 모든 규칙이 일치할 때만 태그가 삭제됩니다. 유지 규칙과 일치하지 않는 태그(dev-44, dev-v43, dev-v42, v43, v42)의 경우:
   • dev-44와 dev-43은 다음보다 오래된 태그 제거와 일치하지 않아 유지됩니다.
   • dev-v42, v43, v42는 다음보다 오래된 태그 제거 및 다음과 일치하는 태그 제거 규칙과 모두 일치하므로 이 세 태그를 삭제할 수 있습니다.

정리 정책 만들기#

API 또는 UI에서 정리 정책을 만들 수 있습니다.

UI에서 정리 정책을 만들려면:

1. 왼쪽 사이드바에서 Settings > Packages and registries를 선택합니다.

2. Container registry를 확장합니다.

3. Container registry cleanup policies 아래에서 Set cleanup rules를 선택합니다.

4. 필드를 입력합니다:

   필드	설명
   Toggle	정책을 켜거나 끕니다.
   Run cleanup	정책이 실행되는 빈도.
   Keep the most recent	각 이미지에 대해 항상 유지할 태그 수.
   Keep tags matching	보존할 태그를 결정하는 정규식 패턴. latest 태그는 항상 보존됩니다. 모든 태그에는 .*를 사용하세요. 다른 정규식 패턴 예시도 참조하세요.
   Remove tags older than	X일보다 오래된 태그만 제거합니다. 첫 번째 정리 중에 가장 오래된 이미지만 삭제되도록 높은 숫자로 시작해야 합니다. 정리 백그라운드 작업자가 사용하는 리소스를 모니터링한 후 일 수를 점진적으로 줄일 수 있습니다.
   Remove tags matching	제거할 태그를 결정하는 정규식 패턴. 이 값은 비워 둘 수 없습니다. 첫 번째 정리 중에 소수의 이미지만 삭제되도록 비교적 구체적인 정규식으로 시작해야 합니다. 정리 백그라운드 작업자가 사용하는 리소스를 모니터링한 후 모든 태그와 일치하도록 .*까지 정규식을 더 일반적으로 조정합니다. 자세한 내용은 정규식 패턴 예시를 참조하세요.

   [!note] 유지 및 제거 정규식 패턴은 자동으로 \A 및 \Z 앵커로 둘러싸이므로 포함할 필요가 없습니다. 그러나 정규식 패턴을 선택하고 테스트할 때 이 점을 고려해야 합니다.

5. Save를 선택합니다.

정책은 선택한 예약된 간격으로 실행됩니다.

정규식 패턴 예시#

정리 정책은 정규식 패턴을 사용하여 UI 및 API에서 보존하거나 제거할 태그를 결정합니다.

GitLab은 정리 정책에서 정규식에 RE2 구문을 사용합니다.

다음은 사용할 수 있는 정규식 패턴의 몇 가지 예입니다:

• 모든 태그 일치:

  .*
  

  이 패턴은 만료 정규식의 기본값입니다.

• v로 시작하는 태그 일치:

  v.+
  

• main이라는 이름의 태그만 일치:

  main
  

• release라는 이름이거나 release로 시작하는 태그 일치:

  release.*
  

• v로 시작하거나, main이라는 이름이거나, release로 시작하는 태그 일치:

  (?:v.+|main|release.*)
  

리소스 절약을 위한 정리 제한 설정#

정리 정책은 백그라운드 프로세스로 실행됩니다. 삭제할 태그 수에 따라 프로세스가 완료되는 데 시간이 걸릴 수 있습니다.

다음 애플리케이션 설정을 사용하여 서버 리소스 고갈을 방지할 수 있습니다:

사전 요구 사항:

• 관리자 액세스.

Rails 콘솔에서 이 설정을 변경할 수 있습니다. 예를 들면:

ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3)

Admin 영역에서 이 설정을 변경하려면:

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Container Registry를 확장합니다.

정리 정책 API 사용#

GitLab API를 사용하여 정리 정책을 설정, 업데이트 및 비활성화할 수 있습니다.

예시:

• 모든 태그를 선택하고, 이미지당 최소 1개의 태그를 유지하고, 14일보다 오래된 태그를 정리하고, 한 달에 한 번 실행하고, main이라는 이름의 이미지를 보존하며, 정책이 활성화된 경우:

  curl --fail-with-body --request PUT --header 'Content-Type: application/json;charset=UTF-8'
       --header "PRIVATE-TOKEN: <your_access_token>" \
       --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":".*","name_regex_keep":".*-main"}}' \
       "https://gitlab.example.com/api/v4/projects/2"
  

API 사용 시 cadence에 대한 유효한 값:

• 1d (매일)
• 7d (매주)
• 14d (2주마다)
• 1month (매월)
• 3month (분기마다)

API 사용 시 keep_n(이미지 이름당 유지되는 태그 수)에 대한 유효한 값:

• 1
• 5
• 10
• 25
• 50
• 100

API 사용 시 older_than(태그가 자동으로 제거되는 일 수)에 대한 유효한 값:

• 1d
• 3d
• 7d
• 14d
• 30d
• 60d
• 90d
• 180d
• 365d
• 730d
• 1095d

자세한 내용은 API 문서를 참조하세요: 프로젝트 API 편집.

외부 컨테이너 레지스트리와 함께 사용#

외부 컨테이너 레지스트리를 사용하는 경우, 프로젝트에서 정리 정책을 실행하면 성능 위험이 있을 수 있습니다. 프로젝트에서 수천 개의 태그를 제거하는 정책을 실행하면 GitLab 백그라운드 작업이 백업되거나 완전히 실패할 수 있습니다.

컨테이너 레지스트리 스토리지 추가 감소 옵션#

다음은 프로젝트에서 사용하는 컨테이너 레지스트리 스토리지를 줄이기 위해 사용할 수 있는 몇 가지 다른 옵션입니다:

• GitLab UI를 사용하여 개별 이미지 태그 또는 모든 태그가 포함된 전체 리포지터리를 삭제합니다.

• API를 사용하여 개별 이미지 태그를 삭제합니다.

• API를 사용하여 모든 태그가 포함된 전체 컨테이너 레지스트리 리포지터리를 삭제합니다.

• API를 사용하여 레지스트리 리포지터리 태그를 대량으로 삭제합니다.

문제 해결#

스토리지 크기를 사용할 수 없음#

컨테이너 레지스트리 스토리지 크기 정보를 볼 수 없는 경우:

1. 관리자에게 메타데이터 데이터베이스가 올바르게 구성되었는지 확인하도록 요청합니다.

2. 레지스트리 스토리지 백엔드가 올바르게 구성되고 접근 가능한지 확인합니다.

3. 스토리지 관련 오류에 대한 레지스트리 로그를 확인합니다:

   sudo gitlab-ctl tail registry
   

Something went wrong while updating the cleanup policy.#

이 오류 메시지가 표시되면 정규식 패턴이 유효한지 확인합니다.

Golang 플레이버를 사용하여 regex101 정규식 테스터로 테스트할 수 있습니다. 일반적인 정규식 패턴 예시를 확인하세요.

정리 정책이 태그를 삭제하지 않음#

다음과 같은 다양한 이유가 있을 수 있습니다:

• GitLab Self-Managed를 사용 중이고 컨테이너 리포지터리에 태그가 1000개 이상 있는 경우, 로그에 error authorizing context: invalid token이 있는 컨테이너 레지스트리 토큰 만료 문제가 발생할 수 있습니다.

  이를 해결하려면 두 가지 해결 방법이 있습니다:

  • 정리 정책에 대한 제한을 설정할 수 있습니다. 이는 시간 내에서 정리 실행을 제한하고 만료된 토큰 오류를 방지합니다.

  • 컨테이너 레지스트리 인증 토큰의 만료 지연을 연장합니다. 기본값은 5분입니다.

또는 삭제할 태그 목록을 생성하고 해당 목록을 사용하여 태그를 삭제할 수 있습니다. 목록을 생성하고 태그를 삭제하려면:

1. 다음 셸 스크립트를 실행합니다. for 루프 바로 앞의 명령어는 루프를 시작할 때 list_o_tags.out이 항상 재초기화되도록 합니다. 이 명령어를 실행하면 모든 태그 이름이 list_o_tags.out 파일에 기록됩니다:

   # Get a list of all tags in a certain container repository while considering [pagination](../../../api/rest/_index.md#pagination)
   echo -n "" > list_o_tags.out; for i in {1..N}; do curl --fail-with-body --header 'PRIVATE-TOKEN: ' "https://gitlab.example.com/api/v4/projects//registry/repositories/<container_repo_id>/tags?per_page=100&page=${i}" | jq '.[].name' | sed 's:^.\(.*\).$:\1:' >> list_o_tags.out; done
   

   Rails 콘솔에 접근할 수 있는 경우 다음 명령어를 입력하여 날짜로 제한된 태그 목록을 검색할 수 있습니다:

   output = File.open( "/tmp/list_o_tags.out","w" )
   Project.find().container_repositories.find(<container_repo_id>).tags.each do |tag|
     output << tag.name + "\n" if tag.created_at < 1.month.ago
   end;nil
   output.close
   

   이 명령 집합은 created_at 날짜가 한 달 이상 된 모든 태그를 나열하는 /tmp/list_o_tags.out 파일을 생성합니다.

2. list_o_tags.out 파일에서 유지하려는 태그를 제거합니다. 예를 들어 sed를 사용하여 파일을 파싱하고 태그를 제거할 수 있습니다.

   LinuxmacOS

   # Remove the `latest` tag from the file
   sed -i '/latest/d' list_o_tags.out

   # Remove the first N tags from the file
   sed -i '1,Nd' list_o_tags.out

   # Remove the tags starting with `Av` from the file
   sed -i '/^Av/d' list_o_tags.out

   # Remove the tags ending with `_v3` from the file
   sed -i '/_v3$/d' list_o_tags.out

   # Remove the `latest` tag from the file
   sed -i .bak '/latest/d' list_o_tags.out

   # Remove the first N tags from the file
   sed -i .bak '1,Nd' list_o_tags.out

   # Remove the tags starting with `Av` from the file
   sed -i .bak '/^Av/d' list_o_tags.out

   # Remove the tags ending with `_v3` from the file
   sed -i .bak '/_v3$/d' list_o_tags.out