에이전트 API

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

GitLab 14.10에 도입
GitLab 15.0에 도입된 Agent Tokens API

GitLab Kubernetes 에이전트와 작업하기 위해 에이전트 API를 사용하세요.

프로젝트에 대한 에이전트 목록

프로젝트에 등록된 에이전트 목록을 반환합니다.

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

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

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

단일 에이전트의 세부 정보를 가져옵니다.

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

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에서 도입되었습니다.

단일 에이전트 토큰을 가져옵니다.

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

에이전트 토큰이 취소된 경우 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가 제거되었습니다.

에이전트에 대한 새로운 토큰을 생성합니다.

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

한 번에 두 개의 활성 토큰만을 가질 수 있습니다.

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

프로젝트에 대한 에이전트 목록

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

프로젝트에 대리자 등록하기

등록된 대리자 삭제

대리자의 토큰 목록

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

에이전트 토큰 생성

에이전트 토큰 취소

도움말

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

도움받기