工作区设置

工作区设置配置 GitLab agent for Kubernetes 如何管理 Kubernetes 集群中的远程开发环境。这些设置控制：

• 资源分配
• 安全
• 网络
• 生命周期管理

设置基本工作区配置

要设置基本工作区配置：

1. 打开你的配置 YAML 文件。

2. 添加这些必需的最小设置：

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

3. 提交更改。

如果你的工作区配置不工作，请参阅 排查工作区问题。

配置参考

enabled

使用此设置来定义是否：

• GitLab agent for Kubernetes 可以与 GitLab 实例通信。
• 你可以使用 GitLab agent for Kubernetes 创建工作区。

默认值为 false。

要在 agent 配置中启用远程开发，将 enabled 设置为 true：

remote_development:
  # 注意：这是一个部分示例。
  # 一些必需字段未包含。
  enabled: true

dns_zone

使用此设置来定义工作区可用的 URL 的 DNS zone。

示例配置：

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

使用此设置来定义允许作为工作区出站目的地的 IP CIDR 范围列表。

在以下情况下定义出站规则：

• 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

使用此设置来定义每个工作区容器的默认 requests 和 limits 的 CPU 和 memory。 你在 devfile 中定义的任何资源都会覆盖此设置。

对于 default_resources_per_workspace_container，requests 和 limits 是必需的。 有关可能的 CPU 和 memory 值的更多信息，请参阅 Kubernetes 中的资源单位。

示例配置：

remote_development:
  # 注意：这是一个部分示例。
  # 一些必需字段未包含。
  default_resources_per_workspace_container:
    requests:
      cpu: "0.5"
      memory: "512Mi"
    limits:
      cpu: "1"
      memory: "1Gi"

max_resources_per_workspace

使用此设置来定义每个工作区的最大 requests 和 limits 的 CPU 和 memory。

对于 max_resources_per_workspace，requests 和 limits 是必需的。 有关可能的 CPU 和 memory 值的更多信息，请参阅：

• Kubernetes 中的资源单位
• 资源配额

当工作区超过你为 requests 和 limits 设置的值时，工作区将失败。

示例配置：

remote_development:
  # 注意：这是一个部分示例。
  # 一些必需字段未包含。
  max_resources_per_workspace:
    requests:
      cpu: "1"
      memory: "1Gi"
    limits:
      cpu: "2"
      memory: "2Gi"

你定义的最大资源必须包括 init 容器执行诸如克隆项目存储库等引导操作所需的任何资源。

workspaces_quota

使用此设置来设置 GitLab agent for Kubernetes 的最大工作区数量。

当以下情况发生时，你无法为 agent 创建新工作区：

• agent 的工作区数量已达到定义的 workspaces_quota。
• workspaces_quota 设置为 0。

如果 workspaces_quota 设置为低于 agent 的非终止工作区数量的值，agent 的工作区不会自动终止。

默认值为 -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 中使用用户命名空间功能。

用户命名空间 将容器内运行的用户与主机上的用户隔离开。

默认值为 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：

• 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 或容器配置安全上下文。

image_pull_secrets

使用此设置来指定工作区拉取私有镜像所需的类型为 kubernetes.io/dockercfg 或 kubernetes.io/dockerconfigjson 的现有 Kubernetes secrets。

默认值为 []。

示例配置：

remote_development:
  # 注意：这是一个部分示例。
  # 一些必需字段未包含。
  image_pull_secrets:
    - name: "image-pull-secret-name"
      namespace: "image-pull-secret-namespace"

在此示例中，来自命名空间 image-pull-secret-namespace 的 secret image-pull-secret-name 被同步到工作区的命名空间。

对于 image_pull_secrets，name 和 namespace 属性是必需的。secret 名称必须是唯一的。 如果设置了 shared_namespace，secret 的命名空间必须与 shared_namespace 相同。

如果你指定的 secret 在 Kubernetes 集群中不存在，则该 secret 会被忽略。 当你删除或更新 secret 时，secret 会在引用该 secret 的所有工作区命名空间中被删除或更新。

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 的更多信息，请参阅 标签。

max_active_hours_before_stop

此设置在工作区处于活动状态达到指定小时数后自动停止 agent 的工作区。活动状态是任何非停止或非终止状态。

此设置的计时器在你创建工作区时启动，并在每次你重启工作区时重置。 即使工作区处于错误或失败状态，此设置也适用。

默认值为 36，即一天半。这可以避免在工作区在用户的典型工作时间期间停止。

示例配置：

remote_development:
  # 注意：这是一个部分示例。
  # 一些必需字段未包含。
  max_active_hours_before_stop: 60

有效值：

• 是一个整数。
• 大于或等于 1。
• 小于或等于 8760（一年）。
• max_active_hours_before_stop + max_stopped_hours_before_termination 必须小于或等于 8760。

自动停止仅在完全协调时触发，每小时发生一次。 这意味着工作区可能会比配置值多活动长达一小时。

max_stopped_hours_before_termination

使用此设置在工作区处于停止状态达到指定小时数后自动终止 agent 的工作区。

默认值为 722，大约一个月。

示例配置：

remote_development:
  # 注意：这是一个部分示例。
  # 一些必需字段未包含。
  max_stopped_hours_before_termination: 4332

有效值：

• 是一个整数。
• 大于或等于 1。
• 小于或等于 8760（一年）。
• max_active_hours_before_stop + max_stopped_hours_before_termination 必须小于或等于 8760。

自动终止仅在完全协调时触发，每小时发生一次。 这意味着工作区可能会比配置值多停止长达一小时。

shared_namespace

使用此设置为所有工作区指定一个共享的 Kubernetes 命名空间。

默认值为 ""，这会在其自己的独立 Kubernetes 命名空间中创建每个新工作区。

当你指定一个值时，所有工作区都存在于该 Kubernetes 命名空间中，而不是单独的命名空间。

为 shared_namespace 设置值会对 image_pull_secrets 和 max_resources_per_workspace 的可接受值施加限制。

示例配置：

remote_development:
  # 注意：这是一个部分示例。
  # 一些必需字段未包含。
  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: ""