Container Registry API 사용 가이드

페이지 이동경로

Container Registry API 사용 가이드

Container Registry 서비스는 사용자가 직접 자원을 관리하기 위한 API를 제공합니다.
Distribution Registry 기능은 Proxy로 제공되며, 자세한 사항은 Docker Registry HTTP API V2 문서를 참고하시기 바랍니다.
API 사용을 위해서는 액세스 키와 액세스 인증 토큰이 필요하므로, 다음을 참고하여 액세스 키와 액세스 인증 토큰을 획득 후 API를 사용하시기 바랍니다.

액세스 키 발급하기

IAM 사용자 자격 증명인 액세스 키(Access Key)는 액세스 키 ID와 액세스 보안 키를 의미하며, API 인증 토큰 발급 시 필요한 정보입니다.
카카오 i 클라우드 콘솔의 설정 > 사용자 액세스 키에서 사용자의 자격 증명으로 사용자 액세스 키를 발급할 수 있습니다.
사용자 액세스 키 ID와 보안 키를 발급하는 방법은 설정 가이드 > 사용자 액세스 키 문서를 참고해 주세요.

액세스 인증 토큰 획득하기

API 인증 토큰은 카카오 i 클라우드 계정 아이디와 비밀번호를 대신하는 토큰으로, API 인증 토큰을 사용하여 CLI나 API를 통해서 애플리케이션이나 서비스를 인증할 수 있습니다. 액세스 키 발급 후, 사용자 액세스 키 ID와 사용자 액세스 보안 키를 이용해 API 인증 토큰을 발급할 수 있습니다.

API 엔드포인트

API 요청을 위한 Container Registry API 엔드포인트는 다음과 같습니다.

https://kic-cr-service.kr-central-1.kcr.dev

레지스트리

레지스트리 접근 확인

레지스트리에 접근 가능한지 요청합니다.

HTTP 요청

GET /registry/proxy/{project_name}/v2/ HTTP/1.1
X-Auth-Token: {X-Auth-Token}

파라미터 입력 정보

이름 필수 종류 설명
project_name 필수 path Kakao i Cloud 프로젝트 고유 ID
X-Auth-Token 필수 header API 인증 토큰

HTTP 응답 본문

200 OK
Content-Type: application/json

{}

HTTP 응답 상태

상태 메시지 설명
200 OK 정상적으로 불러왔습니다.
401 Unauthorized API 인증 토큰으로 레지스트리를 접근할 수 없습니다.
429 Too Many Requests 짧은 시간 내에 많은 양을 요청하여 접근이 제한됩니다.

레지스트리 이미지 목록 요청(카탈로그)

레지스트리 내에 이미지 목록을 요청합니다.

HTTP 요청

GET /registry/proxy/{project_name}/v2/_catalog HTTP/1.1
X-Auth-Token: {X-Auth-Token}

파라미터 입력 정보

이름 필수 여부 종류 설명
project_name 필수 path Kakao i Cloud 프로젝트 고유 ID
X-Auth-Token 필수 header API 인증 토큰

HTTP 응답 본문

200 OK
Content-Type: application/json

{
    "repositories": [
        "repository/image",
        ...
    ]
}

파라미터 입력 정보

이름 JSON 타입 설명
repositories array<string> repository/image 형태의 문자열 배열

HTTP 응답 상태

상태 메시지 설명
200 OK 정상적으로 불러왔습니다.
401 Unauthorized API 인증 토큰으로 레지스트리를 접근할 수 없습니다.
429 Too Many Requests 짧은 시간 내에 많은 양을 요청하여 접근이 제한됩니다.

태그 목록

해당 리포지토리, 이미지의 태그 전체 목록을 요청합니다.

HTTP 요청

GET /registry/proxy/{project_name}/v2/{repository}/{image}/tags/list HTTP/1.1
X-Auth-Token: {X-Auth-Token}

파라미터 입력 정보

이름 필수 여부 종류 설명
project_name 필수 path Kakao i Cloud 프로젝트 고유 ID
repository 필수 path 리포지토리 이름
image 필수 path 이미지 이름
X-Auth-Token 필수 header API 인증 토큰

HTTP 응답 본문

200 OK
Content-Type: application/json

{
    "name": "repository/image",
    "tags": [
        "tag"
        ...
    ]
}

JSON 응답 본문 설명

이름 JSON 타입 설명
name string repository/image 형태의 문자열
tags array<string> 태그 이름 배열

HTTP 응답 상태

상태 메시지 설명
200 OK 이미지가 존재하고, 정상적으로 불러왔습니다.
401 Unauthorized API 인증 토큰으로 레지스트리를 접근할 수 없습니다.
403 Forbbiden 유효한 리포지토리가 아니거나 현재 이미지가 기한 만료 등으로 정상 접근 불가 상태입니다.
404 Not Found 이미지가 존재하지 않습니다.
429 Too Many Requests 짧은 시간 내에 많은 양을 요청하여 접근이 제한됩니다.

Manifest

Manifest 조회

이미지 내 태그 또는 다이제스트의 Manifest 정보를 요청합니다.

HTTP 요청

GET /registry/proxy/{project_name}/v2/{repository}/{image}/manifests/{reference} HTTP/1.1
X-Auth-Token: {X-Auth-Token}
Accept: {Accept}

파라미터 입력 정보

이름 필수 여부 종류 설명
project_name 필수 path Kakao i Cloud 프로젝트 고유 ID
repository 필수 path 리포지토리 이름
image 필수 path 이미지 이름
reference 필수 path 태그 이름 또는 Digest
X-Auth-Token 필수 header API 인증 토큰
Accept 선택 header 요청할 Manifest Media Type

HTTP 응답

200 OK
Docker-Content-Digest: {digest}
Content-Type: {manifest-media-type}

{
    "name": "repository/image",
    "tag": "tag",
    "fsLayers": [
        {
            "blobSum": "{digest}"
        },
        ...
    ],
    "history": "{v1 images}"
}

응답 헤더 설명

이름 설명
Docker-Content-Digest 요청한 Manifest의 Digest
Content-Type 요청한 Manifest의 Media Type

Manifest의 형태는 삽입 및 요청 형태에 따라 다르며, 자세한 내용은 Manifest v2, Schema 1, Manifest v2, Schema 2 문서를 참고해 주세요.

HTTP 응답 상태

상태 메시지 설명
200 OK 이미지가 존재하고, 정상적으로 불러왔습니다.
400 Bad Request 리포지토리, 이미지, 태그, 다이제스트 등이 유효하지 않습니다.
401 Unauthorized API 인증 토큰으로 레지스트리를 접근할 수 없습니다.
403 Forbbiden 유효한 리포지토리가 아니거나 현재 이미지가 기한 만료 등으로 정상 접근 불가 상태입니다.
404 Not Found Manifest가 존재하지 않습니다.
429 Too Many Requests 짧은 시간 내에 많은 양을 요청하여 접근이 제한됩니다.

Manifest 삽입

대상 이미지 태그 또는 다이제스트의 Manifest 정보를 삽입합니다.

HTTP 요청

PUT /registry/proxy/{project_name}/v2/{repository}/{image}/manifests/{reference} HTTP/1.1
X-Auth-Token: {X-Auth-Token}
Content-Type: {Content-Type}

{
    "name": "repository/image",
    "tag": "tag",
    "fsLayers": [
        {
            "blobSum": "{digest}"
        },
        ...
    ],
    "history": "{v1 images}"
}

Manifest의 형태는 삽입 및 요청 형태에 따라 다르며, 자세한 내용은 Manifest v2, Schema 1, Manifest v2, Schema 2 문서를 참고해 주세요.

파라미터 입력 정보

파라미터 필수 여부 종류 설명
project_name 필수 path Kakao i Cloud 프로젝트 고유 ID
repository 필수 path 리포지토리 이름
image 필수 path 이미지 이름
reference 필수 path 태그 이름 또는 Digest
X-Auth-Token 필수 header API 인증 토큰
Content-Type 필수 header 삽입 할 Manifest Media Type

HTTP 응답

201 Created
Location: {url}
Docker-Content-Digest: {digest}

응답 헤더 설명

이름 설명
Location 삽입한 Manifest의 저장 URL
Docker-Content-Digest 삽입한 Manifest의 Digest

HTTP 응답 상태

상태 메시지 설명
201 Created 다이제스트를 정상적으로 저장했습니다.
400 Bad Request 리포지토리, 이미지, 태그, 다이제스트, Manifest 내 Blob 정보 등이 유효하지 않습니다.
401 Unauthorized API 인증 토큰으로 레지스트리를 접근할 수 없습니다.
403 Forbbiden 유효한 리포지토리가 아니거나 현재 이미지가 기한 만료 등으로 정상 접근 불가 상태입니다.
429 Too Many Requests 짧은 시간 내에 많은 양을 요청하여 접근이 제한됩니다.

Blob

Blob 요청

이미지 내 Blob을 요청합니다.

HTTP 요청

GET /registry/proxy/{project_name}/v2/{repository}/{image}/blobs/{digest} HTTP/1.1
X-Auth-Token: {X-Auth-Token}

파라미터 입력 정보

파라미터 필수 여부 종류 설명
project_name 필수 path Kakao i Cloud 프로젝트 고유 ID
repository 필수 path 리포지토리 이름
image 필수 path 이미지 이름
digest 필수 path Blob Digest
X-Auth-Token 필수 header API 인증 토큰

HTTP 응답

200 OK
Content-Length: {Content-Length}
Docker-Content-Digest: {digest}
Content-Type: application/octet-stream

{blob binary data}

응답 헤더 설명

이름 설명
Content-Length Blob의 용량 (byte)
Docker-Content-Digest 요청한 Blob의 Digest

HTTP 응답 상태

상태 메시지 설명
200 OK 이미지가 존재하고, 정상적으로 불러왔습니다.
400 Bad Request 리포지토리, 이미지, 태그, 다이제스트 등이 유효하지 않습니다.
401 Unauthorized API 인증 토큰으로 레지스트리를 접근할 수 없습니다.
403 Forbbiden 유효한 리포지토리가 아니거나 현재 이미지가 기한 만료 등으로 정상 접근 불가 상태입니다.
404 Not Found Blob이 존재하지 않습니다.
429 Too Many Requests 짧은 시간 내에 많은 양을 요청하여 접근이 제한됩니다.