Docker Hub API
Docker Hub API
Docker Hub는 Docker가 제공하는 서비스로 팀과 함께 컨테이너 이미지를 찾고 공유하기 위한 것이에요. 세계에서 가장 큰 컨테이너 이미지 라이브러리이자 커뮤니티예요. 이 API 레퍼런스는 인증, 액세스 토큰, 감사 로그, 조직, 그룹, SCIM 등 Docker Hub의 기능을 프로그래밍 방식으로 다루는 방법을 설명해요.
출처: 문서
본문
호스팅 API — Docker Hub API · API 2-beta · 54개 작업 · 69개의 이름 붙은 스키마
개요 (Overview)
Docker Hub는 Docker가 제공하는 서비스로, 팀과 함께 컨테이너 이미지를 찾고 공유하기 위한 것이에요.
이는 세계에서 가장 큰 컨테이너 이미지 라이브러리이자 커뮤니티예요.
Docker Hub UI와 Docker Hub CLI 도구(현재 실험적) 외에도 Docker는 Docker Hub와 상호작용할 수 있는 API를 제공해요.
Docker Hub API 문서를 살펴보며 지원되는 엔드포인트를 탐색해 보세요.
Docker Hub API에 연결하기
scimToken
조직에 구성된 SCIM 프로비저닝 토큰을 사용해요.
https://hub.docker.com
변경 로그 (Changelog)
Docker Hub API 버전 간 변경 사항 요약은 변경 로그를 참조하세요.
리소스 (Resources)
문서화된 API와 상호작용할 수 있는 리소스는 다음과 같아요.
- Docker Hub CLI 도구 (현재 실험적)
속도 제한 (Rate Limiting)
Docker Hub API는 분당 수행할 수 있는 요청 수에 제한이 있어요.
제한에 도달하지 않았다면 API의 각 요청에 대해 응답에 다음 헤더가 반환돼요.
X-RateLimit-Limit— 분당 요청 수 제한.X-RateLimit-Remaining— 제한 기간 내 남은 호출 수.X-RateLimit-Reset— 남은 호출 수가 초기화되는 Unix 타임스탬프.
제한에 도달했다면 응답 상태 429와 Retry-After 헤더를 받게 돼요. Retry-After 헤더는 API를 다시 호출할 수 있을 때까지 기다려야 하는 초 수를 지정해요.
참고: 이 속도 제한은 남용 방지(anti-abuse) 및 Docker Hub 다운로드/풀 속도 제한과는 별개예요. Docker Hub 풀 속도 제한에 대해 더 알아보려면 사용량 및 제한을 참조하세요.
인증 (Authentication)
대부분의 Docker Hub API 엔드포인트는 사용 전에 Docker 자격 증명으로 인증해야 해요.
또한 Docker Hub UI 기능과 비슷하게, API 엔드포인트 응답은 구독(Personal, Pro, Team)과 계정의 권한에 따라 달라질 수 있어요.
각 구독에서 사용할 수 있는 기능과 기존 구독 업그레이드에 대해 더 알아보려면 Docker Pricing을 참조하세요.
유형 (Types)
Docker Hub API는 다음 인증 유형을 지원해요. 각 인증 유형을 Create access token 라우트와 함께 사용해 베어러 토큰을 얻어야 해요.
Password
사용자 이름과 비밀번호를 사용하는 것은 Docker에 사용자로 인증하는 가장 강력하지만 가장 덜 안전한 방법이에요. 스코프 없이 사용자의 리소스에 접근할 수 있게 해 줘요.
일반적으로는 대신 개인 액세스 토큰(PAT)을 사용할 것을 권장해요.
조직에서 SSO를 강제하면 비밀번호 인증 유형을 사용할 수 없어요.
Personal Access Token (PAT)
사용자 이름과 PAT를 사용하는 것은 Docker에 사용자로 인증하는 가장 안전한 방법이에요. PAT는 특정 리소스와 스코프로 범위가 지정돼요.
현재 PAT는 기능이 제한되어 있어 더 안전한 비밀번호예요. 향후 조직 액세스 토큰 같은 세분화된 접근을 추가해 사용과 보안을 향상시킬 수 있어요.
Organization Access Token (OAT)
조직 액세스 토큰은 조직 내 특정 리소스와 스코프로 범위가 지정돼요. 조직 소유자가 관리해요.
이 토큰들은 자동화를 위한 것이며 사용자가 사용하기 위한 것이 아니에요.
OAT에서 발급된 베어러 토큰을 지원하는 작업은 그 설명에 명시돼 있어요.
Authentication
인증 엔드포인트를 사용하면 Docker Hub API로 인증할 수 있어요. 자세한 내용은 인증을 참조하세요.
Personal Access Tokens
개인 액세스 토큰 엔드포인트로 개인 액세스 토큰을 관리할 수 있어요. 자세한 내용은 Access Tokens을 참조하세요.
Docker CLI에서 비밀번호 대신 개인 액세스 토큰을 사용하거나, Create an authentication token 라우트에서 베어러 토큰을 얻는 데 사용할 수 있어요.
Scopes
각 스코프 그룹(여기서는 "repo")에서 더 낮은 스코프는 자동으로 가정되므로 1개의 스코프만 정의하면 돼요. 예를 들어 repo:write를 정의하면 API는 repo:read와 repo:public_read 모두의 스코프를 가정해요. repo:write와 repo:read를 모두 정의하면 repo:read는 repo:write가 가정하므로 무시돼요.
개인 액세스 토큰을 비밀번호처럼 취급하고 비밀로 유지하세요. 생성 후에는 토큰을 검색할 수 없어요.
감사 로그 (Audit Logs)
감사 로그 API 엔드포인트를 사용해 네임스페이스 전반의 감사 로그 이벤트를 쿼리할 수 있어요. 자세한 내용은 Audit Logs를 참조하세요.
조직 설정 (Org Settings)
조직 설정 API 엔드포인트로 조직의 설정을 관리할 수 있어요.
저장소 (Repositories)
저장소 엔드포인트로 저장소의 태그에 접근할 수 있어요.
조직 (Organizations)
조직 엔드포인트로 조직과 상호작용하고 관리할 수 있어요. 자세한 내용은 Organization administration overview를 참조하세요.
그룹 (Groups/Teams)
그룹 엔드포인트로 조직의 팀과 그 구성원을 관리할 수 있어요. 자세한 내용은 Create and manage a team를 참조하세요.
초대 (Invites)
초대 엔드포인트로 사용자가 Docker 조직에 가입하도록 하는 초대를 관리할 수 있어요. 자세한 내용은 Invite members를 참조하세요.
SCIM
SCIM은 ID 제공자(IdP) 내에서 사용자를 관리할 수 있게 해 주는 프로비저닝 시스템이에요. 자세한 내용은 System for Cross-domain Identity management를 참조하세요.
조직 액세스 토큰 (Organization Access Tokens)
조직 액세스 토큰 엔드포인트로 조직 액세스 토큰(OAT)을 관리할 수 있어요. 자세한 내용은 Organization access tokens을 참조하세요.
OAT는 /v2/namespaces/{namespace}/repositories/ 아래의 현대적인 네임스페이스 스코프 라우트에 대한 요청만 인증해요. 레거시 저장소 경로는 토큰의 스코프와 무관하게 OAT를 지원하지 않으며, 모든 OAT를 403 token issued from organization access token is not allowed로 거부해요.
GET /v2/repositories/{namespace}/{repository}— Get repository를 대신 사용하세요.GET /v2/repositories/{namespace}— List repositories를 대신 사용하세요.GET /v2/users/{username}/repositories— List repositories를 대신 사용하세요.
작업 (Operations)
| 메서드 | 경로 | 설명 |
|---|---|---|
| GET | /v2/access-tokens |
개인 액세스 토큰 나열 |
| POST | /v2/access-tokens |
개인 액세스 토큰 생성 |
| GET | /v2/access-tokens/{uuid} |
개인 액세스 토큰 조회 |
| DELETE | /v2/access-tokens/{uuid} |
개인 액세스 토큰 삭제 |
| PATCH | /v2/access-tokens/{uuid} |
개인 액세스 토큰 업데이트 |
| GET | /v2/auditlogs/{account} |
감사 로그 이벤트 나열 |
| GET | /v2/auditlogs/{account}/actions |
감사 로그 작업 나열 |
| POST | /v2/auth/token |
액세스 토큰 생성 |
| POST | /v2/invites/bulk |
초대 대량 생성 |
| DELETE | /v2/invites/{id} |
초대 취소 |
| PATCH | /v2/invites/{id}/resend |
초대 다시 보내기 |
| GET | /v2/namespaces/{namespace}/repositories |
네임스페이스의 저장소 나열 |
| POST | /v2/namespaces/{namespace}/repositories |
새 저장소 생성 |
| GET | /v2/namespaces/{namespace}/repositories/{repository} |
네임스페이스의 저장소 조회 |
| HEAD | /v2/namespaces/{namespace}/repositories/{repository} |
네임스페이스의 저장소 확인 |
| PATCH | /v2/namespaces/{namespace}/repositories/{repository}/immutabletags |
저장소 불변 태그 업데이트 |
| POST | /v2/namespaces/{namespace}/repositories/{repository}/immutabletags/verify |
저장소 불변 태그 확인 |
| GET | /v2/namespaces/{namespace}/repositories/{repository}/tags |
저장소 태그 나열 |
| HEAD | /v2/namespaces/{namespace}/repositories/{repository}/tags |
저장소 태그 확인 |
| GET | /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag} |
저장소 태그 읽기 |
| HEAD | /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag} |
저장소 태그 확인 |
| GET | /v2/orgs/{name}/access-tokens |
액세스 토큰 나열 |
| POST | /v2/orgs/{name}/access-tokens |
액세스 토큰 생성 |
| GET | /v2/orgs/{name}/settings |
조직 설정 조회 |
| PUT | /v2/orgs/{name}/settings |
조직 설정 업데이트 |
| GET | /v2/orgs/{org_name}/access-tokens/{access_token_id} |
액세스 토큰 조회 |
| DELETE | /v2/orgs/{org_name}/access-tokens/{access_token_id} |
액세스 토큰 삭제 |
| PATCH | /v2/orgs/{org_name}/access-tokens/{access_token_id} |
액세스 토큰 업데이트 |
| GET | /v2/orgs/{org_name}/groups |
조직의 그룹 조회 |
| POST | /v2/orgs/{org_name}/groups |
새 그룹 생성 |
| GET | /v2/orgs/{org_name}/groups/{group_name} |
조직의 그룹 조회 |
| PUT | /v2/orgs/{org_name}/groups/{group_name} |
조직 그룹의 세부 정보 업데이트 |
| DELETE | /v2/orgs/{org_name}/groups/{group_name} |
조직 그룹 삭제 |
| PATCH | /v2/orgs/{org_name}/groups/{group_name} |
조직 그룹의 일부 세부 정보 업데이트 |
| GET | /v2/orgs/{org_name}/groups/{group_name}/members |
그룹 구성원 나열 |
| POST | /v2/orgs/{org_name}/groups/{group_name}/members |
그룹에 구성원 추가 |
| DELETE | /v2/orgs/{org_name}/groups/{group_name}/members/{username} |
그룹에서 사용자 제거 |
| GET | /v2/orgs/{org_name}/invites |
조직 초대 나열 |
| GET | /v2/orgs/{org_name}/members |
조직 구성원 나열 |
| GET | /v2/orgs/{org_name}/members/export |
조직 구성원 CSV 내보내기 |
| PUT | /v2/orgs/{org_name}/members/{username} |
조직 구성원 업데이트 (역할) |
| DELETE | /v2/orgs/{org_name}/members/{username} |
조직에서 구성원 제거 |
| POST | /v2/repositories/{namespace}/{repository}/groups |
저장소에 접근을 위해 그룹(팀) 할당 |
| GET | /v2/scim/2.0/ResourceTypes |
리소스 유형 나열 |
| GET | /v2/scim/2.0/ResourceTypes/{name} |
리소스 유형 조회 |
| GET | /v2/scim/2.0/Schemas |
스키마 나열 |
| GET | /v2/scim/2.0/Schemas/{id} |
스키마 조회 |
| GET | /v2/scim/2.0/ServiceProviderConfig |
서비스 제공자 구성 조회 |
| GET | /v2/scim/2.0/Users |
사용자 나열 |
| POST | /v2/scim/2.0/Users |
사용자 생성 |
| GET | /v2/scim/2.0/Users/{id} |
사용자 조회 |
| PUT | /v2/scim/2.0/Users/{id} |
사용자 업데이트 |
| POST | /v2/users/2fa-login |
2차 인증 |
| POST | /v2/users/login |
인증 토큰 생성 |
스키마 (Schemas)
AuditLog,AuditLogAction,AuditLogActions,AuthCreateTokenResponse,GetAuditActionsResponse,GetAuditLogsResponse,PostUsers2FALoginErrorResponse,PostUsersLoginErrorResponse,PostUsersLoginSuccessResponse,RepositoryGroup,RepositoryGroupCreationRequest,Users2FALoginRequest,UsersLoginRequestaccessToken,bulk_invite,category,createAccessTokenRequest,createAccessTokensResponse,createOrgAccessTokenRequest,createOrgAccessTokenResponse,email_address,email_with_username,error,getAccessTokensResponse,getOrgAccessTokenResponse,getOrgAccessTokensResponse,group_member,image,immutable_tags_settings,immutable_tags_verify_request,immutable_tags_verify_response,invite,layer,legacy_email_address,list_repositories_responseorgAccessToken,orgAccessTokenResource,orgSettings,org_group,org_member,org_member_paginated,page,paginated_tags,patchAccessTokenRequest,patchAccessTokenResponse,repo_creation_request,repo_permissions,repository_info,repository_list_entry,restricted_imagesscim_email,scim_error,scim_group,scim_resource_type,scim_schema,scim_schema_attribute,scim_schema_parent_attribute,scim_service_provider_config,scim_user,scim_user_display_name,scim_user_id,scim_user_name,scim_user_schemas,scim_user_username,tag,updateOrgAccessTokenRequest,updateOrgAccessTokenResponse,update_repository_immutable_tags_request,user