API Key 관리

VPC 환경에서 이용 가능합니다.

API Key는 ML expert Platform 콘솔에 로그인하지 않는 외부 프로그램이나 자동화 작업이 ML expert Platform의 리소스에 접근할 때 사용하는 인증 수단입니다. Model Registry CLI/SDK, Data Manager SDK, Pipelines SDK, 비공개로 운영하는 추론 엔드포인트 호출에 사용합니다.

이 가이드에서는 API Key의 종류와 권한 모델, 발급·조회·삭제 방법, 서비스별 사용 방법을 설명합니다.

API Key 종류

API Key는 발급 범위에 따라 두 종류로 나뉩니다. 접근하려는 리소스가 어디에 속하는지에 따라 종류를 선택합니다.

• 데이터셋은 Workspace 소유 리소스이므로 Workspace API Key로만 접근할 수 있습니다.
• 추론 엔드포인트와 Pipelines는 Project 소유 리소스이므로 Project API Key로만 접근할 수 있습니다.
• 하나의 API Key에 여러 권한을 함께 담을 수 있습니다. 서로 다른 Workspace 또는 Project의 리소스에 접근해야 하면 각각 API Key를 발급합니다.

권한 모델

API Key는 리소스 종류(Type), 권한 등급(Scope), 대상(Target) 의 조합으로 권한을 지정합니다. API Key는 지정한 권한 범위 안에서만 동작하며 그 밖의 요청은 거부됩니다.

Project API Key에 지정할 수 있는 권한

Workspace API Key에 지정할 수 있는 권한

권한 등급은 상위 등급이 하위 등급을 포함합니다(admin ⊇ writer ⊇ reader).

대상(Target) 지정 규칙

• 대상을 지정하면 이름이 일치하는 리소스에만 권한이 적용됩니다.
• 대상을 지정하지 않으면 해당 Project 또는 Workspace 안의 같은 종류 리소스 전체에 권한이 적용됩니다.
• 대상은 리소스 이름 기준으로 적용됩니다. 발급 시점에 없는 이름을 지정하면 나중에 같은 이름의 리소스가 생성될 때 권한이 적용됩니다.
• KubeflowPipeline은 대상을 지정할 수 없으며 항상 Project 전체에 적용됩니다.

API Key 관리 권한

API Key 목록 조회, 토큰 보기, 발급, 삭제는 해당 Project 또는 Workspace의 Admin 역할을 가진 사용자만 수행할 수 있습니다. API Key 목록에는 토큰 원문이 포함되므로 Writer, Reader 역할에는 API Key 탭이 표시되지 않습니다.

역할을 지정하는 방법은 Members와 Member Settings를 참조해 주십시오.

API Key 발급

Project API Key를 발급하는 방법은 다음과 같습니다. Workspace API Key는 Workspace > Dashboard > API Keys 탭에서 같은 방법으로 발급합니다.

1. ML expert Platform 콘솔에서 Project를 선택하고 Home > API Key 탭으로 이동해 주십시오.
2. 목록 상단의 Add를 클릭해 주십시오. 발급된 키가 하나도 없으면 화면 가운데의 추가 버튼을 클릭해 주십시오.
3. API Key 발급 팝업 창에 다음 항목을 입력해 주십시오.
   • API Key 이름: 영소문자(a-z), 숫자(0-9), 하이픈(-)을 사용하여 63자 이하로 입력합니다. 영소문자 또는 숫자로 시작하고 끝나야 합니다.
   • 유효기간(일): 1~365 사이의 정수를 입력하거나, 입력란 오른쪽의 7d, 30d, 90d, 365d 중 하나를 선택합니다. 기본값은 30일이며, 입력란 아래에 만료 예정 시각이 표시됩니다.
   • 설명(선택): 사용처나 발급 대상을 256자 이하로 기록합니다.
   • Permissions: 리소스 종류, 권한 등급, 대상을 선택합니다. 권한 행을 더 추가하려면 권한 추가 버튼을 클릭합니다. 권한은 1개 이상 추가해야 하며, 같은 (리소스 종류, 권한 등급) 조합은 한 번만 추가할 수 있습니다.
4. 발급을 클릭해 주십시오.
   • 발급 직후에는 목록의 상태가 발급 중으로 표시될 수 있습니다. 잠시 후 목록을 새로 고치면 토큰을 확인할 수 있습니다.

API Key 조회

Home > API Key 탭(Workspace는 Dashboard > API Keys 탭)의 목록에는 API Key 이름, Permissions, Expiration At(만료 시각), 상태, 발급자, 설명이 표시됩니다. 토큰 값을 확인하는 방법은 다음과 같습니다.

1. 목록에서 확인할 API Key 행의 보기를 클릭해 주십시오.
2. API Key 보기 창에서 이름, 발급자, 설명, 만료 시각, Permissions, 토큰을 확인하고 확인을 클릭해 주십시오.

토큰만 클립보드에 복사하려면 행의 복사를 클릭해 주십시오.

목록의 상태는 다음과 같습니다.

API Key 삭제

API Key를 삭제하면 해당 토큰으로 들어오는 요청은 즉시 거부됩니다.

1. Home > API Key 탭(Workspace는 Dashboard > API Keys 탭)으로 이동합니다.
2. 목록에서 삭제할 API Key 행의 체크박스를 선택합니다. 한 번에 하나만 선택할 수 있습니다.
3. 목록 상단의 Delete를 클릭합니다.
4. API Key 삭제 창에서 삭제를 클릭합니다.

만료된 API Key도 같은 방법으로 삭제합니다.

API Key 사용

API Key는 HTTP 요청의 Authorization 헤더에 Bearer 토큰으로 전달합니다. 서비스별 사용 방법은 다음과 같습니다.

추론 엔드포인트 호출

추론 엔드포인트를 비공개로 운영하려면 InferenceService 또는 LLMInferenceService에 다음 어노테이션을 설정합니다. 어노테이션을 설정하지 않으면 엔드포인트는 인증 없이 호출할 수 있습니다.

metadata:
  annotations:
    mlx.navercorp.com/access-mode: restricted

비공개 엔드포인트는 다음 두 가지 방법으로 호출할 수 있습니다.

• 대상 InferenceService(또는 LLMInferenceService)에 invoke 권한이 있는 Project API Key
• 해당 Project 멤버의 kubeconfig 토큰

Project API Key로 호출하는 예는 다음과 같습니다. 엔드포인트 URL은 배포한 서비스의 IngressRoute에서 확인합니다. 추론 서비스 배포와 IngressRoute 설정은 Serving을 참조해 주십시오.

curl -H "Authorization: Bearer {API Key}" \
  -H "Content-Type: application/json" \
  https://{추론 엔드포인트 URL}/v1/models/{InferenceService 이름}:predict \
  --data-binary @input.json

Pipelines SDK

ML expert Platform 밖(로컬 PC, CI 서버 등)에서 Pipelines SDK로 파이프라인을 실행하려면 KubeflowPipeline writer 권한이 있는 Project API Key가 필요합니다.

import kfp

client = kfp.Client(
    host="https://{ML expert Platform 도메인}/pipeline",
    existing_token="{API Key}",
    namespace="p-{Project 이름}",
)

• KubeflowPipeline 권한이 없는 API Key로 호출하면 403 APIKey does not grant KubeflowPipeline access 오류가 발생합니다. 권한은 발급 후 추가할 수 없으므로 새 API Key를 발급하십시오.
• Workspace API Key는 Pipelines API에 사용할 수 없습니다.
• Project를 생성한 직후에는 403 project serviceaccount not provisioned 오류가 발생할 수 있습니다. 잠시 후 다시 시도하십시오.

파이프라인 작성 방법은 Pipelines를 참조해 주십시오.

Model Registry CLI/SDK

Model Registry CLI/SDK는 환경 변수 MLX_APIKEY 또는 mlx configure 명령으로 API Key를 설정합니다.

export MLX_ENDPOINT_URL="https://{ML expert Platform 도메인}"
export MLX_APIKEY="{API Key}"

• Project의 모델은 Model 권한이 있는 Project API Key, Workspace의 모델은 Model 권한이 있는 Workspace API Key를 사용합니다.
• 모델 조회·다운로드에는 reader, 모델·버전 생성과 파일 업로드·삭제에는 writer 권한이 필요합니다.
• 추론 서비스가 Model Registry의 모델을 내려받을 때 사용하는 storage-config Secret에도 Model reader 권한이 있는 API Key를 넣습니다.

자세한 사용 방법은 Model Registry를 참조해 주십시오.

Data Manager SDK

Data Manager SDK는 Dataset 권한이 있는 Workspace API Key로 로그인합니다.

from mlx.sdk.data import login

login("{API Key}", "{ML expert Platform 도메인}")

특정 데이터셋만 허용하려면 권한의 대상에 데이터셋 이름을 지정합니다. 자세한 사용 방법은 Data Manager를 참조해 주십시오.

API Key와 kubeconfig 비교

ML expert Platform은 API Key 외에 Project 단위 kubeconfig도 제공합니다. 용도에 맞게 선택합니다.

kubeconfig 발급 방법은 Overview를 참조해 주십시오.

문제 해결