KubernetesエージェントAPI

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このAPIを使用して、Kubernetes向けGitLabエージェントを操作します。

プロジェクトのエージェントをリスト表示します

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

このエンドポイントを使用するには、デベロッパーロール以上が必要です。

GET /projects/:id/cluster_agents

パラメータは以下のとおりです:

属性	型	必須	説明
`id`	整数または文字列	はい	認証されたユーザーが管理するプロジェクトの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>" \
  --url "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
  }
]

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

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

このエンドポイントを使用するには、デベロッパーロール以上が必要です。

GET /projects/:id/cluster_agents/:agent_id

パラメータは以下のとおりです:

属性	型	必須	説明
`id`	整数または文字列	はい	認証されたユーザーが管理するプロジェクトのID、またはURLエンコードされたプロジェクトのパス。
`agent_id`	整数	はい	エージェントの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>" \
  --url "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`	整数または文字列	はい	認証されたユーザーが管理するプロジェクトのID、またはURLエンコードされたプロジェクトのパス。
`name`	文字列	はい	エージェントの名前。

応答:

レスポンスは、次のフィールドを持つ新しいエージェントです:

属性	型	説明
`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 --request POST \
  --header "Private-Token: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents" \
  --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`	整数または文字列	はい	認証されたユーザーが管理するプロジェクトのID、またはURLエンコードされたプロジェクトのパス。
`agent_id`	整数	はい	エージェントのID

リクエスト例:

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

エージェントのトークンをリスト表示

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

このエンドポイントを使用するには、デベロッパーロール以上が必要です。

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

サポートされている属性は以下のとおりです:

属性	型	必須	説明
`id`	整数または文字列	はい	認証されたユーザーが管理するプロジェクトのID、またはURLエンコードされたプロジェクトのパス。
`agent_id`	整数または文字列	はい	エージェントの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>" \
  --url "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フィールドは、単一のエージェントトークンを取得するときにのみ返されます。

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

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

このエンドポイントを使用するには、デベロッパーロール以上が必要です。

エージェントトークンが失効された場合、404を返します。

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

サポートされている属性は以下のとおりです:

属性	型	必須	説明
`id`	整数または文字列	はい	認証されたユーザーが管理するプロジェクトのID、またはURLエンコードされたプロジェクトのパス。
`agent_id`	整数	はい	エージェントのID。
`token_id`	整数	はい	トークンの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>" \
  --url "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
}

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

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

このエンドポイントを使用するには、少なくともメンテナーのロールが必要です。

1つのエージェントが持つことができるアクティブなトークンは2つだけです。

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

サポートされている属性は以下のとおりです:

属性	型	必須	説明
`id`	整数または文字列	はい	認証されたユーザーが管理するプロジェクトのID、またはURLエンコードされたプロジェクトのパス。
`agent_id`	整数	はい	エージェントのID。
`name`	文字列	はい	トークンの名前。
`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はPOSTエンドポイントのレスポンスでのみ返され、後で取得することはできません。

リクエスト例:

curl --request POST \
  --header "Private-Token: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens" \
  --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"
}

エージェントトークンを失効する

エージェントのトークンを失効します。

このエンドポイントを使用するには、少なくともメンテナーのロールが必要です。

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

サポートされている属性は以下のとおりです:

| 属性 | タイプ | 必須 | 説明 | |————|——————-|———-|—————————————————————————————————————- -| | id | 整数または文字列 | はい | が管理するURLエンコードされたプロジェクトのパスのID。 | | agent_id | 整数 | はい | エージェントのID。 | | token_id | 整数 | はい | トークンのID。 |

リクエスト例:

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

受信エージェント

プラン: Ultimate
提供形態: GitLab Self-Managed

受容エージェントを使用すると、GitLabインスタンスへのネットワーク接続を確立できないがGitLabからは接続できるKubernetesクラスターと、GitLabを統合できます。

受容エージェントのURL設定をリスト表示

エージェントのURL設定のリストを返します。

このエンドポイントを使用するには、デベロッパーロール以上が必要です。

GET /projects/:id/cluster_agents/:agent_id/url_configurations

サポートされている属性は以下のとおりです:

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

応答:

レスポンスは、次のフィールドを持つURL設定のリストです:

属性	型	説明
`id`	整数	URL構成のID。
`agent_id`	整数	URL設定が属するエージェントのID。
`url`	文字列	このURL設定のURL。
`public_key`	文字列	（オプション）JWT認証が使用されている場合、Base64エンコードされた公開キー。
`client_cert`	文字列	（オプション）mTLS認証が使用されている場合は、PEM形式のクライアント証明書。
`ca_cert`	文字列	（オプション）エージェントのエンドポイントを検証するための、PEM形式のCA証明書。
`tls_host`	文字列	エージェントのエンドポイント証明書のサーバー名を検証するためのTLSホスト名（オプション）。

リクエスト例:

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

レスポンス例:

[
  {
    "id": 1,
    "agent_id": 5,
    "url": "grpcs://agent.example.com:4242",
    "public_key": "..."
  }
]

public_keyまたはclient_certのどちらかが設定されていますが、両方が設定されることはありません。

単一のエージェントのURL設定を取得

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

このエンドポイントを使用するには、デベロッパーロール以上が必要です。

GET /projects/:id/cluster_agents/:agent_id/url_configurations/:url_configuration_id

サポートされている属性は以下のとおりです:

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

応答:

レスポンスは、次のフィールドを持つ単一のURL設定です:

属性	型	説明
`id`	整数	URL構成のID。
`agent_id`	整数	URL設定が属するエージェントのID。
`url`	文字列	このURL設定のエージェントURL。
`public_key`	文字列	（オプション）JWT認証が使用されている場合、Base64エンコードされた公開キー。
`client_cert`	文字列	（オプション）mTLS認証が使用されている場合は、PEM形式のクライアント証明書。
`ca_cert`	文字列	（オプション）エージェントのエンドポイントを検証するための、PEM形式のCA証明書。
`tls_host`	文字列	エージェントのエンドポイント証明書のサーバー名を検証するためのTLSホスト名（オプション）。

リクエスト例:

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

レスポンス例:

{
  "id": 1,
  "agent_id": 5,
  "url": "grpcs://agent.example.com:4242",
  "public_key": "..."
}

public_keyまたはclient_certのどちらかが設定されていますが、両方が設定されることはありません。

エージェントのURL設定を作成

エージェントの新しいURL設定を作成します。

このエンドポイントを使用するには、少なくともメンテナーのロールが必要です。

1つのエージェントが一度に持つことができるURL設定は1つのみです。

POST /projects/:id/cluster_agents/:agent_id/url_configurations

サポートされている属性は以下のとおりです:

属性	型	必須	説明
`id`	整数または文字列	はい	認証されたユーザーが管理するプロジェクトのID、またはURLエンコードされたプロジェクトのパス。
`agent_id`	整数	はい	エージェントのID。
`url`	文字列	はい	このURL設定のエージェントURL。
`client_cert`	文字列	いいえ	mTLS認証を使用する場合、PEM形式のクライアント証明書。`client_key`と共に指定する必要があります。
`client_key`	文字列	いいえ	mTLS認証を使用する場合、PEM形式のクライアントキー。`client_cert`と共に指定する必要があります。
`ca_cert`	文字列	いいえ	エージェントのエンドポイントを検証するための、PEM形式のCA証明書。
`tls_host`	文字列	いいえ	エージェントのエンドポイント証明書のサーバー名を検証するためのTLSホスト名。

応答:

レスポンスは、次のフィールドを持つ新しいURL設定です:

属性	型	説明
`id`	整数	URL構成のID。
`agent_id`	整数	URL設定が属するエージェントのID。
`url`	文字列	このURL設定のエージェントURL。
`public_key`	文字列	（オプション）JWT認証が使用されている場合、Base64エンコードされた公開キー。
`client_cert`	文字列	（オプション）mTLS認証が使用されている場合は、PEM形式のクライアント証明書。
`ca_cert`	文字列	（オプション）エージェントのエンドポイントを検証するための、PEM形式のCA証明書。
`tls_host`	文字列	エージェントのエンドポイント証明書のサーバー名を検証するためのTLSホスト名（オプション）。

JWTトークンでURL設定を作成するリクエストの例:

curl --request POST \
  --header "Private-Token: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations" \
  --data '{"url":"grpcs://agent.example.com:4242"}'

JWT認証のレスポンス例:

{
  "id": 1,
  "agent_id": 5,
  "url": "grpcs://agent.example.com:4242",
  "public_key": "..."
}

ファイルclient.pemおよびclient-key.pemからクライアント証明書とキーペアを使用してmTLS認証を使用するURL設定を作成するリクエストの例:

curl --request POST \
  --header "Private-Token: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations" \
  --data '{"url":"grpcs://agent.example.com:4242", \
           "client_cert":"'"$(awk -v ORS='\\n' '1' client.pem)"'", \
           "client_key":"'"$(awk -v ORS='\\n' '1' client-key.pem)"'"}'

mTLS認証のレスポンスの例:

{
  "id": 1,
  "agent_id": 5,
  "url": "grpcs://agent.example.com:4242",
  "client_cert": "..."
}

client_certとclient_keyが指定されていない場合、プライベート公開キーペアが生成され、mTLS認証の代わりにJWT認証が使用されます。

エージェントのURL設定を削除

エージェントのURL設定を削除します。

このエンドポイントを使用するには、少なくともメンテナーのロールが必要です。

DELETE /projects/:id/cluster_agents/:agent_id/url_configurations/:url_configuration_id

サポートされている属性は以下のとおりです:

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

リクエスト例:

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