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は、発行範囲によって2種類に分けられます。アクセスしようとするリソースがどこに属するかによって、種類を選択します。

• データセットは Workspaceが所有するリソースであるため、Workspace API Keyでのみアクセスできます。
• 推論エンドポイントと Pipelinesは Projectが所有するリソースであるため、Project API Keyでのみアクセスできます。
• 1つの 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をクリックします。発行されたキーが1つもない場合は、画面中央の追加ボタンをクリックします。
3. API Key発行のポップアップに以下の項目を入力します。
   • API Key名: 英小文字(a-z)、数字(0-9)、ハイフン(-)を使用して、63文字以内で入力します。先頭と末尾は、英小文字または数字にする必要があります。
   • 有効期間(日): 1~365の整数を入力するか、入力欄の右側にある7d、30d、90d、365dのいずれかを選択します。デフォルト値は30日で、入力欄の下に有効期限が予定されている時刻が表示されます。
   • 説明(オプション): 利用先や発行対象を256文字以内で記入します。
   • Permissions: リソースタイプ、権限レベル、対象を選択します。権限をさらに追加するには、権限追加ボタンをクリックします。権限は1つ以上追加する必要があり、同じ(リソースタイプ、権限レベル)組み合わせは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の行のチェックボックスを選択します。一度に1つだけ選択できます。
3. リストの上部にある Deleteをクリックします。
4. API Key削除画面で削除をクリックします。

有効期限が切れた API Keyも、同じ方法で削除します。

API Key使用

APIキーは、HTTPリクエストの Authorization ヘッダに Bearerトークンとして送信します。各サービスの使用方法は、次の通りです。

推論エンドポイントの呼び出し

推論エンドポイントを非公開で運用するには、InferenceService または LLMInferenceServiceに次のアノテーションを設定します。アノテーションを設定しない場合、エンドポイントは認証なしで呼び出すことができます。

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

非公開エンドポイントは、次の2つの方法で呼び出すことができます。

• 対象 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には使用できません。
• プロジェクトを作成した直後は、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をご参照ください。

トラブルシューティング