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

教程：在 AWS 上设置工作区基础设施

本教程将指导您使用 OpenTofu（Terraform 的开源分支）通过基础设施即代码 (IaC) 在 AWS 上设置 GitLab 工作区基础设施。

开始之前

要完成本教程，您需要：

  • 一个 Amazon Web Services (AWS) 账户。
  • 一个用于您工作区环境的域名。

要设置 GitLab 工作区基础设施：

  1. Fork the repository
  2. Set up AWS credentials
  3. Prepare domain and certificates
  4. Create required keys
  5. Create a GitLab Agent for Kubernetes token
  6. Configure GitLab OAuth
  7. Configure CI/CD variables
  8. Update the GitLab agent for Kubernetes configuration
  9. Run the pipeline
  10. Configure DNS records
  11. Authorize the agent
  12. Create a workspace and verify setup

Fork the repository

首先，您需要创建基础设施设置仓库的副本，以便为您的环境进行配置。

无法从您个人命名空间中的项目创建工作区。请将仓库 fork 到顶级群组或子群组中。

要 fork 仓库：

  1. 访问 Workspaces Infrastructure Setup AWS 仓库。
  2. 创建仓库的 fork。更多信息，请参阅 Create a fork。

Set up AWS credentials

接下来，在 AWS 中设置必要的权限，以便正确配置基础设施。

要设置 AWS 凭证：

  1. 创建一个 IAM User 或 IAM Role。

  2. 分配以下权限：

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "ec2:*",
        "eks:*",
        "elasticloadbalancing:*",
        "autoscaling:*",
        "cloudwatch:*",
        "logs:*",
        "kms:DescribeKey",
        "kms:TagResource",
        "kms:UntagResource",
        "kms:ListResourceTags",
        "kms:CreateKey",
        "kms:CreateAlias",
        "kms:ListAliases",
        "kms:DeleteAlias",
        "iam:AddRoleToInstanceProfile",
        "iam:AttachRolePolicy",
        "iam:CreateInstanceProfile",
        "iam:CreateRole",
        "iam:CreateServiceLinkedRole",
        "iam:GetRole",
        "iam:ListAttachedRolePolicies",
        "iam:ListRolePolicies",
        "iam:ListRoles",
        "iam:PassRole",
        "iam:DetachRolePolicy",
        "iam:ListInstanceProfilesForRole",
        "iam:DeleteRole",
        "iam:CreateOpenIDConnectProvider",
        "iam:CreatePolicy",
        "iam:TagOpenIDConnectProvider",
        "iam:GetPolicy",
        "iam:GetPolicyVersion",
        "iam:GetOpenIDConnectProvider",
        "iam:DeleteOpenIDConnectProvider",
        "iam:ListPolicyVersions",
        "iam:DeletePolicy"
      ],
      "Resource": "*"
    }
  ]
}

  3. 为用户或角色 Create an access key。

  4. 保存您的访问密钥 ID 和秘密访问密钥。稍后在配置 CI/CD 变量时需要使用它们。

Prepare domain and certificates

要让您的工作区可访问，您需要一个域名和 TLS 证书来保护连接。

要准备您的域名和证书：

  1. 购买一个域名或使用现有域名作为您的工作区环境。
  2. 为以下内容创建 TLS 证书：
    • GitLab Workspaces Proxy Domain。例如，workspaces.example.dev。
    • GitLab Workspaces Proxy Wildcard Domain。例如，*.workspaces.example.dev。

更多信息，请参阅 Generate TLS certificates。

Create required keys

现在，您需要为身份验证和 SSH 连接创建安全密钥。

要创建所需的密钥：

  1. 生成一个由随机字母、数字和特殊字符组成的签名密钥。 例如，运行：

    openssl rand -base64 32

  2. 生成 SSH 主机密钥：

    ssh-keygen -f ssh-host-key -N '' -t rsa

Create a GitLab agent for Kubernetes token

GitLab Agent for Kubernetes 将您的 AWS Kubernetes 集群连接到 GitLab。

要为代理创建令牌：

  1. 转到您的群组。
  2. 在左侧边栏，选择 Search or go to 并找到您的项目。
  3. 选择 Operate > Kubernetes clusters。
  4. 选择 Connect a cluster。
  5. 为您的代理输入一个名称并保存以备后用。例如，gitlab-workspaces-agentk-eks。
  6. 选择 Create and register。
  7. 保存令牌和 KAS 地址以备后用。
  8. 选择 Continue。

Configure GitLab OAuth

接下来，设置 OAuth 身份验证以安全地访问工作区。

要配置 GitLab OAuth：

  1. 转到 User settings：

    1. 选择您的个人资料图片，然后选择 Preferences。

  2. 在左侧边栏，选择 Applications。

  3. 向下滚动到 OAuth applications。

  4. 选择 Add new application。

  5. 更新以下设置：

    • Name: GitLab Workspaces Proxy
    • Redirect URI: 例如，https://workspaces.example.dev/auth/callback。替换为您的用户定义的域名。
    • 选择 Confidential 复选框。
    • Scopes: api, read_user, openid, 和 profile。

  6. 选择 Save application。

  7. 保存 Application ID 和 Secret 以用于您的 CI/CD 变量。

  8. 选择 Continue。

Configure CI/CD variables

现在，您需要将必要的变量添加到您的 CI/CD 配置中，以便基础设施管道可以运行。

要配置 CI/CD 变量：

  1. 在左侧边栏，选择 Search or go to 并找到您的项目。

  2. 选择 Settings > CI/CD。

  3. 展开 Variables。

  4. 在 Project variables 部分，添加以下必需变量：

    Variable Value
    AWS_ACCESS_KEY_ID AWS 访问密钥 ID。
    AWS_SECRET_ACCESS_KEY AWS 秘密访问密钥。
    TF_VAR_agent_token GitLab Agent for Kubernetes 令牌。
    TF_VAR_kas_address GitLab Kubernetes Agent Server 地址。如果在 GitLab Self-Managed 实例上则需要。例如，wss://kas.gitlab.com。
    TF_VAR_workspaces_proxy_auth_client_id OAuth 应用程序客户端 ID。
    TF_VAR_workspaces_proxy_auth_client_secret OAuth 应用程序密钥。
    TF_VAR_workspaces_proxy_auth_redirect_uri OAuth 回调 URL。例如，https://workspaces.example.dev/auth/callback。
    TF_VAR_workspaces_proxy_auth_signing_key 您生成的签名密钥。
    TF_VAR_workspaces_proxy_domain 工作区代理的域名。
    TF_VAR_workspaces_proxy_domain_cert 代理域名的 TLS 证书。
    TF_VAR_workspaces_proxy_domain_key 代理域名的 TLS 密钥。
    TF_VAR_workspaces_proxy_ssh_host_key 您生成的 SSH 主机密钥。
    TF_VAR_workspaces_proxy_wildcard_domain 工作区的通配符域名。
    TF_VAR_workspaces_proxy_wildcard_domain_cert 通配符域名的 TLS 证书。
    TF_VAR_workspaces_proxy_wildcard_domain_key 通配符域名的 TLS 密钥。

  5. 可选。添加以下任何变量来自定义您的部署：

    Variable Value
    TF_VAR_region AWS 区域。
    TF_VAR_zones AWS 可用区。
    TF_VAR_name 资源名称前缀。
    TF_VAR_cluster_endpoint_public_access 集群端点的公共访问。
    TF_VAR_cluster_node_instance_type Kubernetes 节点的 EC2 实例类型。
    TF_VAR_cluster_node_count_min 工作节点的最小数量。
    TF_VAR_cluster_node_count_max 工作节点的最大数量。
    TF_VAR_cluster_node_count 工作节点的数量。
    TF_VAR_cluster_node_labels 要应用于集群节点的标签映射。
    TF_VAR_agent_namespace Agent 的 Kubernetes 命名空间。
    TF_VAR_workspaces_proxy_namespace 工作区代理的 Kubernetes 命名空间。
    TF_VAR_workspaces_proxy_ingress_class_name Ingress 类名称。
    TF_VAR_ingress_nginx_namespace Ingress-NGINX 的 Kubernetes 命名空间。

干得好！您已经为您的基础设施部署配置了所有必要的变量。

Update the GitLab agent for Kubernetes configuration

现在，您需要配置 GitLab Agent for Kubernetes 以支持工作区。

要更新代理配置：

  1. 在您的 fork 仓库中，打开 .gitlab/agents/gitlab-workspaces-agentk-eks/config.yaml 文件。

    包含 config.yaml 文件的目录必须与您在 Create a GitLab agent for Kubernetes token 步骤中创建的代理名称匹配。

  2. 使用以下必需字段更新文件：

    remote_development:
  enabled: true
  dns_zone: "workspaces.example.dev"  # 替换为您的域名

    更多配置选项，请参阅 Workspace settings。

  3. 提交并推送这些更改到您的仓库。

Run the pipeline

是时候部署您的基础设施了。您将运行 CI/CD 管道来在 AWS 中创建所有必要的资源。

要运行管道：

  1. 在您的 GitLab 项目中创建新管道：
    1. 在左侧边栏，选择 Build > Pipelines。
    2. 选择 New pipeline 并再次选择 New pipeline 以确认。
  2. 验证 plan 作业成功，然后手动触发 apply 作业。

当 OpenTofu 代码运行时，它会在 AWS 中创建这些资源：

  • 一个虚拟私有云 (VPC)。
  • 一个弹性 Kubernetes 服务 (EKS) 集群。
  • 一个 GitLab Agent for Kubernetes Helm 发布。
  • 一个 GitLab Workspaces Proxy Helm 发布。
  • 一个 Ingress NGINX Helm 发布。

太棒了！您的基础设施现在正在部署中。这可能需要一些时间才能完成。

Configure DNS records

现在您的基础设施已部署，您需要配置 DNS 记录以指向您的新环境。

要配置 DNS 记录：

  1. 从管道输出中获取 Ingress-NGINX 负载均衡器地址：

    kubectl get services -n ingress-nginx ingress-nginx-controller

  2. 创建将您的域名指向此地址的 DNS 记录。例如：

    • workspaces.example.dev → 负载均衡器 IP 地址
    • *.workspaces.example.dev → 负载均衡器 IP 地址

Authorize the agent

接下来，您将授权 GitLab Agent for Kubernetes 连接到您的 GitLab 实例。

要授权代理：

  1. 在左侧边栏，选择 Search or go to 并找到您的群组。
  2. 选择 Settings > Workspaces。
  3. 在 Group agents 部分，选择 All agents 选项卡。
  4. 从可用代理列表中，找到状态为 Blocked 的代理，然后选择 Allow。
  5. 在确认对话框中，选择 Allow agent。

Create a workspace and verify setup

最后，让我们通过创建一个测试工作区来确保一切正常工作。

要验证您的工作区设置：

  1. 按照 Create a workspace 中的步骤创建新工作区。
  2. 从您的项目中，选择 Code。
  3. 选择您的工作区名称。
  4. 通过打开 Web IDE、访问终端或更改项目文件来与工作区交互。

恭喜！您已成功在 AWS 上设置了 GitLab 工作区基础设施。您的用户现在可以为他们的项目创建开发工作区环境。

如果您遇到任何问题，请检查日志以获取更多详细信息，并参阅 Troubleshooting workspaces 获取指导。

相关主题