Container Registry API 사용 가이드

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

사전 작업

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	짧은 시간 내에 많은 양을 요청하여 접근이 제한됩니다.

클라우드 가이드 센터 User Guide