본문으로 건너뛰기

Container Registry API

API 사용 준비

API를 호출하기 위해 필요한 사전 작업은 API 사용 준비 문서를 참고하시기 바랍니다.

API 개요

Container Registry 서비스는 사용자가 직접 자원을 관리하기 위한 API를 제공합니다.

  • Distribution Registry 기능을 Proxy로 제공하며, 자세한 사항은 Registry API 문서를 참고하시기 바랍니다.

  • API 사용을 위해서는 액세스 키와 액세스 인증 토큰이 필요합니다.

  • 아래 가이드를 통해 액세스 키를 먼저 생성한 후 인증 토큰을 받아야만 서비스 API를 사용할 수 있습니다.

사전 작업

API 사용을 위해서는 액세스 키와 액세스 인증 토큰이 필요하므로, 다음을 참고하여 액세스 키와 액세스 인증 토큰을 획득 후 API를 사용하시기 바랍니다.

사용자 액세스 키 발급

IAM 사용자 자격 증명인 액세스 키(Access Key)는 액세스 키 ID와 액세스 보안 키를 의미하며, API 인증 토큰 발급 시 필요한 정보입니다.
API 사용 준비 문서를 참고하여 사용자 액세스 키를 발급하시기 바랍니다.

주의

사용자 액세스 키 ID 및 액세스 보안 키 생성 시, 사용자 액세스 키 만들기 창을 닫은 이후에는 정보를 다시 조회할 수 없습니다. 해당 정보를 복사하여 클립보드에 저장 후 별도로 관리하시기 바랍니다.

API 인증 토큰 발급

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

API 사용 준비 문서를 참고하여 API 인증 토큰을 발급하시기 바랍니다.

안내

기본적으로 API 인증 토큰은 12시간 이후 만료되며, 상황에 따라 12시간 이내라도 변경되거나 만료될 수 있습니다.

Container Registry API

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

API 엔드포인트

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

API 엔드포인트
https://kic-cr-service.{리전명}.kcr.dev

레지스트리

레지스트리 접근 확인

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

HTTP 요청

HTTP 요청
GET /registry/proxy/{project_name}/v2/ 
X-Auth-Token: {X-Auth-Token}
이름필수종류설명
project_name필수pathKakaoCloud 프로젝트 고유 ID
X-Auth-Token필수headerAPI 인증 토큰
HTTP 응답
200 OK
Content-Type: application/json

{}

HTTP 응답 상태

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

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

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

HTTP 요청
GET /registry/proxy/{project_name}/v2/_catalog 
X-Auth-Token: {X-Auth-Token}
이름필수 여부종류설명
project_name필수pathKakaoCloud 프로젝트 고유 ID
X-Auth-Token필수headerAPI 인증 토큰
HTTP 응답 본문
200 OK
Content-Type: application/json

{
"repositories": [
"repository/image",
...
]
}
이름JSON 타입설명
repositoriesarray<string>repository/image 형태의 문자열 배열

HTTP 응답 상태

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

태그 목록 요청

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

HTTP 요청
GET /registry/proxy/{project_name}/v2/{repository}/{image}/tags/list 
X-Auth-Token: {X-Auth-Token}
이름필수 여부종류설명
project_name필수pathKakaoCloud 프로젝트 고유 ID
repository필수path리포지토리 이름
image필수path이미지 이름
X-Auth-Token필수headerAPI 인증 토큰
응답 본문
200 OK
Content-Type: application/json

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

JSON 응답 본문 설명

이름JSON 타입설명
namestringrepository/image 형태의 문자열
tagsarray<string>태그 이름 배열

HTTP 응답 상태

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

Manifest

Manifest 조회

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

HTTP 요청
GET /registry/proxy/{project_name}/v2/{repository}/{image}/manifests/{reference} 
X-Auth-Token: {X-Auth-Token}
Accept: {Accept}
이름필수 여부종류설명
project_name필수pathKakaoCloud 프로젝트 고유 ID
repository필수path리포지토리 이름
image필수path이미지 이름
reference필수path태그 이름 또는 Digest
X-Auth-Token필수headerAPI 인증 토큰
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 응답 상태

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

Manifest 삽입

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

HTTP 요청

HTTP 요청
PUT /registry/proxy/{project_name}/v2/{repository}/{image}/manifests/{reference} 
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필수pathKakaoCloud 프로젝트 고유 ID
repository필수path리포지토리 이름
image필수path이미지 이름
reference필수path태그 이름 또는 Digest
X-Auth-Token필수headerAPI 인증 토큰
Content-Type필수header삽입 할 Manifest Media Type

HTTP 응답

HTTP 응답
201 Created
Location: {url}
Docker-Content-Digest: {digest}
이름설명
Location삽입한 Manifest의 저장 URL
Docker-Content-Digest삽입한 Manifest의 Digest

HTTP 응답 상태

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

Blob

Blob 요청

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

HTTP 요청
GET /registry/proxy/{project_name}/v2/{repository}/{image}/blobs/{digest} 
X-Auth-Token: {X-Auth-Token}
파라미터필수 여부종류설명
project_name필수pathKakaoCloud 프로젝트 고유 ID
repository필수path리포지토리 이름
image필수path이미지 이름
digest필수pathBlob Digest
X-Auth-Token필수headerAPI 인증 토큰

HTTP 응답

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

{blob binary data}
이름설명
Content-LengthBlob의 용량 (byte)
Docker-Content-Digest요청한 Blob의 Digest
HTTP 응답 상태
상태메시지설명
200OK이미지가 존재하고, 정상적으로 불러왔습니다.
400Bad Request리포지토리, 이미지, 태그, 다이제스트 등이 유효하지 않습니다.
401UnauthorizedAPI 인증 토큰으로 레지스트리에 접근할 수 없습니다.
403Forbidden유효한 리포지토리가 아니거나 현재 이미지가 기한 만료 등으로 정상 접근 불가 상태입니다.
404Not FoundBlob이 존재하지 않습니다.
429Too Many Requests짧은 시간 내에 많은 양을 요청하여 접근이 제한됩니다.