워크스페이스 설정은 Kubernetes용 GitLab 에이전트가 Kubernetes 클러스터에서 원격 개발 환경을 관리하는 방식을 구성합니다. 이러한 설정은 다음을 제어합니다:

• 리소스 할당
• 보안
• 네트워킹
• 라이프사이클 관리

기본 워크스페이스 구성 설정#

기본 워크스페이스 구성을 설정하려면:

1. 구성 YAML 파일을 엽니다.

2. 다음 최소 필수 설정을 추가합니다:

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

3. 변경 사항을 커밋합니다.

워크스페이스 구성이 작동하지 않는 경우 워크스페이스 문제 해결을 참조하십시오.

구성 참조#

enabled#

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

• Kubernetes용 GitLab 에이전트가 GitLab 인스턴스와 통신할 수 있는지 여부.
• Kubernetes용 GitLab 에이전트로 워크스페이스를 만들 수 있는지 여부.

기본값은 false입니다.

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

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  enabled: true

dns_zone#

이 설정을 사용하여 워크스페이스를 사용할 수 있는 URL의 DNS 영역을 정의합니다.

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  dns_zone: "<workspaces.example.dev>"

gitlab_workspaces_proxy#

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

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  gitlab_workspaces_proxy:
    namespace: "<custom-gitlab-workspaces-proxy-namespace>"

network_policy#

이 설정을 사용하여 각 워크스페이스에 대한 네트워크 정책을 정의합니다. 이 설정은 워크스페이스에 대한 네트워크 트래픽을 제어합니다.

기본값은:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  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이므로 각 워크스페이스에 대한 네트워크 정책이 생성됩니다.
• 이그레스 규칙은 IP CIDR 범위 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16을 제외한 모든 인터넷 트래픽(0.0.0.0/0)을 허용합니다.

네트워크 정책의 동작은 Kubernetes 네트워크 플러그인에 따라 다릅니다. 자세한 내용은 Kubernetes 문서를 참조하십시오.

network_policy.enabled#

이 설정을 사용하여 각 워크스페이스에 대한 네트워크 정책을 생성할지 여부를 정의합니다. network_policy.enabled의 기본값은 true입니다.

network_policy.egress#

히스토리

• GitLab 16.7에서 도입.

이 설정을 사용하여 워크스페이스에서 이그레스 대상으로 허용할 IP CIDR 범위 목록을 정의합니다.

다음과 같은 경우 이그레스 규칙을 정의합니다:

• GitLab 인스턴스가 개인 IP 범위에 있는 경우.
• 워크스페이스가 개인 IP 범위의 클라우드 리소스에 액세스해야 하는 경우.

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

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  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 및 메모리 값에 대한 자세한 내용은 Kubernetes의 리소스 단위를 참조하십시오.

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  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 및 메모리 값에 대한 자세한 내용은 다음을 참조하십시오:

• Kubernetes의 리소스 단위
• 리소스 할당량

requests와 limits에 설정한 값을 초과하면 워크스페이스가 실패합니다.

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  max_resources_per_workspace:
    requests:
      cpu: "1"
      memory: "1Gi"
    limits:
      cpu: "2"
      memory: "2Gi"

정의하는 최대 리소스에는 프로젝트 저장소 클론과 같은 부트스트래핑 작업을 수행하는 init 컨테이너에 필요한 리소스가 포함되어야 합니다.

workspaces_quota#

히스토리

• GitLab 16.9에서 도입.

이 설정을 사용하여 Kubernetes용 GitLab 에이전트에 대한 최대 워크스페이스 수를 설정합니다.

다음 경우에는 에이전트에 대한 새 워크스페이스를 만들 수 없습니다:

• 에이전트의 워크스페이스 수가 정의된 workspaces_quota에 도달한 경우.
• workspaces_quota가 0으로 설정된 경우.

workspaces_quota가 에이전트의 종료되지 않은 워크스페이스 수보다 낮은 값으로 설정된 경우 에이전트의 워크스페이스는 자동으로 종료되지 않습니다.

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

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  workspaces_quota: 10

workspaces_per_user_quota#

히스토리

• GitLab 16.9에서 도입.

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

다음 경우에는 사용자에 대한 새 워크스페이스를 만들 수 없습니다:

• 사용자의 워크스페이스 수가 정의된 workspaces_per_user_quota에 도달한 경우.
• workspaces_per_user_quota가 0으로 설정된 경우.

workspaces_per_user_quota가 사용자의 종료되지 않은 워크스페이스 수보다 낮은 값으로 설정된 경우 사용자의 워크스페이스는 자동으로 종료되지 않습니다.

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

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  workspaces_per_user_quota: 3

use_kubernetes_user_namespaces#

히스토리

• GitLab 17.4에서 도입.

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

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

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

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  use_kubernetes_user_namespaces: true

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

default_runtime_class#

히스토리

• GitLab 17.4에서 도입.

이 설정을 사용하여 워크스페이스의 컨테이너를 실행하는 데 사용되는 컨테이너 런타임 구성을 선택합니다.

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

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  default_runtime_class: "example-runtime-class-name"

유효한 값:

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

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

allow_privilege_escalation#

히스토리

• GitLab 17.4에서 도입.

이 설정을 사용하여 프로세스가 상위 프로세스보다 더 많은 권한을 획득할 수 있는지 여부를 제어합니다.

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

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

• default_runtime_class가 비어 있지 않은 값으로 설정된 경우.
• use_kubernetes_user_namespaces가 true로 설정된 경우.

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  default_runtime_class: "example-runtime-class-name"
  allow_privilege_escalation: true

allow_privilege_escalation에 대한 자세한 내용은 파드 또는 컨테이너에 대한 보안 컨텍스트 구성을 참조하십시오.

image_pull_secrets#

히스토리

• GitLab 17.6에서 도입.

이 설정을 사용하여 워크스페이스가 개인 이미지를 가져오기 위해 필요한 kubernetes.io/dockercfg 또는 kubernetes.io/dockerconfigjson 유형의 기존 Kubernetes 시크릿을 지정합니다.

기본값은 []입니다.

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  image_pull_secrets:
    - name: "image-pull-secret-name"
      namespace: "image-pull-secret-namespace"

이 예시에서 image-pull-secret-namespace 네임스페이스의 image-pull-secret-name 시크릿이 워크스페이스의 네임스페이스에 동기화됩니다.

image_pull_secrets의 경우 name 및 namespace 속성이 필요합니다. 시크릿의 이름은 고유해야 합니다. shared_namespace가 설정된 경우 시크릿의 네임스페이스는 shared_namespace와 동일해야 합니다.

지정한 시크릿이 Kubernetes 클러스터에 존재하지 않으면 시크릿이 무시됩니다. 시크릿을 삭제하거나 업데이트하면 시크릿이 참조된 모든 워크스페이스의 네임스페이스에서 삭제되거나 업데이트됩니다.

annotations#

히스토리

• GitLab 17.4에서 도입.

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

기본값은 {}입니다.

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  annotations:
    "example.com/key": "value"

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

• 선택 사항. 접두사. 접두사는 253자 이하여야 하며 마침표로 구분된 DNS 레이블을 포함해야 합니다. 접두사는 슬래시(/)로 끝나야 합니다.
• 이름. 이름은 63자 이하여야 하며 영숫자 문자, 대시(-), 밑줄(_), 마침표(.)만 포함해야 합니다. 이름은 영숫자 문자로 시작하고 끝나야 합니다.

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

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

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

labels#

히스토리

• GitLab 17.4에서 도입.

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

기본값은 {}입니다.

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  labels:
    "example.com/key": "value"

레이블 키는 두 부분으로 구성된 문자열입니다:

• 선택 사항. 접두사. 접두사는 253자 이하여야 하며 마침표로 구분된 DNS 레이블을 포함해야 합니다. 접두사는 슬래시(/)로 끝나야 합니다.
• 이름. 이름은 63자 이하여야 하며 영숫자 문자, 대시(-), 밑줄(_), 마침표(.)만 포함해야 합니다. 이름은 영숫자 문자로 시작하고 끝나야 합니다.

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

유효한 레이블 값:

• 63자 이하를 포함합니다. 값은 비어 있을 수 있습니다.
• 영숫자 문자로 시작하고 끝납니다.
• 대시(-), 밑줄(_), 마침표(.)를 포함할 수 있습니다.

labels에 대한 자세한 내용은 레이블을 참조하십시오.

max_active_hours_before_stop#

히스토리

• GitLab 17.6에서 도입.

이 설정은 에이전트의 워크스페이스가 지정된 시간(시간 단위) 동안 활성 상태였던 후에 자동으로 중지합니다. 활성 상태는 중지되거나 종료되지 않은 모든 상태입니다.

이 설정의 타이머는 워크스페이스를 만들 때 시작되며 워크스페이스를 다시 시작할 때마다 초기화됩니다. 워크스페이스가 오류 또는 실패 상태에 있는 경우에도 적용됩니다.

기본값은 36(하루 반)입니다. 이는 사용자의 일반적인 근무 시간 동안 워크스페이스가 중지되는 것을 방지합니다.

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  max_active_hours_before_stop: 60

유효한 값:

• 정수입니다.
• 1 이상입니다.
• 8760(1년) 이하입니다.
• max_active_hours_before_stop + max_stopped_hours_before_termination이 8760 이하여야 합니다.

자동 중지는 매 시간마다 발생하는 전체 조정 시에만 트리거됩니다. 즉, 워크스페이스는 구성된 값보다 최대 1시간 더 활성 상태일 수 있습니다.

max_stopped_hours_before_termination#

히스토리

• GitLab 17.6에서 도입.

이 설정을 사용하여 에이전트의 워크스페이스가 지정된 시간(시간 단위) 동안 중지 상태였던 후에 자동으로 종료합니다.

기본값은 722(약 1개월)입니다.

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  max_stopped_hours_before_termination: 4332

유효한 값:

• 정수입니다.
• 1 이상입니다.
• 8760(1년) 이하입니다.
• max_active_hours_before_stop + max_stopped_hours_before_termination이 8760 이하여야 합니다.

자동 종료는 매 시간마다 발생하는 전체 조정 시에만 트리거됩니다. 즉, 워크스페이스는 구성된 값보다 최대 1시간 더 중지 상태일 수 있습니다.

shared_namespace#

히스토리

• GitLab 18.0에서 도입.

이 설정을 사용하여 모든 워크스페이스에 대한 공유 Kubernetes 네임스페이스를 지정합니다.

기본값은 ""이며, 이는 각 새 워크스페이스가 자체적인 별도의 Kubernetes 네임스페이스에 생성됨을 의미합니다.

값을 지정하면 모든 워크스페이스가 개별 네임스페이스 대신 해당 Kubernetes 네임스페이스에 존재합니다.

shared_namespace에 값을 설정하면 image_pull_secrets 및 max_resources_per_workspace에 허용되는 값에 제한이 생깁니다.

구성 예시:

remote_development:
  # NOTE: This is a partial example.
  # Some required fields are not included.
  shared_namespace: "example-shared-namespace"

유효한 값:

• 최대 63자를 포함합니다.
• 소문자 영숫자 문자 또는 '-'만 포함합니다.
• 영숫자 문자로 시작합니다.
• 영숫자 문자로 끝납니다.

Kubernetes 네임스페이스에 대한 자세한 내용은 네임스페이스를 참조하십시오.

완전한 예시 구성#

다음 구성은 완전한 예시 구성입니다. 구성 참조의 모든 사용 가능한 설정을 포함합니다:

remote_development:
  enabled: true
  dns_zone: workspaces.dev.test
  gitlab_workspaces_proxy:
    namespace: "gitlab-workspaces"

  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"

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

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

  workspaces_quota: 10
  workspaces_per_user_quota: 3

  use_kubernetes_user_namespaces: false
  default_runtime_class: "standard"
  allow_privilege_escalation: false

  image_pull_secrets:
    - name: "registry-secret"
      namespace: "default"

  annotations:
    environment: "production"
    team: "engineering"

  labels:
    app: "workspace"
    tier: "development"

  max_active_hours_before_stop: 60
  max_stopped_hours_before_termination: 4332
  shared_namespace: ""