Help us learn about your current experience with the documentation. Take the survey.

教程：为 Kubernetes 设置 GitLab Agent

本教程将向您展示如何：

设置 GitLab Agent for Kubernetes 以便用户可以在项目中创建和管理工作空间。
设置 GitLab 工作空间代理，用于对集群中的工作空间进行身份验证和授权。

在配置支持工作空间的 GitLab Agent for Kubernetes 之前，您必须完成本教程中的设置步骤。完成教程后，使用 GitLab Agent for Kubernetes 配置来配置您的 Agent。

开始之前

在开始本教程之前，您必须具备：

对您的 GitLab 实例的管理员权限或您组的所有者角色。
一个正在运行的 Kubernetes 集群。
本地机器上的 helm 3.11.0 或更高版本和 kubectl。
能够在您的 DNS 提供商中配置通配符域名的权限。例如，工作空间访问需要 *.workspaces.example.dev。

在本教程中，使用以下层次结构：

%%{init: {'theme':'neutral'}}%%
graph TD;
    classDef active fill:lightgreen, stroke:#green, color:green, stroke-width:1px;

    topGroup[Top-level group]
    subGroup[Subgroup]
    workspaceProject[Workspace project]
    agentProject[Agent project]
    workspaceAgent[Workspace agent]

    topGroup --> subGroup

    subGroup --> workspaceProject
    subGroup --> agentProject
    agentProject -.- workspaceAgent

    class workspaceProject active;

安装 Ingress 控制器

在您的 Kubernetes 集群中安装您选择的 Ingress 控制器，以便将外部流量路由到您的工作空间。Ingress 控制器必须支持 WebSockets。以下示例使用 Ingress NGINX 控制器。

在您的 Kubernetes 集群中安装 Ingress 控制器。

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace gitlab-ingress-controller \
  --create-namespace

获取负载均衡器的外部 IP 地址。在更新 DNS 记录时需要此地址。
```
kubectl get svc -n gitlab-ingress-controller ingress-nginx-controller
```

安装 GitLab Agent for Kubernetes

在您的 Kubernetes 集群中安装 GitLab Agent for Kubernetes，以将您的集群连接到 GitLab：

完成为 Kubernetes 安装 Agent 中的安装选项之一。
记录您配置的 agentName。在为工作空间配置 Agent 时需要它。

安装 GitLab Agent Server for Kubernetes

GitLab Agent Server for Kubernetes (KAS) 是与您集群中的 Agent 通信的组件。

在 GitLab.com 上，Agent Server 默认可在 wss://kas.gitlab.com 访问。
在 GitLab 自托管版上，管理员必须设置 Kubernetes Agent Server (KAS)。之后它将在 wss://gitlab.example.com/-/kubernetes-agent/ 可用。

配置 GitLab Agent for Kubernetes

要在 Agent 项目中配置 remote_development 模块：

在左侧边栏，选择 搜索或跳转 并找到您的项目。
在您的项目中，创建一个 .gitlab/agents/<agentName>/config.yaml 文件。 agentName 是您在设置工作空间基础设施时配置的 Agent 名称。

在 config.yaml 中，使用以下配置进行工作空间设置：

remote_development:
  enabled: true
  dns_zone: "<workspaces.example.dev>" # 工作空间可用 URL 的 DNS 区域

有关完整的配置选项列表，请参阅工作空间配置参考。

GitLab Agent for Kubernetes 在一个项目中配置，但您可以在其他项目工作空间中使用它。每个项目不需要单独的 Agent。

在您在组中允许 Agent 之前，配置的 Agent 不可见。

在您的组中允许 GitLab Agent for Kubernetes

当您在组中允许一个 Agent 时，该组、其子组以及这些组中的所有项目都可以使用该 Agent。

只需要一个 Agent。您可以使用同一个 Agent 从组中的所有项目创建工作空间。

要在您的组中允许 GitLab Agent for Kubernetes 并使其对该组中的所有项目可用：

在左侧边栏，选择 搜索或跳转 并找到您的组。
选择设置 > 工作空间。
在 组 Agent 部分，选择 所有 Agent 标签页。
对于 GitLab Agent for Kubernetes，选择允许。
在确认对话框中，选择 允许 Agent。

授予工作空间权限

授予至少拥有工作空间和 Agent 项目 Developer 角色的用户创建和管理工作空间的必要权限。您可以：

生成 TLS 证书

工作空间访问需要通配符域名，因为每个工作空间都有自己的子域名。您必须为以下内容生成 TLS 证书：

gitlab-workspaces-proxy 监听的域名（GITLAB_WORKSPACES_PROXY_DOMAIN）。
工作空间可用的通配符域名（GITLAB_WORKSPACES_WILDCARD_DOMAIN）。

例如，如果您的基域是 workspaces.example.dev：

GITLAB_WORKSPACES_PROXY_DOMAIN 是 workspaces.example.dev。
GITLAB_WORKSPACES_WILDCARD_DOMAIN 是 *.workspaces.example.dev。
单个工作空间在类似 workspace-1.workspaces.example.dev 的 URL 上可用。

您可以从任何证书颁发机构生成证书。如果为您的 Kubernetes 集群配置了 cert-manager，您可以使用它来自动创建和续订 TLS 证书。

手动生成证书：

安装 Certbot 以启用 HTTPS：
```
brew install certbot
```

使用 ACME DNS 生成 Let’s Encrypt 证书，并在您的 DNS 提供商中创建 TXT 记录：

export EMAIL="YOUR_EMAIL@example.dev"
export GITLAB_WORKSPACES_PROXY_DOMAIN="workspaces.example.dev"
export GITLAB_WORKSPACES_WILDCARD_DOMAIN="*.workspaces.example.dev"

certbot -d "${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
  -m "${EMAIL}" \
  --config-dir ~/.certbot/config \
  --logs-dir ~/.certbot/logs \
  --work-dir ~/.certbot/work \
  --manual \
  --preferred-challenges dns certonly

certbot -d "${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
  -m "${EMAIL}" \
  --config-dir ~/.certbot/config \
  --logs-dir ~/.certbot/logs \
  --work-dir ~/.certbot/work \
  --manual \
  --preferred-challenges dns certonly

使用输出中的证书目录设置以下环境变量：

export WORKSPACES_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/fullchain.pem"
export WORKSPACES_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/privkey.pem"
export WILDCARD_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}-0001/fullchain.pem"
export WILDCARD_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}-0001/privkey.pem"

根据您的环境，certbot 命令可能会将证书和密钥保存在不同的路径上。要获取确切路径，请运行：

certbot certificates \
  --config-dir ~/.certbot/config \
  --logs-dir ~/.certbot/logs \
  --work-dir ~/.certbot/work

证书过期时您必须续订它们。例如，Let’s Encrypt 证书在三个月后过期。要自动续订证书，请参阅 cert-manager。

注册 GitLab OAuth 应用

要在您的 GitLab 实例上注册 OAuth 应用：

在 GitLab 中创建 OAuth 应用。您可以创建：
- 用户拥有的应用
- 组拥有的应用
- 来自管理区域的全局应用
将重定向 URI 设置为 https://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callback。
确保 Confidential 复选框被选中。默认情况下应该被选中。
如果您创建全局应用，还要选中 Trusted 复选框。
将范围设置为 api、read_user、openid 和 profile。

导出您的配置值：

export GITLAB_URL="https://gitlab.com"
export CLIENT_ID="your_application_id"
export CLIENT_SECRET="your_application_secret"
export REDIRECT_URI="https://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callback"
export SIGNING_KEY="make_up_a_random_key_consisting_of_letters_numbers_and_special_chars"

安全地存储客户端 ID 和生成的密钥，例如在 1Password 中。

生成 SSH 主机密钥

生成 RSA 密钥：

ssh-keygen -f ssh-host-key -N '' -t rsa
export SSH_HOST_KEY=$(pwd)/ssh-host-key

或者，您也可以生成 ECDSA 密钥。

创建 Kubernetes 密钥

创建 Kubernetes 密钥：

kubectl create namespace gitlab-workspaces

kubectl create secret generic gitlab-workspaces-proxy-config \
  --namespace="gitlab-workspaces" \
  --from-literal="auth.client_id=${CLIENT_ID}" \
  --from-literal="auth.client_secret=${CLIENT_SECRET}" \
  --from-literal="auth.host=${GITLAB_URL}" \
  --from-literal="auth.redirect_uri=${REDIRECT_URI}" \
  --from-literal="auth.signing_key=${SIGNING_KEY}" \
  --from-literal="ssh.host_key=$(cat ${SSH_HOST_KEY})"

kubectl create secret tls gitlab-workspace-proxy-tls \
  --namespace="gitlab-workspaces" \
  --cert="${WORKSPACES_DOMAIN_CERT}" \
  --key="${WORKSPACES_DOMAIN_KEY}"

kubectl create secret tls gitlab-workspace-proxy-wildcard-tls \
  --namespace="gitlab-workspaces" \
  --cert="${WILDCARD_DOMAIN_CERT}" \
  --key="${WILDCARD_DOMAIN_KEY}"

安装 GitLab 工作空间代理 Helm chart

安装 GitLab 工作空间代理的 Helm chart：

添加 helm 仓库：

helm repo add gitlab-workspaces-proxy \
  https://gitlab.com/api/v4/projects/gitlab-org%2fworkspaces%2fgitlab-workspaces-proxy/packages/helm/devel

对于 Helm chart 0.1.13 及更早版本，使用以下命令：

helm repo add gitlab-workspaces-proxy \
  https://gitlab.com/api/v4/projects/gitlab-org%2fremote-development%2fgitlab-workspaces-proxy/packages/helm/devel

安装和升级 chart：

Chart 版本 0.1.20 及更早版本包含一个安全漏洞，即在通配符域上设置 cookie。您应该升级到 chart 版本 0.1.21 或更高版本。有关更多信息，请参阅漏洞修复。

在 chart 版本 0.1.16 之前，Helm chart 安装会自动创建密钥。如果您从早于 0.1.16 的版本升级，在运行升级命令之前创建所需的 Kubernetes 密钥。

helm repo update

helm upgrade --install gitlab-workspaces-proxy \
  gitlab-workspaces-proxy/gitlab-workspaces-proxy \
  --version=0.1.21 \
  --namespace="gitlab-workspaces" \
  --set="ingress.enabled=true" \
  --set="ingress.hosts[0].host=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
  --set="ingress.hosts[0].paths[0].path=/" \
  --set="ingress.hosts[0].paths[0].pathType=ImplementationSpecific" \
  --set="ingress.hosts[1].host=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
  --set="ingress.hosts[1].paths[0].path=/" \
  --set="ingress.hosts[1].paths[0].pathType=ImplementationSpecific" \
  --set="ingress.tls[0].hosts[0]=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
  --set="ingress.tls[0].secretName=gitlab-workspace-proxy-tls" \
  --set="ingress.tls[1].hosts[0]=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
  --set="ingress.tls[1].secretName=gitlab-workspace-proxy-wildcard-tls" \
  --set="ingress.className=nginx"

如果您使用不同的 Ingress 类，请修改 ingress.className 参数。

验证您的设置

验证 gitlab-workspaces 命名空间的 Ingress 配置：
```
kubectl -n gitlab-workspaces get ingress
```
验证 pod 是否正在运行：
```
kubectl -n gitlab-workspaces get pods
```

更新您的 DNS 记录

更新您的 DNS 记录：

将 ${GITLAB_WORKSPACES_PROXY_DOMAIN} 和 ${GITLAB_WORKSPACES_WILDCARD_DOMAIN} 指向 Ingress 控制器暴露的负载均衡器外部 IP 地址。
检查 gitlab-workspaces-proxy 是否可访问：
```
curl --verbose --location ${GITLAB_WORKSPACES_PROXY_DOMAIN}
```
在您创建工作空间之前，此命令会返回 400 Bad Request 错误。
从另一个终端，检查代理日志：
```
kubectl -n gitlab-workspaces logs -f -l app.kubernetes.io/name=gitlab-workspaces-proxy
```
在您创建工作空间之前，此命令会返回 could not find upstream workspace upstream not found 错误。

更新 GitLab Agent for Kubernetes 配置

如果您将代理的 Helm chart 部署到 gitlab-workspaces 以外的命名空间，请更新您的 GitLab Agent for Kubernetes 配置：

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