23. 基础设施即代码设置

预计完成时间：60 分钟

可操作组件所有者：IAC

技能配置文件：部署工程师

Google Distributed Cloud (GDC) 网闸隔离环境中的基础设施即代码 (IaC) 包含两个系统：

  • Config Sync 是分布式云基础设施即代码 (IaC) 中用于管理集群级资源和共享服务的组件。

  • GitLab 托管一个 Git 代码库，该代码库用作 Config Sync 的可靠来源 (SoT)。目标集群是指 Config Sync 从代码库中的 SoT 管理的集群。

    • GitLab 包含一个代码审核系统，用于对政策和配置变更实施多方审批 (MPA)。

部署涉及以下两种可用区类型：

  • 锚定可用区：已成为全球控制平面一部分的可用区。第一个可用区是部署的锚定可用区。
  • 加入区域：加入全球控制平面的区域。

Config Sync 管理 root-admin 和组织管理员集群中的 Kubernetes 对象。它配置为从主 root-admin 集群中由 GitLab 提供的分布式云 IaC 代码库读取数据。

Distributed Cloud 在引导期间安装 IaC。运行以下手动步骤以完成 IaC 设置。

23.1. 设置第一个可用区 IaC

本部分包含在部署的第一个可用区中设置 IaC 的步骤。

23.2. 前提条件

  • 已启动根管理员集群。
  • 在 OC IT 的 Active Directory Federation Services (ADFS) 实例中创建一个 SAML 客户端，作为 GitLab 中的身份联合客户端。

23.3. 第 0 天访问 GitLab

  1. 在 https://iac.GDC_URL 中打开 GitLab Web 控制台。GDC_URL 是 CIQ 中指定的网域。

    # Use the root kubeconfig of the root admin cluster.
export ANCHOR_KUBECONFIG=ANCHOR_ZONE_KUBECONFIG
echo https://$(kubectl --kubeconfig $ANCHOR_KUBECONFIG get dnsregistrations \
     -n gitlab-system iac -o jsonpath='{.status.fqdn}')

  2. 使用第 0 天的用户名：ioadmin。

  3. 运行以下命令以获取密码：

    export IO_ADMIN_PWD=$(kubectl --kubeconfig $ANCHOR_KUBECONFIG \
  get secret gitlab-basic-users -n gitlab-system  \
  -o jsonpath='{.data.admin}' | base64 -d)

  4. 登录并依次前往菜单 > 项目 > 探索项目 gdch / iac，验证 iac Git 代码库是否已创建。

23.4. 创建管理员用户

  1. 在 ADFS 中创建专用管理员用户。您不得将它们用于非管理用途，并且它们必须具有“-ga”扩展名。请注意，您的初始管理员用户必须在此处使用与在 Active Directory 联合身份验证服务 (ADFS) 中使用的相同的 email。

  2. 运行以下命令以创建新用户：

    export NEW_USER_NAME=NEW_USER_NAME
export NEW_USER_USERNAME=NEW_USERNAME
export NEW_USER_PWD=NEW_USER_PWD
export NEW_USER_EMAIL=NEW_USER_EMAIL
export GDC_URL=GDC_URL
export TOKEN=$(curl -X POST https://iac.$GDC_URL/oauth/token \
    -d "grant_type=password&username=ioadmin&password=${IO_ADMIN_PWD}" \
    | jq -r '.access_token')
USERID=$(curl -X GET https://iac.$GDC_URL/api/v4/users \
    -d access_token=${TOKEN} -d username=ioadmin |\
    sed -E 's/.*"id":"?([^,"]*)"?.*/\1/')
curl -X POST https://iac.$GDC_URL/api/v4/users \
    -d username=${NEW_USER_USERNAME} -d password=${NEW_USER_PWD} -d name=${NEW_USER_NAME} \
    -d email=${NEW_USER_EMAIL} -d admin=true -d access_token=${TOKEN} 
curl -X POST https://iac.$GDC_URL/oauth/revoke \
    -d client_id=${USERID} -d "token=${TOKEN}"

23.5. 更新 GitLab 许可

GitLab 的许多功能都需要“Ultimate”许可才能正常运行。在此步骤中，您将使用网站自己的许可替换 GDC 随附的临时许可。如需了解完整详情，请参阅使用许可文件或密钥激活 GitLab EE。

您收到的网站许可密钥是一个 base64 编码的 ASCII 文本文件，扩展名为 .gitlab-license。您将使用此密钥激活 GitLab。

  1. 以 ioadmin 身份登录 GitLab Web 控制台。
  2. 在导航栏中，依次选择菜单和管理。
  3. 在导航菜单中，依次选择设置和常规。
  4. 在“添加许可”区域中，通过上传文件或输入密钥来添加许可。
  5. 选中“服务条款”复选框。
  6. 选择“添加许可”。

23.6. 设置 GitLab 代码库

ConfigSync 管理根管理员集群和组织管理员集群中的 Kubernetes 对象，并配置为从根管理员集群中由 GitLab 提供的 Distributed Cloud IaC 代码库读取数据。

我们需要设置初始 GitLab 文件夹，以便 Configsync 可以使用配置并将其应用于所需的 Kubernetes 集群。

infrastructure
│   └── zonal
│     └── zones
│         ├── ${anchor_zone_name}
│           ├── root-admin
│             ├── kustomization.yaml
│   └── global
│     └── orgs
│         ├── root
│           ├── kustomization.yaml

按照以下步骤创建初始文件结构：

  1. 通过“菜单 -> 探索项目”打开 iac 代码库。

  2. 打开“Web IDE”。

  3. 在 /infrastructure/zonal/zones/${anchor_zone_name}/root-admin/kustomization.yaml 中创建一个包含以下内容的文件：

    apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
metadata:
  name: root-admin-kustomization

  4. 点击“提交”按钮。

  5. 选择“提交到主分支”，然后确认。

23.7. 设置多方审批 (MPA)

您可以使用此部分将系统配置为强制要求对每个合并请求进行审批，以防止任何直接提交（不创建合并请求）到 iac 代码库的操作，从而强制执行多方审批 (MPA)。main

23.7.1. 在 GitLab 中启用合并请求审批

  1. 前往 iac 代码库。

  2. 使用 Web IDE 在根文件夹中创建一个名为 CODEOWNERS 的文件，并添加 Distributed Cloud 群组作为代码库所有者（作为第一步）：

    [Repository Owners]
* @gdch

    只有添加到 CODEOWNERS 文件中的用户才能批准 iac 仓库中的合并请求。此通用文件仅用于设置。如需详细了解精细的审批权限，请参阅 IAC-R0007。

  3. 点击提交按钮。

  4. 选择提交到主分支并确认。

  5. 如需向 CODEOWNERS 文件添加更多用户，请创建合并请求，以供 CODEOWNERS 中的现有用户批准。

23.8. 将 Active Directory Federation Services (ADFS) 连接到 GitLab

您可以使用 GitLab 的 Auth 框架，通过 SAML 客户端将 ADFS 连接到 GitLab。

如果您为身份提供商使用私有证书授权机构，则必须将其添加到 GitLab 实例。获取 ADFS CA 证书的 base64 版本，并将其放入 Secret 中。

cat <<EOF > adfs-ca-cert-secret.yaml
apiVersion: v1
data:
  tls.crt: ADFS_CA_CERTIFICATE_BASE64
kind: Secret
metadata:
  name: adfs-ca-cert-secret
  namespace: gitlab-system
type: Opaque
EOF

kubectl apply -f adfs-ca-cert-secret.yaml

23.8.1. 配置 ADFS 以进行 SAML 身份验证

在您使用 Helm 配置将 GitLab 连接到 ADFS 之前，ADFS 必须创建 SAML 客户端。在 Windows 实例中，按以下步骤操作：

  1. 以管理员身份运行 AD FS 管理应用。

    点击“以管理员身份运行”。

  2. 在 AD FS 目录中，点击 Relying Party Trust 文件夹。在操作面板中，点击添加信赖方信任。

  3. 系统会打开添加信赖方信任向导。在第一步中，选择声明感知，然后点击开始。

  4. 选择手动输入有关信赖方的数据，然后点击下一步。

  5. 在显示名称和备注字段中输入有关 ADFS 实例的一些可识别的信息。点击下一步。

  6. 点击下一步，跳过配置证书这一步。

  7. 点击启用对 SAML 2.0 WebSSO 协议的支持复选框。在信赖方 SAML 2.0 单点登录服务网址字段中，输入以下内容：https://iac.GDC_URL/users/auth/saml/callback。

    将 GDC_URL 替换为 GDC 中组织的网址。

  8. 为 IaC 命名，然后添加以下内容：

    https://iac.GDC_URL.sesame.street https://iac.GDC_URL.sesame.street/users/auth/saml/callback

  9. 依次点击配置标识符、选择访问权限控制政策和准备添加信任步骤中的下一步，以完成向导。

      # Replace GDC_URL with the cells URL, for example, bert.sesame.street
  https://iac.GDC_URL
  https://iac.GDC_URL/users/auth/saml/callback

  10. 显示内容会更新为新创建的信赖方信任。 右键点击相应项，然后选择修改声明颁发政策。

    包含“已启用”“类型”“标识符”和“访问权限控制政策”列的信赖方信任列表

  11. 点击添加规则按钮，在选择规则类型步骤中，选择声明规则模板，即将 LDAP 属性作为声明发送。点击下一步。

  12. 在配置声明规则步骤中，填写以下参数：

    1. 在声明规则名称字段中，输入 Email。
    2. 在属性存储列表中，选择 Active Directory。
    3. 在 LDAP 属性与出站声明类型的映射表中，在 LDAP 属性列中，选择或输入 E-Mail-Addresses。

    4. 在表格的出站声明类型列中，选择或输入 E-Mail Address。

    5. 完成向导。

  13. 点击添加规则按钮。

  14. 右键点击相应项，然后再次点击该项上的修改声明颁发政策。

  15. 在选择规则类型步骤中，选择转换传入声明的声明规则模板。点击下一步。

  16. 在配置声明规则步骤中，填写以下参数：

    1. 在声明规则名称字段中，输入 Transform email to nameid。
    2. 在传入声明类型字段中，选择或输入 E-Mail Address。
    3. 在出站声明类型字段中，选择或输入 Name ID。
    4. 在传出名称 ID 格式字段中，选择或输入 Persistent Identifier。

    5. 选择 Pass through all claim values 选项。

    6. 完成向导。

23.8.2. 向 GitLab 添加 SAML 配置

本部分介绍了向 Gitlab 添加 SAML 配置的步骤。

23.8.2.1. 在身份提供方中注册 GitLab

在 ADFS 中打开 SAML 客户端配置。GitLab 需要以下值才能与您的 IdP 集成：

  • assertion_customer_service_url - IdP 在对用户进行身份验证后会重定向到此网址。将其设置为 https://iac.GDC_URL/users/auth/saml/callback。

    将 GDC_URL 替换为 GDC 中组织的网址。

  • idp_cert_fingerprint - GitLab 使用此指纹来验证传入 SAML 消息的证书。如需在 ADFS 中查找 idp_cert_fingerprint，请按以下步骤操作：

    1. 以管理员身份运行应用 AD FS Management。

    2. 在目录树中，依次点击 AD FS > Service > Certificates，然后点击 Certificates 文件夹。您会在令牌签名部分看到证书。右键点击该证书，然后选择查看证书。

      ADFS 查看证书。

    3. 在证书窗口中，前往 Details 标签页。滚动浏览列表，直到看到名为 Thumbprint 的项。点击相应项，然后复制控制台中显示的内容。

      ADFS 获取指纹。

  • idp_sso_target_url - GitLab 在通过 SAML 进行身份验证时将以该端点为目标。如需在 ADFS 中查找 idp_sso_target_url，请按以下步骤操作：

    1. 以管理员身份运行 AD FS 管理应用。

    2. 在目录树中，依次点击 AD FS > Service > Endpoints 文件夹

      端点。

      ADFS 获取端点。

    3. 在中间的屏幕上，找到类型为 SAML 2.0/WS-Federation 的行。目标端点是您的 ADFS 网址和目标端点。例如，如果您的实例的域名为 https://ocit.gdch.test/，目标端点为 /adfs/ls，则 idp_sso_target_url 为 https://ocit.gdch.test/adfs/ls。

  • issuer - GitLab 用于标识自身的网址。使用 https://iac.GDC_URL。

    准备上述 IdP 值，并将它们写入名为 custom_saml.yaml 的自定义配置。修改此 YAML 文件，以获取 SAML 客户端所需的配置。

    cat <<EOF > custom_saml.yaml
name: saml
label: "ADFS SAML" # This is the label the login button will use.
args:
  assertion_consumer_service_url: "https://iac.GDC_URL/users/auth/saml/callback"
  idp_cert_fingerprint: "ADFS_IDP_CERT_FINGERPRINT"
  idp_sso_target_url: "ADFS_IDP_SSO_TARGET_URL"
  issuer: "https://iac.GDC_URL"

  # These parameters are necessary for ADFS to connect to GitLab. Do not change unless you are sure of what you're doing.
  name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
  attribute_statements: { email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }
EOF

    准备就绪后，将您的配置作为名为 custom-gitlab-saml-provider 的 Secret 应用。

    cat <<EOF > custom-gitlab-saml-provider.yaml
apiVersion: v1
data:
  provider: |
  $(cat custom_saml.yaml | base64 -w 0)
kind: Secret
metadata:
  name: custom-gitlab-saml-provider
  namespace: gitlab-system
  annotations:
    "helm.sh/hook": post-install,post-upgrade
    "helm.sh/hook-weight": "-5"
EOF
kubectl apply -f custom-gitlab-saml-provider.yaml

    您可以在创建 subcomponentoverride.yaml 时使用该 Secret。如需详细了解变量，请参阅 GitLab 文档。

    cat <<EOF > subcomponentoverride.yaml
apiVersion: lcm.private.gdc.goog/v1
kind: SubcomponentOverride
metadata:
  name: iac-gitlab
  namespace: root
spec:
  subComponentRef: "iac-gitlab"
  backend:
    operableParameters:
      omniauth:
        enabled: true
        providers:
        - secret: custom-gitlab-saml-provider
      certificates:
        customCAs:
        - secret: adfs-ca-cert-secret
        - configMap: trust-store-root-ext
EOF
kubectl apply -f subcomponentoverride.yaml

这会创建子组件替换项。如需验证配置是否已创建，请运行： sh kubectl get subcomponentoverride -n root

输出类似于以下内容：

NAME            AGE
iac-gitlab   1s

23.8.2.2. 初始化第一个登录的 SAML 用户

启用 SAML 会移除本地登录。用户必须完成紧急访问程序，才能重新启用本地登录并重新获得对 ioadmin 的访问权限。

在创建管理员用户中创建的第一个初始化的管理员将无需进一步修改即可作为管理员使用。他们不应有权访问项目。如需将用户添加到 Distributed Cloud 项目，请按照从 ADFS 吸引新用户中的步骤操作。

23.8.3. 验证 ADFS 连接

  1. 检查 GitLab webservice pod 的状态：

    kubectl --kubeconfig $KUBECONFIG get pod -l app=webservice,release=gitlab -n gitlab-system
    名称 准备就绪 STATUS 重新启动 年龄
    gitlab-webservice-default-5d99b4d7c7-9fmln 2/2 正在运行 0 4 分 6 秒
    gitlab-webservice-default-5d99b4d7c7-w99p4 2/2 正在运行 0 96s
    gitlab-webservice-default-7884d4c8b9-qjhtv 2/2 正在终止 0 18 小时

  2. 前往 https://iac.GDC_URL，验证您是否看到此界面，该界面显示了用于使用 SSO 登录的 ADFS SAML 按钮，并且没有直接登录用户和密码字段。

  3. 点击 ADFS SAML。验证系统是否要求您登录 ADFS。

  4. 登录 ADFS 后，验证您是否已登录 GitLab，以及现在是否能够与应用互动。

23.9. 锁定 Day 0 管理员账号

启用 SAML 后，停用网页界面的密码身份验证，然后重置 ioadmin 的密码，因为 API 访问权限会保留。

  1. 运行以下脚本：

      export KUBECONFIG=/root/release/root-admin/root-admin-kubeconfig
  export PWD=$(kubectl get secret gitlab-basic-users -n gitlab-system -o yaml \
      | grep admin | head -n1 | awk '{print $2}' | xargs echo | base64 -d)
  export TOKEN=$(curl -X POST https://iac.GDC_URL/oauth/token \
      -d "grant_type=password&username=ioadmin&password=${PWD}" \
      | jq -r '.access_token')
  curl -X PUT  https://iac.GDC_URL/api/v4/application/settings \
      -d access_token=${TOKEN} \
      -d password_authentication_enabled_for_web=false
  NEWPASS=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)
  USERID=$(curl -X GET https://iac.GDC_URL/api/v4/users \
      -d access_token=${TOKEN} -d username=ioadmin |\
      jq -r '.[] | .id')
  curl -X PUT  https://iac.GDC_URL/api/v4/users/${USERID} \
      -d access_token=${TOKEN} -d username=ioadmin \
      -d "password=${NEWPASS}" \
      -d user_id=${USERID}
  curl -X POST https://iac.GDC_URL/oauth/revoke \
      -d client_id=${USERID} -d "token=${TOKEN}"

  2. 将新密码存储在 Secret gitlab-basic-users 中。

      kubectl patch secret gitlab-basic-users -n gitlab-system --type=json -p'[{"op": "replace", "path": "/data/admin", "value": '"$(echo $NEWPASS | base64 -w0)"'}]'

使用 OI ADFS 中的账号登录。

23.10. 设置加入区域 IaC

本部分介绍了在部署的加入可用区中设置 IaC 的步骤。

23.11. 前提条件

在设置加入区域之前，您必须引导根管理员集群。

23.12. 配置 configsync 凭据

请按照以下步骤配置 Config Sync 凭据：

  1. 连接到锚定可用区的根管理员集群。

  2. 检索 Config Sync 凭据：

    kubectl --kubeconfig $ANCHOR_KUBECONFIG get secret -n config-management-system iac-creds-replica -o json |\
    jq 'del(.metadata.creationTimestamp, .metadata.resourceVersion, .metadata.uid)' > iac-creds-replica.json

  3. 复制 iac-creds-replica.json 文件。

  4. 连接到加入可用区的根管理员集群。

  5. 粘贴 iac-creds-replica.json 文件。

  6. 将 Config Sync 凭据应用于根管理员集群：

    # Use the root kubeconfig of the root admin cluster.
export JOINING_KUBECONFIG=JOINING_ZONE_KUBECONFIG
kubectl --kubeconfig $JOINING_KUBECONFIG apply -f iac-creds-replica.json

  7. 确保已配置 Config Sync 凭据：

    kubectl --kubeconfig $JOINING_KUBECONFIG get secret -n config-management-system \
    iac-creds-replica -o yaml

23.13. 配置 Config Sync 可靠来源

请按照以下步骤配置 Config Sync 可靠来源：

  1. 连接到锚定可用区的根管理员集群。

  2. 获取 GitLab 的 FQDN：

    export primaryDnsFQDN=$(kubectl --kubeconfig $ANCHOR_KUBECONFIG get DNSRegistration \
    -n gitlab-system iac -o jsonpath='{.status.fqdn}')

  3. 连接到加入可用区的根管理员集群。

  4. 创建 IaC SubcomponentOverride 文件：

    echo "apiVersion: lcm.private.gdc.goog/v1
kind: SubcomponentOverride
metadata:
    name: iac
    namespace: root
spec:
    subComponentRef: "iac-configsync"
    backend:
        operableParameters:
            primaryDnsFQDN: ${primaryDnsFQDN}" > iac-subcomponentoverride.yaml

  5. 配置 Config Sync 目标：

    kubectl --kubeconfig $JOINING_KUBECONFIG apply -f iac-subcomponentoverride.yaml

  6. 确保已配置 Config Sync Git 代码库：

    kubectl --kubeconfig $JOINING_KUBECONFIG get RootSync -n config-management-system \
    root-sync -o jsonpath='{.spec.git.repo}'

  7. 确保 Config Sync 在锚定区域和加入区域中均无错误。

    kubectl --kubeconfig $JOINING_KUBECONFIG get RootSync \
    -n config-management-system root-sync \
    -o jsonpath='{.status.source.errors[0].errorMessage}'

    1. 如果 root-sync 包含错误 KNV2004，则锚定可用区或加入可用区使用的目录路径在 iac 代码库中不存在。运行以下命令，找到所需目录：

      kubectl --kubeconfig $JOINING_KUBECONFIG get RootSync \
    -n config-management-system root-sync
    -o jsonpath='{.spec.git.dir}'

    2. 在 iac 代码库中创建上一个命令输出的路径，并添加一个通用的 kustomization.yaml 文件。然后合并到 main 分支。

    3. 重新运行原始 get RootSync 命令，以确保 Config Sync 没有错误。