GitLab 에이전트 구성

Tier: 프리미엄, 얼티밋 Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab 15.11에 도입됨 remote_development_feature_flag이란 이름의 플래그와 함께. 기본적으로 비활성화됨.
GitLab 16.0에서 GitLab.com 및 Self-managed에 사용되도록 설정됨.
GitLab 16.7에 대해 일반 사용 가능. 기능 플래그 remote_development_feature_flag 제거됨.

작업 공간 인프라를 설정할 때, 작업 공간을 지원하기 위해 GitLab 에이전트를 구성해야 합니다. 본 가이드는 이미 Kubernetes 클러스터에 GitLab 에이전트가 설치되어 있다고 가정합니다.

필수 조건:

에이전트 구성은 remote_development 모듈이 활성화되어 있어야 하며, 이 모듈의 필수 필드가 올바르게 설정되어 있어야 합니다. 자세한 내용은 작업 공간 설정을 참조하십시오.
작업 공간을 생성하는 목적으로 그룹에서 에이전트를 허용해야 합니다. 작업 공간을 생성하는 동안 사용자는 작업 공간 프로젝트의 부모 그룹 중 어떤 그룹에 연결된 허용된 에이전트를 선택할 수 있습니다.
작업 공간 생성자는 에이전트가 속한 프로젝트의 개발자 역할을 가져야 합니다.

그룹 내에서 작업 공간 생성을 위한 에이전트 승인

GitLab 17.2에 도입된 새로운 승인 전략.

레거시 승인 전략을 대체하는 새로운 승인 전략으로, 그룹 소유자 및 관리자는 그룹 내에서 작업 공간을 호스팅하는 데 사용할 수 있는 클러스터 에이전트를 제어할 수 있습니다.

예를 들어, 작업 공간 프로젝트의 경로가 top-group/subgroup-1/subgroup-2/workspace-project인 경우, top-group, subgroup-1, 또는 subgroup-2 그룹 중 어떤 그룹의 구성된 에이전트든 사용할 수 있습니다.

%%{init: {'theme':'neutral'}}%% graph TD; classDef active fill:lightgreen, stroke:#green, color:green, stroke-width:1px; topGroup[최상위 그룹, 허용된 에이전트 1] subgroup1[하위 그룹 1, 허용된 에이전트 2] subgroup2[하위 그룹 2, 허용된 에이전트 3] wp(작업 공간 프로젝트, 에이전트 1, 2 & 3 모두 사용 가능) topGroup --> subgroup1 subgroup1 --> subgroup2 subgroup2 --> wp class wp active;

만일 클러스터 에이전트가 한 그룹, 예를 들어 subgroup-1에서 허용되었다면, 해당 클러스터 에이전트는 subgroup-1 하위의 모든 프로젝트(중첩된 프로젝트 포함)에서 작업 공간을 생성하는 데 사용할 수 있습니다. 따라서 클러스터 에이전트가 허용된 그룹을 고려해야 할 수도 있으며, 이는 클러스터 에이전트가 작업 공간을 호스팅하는 데 사용될 수 있는 범위에 영향을 미칠 수 있습니다.

그룹 내에서 작업 공간을 위한 클러스터 에이전트 허용

필수 조건:

작업 공간 인프라를 설정해야 합니다.
인스턴스에 대한 관리자 액세스 또는 그룹의 소유자 역할이 있어야 합니다.

그룹 내에서 작업 공간을 위한 클러스터 에이전트를 허용하려면:

좌측 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
좌측 사이드바에서 설정 > 작업 공간을 선택합니다.
그룹 에이전트 섹션에서 모든 에이전트 탭을 선택합니다.
사용 가능한 에이전트 목록에서 상태가 차단됨인 에이전트를 찾아 허용을 선택합니다.
확인 대화상자에서 에이전트 허용을 선택합니다.

선택한 에이전트의 상태가 허용됨으로 업데이트되고, 해당 에이전트는 허용된 에이전트 탭에 표시됩니다.

그룹 내 작업 공간을 위한 허용된 클러스터 에이전트 제거

필수 조건:

작업 공간 인프라를 설정해야 합니다.
인스턴스에 대한 관리자 액세스 또는 그룹의 소유자 역할이 있어야 합니다.

그룹에서 허용된 클러스터 에이전트를 제거하려면:

좌측 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
좌측 사이드바에서 설정 > 작업 공간을 선택합니다.
그룹 에이전트 섹션에서 허용된 에이전트 탭을 선택합니다.
허용된 에이전트 목록에서 제거하려는 에이전트를 찾아 차단을 선택합니다.
확인 대화상자에서 에이전트 차단을 선택합니다.

선택한 에이전트의 상태가 차단됨으로 업데이트되고, 해당 에이전트는 허용된 에이전트 탭에서 제거됩니다.

그룹에서 허용된 클러스터 에이전트를 제거하더라도 이로 인해 즉시 해당 에이전트를 사용하여 작업하는 것은 중단되지 않습니다. 작동 중인 작업 공간은 자동으로 종료되거나 수동으로 중지되기 전까지 작동을 계속합니다.

레거시 에이전트 승인 전략

GitLab 17.1 및 이전 버전에서는 작업 공간을 생성하기 위해 그룹 내에 허용된 에이전트일 필요가 없습니다. 작업 공간 프로젝트의 최상위 그룹(또는 루트 그룹) 어디에서든지 원하는 구성된 에이전트를 사용하여 작업 공간을 생성할 수 있습니다. 다만, 원격 개발 모듈이 활성화되어 있고 최소한의 루트 그룹에 대한 개발자 역할이 있어야 합니다. 예를 들어, 작업 공간 프로젝트의 경로가 top-group/subgroup-1/subgroup-2/workspace-project라면, top-group 및 해당 하위 그룹에서 구성된 에이전트를 사용할 수 있습니다.

작업 공간 설정

설정	필수 여부	기본값	설명
`enabled`	예	`false`	GitLab 에이전트의 원격 개발 활성화 여부를 나타냅니다.
`dns_zone`	예	없음	작업 공간 사용 가능한 DNS 영역입니다.
`gitlab_workspaces_proxy`	아니요	`gitlab-workspaces`	`gitlab-workspaces-proxy`가 설치된 네임스페이스입니다.
`network_policy`	아니요	`network_policy` 참조	작업 공간의 방화벽 규칙입니다.
`default_resources_per_workspace_container`	아니요	`{}`	작업 공간 컨테이너당 CPU와 메모리의 기본 요청 및 제한입니다.
`max_resources_per_workspace`	아니요	`{}`	작업 공간당 CPU 및 메모리의 최대 요청 및 제한입니다.
`workspaces_quota`	아니요	`-1`	GitLab 에이전트에 대한 최대 작업 공간 수입니다.
`workspaces_per_user_quota`	아니요	`-1`	사용자당 최대 작업 공간 수입니다.
`use_kubernetes_user_namespaces`	아니요	`false`	Kubernetes에서 사용자 네임스페이스를 사용할지 여부입니다.
`default_runtime_class`	아니요	`""`	기본 Kubernetes `RuntimeClass`입니다.
`allow_privilege_escalation`	아니요	`false`	권한 상승 허용 여부입니다.
`annotations`	아니요	`{}`	Kubernetes 객체에 적용할 주석입니다.
`labels`	아니요	`{}`	Kubernetes 객체에 적용할 레이블입니다.

참고: 설정의 값이 잘못된 경우 해당 값이 수정될 때까지 어떤 설정도 업데이트할 수 없습니다. 이러한 설정(단, enabled는 제외)을 업데이트해도 기존 작업 공간에는 영향을 주지 않습니다.

`enabled`

이 설정을 사용하여 다음을 정의합니다:

GitLab 에이전트가 GitLab 인스턴스와 통신할 수 있는지 여부.
GitLab 에이전트와 함께 작업 공간을 생성할 수 있는지 여부.

기본값은 false입니다.

에이전트 구성에서 원격 개발을 활성화하려면 enabled를 true로 설정하세요:

remote_development:
  enabled: true

원격 개발이 비활성화되면 관리자는 Kubernetes 클러스터에서 실행 중인 작업 공간을 수동으로 삭제해야 합니다.

`dns_zone`

이 설정을 사용하여 작업 공간이 있는 URL의 DNS 영역을 정의합니다.

예시 구성:

remote_development:
  dns_zone: "<workspaces.example.dev>"

`gitlab_workspaces_proxy`

이 설정을 사용하여 gitlab-workspaces-proxy가 설치된 네임스페이스를 정의합니다. gitlab_workspaces_proxy.namespace의 기본값은 gitlab-workspaces입니다.

예시 구성:

remote_development:
  gitlab_workspaces_proxy:
    namespace: "<custom-gitlab-workspaces-proxy-namespace>"

`network_policy`

이 설정을 사용하여 각 작업 공간의 네트워크 정책을 정의합니다. 이 설정은 작업 공간의 네트워크 트래픽을 제어합니다.

기본값은:

remote_development:
  network_policy:
    enabled: true
    egress:
      - allow: "0.0.0.0/0"
        except:
          - "10.0.0.0/8"
          - "172.16.0.0/12"
          - "192.168.0.0/16"

이 구성에서:

enabled가 true이기 때문에 각 작업 공간에 대한 네트워크 정책이 생성됩니다.
이그레스 규칙은 인터넷으로 모든 트래픽을 허용하되 (0.0.0.0/0), IP CIDR 범위 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16으로 향하는 트래픽은 제외됩니다.

네트워크 정책의 동작은 Kubernetes 네트워크 플러그인에 따라 다릅니다. 더 많은 정보는 Kubernetes 문서를 참조하세요.

`network_policy.enabled`

이 설정을 사용하여 각 작업 공간에 대한 네트워크 정책이 생성되는지 여부를 정의합니다. network_policy.enabled의 기본값은 true입니다.

`network_policy.egress`

GitLab 16.7에서 도입.

작업 공간에서 egress 목적지로 허용할 IP CIDR 범위 목록을 정의하는 데 사용합니다.

다음 상황에서 egress 규칙을 정의하세요:

GitLab 인스턴스가 사설 IP 범위에 있는 경우.
작업 공간이 사설 IP 범위에 있는 클라우드 리소스에 액세스해야 하는 경우.

목록의 각 요소는 선택적인 except 속성을 포함한 allow 속성을 정의합니다. allow는 트래픽을 허용할 IP 범위를 정의하며, except는 allow 범위에서 제외할 IP 범위를 나열합니다.

예시 구성:

remote_development:
  network_policy:
    egress:
      - allow: "0.0.0.0/0"
        except:
          - "10.0.0.0/8"
          - "172.16.0.0/12"
          - "192.168.0.0/16"
      - allow: "172.16.123.1/32"

이 예시에서:

작업 공간의 트래픽은 다음 상황에서 허용됩니다:
- 대상 IP가 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16이 아닌 범위일 때.
- 대상 IP가 172.16.123.1/32일 때.

`default_resources_per_workspace_container`

GitLab 16.8에서 도입.

이 설정을 사용하여 작업 공간 컨테이너당 CPU 및 메모리에 대한 기본 요청 및 제한을 정의합니다. devfile에서 정의하는 모든 리소스는 이 설정을 재정의합니다.

default_resources_per_workspace_container에는 requests 및 limits가 필요합니다. 가능한 CPU 및 메모리 값에 대한 자세한 정보는 쿠버네티스에서의 리소스 단위를 참조하세요.

예시 구성:

remote_development:
  default_resources_per_workspace_container:
    requests:
      cpu: "0.5"
      memory: "512Mi"
    limits:
      cpu: "1"
      memory: "1Gi"

`max_resources_per_workspace`

GitLab 16.8에서 도입.

이 설정을 사용하여 작업 공간당 CPU 및 메모리에 대한 최대 요청 및 제한을 정의합니다. max_resources_per_workspace에는 requests 및 limits가 필요합니다. 가능한 CPU 및 메모리 값에 대한 자세한 정보는 다음을 참조하세요:

작업 공간이 requests 및 limits로 설정한 값 이상을 사용하면 작업 공간이 실패합니다.

예시 구성:

remote_development:
  max_resources_per_workspace:
    requests:
      cpu: "1"
      memory: "1Gi"
    limits:
      cpu: "2"
      memory: "2Gi"

정의하는 최대 리소스에는 프로젝트 저장소를 복제하는 등 부트스트래핑 작업을 수행하는 이니셜라이저 컨테이너에 필요한 리소스를 포함해야 합니다.

`workspaces_quota`

GitLab 16.9에서 도입.

이 설정을 사용하여 GitLab 에이전트의 최대 작업 공간 수를 설정합니다.

에이전트에 대한 작업 공간 수가 정의한 workspaces_quota에 도달하면 새로운 작업 공간을 생성할 수 없습니다. workspaces_quota가 0으로 설정되면 더 이상의 작업 공간을 생성할 수 없습니다.

workspaces_quota가 에이전트의 종료되지 않은 작업 공간 수보다 작은 값을 설정하면, 에이전트의 작업 공간은 자동으로 종료되지 않습니다.

기본값은 -1 (무제한)입니다. 가능한 값은 -1 이상입니다.

예시 구성:

remote_development:
  workspaces_quota: 10

`workspaces_per_user_quota`

History

Introduced in GitLab 16.9. 이 설정은 사용자 당 최대 작업 공간 수를 설정하는 데 사용됩니다.

사용자의 작업 공간 수가 정의된 workspaces_per_user_quota에 도달했을 때 사용자의 새 작업 공간을 생성할 수 없습니다.

workspaces_per_user_quota가 0으로 설정된 경우
workspaces_per_user_quota가 사용자 당 비종료 작업 공간 수보다 작은 값으로 설정된 경우, 사용자의 작업 공간은 자동으로 종료되지 않습니다.

기본값은 -1 (무제한)입니다. 가능한 값은 -1 이상입니다.

예시 구성:

remote_development:
  workspaces_per_user_quota: 3

`use_kubernetes_user_namespaces`

History

Introduced in GitLab 17.4. 이 설정은 쿠버네티스의 사용자 네임스페이스 기능 사용 여부를 지정하는 데 사용됩니다.

사용자 네임스페이스는 컨테이너 내부에서 실행 중인 사용자를 호스트의 사용자로부터 격리시킵니다. 쿠버네티스 1.30에서 이 기능은 베타 상태입니다.

기본값은 false입니다. 값을 true로 설정하기 전에 쿠버네티스 클러스터가 사용자 네임스페이스를 지원하는지 확인하십시오.

예시 구성:

remote_development:
  use_kubernetes_user_namespaces: true

use_kubernetes_user_namespaces에 대한 자세한 정보는 사용자 네임스페이스를 참조하십시오.

`default_runtime_class`

History

Introduced in GitLab 17.4. 이 설정은 작업 공간에서 실행 중인 컨테이너의 컨테이너 런타임 구성을 선택하는 데 사용됩니다.

기본값은 ""이며, 값이 없음을 나타냅니다.

예시 구성:

remote_development:
  default_runtime_class: "example-runtime-class-name"

253자 이하의 올바른 값
소문자, 숫자, -, 나 .만 포함합니다.
영숫자로 시작하고 끝납니다.

default_runtime_class에 대한 자세한 정보는 런타임 클래스를 참조하십시오.

`allow_privilege_escalation`

History

Introduced in GitLab 17.4. 이 설정은 프로세스가 부모 프로세스보다 더 많은 권한을 획들할 수 있는지 여부를 제어하는 데 사용됩니다. 이 설정은 컨테이너 프로세스에 대해 no_new_privs 플래그를 직접 제어합니다.

기본값은 false입니다. 값은 다음 중 하나인 경우에만 true로 설정할 수 있습니다.

default_runtime_class가 비어 있지 않게 설정된 경우
use_kubernetes_user_namespaces가 true로 설정된 경우

예시 구성:

remote_development:
  default_runtime_class: "example-runtime-class-name"
  allow_privilege_escalation: true

allow_privilege_escalation에 대한 자세한 정보는 Pod나 컨테이너에 대한 보안 컨텍스트 구성를 참조하십시오.

`annotations`

History

Introduced in GitLab 17.4. Kubernetes 객체에 임의의 식별되지 않는 메타데이터를 추가하는 데 사용됩니다.

기본값은 {}입니다.

예시 구성:

remote_development:
  annotations:
    "example.com/key": "value"

올바른 주석 키는 다음으로 구성됩니다.

필수는 아니지만 있으면, 접두사입니다. 접두사는 253자 이하이어야 하며, 점으로 구분된 DNS 레이블을 포함해야 합니다. 접두사는 슬래시(/)로 끝나야 합니다.
이름입니다. 이름은 63자 이하여야 하며, 영숫자, 하이픈(-), 밑줄(_), 및 기간(.)만 포함해야 합니다. 이름은 영숫자로 시작하고 끝나야 합니다.

annotations에 대한 자세한 정보는 Annotations를 참조하십시오.

`labels`

History

Introduced in GitLab 17.4. Kubernetes 객체에 임의의 식별 메타데이터를 추가하는 데 사용됩니다.

기본값은 {}입니다.

예시 구성:

remote_development:
  labels:
    "example.com/key": "value"

라벨 키는 다음으로 구성됩니다.

필수는 아니지만 있으면, 접두사입니다. 접두사는 253자 이하여야 하며, 점으로 구분된 DNS 레이블을 포함해야 합니다. 접두사는 슬래시(/)로 끝나야 합니다.
이름입니다. 이름은 63자 이하여야 하며, 영숫자, 하이픈(-), 밑줄(_), 및 기간(.)만 포함해야 합니다. 이름은 영숫자로 시작하고 끝나야 합니다.

labels에 대한 자세한 정보는 Labels를 참조하십시오.

원격 개발로 사용자 액세스 구성

GitLab 자격 증명으로 연결된 Kubernetes 클러스터에 액세스하는 데 user_access 모듈을 구성할 수 있습니다. 이 모듈은 remote_development 모듈과는 독립적으로 구성 및 실행됩니다.

동일한 GitLab 에이전트에서 user_access와 remote_development를 구성할 때 주의하십시오. remote_development 클러스터는 사용자 자격 증명(예: 개인 접근 토큰)을 쿠버네티스 시크릿으로 관리합니다. user_access를 잘못 구성하면 해당 개인 데이터가 쿠버네티스 API를 통해 접근 가능해질 수 있습니다.

user_access를 구성하는 자세한 정보는 쿠버네티스 액세스 구성를 참조하십시오.

GitLab 에이전트 구성

그룹 내에서 작업 공간 생성을 위한 에이전트 승인

그룹 내에서 작업 공간을 위한 클러스터 에이전트 허용

그룹 내 작업 공간을 위한 허용된 클러스터 에이전트 제거

레거시 에이전트 승인 전략

작업 공간 설정

`enabled`

`dns_zone`

`gitlab_workspaces_proxy`

`network_policy`

`network_policy.enabled`

`network_policy.egress`

`default_resources_per_workspace_container`

`max_resources_per_workspace`

`workspaces_quota`

`workspaces_per_user_quota`

`use_kubernetes_user_namespaces`

`default_runtime_class`

`allow_privilege_escalation`

`annotations`

`labels`

원격 개발로 사용자 액세스 구성

도움말

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

도움받기