에이전트 API

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

에이전트 토큰 API는 GitLab 15.0에서 도입되었습니다.

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>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents"

예시 응답:

[
  {
    "id": 1,
    "name": "에이전트-1",
    "config_project": {
      "id": 20,
      "description": "",
      "name": "테스트",
      "name_with_namespace": "관리자 / 테스트",
      "path": "테스트",
      "path_with_namespace": "root/테스트",
      "created_at": "2022-03-20T20:42:40.221Z"
    },
    "created_at": "2022-04-20T20:42:40.221Z",
    "created_by_user_id": 42
  },
  {
    "id": 2,
    "name": "에이전트-2",
    "config_project": {
      "id": 20,
      "description": "",
      "name": "테스트",
      "name_with_namespace": "관리자 / 테스트",
      "path": "테스트",
      "path_with_namespace": "root/테스트",
      "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>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/1"

예시 응답:

{
  "id": 1,
  "name": "에이전트-1",
  "config_project": {
    "id": 20,
    "description": "",
    "name": "테스트",
    "name_with_namespace": "관리자 / 테스트",
    "path": "테스트",
    "path_with_namespace": "root/테스트",
    "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 --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": "에이전트-1",
  "config_project": {
    "id": 20,
    "description": "",
    "name": "테스트",
    "name_with_namespace": "관리자 / 테스트",
    "path": "테스트",
    "path_with_namespace": "root/테스트",
    "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`	정수 또는 문자열	예	인증된 사용자가 유지하는 프로젝트의 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 --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`	정수 또는 문자열	예	인증된 사용자가 유지 관리하는 프로젝트의 ID 또는 URL로 인코딩된 경로
`agent_id`	정수	예	에이전트의 ID.
`token_id`	정수	예	토큰의 ID.

예시 요청:

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

에이전트 API

프로젝트의 에이전트 디렉터리

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

프로젝트에 에이전트 등록

등록된 에이전트 삭제

에이전트의 토큰 디렉터리

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

에이전트 토큰 생성

에이전트 토큰 취소

도움말

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

도움받기