에이전트 API

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab 14.10에서 소개되었습니다.
GitLab 15.0에서 에이전트 토큰 API가 소개되었습니다.

GitLab Kubernetes 에이전트를 사용하기 위한 에이전트 API입니다.

프로젝트에 등록된 에이전트 디렉터리

프로젝트에 등록된 에이전트의 디렉터리을 반환합니다.

이 엔드포인트를 사용하려면 최소한 Developer 역할이 있어야 합니다.

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>" "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`	정수 또는 문자열	예	인증된 사용자가 유지하는 프로젝트의 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>" "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
}

프로젝트에 에이전트 등록하기

프로젝트에 에이전트를 등록합니다.

이 엔드포인트를 사용하려면 적어도 Maintainer 역할이 있어야 합니다.

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 --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
}

등록된 에이전트 삭제하기

기존의 에이전트 등록을 삭제합니다.

이 엔드포인트를 사용하려면 적어도 Maintainer 역할이 있어야 합니다.

DELETE /projects/:id/cluster_agents/:agent_id

매개변수:

속성	유형	필수 여부	설명
`id`	정수 또는 문자열	예	인증된 사용자가 유지하는 프로젝트의 ID 또는 URL 인코딩 된 경로
`agent_id`	정수	예	에이전트의 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`	정수 또는 문자열	예	인증된 사용자가 유지하는 프로젝트의 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>" "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`	정수 또는 문자열	예	인증된 사용자가 유지하는 프로젝트의 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>" "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이라는 플래그로 도입되었습니다.
두 개의 토큰 제한은 GitLab 16.2에서 일반적으로 사용 가능합니다. 피처 플래그 cluster_agents_limit_tokens_created 제거됨.

에이전트용 새 토큰을 생성합니다.

이 엔드포인트를 사용하려면 적어도 Maintainer 역할이 있어야 합니다.

한 번에 하나의 에이전트에는 두 개의 활성 토큰만 가질 수 있습니다.

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

지원되는 속성:

속성	타입	필수	설명
`id`	integer 또는 string	예	인증된 사용자가 유지하는 프로젝트의 ID 또는 URL 인코딩된 경로
`agent_id`	integer	예	에이전트의 ID
`name`	string	예	토큰의 이름
`description`	string	아니요	토큰에 대한 설명

응답:

응답은 다음과 같은 필드를 가진 새 토큰입니다:

속성	타입	설명
`id`	integer	토큰의 ID
`name`	string	토큰의 이름
`description`	string 또는 null	토큰의 설명
`agent_id`	integer	토큰이 속한 에이전트의 ID
`status`	string	토큰의 상태. “active”와 “revoked”가 유효한 값입니다.
`created_at`	string	토큰이 생성된 ISO8601 날짜 및 시간
`created_by_user_id`	string	토큰을 생성한 사용자의 사용자 ID
`last_used_at`	string 또는 null	토큰을 마지막으로 사용한 ISO8601 날짜 및 시간
`token`	string	비밀 토큰 값

token은 POST 엔드포인트의 응답에만 반환되며 이후에 검색할 수 없습니다.

예시 요청:

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에서 소개됨.

에이전트 토큰을 취소합니다.

이 엔드포인트를 사용하려면 적어도 Maintainer 역할이 있어야 합니다.

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

지원되는 속성:

속성	타입	필수	설명
`id`	integer 또는 string	예	인증된 사용자가 유지하는 프로젝트의 ID 또는 URL 인코딩된 경로
`agent_id`	integer	예	에이전트의 ID
`token_id`	integer	예	토큰의 ID

예시 요청:

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

에이전트 API

프로젝트에 등록된 에이전트 디렉터리

에이전트에 대한 세부 정보 가져오기

프로젝트에 에이전트 등록하기

등록된 에이전트 삭제하기

에이전트용 토큰 디렉터리

단일 에이전트 토큰 가져오기

에이전트 토큰 생성

에이전트 토큰 취소

도움말

기능 사용 가능성과 제품 평가판

도움받기