エージェントAPI

GitLab 14.10で導入されました。
エージェントトークン API は GitLab 15.0 で導入されました。

Kubernetes用のGitLabエージェントと連携するにはAgent APIを使用します。

プロジェクトのエージェントをリストアップします。

プロジェクトに登録されているエージェントの一覧を返します。

このエンドポイントを使用するには、少なくとも Developer ロールを持っている必要があります。

GET /projects/:id/cluster_agents

パラメータを指定します：

属性	種類	必須	説明
`id`	整数または文字列。	yes	認証ユーザーが管理するプロジェクトのIDまたはURLエンコードされたパス

レスポンス

応答は以下のフィールドを持つエージェントのリストです：

属性	種類	説明
`id`	整数。	エージェントのID
`name`	文字列です。	エージェント名
`config_project`	オブジェクトを返します。	エージェントが所属するプロジェクトを表すオブジェクト
`config_project.id`	整数。	プロジェクトのID
`config_project.description`	文字列です。	プロジェクトの説明
`config_project.name`	文字列です。	プロジェクト名
`config_project.name_with_namespace`	文字列です。	プロジェクトの名前空間を含むフルネーム
`config_project.path`	文字列です。	プロジェクトへのパス
`config_project.path_with_namespace`	文字列です。	プロジェクトの名前空間を含むフルパス
`config_project.created_at`	文字列です。	プロジェクトが作成されたISO8601の日時
`created_at`	文字列です。	エージェントが作成されたISO8601の日時
`created_by_user_id`	整数。	エージェントを作成したユーザーのID

リクエストの例

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents"

応答例

[
  {
    "id": 1,
    "name": "agent-1",
    "config_project": {
      "id": 20,
      "description": "",
      "name": "test",
      "name_with_namespace": "Administrator / test",
      "path": "test",
      "path_with_namespace": "root/test",
      "created_at": "2022-03-20T20:42:40.221Z"
    },
    "created_at": "2022-04-20T20:42:40.221Z",
    "created_by_user_id": 42
  },
  {
    "id": 2,
    "name": "agent-2",
    "config_project": {
      "id": 20,
      "description": "",
      "name": "test",
      "name_with_namespace": "Administrator / test",
      "path": "test",
      "path_with_namespace": "root/test",
      "created_at": "2022-03-20T20:42:40.221Z"
    },
    "created_at": "2022-04-20T20:42:40.221Z",
    "created_by_user_id": 42
  }
]

エージェントの詳細の取得

エージェントの詳細を取得します。

このエンドポイントを使用するには、少なくとも Developer ロールを持っている必要があります。

GET /projects/:id/cluster_agents/:agent_id

パラメータを指定します：

属性	種類	必須	説明
`id`	整数または文字列。	yes	認証ユーザーが管理するプロジェクトのIDまたはURLエンコードされたパス
`agent_id`	整数。	yes	エージェントのID

レスポンス

レスポンスは、以下のフィールドを持つ単一のエージェントです：

属性	種類	説明
`id`	整数。	エージェントのID
`name`	文字列です。	エージェント名
`config_project`	オブジェクトを返します。	エージェントが所属するプロジェクトを表すオブジェクト
`config_project.id`	整数。	プロジェクトのID
`config_project.description`	文字列です。	プロジェクトの説明
`config_project.name`	文字列です。	プロジェクト名
`config_project.name_with_namespace`	文字列です。	プロジェクトの名前空間を含むフルネーム
`config_project.path`	文字列です。	プロジェクトへのパス
`config_project.path_with_namespace`	文字列です。	プロジェクトの名前空間を含むフルパス
`config_project.created_at`	文字列です。	プロジェクトが作成されたISO8601の日時
`created_at`	文字列です。	エージェントが作成されたISO8601の日時
`created_by_user_id`	整数。	エージェントを作成したユーザーのID

リクエストの例

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/1"

応答例

{
  "id": 1,
  "name": "agent-1",
  "config_project": {
    "id": 20,
    "description": "",
    "name": "test",
    "name_with_namespace": "Administrator / test",
    "path": "test",
    "path_with_namespace": "root/test",
    "created_at": "2022-03-20T20:42:40.221Z"
  },
  "created_at": "2022-04-20T20:42:40.221Z",
  "created_by_user_id": 42
}

エージェントのプロジェクト登録

エージェントをプロジェクトに登録します。

このエンドポイントを使用するには、少なくともメンテナーのロールを持っている必要があります。

POST /projects/:id/cluster_agents

パラメータを指定します：

属性	種類	必須	説明
`id`	整数または文字列。	yes	認証ユーザーが管理するプロジェクトのIDまたはURLエンコードされたパス
`name`	文字列です。	yes	エージェント名

レスポンス

応答は、以下のフィールドを持つ新しいエージェントです：

属性	種類	説明
`id`	整数。	エージェントのID
`name`	文字列です。	エージェント名
`config_project`	オブジェクトを返します。	エージェントが所属するプロジェクトを表すオブジェクト
`config_project.id`	整数。	プロジェクトのID
`config_project.description`	文字列です。	プロジェクトの説明
`config_project.name`	文字列です。	プロジェクト名
`config_project.name_with_namespace`	文字列です。	プロジェクトの名前空間を含むフルネーム
`config_project.path`	文字列です。	プロジェクトへのパス
`config_project.path_with_namespace`	文字列です。	プロジェクトの名前空間を含むフルパス
`config_project.created_at`	文字列です。	プロジェクトが作成されたISO8601の日時
`created_at`	文字列です。	エージェントが作成されたISO8601の日時
`created_by_user_id`	整数。	エージェントを作成したユーザーのID

リクエストの例

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents" \
    -H "Content-Type:application/json" \
    -X POST --data '{"name":"some-agent"}'

応答例

{
  "id": 1,
  "name": "agent-1",
  "config_project": {
    "id": 20,
    "description": "",
    "name": "test",
    "name_with_namespace": "Administrator / test",
    "path": "test",
    "path_with_namespace": "root/test",
    "created_at": "2022-03-20T20:42:40.221Z"
  },
  "created_at": "2022-04-20T20:42:40.221Z",
  "created_by_user_id": 42
}

登録エージェントの削除

既存のエージェント登録を削除します。

このエンドポイントを使用するには、少なくともメンテナーのロールを持っている必要があります。

DELETE /projects/:id/cluster_agents/:agent_id

パラメータを指定します：

属性	種類	必須	説明
`id`	整数または文字列。	yes	認証ユーザーが管理するプロジェクトのIDまたはURLエンコードされたパス
`agent_id`	整数。	yes	エージェントのID

リクエストの例

curl --request DELETE --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/1

エージェントのトークンをリストアップします。

GitLab 15.0 で導入されました。

エージェントのアクティブなトークンのリストを返します。

このエンドポイントを使用するには、少なくとも Developer ロールを持っている必要があります。

GET /projects/:id/cluster_agents/:agent_id/tokens

サポートされる属性：

属性	種類	必須	説明
`id`	整数または文字列。	yes	認証されたユーザーが管理するプロジェクトのIDまたはURLエンコードされたパス。
`agent_id`	整数または文字列。	yes	エージェントのID。

レスポンス

レスポンスは以下のフィールドを持つトークンのリストです：

属性	種類	説明
`id`	整数。	トークンの ID。
`name`	文字列です。	トークンの名前。
`description`	文字列または null	トークンの説明。
`agent_id`	整数。	トークンが属するエージェントの ID。
`status`	文字列です。	トークンのステータス。有効な値は`active` および`revoked` です。
`created_at`	文字列です。	トークンが作成された ISO8601 時刻。
`created_by_user_id`	文字列です。	トークンを作成したユーザーのユーザーID。

リクエストの例

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens"

応答例

[
  {
    "id": 1,
    "name": "abcd",
    "description": "Some token",
    "agent_id": 5,
    "status": "active",
    "created_at": "2022-03-25T14:12:11.497Z",
    "created_by_user_id": 1
  },
  {
    "id": 2,
    "name": "foobar",
    "description": null,
    "agent_id": 5,
    "status": "active",
    "created_at": "2022-03-25T14:12:11.497Z",
    "created_by_user_id": 1
  }
]

トークンのlast_used_at フィールドは、単一のエージェントトークンを取得する場合にのみ返されます。

単一エージェントトークンの取得

GitLab 15.0 で導入されました。

単一のエージェントトークンを取得します。

このエンドポイントを使用するには、少なくとも Developer ロールを持っている必要があります。

エージェントトークンが失効している場合は404 を返します。

GET /projects/:id/cluster_agents/:agent_id/tokens/:token_id

サポートされる属性：

属性	種類	必須	説明
`id`	整数または文字列。	yes	認証されたユーザーが管理するプロジェクトのIDまたはURLエンコードされたパス。
`agent_id`	整数。	yes	エージェントのID。
`token_id`	整数。	yes	トークンの ID。

レスポンス

レスポンスは以下のフィールドを持つ単一のトークンです：

属性	種類	説明
`id`	整数。	トークンの ID。
`name`	文字列です。	トークンの名前。
`description`	文字列または null	トークンの説明。
`agent_id`	整数。	トークンが属するエージェントの ID。
`status`	文字列です。	トークンのステータス。有効な値は`active` および`revoked` です。
`created_at`	文字列です。	トークンが作成された ISO8601 時刻。
`created_by_user_id`	文字列です。	トークンを作成したユーザーのユーザーID。
`last_used_at`	文字列または null	トークンが最後に使用された ISO8601 時刻。

リクエストの例

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/token/1"

応答例

{
  "id": 1,
  "name": "abcd",
  "description": "Some token",
  "agent_id": 5,
  "status": "active",
  "created_at": "2022-03-25T14:12:11.497Z",
  "created_by_user_id": 1,
  "last_used_at": null
}

エージェントトークンの作成

GitLab 15.0 で導入されました。
GitLab 16.1でcluster_agents_limit_tokens_created というフラグで2トークンの制限が導入。
GitLab 16.2で2トークンの制限が一般的に利用可能に。機能フラグcluster_agents_limit_tokens_created を削除しました。

エージェントに新しいトークンを作成します。

このエンドポイントを使用するには、少なくともメンテナーのロールを持っている必要があります。

エージェントは、一度に2つのアクティブなトークンしか持つことができません。

POST /projects/:id/cluster_agents/:agent_id/tokens

サポートされる属性：

属性	種類	必須	説明
`id`	整数または文字列。	yes	認証されたユーザーが管理するプロジェクトのIDまたはURLエンコードされたパス。
`agent_id`	整数。	yes	エージェントのID。
`name`	文字列です。	yes	トークンの名前。
`description`	文字列です。	いいえ	トークンの説明

レスポンス

レスポンスは以下のフィールドを持つ新しいトークンです：

属性	種類	説明
`id`	整数。	トークンの ID。
`name`	文字列です。	トークンの名前。
`description`	文字列または null	トークンの説明。
`agent_id`	整数。	トークンが属するエージェントの ID。
`status`	文字列です。	トークンのステータス。有効な値は`active` および`revoked` です。
`created_at`	文字列です。	トークンが作成された ISO8601 時刻。
`created_by_user_id`	文字列です。	トークンを作成したユーザーのユーザーID。
`last_used_at`	文字列または null	トークンが最後に使用された ISO8601 時刻。
`token`	文字列です。	シークレットトークンの値。

token はtoken エンドポイントのレスポンスでのみ返され、それ以降は取得できません。

リクエストの例

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens" \
    -H "Content-Type:application/json" \
    -X POST --data '{"name":"some-token"}'

応答例

{
  "id": 1,
  "name": "abcd",
  "description": "Some token",
  "agent_id": 5,
  "status": "active",
  "created_at": "2022-03-25T14:12:11.497Z",
  "created_by_user_id": 1,
  "last_used_at": null,
  "token": "qeY8UVRisx9y3Loxo1scLxFuRxYcgeX3sxsdrpP_fR3Loq4xyg"
}

エージェントトークンの失効

GitLab 15.0 で導入されました。

エージェントトークンを失効させます。

このエンドポイントを使用するには、少なくともメンテナーのロールを持っている必要があります。

DELETE /projects/:id/cluster_agents/:agent_id/tokens/:token_id

サポートされる属性：

属性(Attribute) タイプ(Type) 必須(Required) 説明(Description) ————– id 整数または文字列(String) yes 認証されたユーザーによって管理されているプロジェクトの ID またはURL エンコードされたパス。 agent_id integer yes エージェントの ID。 token_id ｜整数｜yes｜トークンのID。

リクエストの例

curl --request DELETE --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens/1

エージェントAPI

プロジェクトのエージェントをリストアップします。

エージェントの詳細の取得

エージェントのプロジェクト登録

登録エージェントの削除

エージェントのトークンをリストアップします。

単一エージェントトークンの取得

エージェントトークンの作成

エージェントトークンの失効

Help & feedback

Docs

Product

Feature availability and product trials

Get Help