히스토리

• GitLab 18.5에서 container_virtual_registries라는 플래그와 함께 도입. 기본적으로 비활성화됨.
• GitLab 18.9에서 실험에서 베타로 변경.
• GitLab 18.10에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화.

이 API를 사용하여:

• 컨테이너 레지스트리를 위한 가상 레지스트리를 생성·관리합니다.
• 업스트림 컨테이너 레지스트리를 구성합니다.
• 캐시된 컨테이너 이미지와 매니페스트를 관리합니다.

가상 레지스트리를 통해 컨테이너 이미지를 가져오는 방법은 컨테이너 가상 레지스트리를 참조하세요.

가상 레지스트리 관리#

다음 엔드포인트를 사용하여 컨테이너 레지스트리를 위한 가상 레지스트리를 생성·관리합니다.

모든 가상 레지스트리 목록 조회#

그룹의 모든 컨테이너 가상 레지스트리를 나열합니다.

GET /groups/:id/-/virtual_registries/container/registries

지원되는 속성:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/container/registries"

응답 예시:

[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-container-virtual-registry",
    "description": "My container virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]

가상 레지스트리 생성#

그룹의 컨테이너 가상 레지스트리를 생성합니다.

POST /groups/:id/-/virtual_registries/container/registries

요청 예시:

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data '{"name": "my-container-virtual-registry", "description": "My container virtual registry"}' \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/container/registries"

응답 예시:

{
  "id": 1,
  "group_id": 5,
  "name": "my-container-virtual-registry",
  "description": "My container virtual registry",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z"
}

가상 레지스트리 조회#

지정된 컨테이너 가상 레지스트리를 조회합니다.

GET /virtual_registries/container/registries/:id

파라미터:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/registries/1"

응답 예시:

{
  "id": 1,
  "group_id": 5,
  "name": "my-container-virtual-registry",
  "description": "My container virtual registry",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z",
  "registry_upstreams": [
    {
      "id": 2,
      "position": 1,
      "upstream_id": 2
    }
  ]
}

가상 레지스트리 업데이트#

지정된 컨테이너 가상 레지스트리를 업데이트합니다.

PATCH /virtual_registries/container/registries/:id

요청 예시:

curl --request PATCH \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"name": "my-container-virtual-registry", "description": "My container virtual registry"}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/registries/1"

성공하면 200 OK 상태 코드를 반환합니다.

가상 레지스트리 삭제#

지정된 컨테이너 가상 레지스트리를 삭제합니다.

DELETE /virtual_registries/container/registries/:id

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/registries/1"

성공하면 204 No Content 상태 코드를 반환합니다.

가상 레지스트리의 캐시 항목 삭제#

히스토리

• GitLab 18.7에서 container_virtual_registries라는 플래그와 함께 도입. 기본적으로 비활성화됨.
• GitLab 18.9에서 실험에서 베타로 변경.
• GitLab 18.10에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화.

컨테이너 가상 레지스트리의 모든 전용 업스트림 레지스트리에서 모든 캐시 항목을 삭제하도록 예약합니다. 다른 가상 레지스트리와 연결된 업스트림 레지스트리의 캐시 항목은 삭제 예약되지 않습니다.

DELETE /virtual_registries/container/registries/:id/cache

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/registries/1/cache"

성공하면 204 No Content 상태 코드를 반환합니다.

업스트림 레지스트리 관리#

다음 엔드포인트를 사용하여 업스트림 컨테이너 레지스트리를 구성·관리합니다.

최상위 그룹의 모든 업스트림 레지스트리 목록 조회#

최상위 그룹의 모든 업스트림 컨테이너 레지스트리를 나열합니다.

GET /groups/:id/-/virtual_registries/container/upstreams

지원되는 속성:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/container/upstreams"

응답 예시:

[
  {
    "id": 1,
    "group_id": 5,
    "url": "https://registry-1.docker.io",
    "name": "Docker Hub",
    "description": "Docker Hub registry",
    "cache_validity_hours": 24,
    "username": "user",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]

업스트림 레지스트리 생성 전 연결 테스트#

히스토리

• GitLab 18.9에서 container_virtual_registries라는 플래그와 함께 도입. 기본적으로 비활성화됨.
• GitLab 18.9에서 실험에서 베타로 변경.
• GitLab 18.10에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화.

가상 레지스트리에 아직 추가되지 않은 컨테이너 업스트림 레지스트리와의 연결을 테스트합니다. 이 엔드포인트는 업스트림 레지스트리를 생성하기 전에 연결 및 자격 증명을 검증합니다.

POST /groups/:id/-/virtual_registries/container/upstreams/test

지원되는 속성:

테스트 워크플로우#

test 엔드포인트는 제공된 업스트림 URL로 테스트 경로를 사용하여 HEAD 요청을 보내 연결 및 인증을 검증합니다. HEAD 요청으로 받은 응답은 다음과 같이 해석됩니다:

요청 예시:

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/container/upstreams/test"
     --data '{"url": "https://registry-1.docker.io", "username": "<your_username>", "password": "<your_password>"}' \

응답 예시:

{
  "success": true
}

가상 레지스트리의 모든 업스트림 레지스트리 목록 조회#

컨테이너 가상 레지스트리의 모든 업스트림 레지스트리를 나열합니다.

GET /virtual_registries/container/registries/:id/upstreams

지원되는 속성:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/registries/1/upstreams"

응답 예시:

[
  {
    "id": 1,
    "group_id": 5,
    "url": "https://registry-1.docker.io",
    "name": "Docker Hub",
    "description": "Docker Hub registry",
    "cache_validity_hours": 24,
    "username": "user",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z",
    "registry_upstream": {
      "id": 1,
      "registry_id": 1,
      "position": 1
    }
  }
]

업스트림 레지스트리 생성#

지정된 컨테이너 가상 레지스트리의 업스트림 컨테이너 레지스트리를 생성합니다.

POST /virtual_registries/container/registries/:id/upstreams

동일한 최상위 그룹에 동일한 URL과 자격 증명(username과 password)을 가진 두 업스트림을 추가할 수 없습니다. 대신 다음 중 하나를 수행할 수 있습니다:

• 동일한 URL을 가진 각 업스트림에 서로 다른 자격 증명을 설정합니다.
• 업스트림을 여러 가상 레지스트리에 연결합니다.

요청 예시:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"url": "https://registry-1.docker.io", "name": "Docker Hub", "description": "Docker Hub registry", "username": "<your_username>", "password": "<your_password>", "cache_validity_hours": 48}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/registries/1/upstreams"

응답 예시:

{
  "id": 1,
  "group_id": 5,
  "url": "https://registry-1.docker.io",
  "name": "Docker Hub",
  "description": "Docker Hub registry",
  "cache_validity_hours": 48,
  "username": "user",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z",
  "registry_upstream": {
    "id": 1,
    "registry_id": 1,
    "position": 1
  }
}

업스트림 레지스트리 조회#

지정된 업스트림 컨테이너 레지스트리를 조회합니다.

GET /virtual_registries/container/upstreams/:id

파라미터:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/upstreams/1"

응답 예시:

{
  "id": 1,
  "group_id": 5,
  "url": "https://registry-1.docker.io",
  "name": "Docker Hub",
  "description": "Docker Hub registry",
  "cache_validity_hours": 24,
  "username": "user",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z",
  "registry_upstreams": [
    {
      "id": 1,
      "registry_id": 1,
      "position": 1
    }
  ]
}

업스트림 레지스트리 업데이트#

지정된 업스트림 컨테이너 레지스트리를 업데이트합니다.

PATCH /virtual_registries/container/upstreams/:id

요청 예시:

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"cache_validity_hours": 72}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/upstreams/1"

성공하면 200 OK 상태 코드를 반환합니다.

업스트림 레지스트리 위치 업데이트#

컨테이너 가상 레지스트리의 정렬된 목록에서 업스트림 컨테이너 레지스트리의 위치를 업데이트합니다.

PATCH /virtual_registries/container/registry_upstreams/:id

요청 예시:

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"position": 5}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/registry_upstreams/1"

성공하면 200 OK 상태 코드를 반환합니다.

업스트림 레지스트리 삭제#

지정된 업스트림 컨테이너 레지스트리를 삭제합니다.

DELETE /virtual_registries/container/upstreams/:id

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/upstreams/1"

성공하면 204 No Content 상태 코드를 반환합니다.

업스트림을 레지스트리에 연결#

지정된 업스트림 컨테이너 레지스트리를 지정된 컨테이너 가상 레지스트리에 연결합니다.

POST /virtual_registries/container/registry_upstreams

요청 예시:

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data '{"registry_id": 1, "upstream_id": 2}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/registry_upstreams"

응답 예시:

{
  "id": 5,
  "registry_id": 1,
  "upstream_id": 2,
  "position": 2
}

레지스트리에서 업스트림 연결 해제#

지정된 업스트림 컨테이너 레지스트리와 지정된 컨테이너 가상 레지스트리 간의 연결을 제거합니다.

DELETE /virtual_registries/container/registry_upstreams/:id

요청 예시:

curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/registry_upstreams/1"

성공하면 204 No Content 상태 코드를 반환합니다.

업스트림 레지스트리의 캐시 항목 삭제#

히스토리

• GitLab 18.7에서 container_virtual_registries라는 플래그와 함께 도입. 기본적으로 비활성화됨.
• GitLab 18.9에서 실험에서 베타로 변경.
• GitLab 18.10에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화.

지정된 업스트림 레지스트리의 모든 캐시 항목을 삭제하도록 예약합니다.

DELETE /virtual_registries/container/upstreams/:id/cache

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/upstreams/1/cache"

성공하면 204 No Content 상태 코드를 반환합니다.

재정의 파라미터로 업스트림 레지스트리 연결 테스트#

히스토리

• GitLab 18.9에서 container_virtual_registries라는 플래그와 함께 도입. 기본적으로 비활성화됨.
• GitLab 18.9에서 실험에서 베타로 변경.
• GitLab 18.10에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화.

선택적 파라미터 재정의와 함께 기존 컨테이너 업스트림 레지스트리와의 연결을 테스트합니다.

이 방법으로 업스트림 레지스트리 구성을 업데이트하기 전에 URL, 사용자 이름 또는 비밀번호 변경 사항을 테스트할 수 있습니다.

POST /virtual_registries/container/upstreams/:id/test

지원되는 속성:

테스트 작동 방식#

이 엔드포인트는 연결 및 인증을 검증하기 위해 테스트 경로를 사용하여 업스트림 URL로 HEAD 요청을 수행합니다. 업스트림에 캐시된 아티팩트가 있는 경우 테스트에 업스트림의 상대 경로가 사용됩니다. 그렇지 않으면 자리 표시자 경로가 사용됩니다.

테스트 동작은 제공된 파라미터에 따라 달라집니다:

• 파라미터 없음: 현재 구성으로 업스트림 테스트 (기존 URL, 사용자 이름, 비밀번호)
• URL 재정의: 새 URL로의 연결 테스트 (사용자 이름과 비밀번호는 함께 제공하거나 전혀 제공하지 않아야 함)
• 자격 증명 재정의: 새 자격 증명으로 기존 URL 테스트

HEAD 요청으로 받은 응답은 다음과 같이 해석됩니다:

요청 예시 (기존 구성 테스트):

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/upstreams/1/test"

요청 예시 (자격 증명 없이 URL 재정의로 테스트):

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"url": "https://registry-1.docker.io"}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/upstreams/1/test"

요청 예시 (URL 및 자격 증명 재정의로 테스트):

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"url": "https://registry-1.docker.io", "username": "<newuser>", "password": "<newpass>"}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/upstreams/1/test"

요청 예시 (자격 증명 재정의로 테스트):

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"username": "<newuser>", "password": "<newpass>"}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/upstreams/1/test"

응답 예시:

{
  "success": true
}

캐시 항목 관리#

다음 엔드포인트를 사용하여 컨테이너 가상 레지스트리의 캐시된 컨테이너 이미지와 매니페스트를 관리합니다.

업스트림 레지스트리 캐시 항목 목록 조회#

컨테이너 업스트림 레지스트리의 캐시된 컨테이너 이미지와 매니페스트를 나열합니다.

GET /virtual_registries/container/upstreams/:id/cache_entries

지원되는 속성:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/upstreams/1/cache_entries?search=library/nginx"

응답 예시:

[
  {
    "id": "MTUgbGlicmFyeS9uZ2lueC9tYW5pZmVzdC9zaGEyNTY6YWJjZGVmZ2hpams=",
    "group_id": 5,
    "upstream_id": 1,
    "upstream_checked_at": "2024-05-30T12:28:27.855Z",
    "file_md5": "44f21d5190b5a6df8089f54799628d7e",
    "file_sha1": "74d101856d26f2db17b39bd22d3204021eb0bf7d",
    "size": 2048,
    "relative_path": "library/nginx/manifests/latest",
    "content_type": "application/vnd.docker.distribution.manifest.v2+json",
    "upstream_etag": "\"686897696a7c876b7e\"",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z",
    "downloads_count": 5,
    "downloaded_at": "2024-06-05T14:58:32.855Z"
  }
]

업스트림 레지스트리 캐시 항목 삭제#

업스트림 레지스트리의 지정된 캐시된 컨테이너 이미지 또는 매니페스트를 삭제합니다.

DELETE /virtual_registries/container/cache_entries/*id

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/container/cache_entries/bGlicmFyeS9uZ2lueC9tYW5pZmVzdHMvbGF0ZXN0"

성공하면 204 No Content 상태 코드를 반환합니다.