23. 基礎架構即程式碼設定

預計完成時間：60 分鐘

可操作元件擁有者：IAC

技能設定檔：部署工程師

Google Distributed Cloud (GDC) 氣隙隔離中的基礎架構即程式碼 (IaC) 包含兩個系統：

  • Config Sync 是 Distributed Cloud 基礎架構即程式碼 (IaC) 中使用的元件，可管理叢集層級資源和共用服務。

  • GitLab 會代管 Git 存放區，做為 Config Sync 的可靠來源 (SoT)。目標叢集是指 Config Sync 從存放區中的 SoT 管理的叢集。

    • GitLab 內建程式碼審查系統，可針對政策和設定變更實作多方核准 (MPA)。

部署作業會涉及下列兩種區域類型：

  • 錨點可用區：已納入全球控制層的可用區。第一個可用區是部署作業的錨定可用區。
  • 加入區域：加入全域控制層的區域。

Config Sync 會管理 root-admin 和機構管理員叢集中的 Kubernetes 物件。這項服務已設定為從主要 root-admin叢集中的 GitLab 提供的 Distributed Cloud IaC 存放區讀取資料。

Distributed Cloud 會在啟動程序期間安裝 IaC。請執行下列手動步驟，完成 IaC 設定。

23.1. 設定第一個區域的 IaC

本節包含在第一個部署區域中設定 IaC 的步驟。

23.2. 必要條件

  • 已啟動根管理員叢集。
  • 在 OC IT 的 Active Directory 同盟服務 (ADFS) 執行個體中建立 SAML 用戶端，做為 GitLab 中的身分同盟用戶端。

23.3. 第 0 天存取 GitLab

  1. 前往 https://iac.GDC_URL 開啟 GitLab 網頁控制台。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. 登入並依序前往「Menu」>「Projects」>「Explore Projects gdch / iac」，確認已建立 iac Git 存放區。

23.4. 建立管理員使用者

  1. 在 ADFS 中建立專屬管理員使用者。您不得將這些檔案用於非管理用途，且檔案必須有「-ga」副檔名。請注意，初始管理員使用者必須在此處使用與 Active Directory Federation Services (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 網頁控制台。
  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. 從「Menu -> Explore Projects」開啟 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. 按一下「Commit」按鈕。

  5. 選取「Commit to the main branch」(提交至主要分支) 並確認。

23.7. 設定多方核准 (MPA)

您可以在這個部分設定系統，強制要求所有合併要求都必須經過核准，才能合併至 iac 存放區，並禁止直接將任何提交內容 (不建立合併要求) 提交至 main 分支版本，以強制執行多方核准 (MPA) 機制。

23.7.1. 在 GitLab 中啟用合併要求核准功能

  1. 前往 iac 存放區。

  2. 使用網頁 IDE 在根資料夾中建立名為 CODEOWNERS 的檔案，並將 Distributed Cloud 群組新增為存放區擁有者，做為第一步：

    [Repository Owners]
* @gdch

    只有新增至 CODEOWNERS 檔案的使用者，才能核准 iac 存放區中的合併要求。這個一般檔案僅供設定用途。如需更詳細的核准權限操作說明，請參閱 IAC-R0007。

  3. 按一下「Commit」按鈕。

  4. 選取「Commit to the main branch」(提交至主要分支)，然後確認。

  5. 如要在 CODEOWNERS 檔案中新增更多使用者，請建立合併要求，並由 CODEOWNERS 中的現有使用者核准。

23.8. 將 Active Directory 同盟服務 (ADFS) 連線至 GitLab

您可以使用 GitLab 的 Auth 架構，透過 SAML 用戶端將 ADFS 連線至 GitLab。

如果您使用私人憑證授權單位做為身分識別提供者，請務必將其新增至 GitLab 執行個體。取得 ADFS CA 憑證的 Base64 版本，並放入密鑰。

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. 「新增信賴憑證者信任精靈」隨即開啟。在第一個步驟中，選取「Claims aware」(宣告感知)，然後按一下「Start」(開始)。

  4. 選取「Enter data about the relying party manually」(手動輸入這個信賴憑證者的相關資料)，然後按一下「Next」(下一步)。

  5. 在「顯示名稱」和「附註」欄位中，輸入 ADFS 執行個體的可辨識資訊。按一下 [Next] (下一步)。

  6. 按一下「下一步」，略過「設定憑證」步驟。

  7. 勾選「啟用 SAML 2.0 WebSSO 通訊協定的支援」核取方塊。在「Relying party SAML 2.0 SSO service URL」欄位中，輸入下列內容： 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. 依序點選「下一步」，完成「設定 ID」、「選擇存取權控管政策」和「準備新增信任」步驟，即可完成精靈設定。

      # 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. 在項目上按一下滑鼠右鍵，然後再次點選項目上的「Edit Claim Issurance Policy」(編輯聲明核發政策)。

  15. 在「選擇規則類型」步驟中，選取「轉換傳入的宣告」的「宣告規則範本」。按一下「Next」(下一步)。

  16. 在「設定宣告規則」步驟中，填寫下列參數：

    1. 在「宣告規則名稱」欄位中輸入 Transform email to nameid。
    2. 在「Incoming claim type」(傳入著作權聲明類型) 欄位中，選取或輸入 E-Mail Address。
    3. 在「傳出宣告類型」欄位中，選取或輸入 Name ID。
    4. 在「Outgoing name ID format」(傳出名稱 ID 格式) 欄位中，選取或輸入 Persistent Identifier。

    5. 選取「傳遞所有聲明值」選項。

    6. 完成精靈。

23.8.2. 在 GitLab 中新增 SAML 設定

本節說明如何將 SAML 設定新增至 GitLab。

23.8.2.1. 在身分識別提供者中註冊 GitLab

在 ADFS 中開啟 SAML 用戶端設定。如要與 IdP 整合，GitLab 需要下列值：

  • 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」>「服務」 >「憑證」，然後按一下「憑證」資料夾。「Token-signing」部分會顯示憑證。在該憑證上按一下滑鼠右鍵，然後選取「檢視憑證」。

      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 的密鑰。

    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 時可以使用密鑰。如要進一步瞭解變數，請參閱 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
    名稱 已準備就緒 狀態 重新啟動 年齡
    gitlab-webservice-default-5d99b4d7c7-9fmln 2/2 執行中 0 4 分 6 秒
    gitlab-webservice-default-5d99b4d7c7-w99p4 2/2 執行中 0 96 秒
    gitlab-webservice-default-7884d4c8b9-qjhtv 2/2 終止中 0 18 小時

  2. 前往 https://iac.GDC_URL，確認您看到這個畫面，其中顯示「ADFS SAML」按鈕，可供您使用單一登入服務登入，且沒有直接登入的使用者名稱和密碼欄位。

  3. 按一下「ADFS SAML」。確認系統是否要求您登入 ADFS。

  4. 登入 ADFS 後，請確認您已登入 GitLab，且現在可以與應用程式互動。

23.9. 鎖定第 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. 將新密碼儲存在密碼 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 沒有錯誤。