• 컨테이너 레지스트리 사용량 보기
• 컨테이너 레지스트리 사용량 계산 방법
  • 지연된 새로고침
• 정리 정책
  • 정리 정책 사용
  • 정리 정책 작동 방식
    • 정리 정책 워크플로 예시
  • 정책 정리 작성
  • 정규식 패턴의 예시
  • 리소스 보존을 위한 정리 제한 설정
  • 정리 정책 API 사용하기
  • 외부 컨테이너 레지스트리에서 사용하기
• 더 많은 컨테이너 레지스트리 저장소 축소 옵션
• 정리 정책 문제 해결
  • 정리 정책 업데이트 중 오류가 발생했습니다.
  • 정리 정책이 어떤 태그도 삭제하지 않습니다

컨테이너 레지스트리 저장 공간 줄이기

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

• 대량의 이미지나 태그를 추가하는 경우:
  • 사용 가능한 태그 또는 이미지 목록을 검색하는 데 더 오래 걸립니다.
  • 서버에서 많은 저장 공간을 차지합니다.

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

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

• GitLab 15.7에서 소개됨

컨테이너 레지스트리의 저장 공간 사용량을 보려면:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 설정 > 사용량 할당을 선택합니다.

자체 관리형 인스턴스의 컨테이너 레지스트리 사용량은 볼 수 없지만 epic 5521에서 제안되었습니다.

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

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

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

• 동일한 이미지를 동일한 리포지토리에서 여러 번 태그하는 경우.
• 동일한 이미지를 동일한 루트 네임스페이스 하위의 다른 리포지토리에 태깅하는 경우.

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

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

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

이미지 레이어는 보통 원본(일반적으로 압축된) 형식으로 저장되어 있습니다. 따라서 특정 이미지 레이어의 측정된 크기는 해당하는 이미지 매니페스트에 표시된 크기와 일치해야 합니다.

태그가 푸시되거나 컨테이너 레지스트리에서 삭제된 후 몇 분 후에 네임스페이스 사용량이 초기화됩니다.

지연된 새로고침

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

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

• 자동화된 가비지 수집 프로세스가 실행되어 태그가 삭제됩니다. 사용자가 태그를 삭제한 후에 가비지 수집 실행이 예정되어 24시간 후에 시작됩니다. 해당 실행에서 이전에 태그가 지정된 이미지가 분석되고 다른 어떤 태그에서도 참조되지 않는 경우 해당 레이어가 삭제됩니다. 레이어가 삭제되면 네임스페이스 사용량이 업데이트됩니다.
• 네임스페이스의 레지스트리 사용량이 제한 미만으로 줄어들면 측정이 지연된 사용량 측정에서 자동으로 변경됩니다. UI에는 현재 사용 중인 측정 방법을 확인할 수 있는 곳이 없지만 issue 386468에서 이를 개선하기로 제안되었습니다.

정리 정책

• “유효 기간 정책”을 “정리 정책”으로 GitLab 13.2에서 이름 변경함.
• GitLab 15.0에서 필요한 권한 변경(개발자에서 관리자로).

정리 정책은 컨테이너 레지스트리에서 태그를 제거하는 예약 작업입니다. 정의된 프로젝트에서는 정규표현식 패턴과 일치하는 태그가 제거됩니다. 기본 레이어와 이미지는 남겨집니다.

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

정리 정책 사용

이러한 예외 사항으로 모든 프로젝트에 대해 정리 정책을 실행할 수 있습니다.

• 자체 관리형 GitLab 인스턴스의 경우 프로젝트는 12.8 이상의 GitLab에서 만들어졌어야 합니다. 그러나 관리자는 GitLab 응용 프로그램 설정에서 container_expiration_policies_enable_historic_entries를 true로 설정함으로써 모든 프로젝트(12.8 이전에 만들어진 것도 포함)에 대해 정리 정책을 활성화할 수 있습니다. 또는 Rails 콘솔에서 다음 명령을 실행할 수 있습니다.

   ApplicationSetting.last.update(container_expiration_policies_enable_historic_entries: true)
  

  모든 프로젝트에 대해 정리 정책을 활성화하면 성능에 영향을 미칠 수 있으며, 특히 외부 레지스트리를 사용하는 경우 더 그렇습니다.

경고: 성능 상의 이유로 GitLab.com에서 컨테이너 이미지가 없는 프로젝트의 경우 활성화된 정리 정책은 자동으로 해제됩니다.

정리 정책 작동 방식

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

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

정리 정책:

1. 주어진 저장소에 대한 모든 태그를 목록으로 수집합니다.
2. latest라는 이름의 태그를 제외합니다.
3. name_regex (만료될 태그)를 평가하고 일치하지 않는 이름은 제외합니다.
4. name_regex_keep 값 (보존할 태그)과 일치하는 태그를 제외합니다.
5. 매니페스트가 없는 태그를 제외합니다 (UI에서 옵션에 포함되지 않음).
6. created_date를 기준으로 남은 태그를 순서대로 정렬합니다.
7. keep_n 값 (유지할 태그 수)을 기준으로 N개의 태그를 제외합니다.
8. older_than 값 (만료 간격)보다 최근인 태그를 제외합니다.
9. 목록에서 남은 태그를 컨테이너 레지스트리에서 삭제합니다.

경고: GitLab.com에서 정리 정책의 실행 시간은 제한됩니다. 정책 실행 후에도 컨테이너 레지스트리에 일부 태그가 남을 수 있습니다. 다음에 정책이 실행되면 남은 태그가 포함됩니다. 모든 태그를 삭제하기 위해 여러 번 실행될 수 있습니다.

경고: GitLab의 자체 관리형 설치는 Docker Registry HTTP API V2 사양을 준수하는 타사 컨테이너 레지스트리를 지원합니다. 그러나 이 사양에는 태그 삭제 작업이 포함되어 있지 않습니다. 따라서 GitLab은 타사 컨테이너 레지스트리와 상호 작용할 때 태그를 삭제하기 위한 우회 방법을 사용합니다. 자세한 내용은 이슈 15737을 참조하십시오. 구현 변형 가능성으로 인해 이 우회 방법은 모든 타사 레지스트리에서 동일한 예측 가능한 방식으로 작동한다는 것을 보장할 수 없습니다. GitLab 컨테이너 레지스트리를 사용하는 경우 이 우회 방법은 필요하지 않습니다. 이 경우 정리 정책이 일관적이고 예측 가능하다고 기대할 수 있습니다.

정리 정책 워크플로 예시

정리 정책에 대한 보존 및 제거 규칙 간의 상호 작용은 복잡할 수 있습니다. 예를 들어 다음과 같은 정리 정책 구성의 프로젝트가 있는 경우:

• 가장 최신 것 유지: 이미지 이름당 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 태그는 Keep tags matching 규칙과 일치하기 때문에 유지돼야 합니다.
   • v44 태그는 가장 최신이기 때문에 가장 최신 것 유지 규칙과 일치하여 유지되어야 합니다.
2. 제거 규칙은 낮은 우선 순위를 갖고 있으며, 모든 규칙이 일치할 때에만 태그가 삭제됩니다. 보존 규칙과 일치하지 않는 태그(dev-44, dev-v43, dev-v42, v43, v42)의 경우:
   • dev-44 및 dev-43는 다음보다 오래된 태그 제거와 일치하지 않으므로 유지됩니다.
   • dev-v42, v43, v42는 다음보다 오래된 태그 제거와 일치하는 태그 제거 규칙 둘 다 일치하기 때문에 삭제됩니다.

정책 정리 작성

API를 사용하여 정책을 정리하거나 UI에서 작성할 수 있습니다.

UI에서 정책을 정리하려면:

1. 프로젝트에서 설정 > 패키지 및 레지스트리로 이동합니다.
2. 정리 정책 섹션에서 정리 규칙 설정을 선택합니다.

3. 다음 필드를 작성합니다:

   필드	설명
   토글	정책을 켜거나 끕니다.
   정리 실행	정책을 얼마나 자주 실행해야 하는지 지정합니다.
   가장 최근 것 유지	각 이미지에 항상 유지해야 하는 태그의 수를 지정합니다.
   일치하는 태그 유지	보존해야 하는 태그를 결정하는 정규식 패턴입니다. latest 태그는 항상 보존됩니다. 모든 태그에 대해 .*을 사용합니다. 다른 정규식 패턴의 예시를 확인하세요.
   이보다 오래된 태그 제거	X일이 지난 태그만 제거합니다.
   일치하는 태그 제거	제거해야 하는 태그를 결정하는 정규식 패턴입니다. 이 값은 비워둘 수 없습니다. 모든 태그에 대해 .*을 사용합니다. 다른 정규식 패턴의 예시를 확인하세요.

4. 저장을 선택합니다.

선택한 예약 간격에 따라 정책이 실행됩니다.

참고: 정책을 편집하고 다시 저장을 선택하면 간격이 재설정됩니다.

정규식 패턴의 예시

UI와 API 모두 정리 정책이 태그를 보존하거나 제거하기 위해 정규식 패턴을 사용합니다.

정규식 패턴은 자동으로 \A와 \Z 앵커로 둘러싸입니다. 따라서 정규식 패턴에서는 어떤 \A, \Z, ^, $ 토큰도 포함시킬 필요가 없습니다.

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

• 모든 태그와 일치:

  .*
  

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

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

  v.+
  

• main이라는 태그만 일치:

  main
  

• release로 시작하거나 release로 명명된 태그와 일치:

  release.*
  

• v로 시작하거나 main으로 명명되거나 release로 시작하는 태그와 일치:

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

리소스 보존을 위한 정리 제한 설정

• GitLab 13.9에서 도입되었습니다. container_registry_expiration_policies_throttling이라는 플래그로 제공. 기본 설정에서 비활성화됨.
• GitLab 14.9에서 기본 설정으로 활성화됨.
• GitLab 15.0에서 container_registry_expiration_policies_throttling 기능 플래그가 제거되었습니다.

정리 정책은 백그라운드 프로세스로 실행됩니다. 이 프로세스는 복잡하며 삭제할 태그의 수에 따라 완료까지 시간이 걸릴 수 있습니다.

다음 응용 프로그램 설정을 사용하여 서버 리소스를 고갈시키지 않도록 설정할 수 있습니다:

• container_registry_expiration_policies_worker_capacity: 동시에 실행되는 최대 정리 작업자 수. 이 값은 0보다 크거나 같아야 합니다. 백그라운드 작업에서 사용하는 리소스를 모니터링한 후 초깃값으로 낮게 설정하고 이후에 증가시켜야 합니다. 모든 작업자를 제거하고 정리 정책을 실행하지 않으려면 0으로 설정합니다. 기본 값은 4입니다.
• container_registry_delete_tags_service_timeout: 작업자가 태그 일괄 삭제에 소요할 수 있는 최대 시간(초). 기본 값은 250입니다.
• container_registry_cleanup_tags_service_max_list_size: 단일 실행에서 삭제할 수 있는 최대 태그 수. 추가 태그는 다른 실행에서 삭제해야 합니다. 삭제한 컨테이너 이미지가 올바르게 삭제되었는지 확인한 후 초깃값으로 낮게 설정하고 이후에 증가시켜야 합니다. 기본 값은 200입니다.
• container_registry_expiration_policies_caching: 정책 실행 중 태그 생성 타임스탬프 캐싱을 활성화하거나 비활성화합니다. 캐시된 타임스탬프는 Redis에 저장됩니다. 기본적으로 활성화됩니다.

자체 관리 인스턴스의 경우 Rails 콘솔에서 해당 설정을 업데이트할 수 있습니다:

ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3)

이 설정은 관리자 영역에서도 사용할 수 있습니다:

1. 왼쪽 사이드바에서 맨 아래에 관리자 영역을 선택합니다.
2. 설정 > CI/CD를 선택합니다.
3. 컨테이너 레지스트리를 확장합니다.

정리 정책 API 사용하기

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

예시:

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

  curl --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 (태그가 자동으로 제거되기까지의 일수)에 대한 유효한 값은 다음과 같습니다:

• 7d
• 14d
• 30d
• 90d

더 많은 세부 정보는 API 문서를 참조하십시오: 프로젝트 API 편집.

외부 컨테이너 레지스트리에서 사용하기

외부 컨테이너 레지스트리를 사용할 때 프로젝트에 정리 정책을 실행하면 성능 리스크가 있을 수 있습니다. 프로젝트가 수천 개의 태그를 삭제하는 정책을 실행하는 경우 GitLab 백그라운드 작업이 지연되거나 완전히 실패할 수 있습니다. GitLab 12.8 이전에 생성된 프로젝트의 경우, 정리 정책을 실행할 때는 삭제되는 태그 수가 최소화되는 경우에만 활성화해야 합니다.

더 많은 컨테이너 레지스트리 저장소 축소 옵션

프로젝트에서 사용하는 컨테이너 레지스트리 저장소의 사용 공간을 줄이기 위해 사용할 수 있는 다른 옵션들은 다음과 같습니다:

• GitLab UI를 사용하여 개별 이미지 태그 또는 모든 태그를 포함하는 저장소 전체를 삭제합니다.
• API를 사용하여 개별 이미지 태그를 삭제합니다.
• API를 사용하여 모든 태그를 포함하는 컨테이너 레지스트리 저장소 전체를 삭제합니다.
• API를 사용하여 대량으로 레지스트리 저장소 태그를 삭제합니다.

정리 정책 문제 해결

정리 정책 업데이트 중 오류가 발생했습니다.

이 오류 메시지가 표시되면 유효한지 확인하기 위해 정규식 패턴을 검사하십시오.

GitLab은 정리 정책에서 정규 표현식에 대해 RE2 구문을 사용합니다. Golang 플레이버를 사용하여 regex101 regex tester로 테스트할 수 있습니다. 일반적인 정규식 패턴 예시를 확인할 수 있습니다.

정리 정책이 어떤 태그도 삭제하지 않습니다

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

• GitLab 13.6 및 이전 버전에서 정리 정책을 실행했을 때 태그를 삭제할 것으로 예상했지만 삭제되지 않는 경우가 있습니다. 이는 정리 정책을 편집하지 않고 Remove tags matching 필드의 값을 수정하지 않고 저장한 경우 발생합니다. 해당 필드에는 플레이스홀더로서 회색으로 .* 값이 포함되어 있습니다. 이 필드에 .* (또는 다른 정규식 패턴)을 명시적으로 입력하지 않으면 nil 값이 제출됩니다. 이 값은 저장된 정리 정책이 어떤 태그와도 일치하지 않도록 합니다. 이 문제를 해결하려면 정리 정책을 수정하고 Remove tags matching 필드에 .*를 입력하고 저장합니다. 이 값을 입력하면 모든 태그를 제거해야 함을 나타냅니다.

• GitLab 자체 관리 인스턴스를 사용하고 컨테이너 저장소에 1000개 이상의 태그가 있는 경우 로그에 error authorizing context: invalid token이 표시되면 컨테이너 레지스트리 토큰 만료 문제가 발생할 수 있습니다. 이 문제를 해결하려면 두 가지 해결책이 있습니다:

  • GitLab 13.9 이상 버전을 사용하는 경우 정리 정책에 제한을 설정하여 실행 시간을 제한하고 만료된 토큰 오류를 방지할 수 있습니다.

  • 컨테이너 레지스트리 인증 토큰의 만료 지연 시간을 연장합니다. 기본값은 5분입니다. 레일즈 콘솔에서 ApplicationSetting.last.update(container_registry_token_expire_delay: <integer>)를 사용하여 사용자 정의 값으로 설정할 수 있습니다. 여기서 <integer>은 원하는 분수입니다. 참고로, GitLab.com에서는 만료 지연 시간을 15분으로 설정합니다. 이 값을 늘리면 권한 취소에 필요한 시간도 늘어납니다.

또 다른 방법으로 삭제해야 할 태그의 목록을 생성하고 해당 목록을 사용하여 태그를 삭제할 수 있습니다. 목록을 생성하고 태그를 삭제하려면:

1. 다음 쉘 스크립트를 실행합니다. for 루프를 시작할 때 list_o_tags.out이 항상 재초기화되도록 하는 명령을 실행합니다. 이 명령을 실행한 후 모든 태그 이름이 list_o_tags.out 파일에 작성됩니다:

   # [페이지네이션](../../../api/rest/index.md#pagination)을 고려하여 특정 컨테이너 저장소의 모든 태그 목록 가져오기
   echo -n "" > list_o_tags.out; for i in {1..N}; do curl --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags?per_page=100&page=${i}" | jq '.[].name' | sed 's:^.\(.*\).$:\1:' >> list_o_tags.out; done
   

   레일즈 콘솔 액세스가 있는 경우 다음 명령을 입력하여 날짜별로 제한된 태그 목록을 검색할 수 있습니다:

   output = File.open( "/tmp/list_o_tags.out","w" )
   Project.find(<Project_id>).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
   

   이 명령 세트는 1개월 이전에 만들어진 모든 태그를 나열하는 /tmp/list_o_tags.out 파일을 생성합니다.

2. list_o_tags.out 파일에서 유지하고 싶은 태그를 제거합니다. 예를 들어, sed를 사용하여 파일을 구문 분석하고 태그를 제거할 수 있습니다.

   Linux

   # 파일에서 `latest` 태그 제거
   sed -i '/latest/d' list_o_tags.out
   
   # 파일에서 처음 N개 태그 제거
   sed -i '1,Nd' list_o_tags.out
   
   # 파일에서 `Av`로 시작하는 태그 제거
   sed -i '/^Av/d' list_o_tags.out
   
   # 파일에서 `_v3`으로 끝나는 태그 제거
   sed -i '/_v3$/d' list_o_tags.out
   

   macOS

   # 파일에서 `latest` 태그 제거
   sed -i .bak '/latest/d' list_o_tags.out
   
   # 파일에서 처음 N개 태그 제거
   sed -i .bak '1,Nd' list_o_tags.out
   
   # 파일에서 `Av`로 시작하는 태그 제거
   sed -i .bak '/^Av/d' list_o_tags.out
   
   # 파일에서 `_v3`으로 끝나는 태그 제거
   sed -i .bak '/_v3$/d' list_o_tags.out
   

3. list_o_tags.out 파일을 다시 확인하여 삭제할 태그만 포함되어 있는지 확인합니다.

4. list_o_tags.out 파일을 사용하여 태그를 삭제하는 쉘 스크립트를 실행합니다:

   # list_o_tags.out을 반복하여 한 번에 한 태그씩 삭제
   while read -r LINE || [[ -n $LINE ]]; do echo ${LINE}; curl --request DELETE --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags/${LINE}"; sleep 0.1; echo; done < list_o_tags.out > delete.logs