GitLab 에이전트 구성

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

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

필수 조건:

  • 에이전트 구성에는 remote_development 모듈이 활성화되어 있어야 하며, 이 모듈의 필수 필드가 올바르게 설정되어 있어야 합니다. 자세한 내용은 워크스페이스 설정을 참조하세요.
  • 에이전트는 워크스페이스를 생성하기 위해 그룹에서 허용되어야 합니다. 워크스페이스 생성 중에 사용자는 워크스페이스 프로젝트의 상위 그룹과 연결된 허용된 에이전트를 선택할 수 있습니다.
  • 워크스페이스 생성자는 에이전트의 프로젝트에 대해 개발자 역할을 가져야 합니다.

워크스페이스 생성을 위한 그룹 내 에이전트 권한

새로운 권한 부여 전략은 구식 권한 부여 전략을 대체하며, 그룹 소유자와 관리자들은 어떤 클러스터 에이전트가 그룹 내에서 워크스페이스를 호스팅하는 데 사용될 수 있는지를 제어할 수 있습니다.

예를 들어, 워크스페이스 프로젝트의 경로가 top-group/subgroup-1/subgroup-2/workspace-project인 경우, top-group, subgroup-1 또는 subgroup-2 그룹의 임의의 구성된 에이전트를 사용할 수 있습니다.

상위 그룹, 허용된 에이전트 1
하위 그룹 1, 허용된 에이전트 2
하위 그룹 2, 허용된 에이전트 3
워크스페이스 프로젝트, 에이전트 1, 2 및 3 모두 사용 가능

하나의 그룹, 예를 들어 subgroup-1에 대해 클러스터 에이전트가 허용되면, 해당 클러스터 에이전트는 모든 하위 프로젝트를 포함하여 subgroup-1 아래의 모든 프로젝트에서 워크스페이스 생성을 위해 사용할 수 있습니다. 따라서 클러스터 에이전트가 허용된 그룹을 고려해야 하며, 이는 클러스터 에이전트가 워크스페이스를 호스팅할 수 있는 범위에 영향을 미칠 수 있습니다.

그룹 내 워크스페이스를 위한 클러스터 에이전트 허용

필수 조건:

그룹 내 워크스페이스를 위한 클러스터 에이전트를 허용하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. 왼쪽 사이드바에서 설정 > 워크스페이스를 선택합니다.
  3. 그룹 에이전트 섹션에서 모든 에이전트 탭을 선택합니다.
  4. 사용 가능한 에이전트 목록에서 상태가 차단됨인 에이전트를 찾아 허용을 선택합니다.
  5. 확인 대화 상자에서 에이전트 허용을 선택합니다.

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

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

사전 요구 사항:

  • 작업 공간 인프라 설정을 완료해야 합니다.
  • 인스턴스에 대한 관리자가 필요하거나 그룹에 대한 소유자 역할이 필요합니다.

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

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 그룹을 찾습니다.

  2. 왼쪽 사이드바에서 Settings > Workspaces를 선택합니다.

  3. Group agents 섹션에서 Allowed agents 탭을 선택합니다.

  4. 허용된 에이전트 목록에서 제거하려는 에이전트를 찾아 Block를 선택합니다.

  5. 확인 대화 상자에서 Block agent를 선택합니다.

선택한 에이전트의 상태가 Blocked로 업데이트되고 에이전트가 Allowed agents 탭에서 제거됩니다.

그룹에서 허용된 클러스터 에이전트를 제거해도 이 에이전트를 사용하는 실행 중인 작업 공간이 즉시 중지되지는 않습니다.
실행 중인 작업 공간은 자동으로 종료되거나 수동으로 중지될 때 중지됩니다.

레거시 에이전트 권한 부여 전략

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 아니오 {} 작업 공간 컨테이너당 기본 요청 및 메모리 제한.
max_resources_per_workspace 아니오 {} 작업 공간당 최대 요청 및 메모리 제한.
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입니다.

예제 구성:

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이므로 각 작업 공간에 대해 생성됩니다.
  • Egress 규칙은 인터넷(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

이 설정을 사용하여 각 작업 공간에 대해 네트워크 정책이 생성되는지 여부를 정의합니다.

기본 값은 true입니다.

network_policy.egress

이 설정을 사용하여 작업 공간에서 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

이 설정을 사용하여 각 워크스페이스 컨테이너에 대한 기본 요청 및 제한을 정의합니다.

devfile에서 정의한 리소스가 이 설정을 덮어씁니다.

default_resources_per_workspace_container의 경우, requests와 limits가 필요합니다.

가능한 CPU 및 메모리 값에 대한 자세한 내용은 Kubernetes의 리소스 단위를 참조하세요.

예제 구성:

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

max_resources_per_workspace

이 설정을 사용하여 각 워크스페이스에 대한 최대 요청 및 제한을 정의합니다.

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 에이전트의 최대 워크스페이스 수를 설정합니다.

에이전트의 워크스페이스 수가 정의된 workspaces_quota에 도달하면 새로운 워크스페이스를 생성할 수 없습니다.

  • workspaces_quota가 0으로 설정된 경우.

workspaces_quota가 비종료된 워크스페이스 수보다 작은 값으로 설정되면, 사용자의 워크스페이스는 자동으로 종료되지 않습니다.

기본값은 -1(제한 없음)이며, 가능 값은 -1 이상이어야 합니다.

예제 구성:

remote_development:
  workspaces_quota: 10

workspaces_per_user_quota

이 설정을 사용하여 사용자당 최대 워크스페이스 수를 설정합니다.

사용자의 워크스페이스 수가 정의된 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

이 설정을 사용하여 Kubernetes에서 사용자 네임스페이스 기능을 사용할지 여부를 지정합니다.

사용자 네임스페이스는 컨테이너 내부에서 실행되는 사용자와 호스트의 사용자를 분리합니다.

Kubernetes 1.30에서 이 기능은 베타 상태입니다.

기본값은 false입니다. 값을 true로 설정하기 전에 Kubernetes 클러스터가 사용자 네임스페이스를 지원하는지 확인하세요.

예제 구성:

remote_development:
  use_kubernetes_user_namespaces: true

use_kubernetes_user_namespaces에 대한 자세한 내용은 사용자 네임스페이스를 참조하세요.

default_runtime_class

이 설정을 사용하여 작업 공간에서 컨테이너를 실행하는 데 사용되는 컨테이너 런타임 구성을 선택합니다.

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

예제 구성:

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

유효한 값:

  • 253자 이하입니다.
  • 소문자, 숫자, -, 또는 .만 포함합니다.
  • 영숫자 문자로 시작합니다.
  • 영숫자 문자로 끝납니다.

default_runtime_class에 대한 자세한 내용은 런타임 클래스를 참조하세요.

allow_privilege_escalation

이 설정을 사용하여 프로세스가 부모 프로세스보다 더 많은 권한을 얻을 수 있는지 제어합니다.

이 설정은 no_new_privs 플래그가 컨테이너 프로세스에 설정되는지를 직접 제어합니다.

기본값은 false입니다. 이 값을 true로 설정할 수 있는 경우는 다음 중 하나입니다:

예제 구성:

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

allow_privilege_escalation에 대한 자세한 내용은 Pod 또는 컨테이너에 대한 보안 컨텍스트 구성을 참조하세요.

annotations

이 설정을 사용하여 Kubernetes 객체에 임의의 비식별 메타데이터를 첨부합니다.

기본값은 {}입니다.

예제 구성:

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

유효한 주석 키는 두 부분으로 구성된 문자열입니다:

  • 선택 사항. 접두사. 접두사는 253자 이하이어야 하며, 점으로 구분된 DNS 레이블을 포함해야 합니다. 접두사는 /로 끝나야 합니다.
  • 이름. 이름은 63자 이하이어야 하며, 영숫자, 대시(-), 밑줄(_), 및 점(.)만 포함할 수 있습니다. 이름은 영숫자 문자로 시작하고 끝나야 합니다.

kubernetes.io 및 k8s.io로 끝나는 접두사는 Kubernetes 핵심 구성 요소에 예약되어 있으므로 사용하지 않아야 합니다.

gitlab.com으로 끝나는 접두사도 예약되어 있습니다.

유효한 주석 값은 문자열입니다.

annotations에 대한 자세한 내용은 주석을 참조하세요.

labels

이 설정을 사용하여 Kubernetes 객체에 임의의 식별 메타데이터를 연결할 수 있습니다.

기본값은 {}입니다.

예제 구성:

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

라벨 키는 두 부분으로 이루어진 문자열입니다:

  • 선택 사항. 접두사. 접두사는 253자 이하 여야 하며, 마침표로 구분된 DNS 라벨을 포함해야 합니다. 접두사는 슬래시(/)로 끝나야 합니다.
  • 이름. 이름은 63자 이하 여야 하며, 알파벳과 숫자, 대시(-), 밑줄(_), 그리고 마침표(.)만 포함할 수 있습니다. 이름은 알파벳이나 숫자로 시작하고 끝나야 합니다.

kubernetes.io 및 k8s.io로 끝나는 접두사를 사용해서는 안 됩니다. 이들은 Kubernetes 핵심 구성 요소를 위해 예약되어 있습니다.

gitlab.com로 끝나는 접두사도 예약되어 있습니다.

유효한 라벨 값:

  • 63자 이하입니다. 값은 비워둘 수 있습니다.
  • 알파벳이나 숫자로 시작하고 끝나야 합니다.
  • 대시(-), 밑줄(_), 그리고 마침표(.)를 포함할 수 있습니다.

labels에 대한 자세한 정보는 Labels를 참조하세요.

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

user_access 모듈을 구성하여 GitLab 자격 증명을 사용해 연결된 Kubernetes 클러스터에 액세스할 수 있습니다.

이 모듈은 remote_development 모듈과 독립적으로 구성되고 실행됩니다.

user_access와 remote_development를 동일한 GitLab 에이전트에서 모두 구성할 때는 주의해야 합니다.

remote_development 클러스터는 사용자 자격 증명(예: 개인 액세스 토큰)을 Kubernetes 비밀로 관리합니다.

user_access의 잘못된 구성은 이 개인 데이터를 Kubernetes API를 통해 접근 가능하게 만들 수 있습니다.

user_access 구성에 대한 자세한 정보는 Configure Kubernetes access를 참조하세요.