使用 kubectl 手動安裝 Config Sync (不建議)

本頁面說明如何使用 kubectl 指令安裝 Config Sync。

事前準備

本節說明使用 kubectl 安裝 Config Sync 前必須滿足的必要條件。

準備本機環境

安裝 Config Sync 前,請先完成下列工作,準備好本機環境:

  • 建立或存取單一可靠資料來源

  • 安裝並初始化 Google Cloud CLI,其中提供這些操作說明中使用的 gcloudkubectlnomos 指令。如果使用 Cloud Shell,Google Cloud CLI 會預先安裝。

  • kubectl 不會由 Google Cloud CLI 預設安裝。如要安裝 kubectl,請使用下列指令:

    gcloud components install kubectl
    
  • 使用 gcloud auth login 指令向 Google Cloud 進行驗證,以便下載 Config Sync 的元件。

準備您的叢集

建立或存取符合 Config Sync 需求的 Google Kubernetes Engine (GKE) Enterprise 版叢集。

準備權限

Google Cloud 安裝 Config Sync 的使用者必須具備 IAM 權限,才能在叢集中建立新角色。如有需要,請使用下列指令授予這些角色:

gcloud container clusters get-credentials CLUSTER_NAME

kubectl create clusterrolebinding cluster-admin-binding \
    --clusterrole cluster-admin --user USER_ACCOUNT

更改下列內容:

  • CLUSTER_NAME:叢集名稱
  • USER_ACCOUNT:您 Google Cloud 帳戶的電子郵件地址

視您在本機系統上設定 Google Cloud CLI 的方式而定,您可能需要加入 --project--zone 欄位。

如果您需要使用 gcpserviceaccount 做為驗證類型,授予 Config Sync 對 OCI 的存取權,則必須具備 iam.serviceAccounts.setIamPolicy 權限,才能建立政策繫結。如要取得這項權限,請授予「服務帳戶管理員」roles/iam.serviceAccountAdmin身分與存取權管理角色。您或許還可透過自訂角色或其他預先定義的角色取得這項權限。

如要進一步瞭解如何授予角色,請參閱管理存取權

註冊叢集

如要將叢集登錄至 Config Sync,請完成下列步驟:

  1. 部署 Config Sync
  2. 授予 Config Sync 對下列項目的唯讀存取權:
  3. 設定 Config Sync

部署 Config Sync

確認符合所有先決條件後,即可下載並套用 YAML 資訊清單,部署 Config Sync。

1.20.0 以上版本

  1. 使用下列指令下載最新版本的 Config Sync 資訊清單。如要下載特定版本,請參閱「下載」一文。

    gcloud storage cp gs://config-management-release/released/latest/config-sync.tar.gz config-sync.tar.gz
    
  2. 解壓縮封存檔:

    tar -xzvf config-sync.tar.gz
  3. 在先前步驟中解壓縮的封存檔中,按照提供的 README 中的操作說明編輯自訂項目。

  4. 如要更新 Config Sync 安裝作業,請套用按照 README 指示建構的已算繪資訊清單:

    kubectl apply -f CONFIG_SYNC_MANIFEST
    

    CONFIG_SYNC_MANIFEST 替換為已算繪資訊清單的名稱。

  5. 將所有用戶端的 nomos 指令替換為新版本。這項變更可確保 nomos 指令一律能取得所有已註冊叢集的狀態,並驗證這些叢集的設定。

1.19.2 以下版本

  1. 下載新版本的 Config Sync 資訊清單和 nomos 指令。

  2. 套用 Config Sync 資訊清單:

    kubectl apply -f config-management-operator.yaml
    
  3. 建立名為 config-management.yaml 的檔案,然後將下列 YAML 檔案複製到該檔案中:

    # config-management.yaml
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      # The `enableMultiRepo` field is set to true to enable RootSync and RepoSync APIs.
      enableMultiRepo: true
      preventDrift: PREVENT_DRIFT
    

    更改下列內容:

    • PREVENT_DRIFT:如果設為 true,系統會啟用 Config Sync 許可控制 Webhook,防止發生差異,方法是拒絕將衝突變更推送至實際叢集。預設為 false。無論這個欄位的值為何,Config Sync 一律會修正差異。
  4. 套用變更:

    kubectl apply -f config-management.yaml
    
  5. 將所有用戶端的 nomos 指令替換為新版本。這項變更可確保 nomos 指令一律能取得所有已註冊叢集的狀態,並驗證這些叢集的設定。

如果 Config Sync 發生問題 (並非 YAML 或 JSON 語法錯誤),導致這項作業失敗,物件可能會在叢集中例項化,但可能無法正常運作。在這種情況下,您可以使用 nomos status 指令檢查物件是否有錯誤。

如果安裝作業順利完成,狀態會顯示為「PENDING」或「SYNCED」。

無效的安裝作業狀態為 NOT CONFIGURED,並列出下列其中一個錯誤:

  • missing git-creds Secret
  • git-creds Secret is missing the key specified by secretType

如要修正問題,請修正設定錯誤。視錯誤類型而定,您可能需要將 Config Sync 資訊清單重新套用至叢集。

如果問題是您忘記建立 git-creds Secret,Config Sync 會在您建立 Secret 後立即偵測到,您不需要重新套用設定。

授予 Config Sync 唯讀存取權

如果您將設定儲存在 Git 中,請務必授予 Config Sync Git 唯讀權限。如果將設定儲存為 OCI 映像檔,您必須授予 Config Sync OCI 的唯讀權限。如果將設定儲存在 Helm 中,則必須授予 Config Sync Helm 的唯讀存取權

授予 Config Sync 的 Git 唯讀存取權

Config Sync 需要 Git 存放區的唯讀權限,才能讀取提交至存放區的設定,並將這些設定套用至叢集。

如果存放區不需要驗證唯讀存取權,您可以繼續設定 Config Sync,並使用 none 做為驗證類型。舉例來說,如果您可以在不登入的情況下,使用網頁介面瀏覽存放區,或是使用 git clone 在本機建立存放區的副本,而不需提供憑證或使用已儲存的憑證,就不需要驗證。在這種情況下,您不需要建立 Secret。

不過,由於大多數使用者對存放區的讀取存取權受到限制,因此需要建立憑證。如果需要憑證,系統會將憑證儲存在每個已註冊叢集的「Secret」中 (除非您使用 Google 服務帳戶)。git-creds密鑰必須命名為 git-creds,因為這是固定值。

Config Sync 支援下列驗證機制:

  • 安全殼層金鑰組 (ssh)
  • Cookiefile (cookiefile)
  • 權杖 (token)
  • Google 服務帳戶 (gcpserviceaccount)
  • Compute Engine 預設服務帳戶 (gcenode)
  • GitHub 應用程式 (githubapp)

請選擇存放區支援的機制。一般而言,我們建議使用 SSH 金鑰組。GitHub 和 Bitbucket 都支援使用 SSH 金鑰組。不過,如果您使用 Cloud Source Repositories 中的存放區,建議改用 Google 服務帳戶,因為程序較簡單。如果貴機構代管存放區,但您不知道支援哪些驗證方法,請與管理員聯絡。

如要使用 Cloud Source Repositories 中的存放區做為 Config Sync 存放區,請完成下列步驟來擷取 Cloud Source Repositories 網址:

  1. 列出所有存放區:

    gcloud source repos list
    
  2. 從輸出內容中,複製要使用的存放區網址。 例如:

    REPO_NAME  PROJECT_ID  URL
    my-repo    my-project  https://source.developers.google.com/p/my-project/r/my-repo-csr
    

    您需要在下一節中設定 Config Sync 時使用這個網址。如果您使用Google Cloud 控制台設定 Config Sync,請在「URL」欄位中新增網址。如果您使用 Google Cloud CLI 設定 Config Sync,請將網址新增至設定檔的 syncRepo 欄位。

安全殼層金鑰組

SSH 金鑰組包含兩個檔案:一個公開金鑰和一個私密金鑰。公開金鑰的副檔名通常是 .pub

如要使用安全殼層金鑰組,請完成下列步驟:

  1. 建立 SSH 金鑰組,允許 Config Sync 對您的 Git 存放區進行驗證。如果您必須對存放區進行驗證才能複製或讀取存放區,此為必要步驟。如果安全性管理員會提供金鑰組給您,請略過這個步驟。您可以將單一金鑰組用於所有叢集,或是針對每個叢集使用專屬的金鑰組,全視您的安全性與法規遵循要求而定。

    以下指令會建立 4096 位元的 RSA 金鑰。我們建議您不要使用低於 4096 位元的值:

    ssh-keygen -t rsa -b 4096 \
    -C "GIT_REPOSITORY_USERNAME" \
    -N '' \
    -f /path/to/KEYPAIR_FILENAME
    

    更改下列內容:

    • GIT_REPOSITORY_USERNAME:您希望 Config Sync 用來向存放區驗證身分的使用者名稱
    • /path/to/KEYPAIR_FILENAME:金鑰組的路徑

    如果您使用第三方 Git 存放區主機 (例如 GitHub),或是想搭配 Cloud Source Repositories 使用服務帳戶,建議您使用不同的帳戶。

  2. 設定存放區來辨識您剛才建立的「公開金鑰」。請參閱您 Git 主機供應商的說明文件。為方便起見,以下提供幾個熱門 Git 主機供應商的操作說明:

  3. 將「私密金鑰」新增到叢集的新 Secret 中:

    kubectl create ns config-management-system && \
    kubectl create secret generic git-creds \
     --namespace=config-management-system \
     --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME
    

    /path/to/KEYPAIR_PRIVATE_KEY_FILENAME 替換為私密金鑰的名稱 (沒有 .pub 後置字串者)。

  4. (建議) 如要使用 SSH 驗證設定已知主機檢查,請將已知主機金鑰新增至 git_creds 密鑰的 data.known_hosts 欄位。如要停用 known_hosts 檢查,可以從密鑰中移除 known_hosts 欄位。如要新增已知主機金鑰,請執行下列指令:

    kubectl edit secret git-creds \
     --namespace=config-management-system
    

    然後在 data 下方新增已知主機項目:

    known_hosts: KNOWN_HOSTS_KEY
    
  5. 將私密金鑰從本機磁碟中刪除,或是保護該金鑰。

  6. 設定 Config Sync 並新增 Git 存放區的網址時,請使用 SSH 通訊協定。如果您使用 Cloud Source Repositories 中的存放區,輸入網址時必須採用下列格式:

    ssh://EMAIL@source.developers.google.com:2022/p/PROJECT_ID/r/REPO_NAME
    

    更改下列內容:

    • EMAIL:你的 Google Cloud 使用者名稱
    • PROJECT_ID:存放區所在專案的 ID Google Cloud
    • REPO_NAME:存放區名稱

Cookiefile

取得 cookiefile 的程序取決於您存放區的設定。如需範例,請參閱 Cloud Source Repositories 說明文件中的「產生靜態憑證」。憑證通常儲存在主目錄的 .gitcookies 檔案中,或是由安全性管理員提供給您。

如要使用 cookiefile,請完成下列步驟:

  1. 建立並取得 cookiefile 後,請將其新增至叢集中的新 Secret。

    如果您未使用 HTTPS Proxy,請使用下列指令建立 Secret:

    kubectl create ns config-management-system && \
    kubectl create secret generic git-creds \
     --namespace=config-management-system \
     --from-file=cookie_file=/path/to/COOKIEFILE
    

    如需使用 HTTPS Proxy,請執行下列指令,將 Proxy 新增至 Secret,並一併新增 cookiefile

    kubectl create ns config-management-system && \
    kubectl create secret generic git-creds \
     --namespace=config-management-system \
     --from-file=cookie_file=/path/to/COOKIEFILE \
     --from-literal=https_proxy=HTTPS_PROXY_URL
    

    更改下列內容:

    • /path/to/COOKIEFILE:適當的路徑和檔案名稱
    • HTTPS_PROXY_URL:與 Git 存放區通訊時使用的 HTTPS Proxy 網址
  2. 如果本機仍須使用 cookiefile,請妥善保管,否則請將其刪除。

權杖

如果貴機構不允許使用安全殼層金鑰,可以選擇使用權杖。有了 Config Sync,您就能使用 GitHub 的個人存取權杖 (PAT)、GitLab 的 PAT 或部署金鑰,或是 Bitbucket 的應用程式密碼做為權杖。

如要使用權杖建立 Secret,請完成下列步驟:

  1. 使用 GitHub、GitLab 或 Bitbucket 建立權杖:

  2. 建立並取得權杖後,請將權杖新增至叢集中的新 Secret。

    如果您未使用 HTTPS Proxy,請使用下列指令建立 Secret:

    kubectl create ns config-management-system && \
    kubectl create secret generic git-creds \
      --namespace="config-management-system" \
      --from-literal=username=USERNAME \
      --from-literal=token=TOKEN
    

    更改下列內容:

    • USERNAME:您要使用的使用者名稱。
    • TOKEN:您在上一個步驟中建立的權杖。

    如需使用 HTTPS Proxy,請執行下列指令,將 Proxy 連同 usernametoken 一併新增至 Secret:

    kubectl create ns config-management-system && \
    kubectl create secret generic git-creds \
     --namespace=config-management-system \
     --from-literal=username=USERNAME \
      --from-literal=token=TOKEN \
     --from-literal=https_proxy=HTTPS_PROXY_URL
    

    更改下列內容:

    • USERNAME:您要使用的使用者名稱。
    • TOKEN:您在上一個步驟中建立的權杖。
    • HTTPS_PROXY_URL:與 Git 存放區通訊時使用的 HTTPS 代理伺服器網址。
  3. 如果本機仍須使用權杖,請妥善保管,否則請刪除。

Google 服務帳戶

如果存放區位於 Cloud Source Repositories,且叢集使用 GKE 適用的工作負載身分聯盟車隊適用的工作負載身分聯盟,您可以使用 Google 服務帳戶,授予 Config Sync 權限,允許存取代管叢集所在專案中的存放區。

  1. 如果您還沒有服務帳戶,請建立服務帳戶

  2. 將 Cloud Source Repositories 讀者 (roles/source.reader) IAM 角色授予 Google 服務帳戶。如要進一步瞭解 Cloud Source Repositories 角色和權限,請參閱授予檢視存放區的權限

    • 如果專案中的所有存放區都適用相同權限,請授予專案層級權限。

      gcloud projects add-iam-policy-binding PROJECT_ID \
        --role=roles/source.reader \
        --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
      
    • 如要讓服務帳戶在專案中對每個存放區擁有不同層級的存取權,請授予存放區專屬權限。

      gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID
      
  3. 如果您使用 Google Cloud 主控台設定 Config Sync,請選取「Workload Identity Federation for GKE」做為「Authentication Type」,然後新增服務帳戶電子郵件地址。

    如果您使用 Google Cloud CLI 設定 Config Sync,請將 gcpserviceaccount 新增為 secretType,然後將服務帳戶電子郵件地址新增至 gcpServiceAccountEmail

  4. 設定 Config Sync 後,請在 Kubernetes 服務帳戶與 Google 服務帳戶之間建立 IAM 政策繫結。系統會等到您完成 Config Sync 初次設定之後,再建立 Kubernetes 服務帳戶。

    如果您使用已註冊至機群的叢集,每個機群只需建立一次政策繫結。註冊至機群的所有叢集都會共用相同的 Workload Identity Federation for GKE 集區。根據機群的相同性概念,如果您在某個叢集中將 IAM 政策新增至 Kubernetes 服務帳戶,則同一個機群中其他叢集上相同命名空間的 Kubernetes 服務帳戶也會取得相同的 IAM 政策。

    有了這個繫結,Config Sync Kubernetes 服務帳戶即可做為 Google 服務帳戶:

    gcloud iam service-accounts add-iam-policy-binding \
        GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --role=roles/iam.workloadIdentityUser \
        --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
        --project=PROJECT_ID
    

更改下列內容:

  • PROJECT_ID:機構的專案 ID。
  • FLEET_HOST_PROJECT_ID:如果您使用 GKE Workload Identity Federation for GKE,這與 PROJECT_ID 相同。如果您使用 GKE 適用的 Fleet 工作負載身分聯盟,這個 ID 是叢集註冊的 Fleet 專案 ID。
  • GSA_NAME:您要用來連線至 Artifact Registry 的自訂 Google 服務帳戶。服務帳戶必須具備 Artifact Registry 讀者 (roles/artifactregistry.reader) IAM 角色。
  • KSA_NAME:調解器的 Kubernetes 服務帳戶。
    • 如果是根存放區,如果 RootSync 名稱是 root-sync,請使用 root-reconciler。否則,請使用 root-reconciler-ROOT_SYNC_NAME。如果您使用 Google Cloud 控制台或 Google Cloud CLI 安裝 Config Sync,Config Sync 會自動建立名為 root-sync 的 RootSync 物件。
  • REPOSITORY:存放區的名稱。
  • POLICY_FILE:具備 Identity and Access Management 政策的 JSON 或 YAML 檔案。

Compute Engine 預設服務帳戶

如果存放區位於 Cloud Source Repositories,且叢集是 GKE,並停用了 GKE 適用的工作負載身分聯盟,則可以使用 gcenode 做為驗證類型。

如果您使用 Google Cloud 控制台設定 Config Sync,請選取「Google Cloud Repository」做為「Authentication Type」

如果您使用 Google Cloud CLI 設定 Config Sync,請將 gcenode 新增為 secretType

選取「Google Cloud Repository」gcenode,即可使用 Compute Engine 預設服務帳戶。您必須將 Cloud Source Repositories Reader (roles/source.reader) IAM 角色授予 Compute Engine 預設服務帳戶。如要進一步瞭解 Cloud Source Repositories 角色和權限,請參閱授予檢視存放區的權限

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com"

PROJECT_ID 替換為貴機構的專案 ID,並將 PROJECT_NUMBER 替換為貴機構的專案編號。

GitHub 應用程式

如果存放區位於 GitHub,您可以將 githubapp 設為驗證類型。

如要使用 GitHub 應用程式,請完成下列步驟:

  1. 按照 GitHub 上的操作說明,佈建 GitHub 應用程式並授予從存放區讀取資料的權限。

  2. 將 GitHub 應用程式設定新增至叢集內的新 Secret:

    使用用戶端 ID

    kubectl create ns config-management-system && \
    kubectl create secret generic git-creds \
      --namespace=config-management-system \
      --from-literal=github-app-client-id=CLIENT_ID \
      --from-literal=github-app-installation-id=INSTALLATION_ID \
      --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
      --from-literal=github-app-base-url=BASE_URL
    
    • CLIENT_ID 替換為 GitHub 應用程式的用戶端 ID。
    • INSTALLATION_ID 替換為 GitHub 應用程式的安裝 ID。
    • /path/to/GITHUB_PRIVATE_KEY 替換為包含私密金鑰的檔案名稱。
    • BASE_URL 替換成 GitHub API 端點的基本網址。只有在存放區並非託管於 www.github.com 時才需要。否則可以省略這個引數,並預設為 https://api.github.com/

    使用應用程式 ID

    kubectl create ns config-management-system && \
    kubectl create secret generic git-creds \
      --namespace=config-management-system \
      --from-literal=github-app-application-id=APPLICATION_ID \
      --from-literal=github-app-installation-id=INSTALLATION_ID \
      --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
      --from-literal=github-app-base-url=BASE_URL
    
    • APPLICATION_ID 替換為 GitHub 應用程式的應用程式 ID。
    • INSTALLATION_ID 替換為 GitHub 應用程式的安裝 ID。
    • /path/to/GITHUB_PRIVATE_KEY 替換為包含私密金鑰的檔案名稱。
    • BASE_URL 替換成 GitHub API 端點的基本網址。只有在存放區並非託管於 www.github.com 時才需要。否則可以省略這個引數,並預設為 https://api.github.com/
  3. 將私密金鑰從本機磁碟中刪除,或是保護該金鑰。

  4. 設定 Config Sync 並新增 Git 存放區的網址時,請使用 githubapp 驗證類型。

授予 Config Sync 對 OCI 的唯讀存取權

Config Sync 需要 Artifact Registry 中儲存的 OCI 映像檔唯讀權限,才能讀取映像檔中包含的設定,並將這些設定套用至叢集。

如果映像檔不需要驗證唯讀存取權,您可以繼續設定 Config Sync,並使用 none 做為驗證類型。舉例來說,如果圖片對外公開,網際網路上的任何人都能存取,就不需要驗證。

不過,大多數使用者都需要建立憑證,才能存取受限制的圖片。 Config Sync 支援下列驗證機制:

  • Kubernetes 服務帳戶 (k8sserviceaccount)
  • Google 服務帳戶 (gcpserviceaccount)
  • Compute Engine 預設服務帳戶 (gcenode)

Kubernetes 服務帳戶

如果將 OCI 映像檔儲存在 Artifact Registry,且叢集使用 GKE 適用的 Workload Identity FederationFleet 適用的 Workload Identity Federation,則可使用 Kubernetes 服務帳戶做為驗證類型。

  1. 將 Artifact Registry Reader (roles/artifactregistry.reader) 身分與存取權管理角色授予 Kubernetes 服務帳戶,並搭配使用 GKE 集區的 Workload Identity Federation。如要進一步瞭解 Artifact Registry 角色和權限,請參閱設定 Artifact Registry 的角色和權限

    • 如果專案中的所有存放區都適用相同權限,請授予專案層級權限。

      gcloud projects add-iam-policy-binding PROJECT_ID \
            --role=roles/artifactregistry.reader \
            --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"
      
    • 如要讓服務帳戶在專案中對每個存放區擁有不同層級的存取權,請授予存放區專屬權限。

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
         --location=LOCATION \
         --role=roles/artifactregistry.reader \
         --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
         --project=PROJECT_ID
      

    更改下列內容:

    • PROJECT_ID:機構的專案 ID。
    • FLEET_HOST_PROJECT_ID:如果您使用 GKE Workload Identity Federation for GKE,這與 PROJECT_ID 相同。如果您使用 GKE 適用的 Fleet 工作負載身分聯盟,這個 ID 是叢集註冊的 Fleet 專案 ID。
    • KSA_NAME:調解器的 Kubernetes 服務帳戶。
      • 如果是根存放區,如果 RootSync 名稱是 root-sync,請使用 root-reconciler。否則,請使用 root-reconciler-ROOT_SYNC_NAME。如果您使用 Google Cloud 控制台或 Google Cloud CLI 安裝 Config Sync,Config Sync 會自動建立名為 root-sync 的 RootSync 物件。
    • REPOSITORY:存放區的 ID。
    • LOCATION:存放區的區域或多區域位置。

Compute Engine 預設服務帳戶

如果 Helm 資訊圖表儲存在 Artifact Registry 中,且叢集是 GKE,並停用了 GKE 適用的工作負載身分聯盟,則可以使用 gcenode 做為驗證類型。Config Sync 會使用 Compute Engine 預設服務帳戶。 您必須授予 Compute Engine 預設服務帳戶 Artifact Registry 的讀取權。

  1. 執行下列指令,授予 Compute Engine 服務帳戶 Artifact Registry 的讀取權限:

    gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
       --role=roles/artifactregistry.reader
    

    PROJECT_ID 替換為貴機構的專案 ID,並將 PROJECT_NUMBER 替換為貴機構的專案編號。

為憑證授權單位設定 Config Sync

如果伺服器設定的憑證來自尚未受信任的憑證授權單位 (CA),您可以設定 Config Sync 使用 CA 憑證,驗證與伺服器的 HTTPS 連線。這項功能支援 Git、Helm 或 OCI 伺服器。CA 憑證必須包含完整的 SSL 憑證 (根/中繼/葉)。如果伺服器已使用信任的 CA,或您並非透過 HTTPS 連線,可以略過這個步驟,並將 caCertSecretRef 設為未設定。

RootSync

  1. 擷取用於核發 Git 伺服器憑證的 CA 憑證,並儲存到檔案中。

  2. 如果是 RootSync 物件,則必須在 config-management-system 命名空間中建立 Secret。例如:

    kubectl create ns config-management-system && 
    kubectl create secret generic ROOT_CA_CERT_SECRET_NAME
    --namespace=config-management-system
    --from-file=cert=/path/to/CA_CERT_FILE

  3. 設定 Config Sync 時,請將 RootSync 物件中 caCertSecretRef.name 欄位的值設為 ROOT_CA_CERT_SECRET_NAME

RepoSync

  1. 擷取用於核發 Git 伺服器憑證的 CA 憑證,並儲存到檔案中。

  2. 如果是 RepoSync 物件,Secret 必須與 RepoSync 建立在相同的命名空間。例如:

    kubectl create ns REPO_SYNC_NAMESPACE && 
    kubectl create secret generic NAMESPACE_CA_CERT_SECRET_NAME
    --namespace=REPO_SYNC_NAMESPACE
    --from-file=cert=/path/to/CA_CERT_FILE

  3. 設定 RepoSync 時,請將 RepoSync 物件中的 caCertSecretRef.name 欄位值設為 NAMESPACE_CA_CERT_SECRET_NAME

授予 Helm Config Sync 唯讀存取權

Config Sync 需要 Helm 存放區的唯讀權限,才能讀取存放區中的 Helm 資訊圖表,並將其安裝至叢集。

如果存放區不需要驗證唯讀存取權,您可以繼續設定 Config Sync,並使用 none 做為驗證類型。舉例來說,如果 Helm 存放區是公開的,網際網路上的任何人都能存取,您就不需要驗證。

不過,大多數使用者都需要建立憑證,才能存取私有 Helm 存放區。 Config Sync 支援下列驗證機制:

  • 權杖 (token)
  • Kubernetes 服務帳戶 (k8sserviceaccount)
  • Google 服務帳戶 (gcpserviceaccount)
  • Compute Engine 預設服務帳戶 (gcenode)

權杖

使用 Helm 存放區使用者名稱和密碼建立密鑰:

kubectl create secret generic SECRET_NAME \
    --namespace=config-management-system \
    --from-literal=username=USERNAME \
    --from-literal=password=PASSWORD

更改下列內容:

  • SECRET_NAME:您要授予 Secret 的名稱。
  • USERNAME:Helm 存放區使用者名稱。
  • PASSWORD:Helm 存放區密碼。

設定 Config Sync 時,您會使用為 spec.helm.secretRef.name 選擇的 Secret 名稱。

Kubernetes 服務帳戶

如果 Helm 資訊圖表儲存在 Artifact Registry,且叢集使用 GKE 適用的 Workload Identity Federation for GKEFleet 適用的 Workload Identity Federation for GKE,則可使用 Kubernetes 服務帳戶做為驗證類型。

  1. 將 Artifact Registry Reader (roles/artifactregistry.reader) 身分與存取權管理角色授予 Kubernetes 服務帳戶,並搭配使用 GKE 集區的 Workload Identity Federation。如要進一步瞭解 Artifact Registry 角色和權限,請參閱設定 Artifact Registry 的角色和權限

    • 如果專案中的所有存放區都適用相同權限,請授予專案層級權限。

      gcloud projects add-iam-policy-binding PROJECT_ID \
         --role=roles/artifactregistry.reader \
         --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"
      
    • 如要讓服務帳戶在專案中對每個存放區擁有不同層級的存取權,請授予存放區專屬權限。

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
         --location=LOCATION \
         --role=roles/artifactregistry.reader \
         --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
         --project=PROJECT_ID
      

    更改下列內容:

    • PROJECT_ID:機構的專案 ID。
    • FLEET_HOST_PROJECT_ID:如果您使用 GKE Workload Identity Federation for GKE,這與 PROJECT_ID 相同。如果您使用 GKE 適用的 Fleet 工作負載身分聯盟,這個 ID 是叢集註冊的 Fleet 專案 ID。
    • KSA_NAME:調解器的 Kubernetes 服務帳戶。
      • 如果是根存放區,如果 RootSync 名稱是 root-sync,請使用 root-reconciler。否則,請使用 root-reconciler-ROOT_SYNC_NAME
    • REPOSITORY:存放區的 ID。
    • LOCATION:存放區的區域或多區域位置。

Compute Engine 預設服務帳戶

如果 Helm 資訊圖表儲存在 Artifact Registry 中,且叢集是 GKE,並停用了 GKE 適用的工作負載身分聯盟,則可以使用 gcenode 做為驗證類型。Config Sync 會使用 Compute Engine 預設服務帳戶。 您必須授予 Compute Engine 預設服務帳戶 Artifact Registry 的讀取權。您可能需要授予 storage-ro 存取權範圍,才能授予唯讀權限來提取圖片。

  1. 授予 Compute Engine 服務帳戶 Artifact Registry 的讀取權限:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
        --role=roles/artifactregistry.reader
    

    PROJECT_ID 替換為貴機構的專案 ID,並將 PROJECT_NUMBER 替換為貴機構的專案編號。

設定 Config Sync

如要設定從根存放區進行同步,您必須建立 RootSync 物件,將根存放區同步至叢集。每個叢集只能建立一個根存放區,且根存放區可以是非結構化存放區階層式存放區

  1. 如果您使用 Config Sync 許可控制器 Webhook (預設會停用許可控制器 Webhook),並在私人叢集中安裝 Config Sync,請新增防火牆規則,允許使用 10250 連接埠。Config Sync 准入 Webhook 會使用通訊埠 10250 來防止差異。

  2. 等待 RootSyncRepoSync CRD 可用:

    until kubectl get customresourcedefinitions rootsyncs.configsync.gke.io reposyncs.configsync.gke.io; do date; sleep 1; echo ""; done
    
  3. 將下列其中一個資訊清單儲存為 root-sync.yaml。請使用與設定來源類型對應的資訊清單版本。

    Git

    # root-sync.yaml
    apiVersion: configsync.gke.io/v1beta1
    kind: RootSync
    metadata:
      name: ROOT_SYNC_NAME
      namespace: config-management-system
    spec:
      sourceType: git
      sourceFormat: ROOT_FORMAT
      git:
        repo: ROOT_REPOSITORY
        revision: ROOT_REVISION
        branch: ROOT_BRANCH
        dir: ROOT_DIRECTORY
        auth: ROOT_AUTH_TYPE
        gcpServiceAccountEmail: ROOT_EMAIL
        secretRef:
          name: ROOT_SECRET_NAME
        noSSLVerify: ROOT_NO_SSL_VERIFY
        caCertSecretRef:
          name: ROOT_CA_CERT_SECRET_NAME
    

    更改下列內容:

    • ROOT_SYNC_NAME:新增 RootSync 物件的名稱。
    • ROOT_FORMAT:新增 unstructured 即可使用非結構化存放區,或新增 hierarchy 即可使用階層式存放區。這些值會區分大小寫。這是選填欄位,預設值為 hierarchy。建議您新增 unstructured,因為這個格式可讓您以最方便的方式整理設定。
    • ROOT_REPOSITORY:新增要當做根存放區的 Git 存放區網址。您可以輸入使用 HTTPS 或 SSH 通訊協定的網址。舉例來說,https://github.com/GoogleCloudPlatform/anthos-config-management-samples 使用 HTTPS 通訊協定。 這是必填欄位。
    • ROOT_REVISION:新增要同步處理的 Git 修訂版本 (標記或雜湊) 或分支。這是選填欄位,預設值為 HEAD。使用雜湊時,必須是完整雜湊,不得使用縮寫形式。
    • ROOT_BRANCH:新增要同步處理的存放區分支版本。這是選填欄位,預設值為 master。建議使用 revision 欄位指定分支名稱,方便管理。如果同時指定 revision 欄位和 branch 欄位,revision 的優先順序會高於 branch
    • ROOT_DIRECTORY:將 Git 存放區中的路徑新增至包含要同步處理設定的根目錄。這個欄位為選填,預設值為存放區的根目錄 (/)。
    • ROOT_AUTH_TYPE:新增下列其中一種驗證類型:

      • none:不使用驗證
      • ssh:使用安全殼層金鑰組
      • cookiefile:使用 cookiefile
      • token:使用權杖
      • gcpserviceaccount:使用 Google 服務帳戶存取 Cloud Source Repositories。
      • gcenode:使用 Google 服務帳戶存取 Cloud Source Repositories。只有在叢集未啟用 Workload Identity Federation for GKE 時,才選取這個選項。

      如要進一步瞭解這些驗證類型,請參閱授予 Config Sync 對 Git 的唯讀存取權

      這是必填欄位。

    • ROOT_EMAIL:如果您新增 gcpserviceaccount 做為ROOT_AUTH_TYPE,請新增 Google 服務帳戶電子郵件地址。例如:acm@PROJECT_ID.iam.gserviceaccount.com

    • ROOT_SECRET_NAME:新增 Secret 名稱。如果設定這個欄位,您必須將 Secret 的公開金鑰新增至 Git 供應商。這是選填欄位。

    • ROOT_NO_SSL_VERIFY:如要停用 SSL 憑證驗證,請將這個欄位設為 true。預設值為 false

    • ROOT_CA_CERT_SECRET_NAME:新增 Secret 名稱。如果設定這個欄位,您的 Git 供應商必須使用這個憑證授權單位 (CA) 核發的憑證。密鑰必須包含名為 cert 的金鑰底下的 CA 憑證。這是選填欄位。

      如要進一步瞭解如何設定 CA 憑證的 Secret 物件,請參閱「設定憑證授權單位

    如要瞭解欄位,以及可新增至 spec 欄位的完整欄位清單,請參閱「RootSync 欄位」。

    這個資訊清單會建立以 Git 為來源的 RootSync 物件。

    OCI

    # root-sync.yaml
    apiVersion: configsync.gke.io/v1beta1
    kind: RootSync
    metadata:
      name: ROOT_SYNC_NAME
      namespace: config-management-system
    spec:
      sourceType: oci
      sourceFormat: ROOT_FORMAT
      oci:
        image: ROOT_IMAGE
        dir: ROOT_DIRECTORY
        auth: ROOT_AUTH_TYPE
        gcpServiceAccountEmail: ROOT_EMAIL
        caCertSecretRef:
          name: ROOT_CA_CERT_SECRET_NAME
    

    更改下列內容:

    • ROOT_SYNC_NAME:新增 RootSync 物件的名稱。
    • ROOT_FORMAT:新增 unstructured 可使用非結構化存放區,新增 hierarchy 則可使用階層式存放區。這些值會區分大小寫。這是選填欄位,預設值為 hierarchy。建議您新增 unstructured,因為這個格式可讓您以最方便的方式整理設定。
    • ROOT_IMAGE:要用做根存放區的 OCI 映像檔網址,例如 LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME。根據預設,系統會從 latest 標記提取圖片,但您也可以改用 TAGDIGEST 提取圖片。 在 PACKAGE_NAME 中指定 TAGDIGEST
      • 如要透過 TAG 提取:LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME:TAG
      • 如要透過 DIGEST 提取:LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME@sha256:DIGEST
    • ROOT_DIRECTORY:在存放區中新增路徑,指向要同步處理的設定所在的根目錄。這個欄位為選填,預設值為存放區的根目錄 (/)。
    • ROOT_AUTH_TYPE:新增下列其中一種驗證類型:

      • none:不使用驗證
      • gcenode:使用 Compute Engine 預設服務帳戶存取 Artifact Registry 中的映像檔。只有在叢集未啟用 GKE 的工作負載身分聯盟時,才選取這個選項。
      • gcpserviceaccount:使用 Google 服務帳戶存取圖片。

      這是必填欄位。

    • ROOT_EMAIL:如果您新增 gcpserviceaccount 做為ROOT_AUTH_TYPE,請新增 Google 服務帳戶電子郵件地址。例如:acm@PROJECT_ID.iam.gserviceaccount.com

    • ROOT_CA_CERT_SECRET_NAME:新增 Secret 名稱。如果設定這個欄位,OCI 供應商必須使用這個憑證授權單位 (CA) 核發的憑證。密鑰必須包含名為 cert 的金鑰底下的 CA 憑證。這是選填欄位。

    如要進一步瞭解如何設定 CA 憑證的 Secret 物件,請參閱「設定憑證授權單位

    如要瞭解欄位,以及可新增至 spec 欄位的完整欄位清單,請參閱「RootSync 欄位」。

    這個資訊清單會建立 RootSync 物件,並使用 OCI 映像檔做為來源。

    Helm

    # root-sync.yaml
    apiVersion: configsync.gke.io/v1beta1
    kind: RootSync
    metadata:
      name: ROOT_SYNC_NAME
      namespace: config-management-system
    spec:
      sourceType: helm
      sourceFormat: ROOT_FORMAT
      helm:
        repo: ROOT_HELM_REPOSITORY
        chart: HELM_CHART_NAME
        version: HELM_CHART_VERSION
        releaseName: HELM_RELEASE_NAME
        namespace: HELM_RELEASE_NAMESPACE
        values:
          foo:
            bar: VALUE_1
          baz:
          - qux: VALUE_2
            xyz: VALUE_3
        includeCRDs: HELM_INCLUDE_CRDS
        auth: ROOT_AUTH_TYPE
          gcpServiceAccountEmail: ROOT_EMAIL
          secretRef:
            name: ROOT_SECRET_NAME
        caCertSecretRef:
          name: ROOT_CA_CERT_SECRET_NAME
    

    更改下列內容:

    • ROOT_SYNC_NAME:新增 RootSync 物件的名稱。
    • ROOT_FORMAT:新增 unstructured 可使用非結構化存放區,新增 hierarchy 則可使用階層式存放區。這些值會區分大小寫。這是選填欄位,預設值為 hierarchy。建議您新增 unstructured,因為這個格式可讓您以最方便的方式整理設定。
    • ROOT_HELM_REPOSITORY:要當做根存放區的 Helm 存放區網址。您可以使用 HTTPS 或 SSH 通訊協定輸入網址。舉例來說,https://github.com/GoogleCloudPlatform/anthos-config-management-samples 使用的是 HTTPS 通訊協定。這是必填欄位。
    • HELM_CHART_NAME:新增 Helm 圖表名稱。這是必填欄位。
    • HELM_CHART_VERSION:圖表版本。 這是選填欄位。如未指定任何值,則會使用最新版本。
    • HELM_RELEASE_NAME:Helm 版本名稱。 這是選填欄位。
    • HELM_RELEASE_NAMESPACE:發布版本的目標命名空間。這項作業只會為範本中含有 namespace: {{ .Release.Namespace }} 的資源設定命名空間。 這是選填欄位。如未指定任何值,則會使用預設命名空間 config-management-system
    • HELM_INCLUDE_CRDS:如要讓 Helm 範本也產生 CustomResourceDefinition,請設為 true。這個欄位為選填。如未指定任何值,預設值為 false,且不會產生 CRD。
    • VALUE:要使用的值,而非隨附於 Helm Chart 的預設值。這個欄位的格式與 Helm 圖表的 values.yaml 檔案相同。這是選填欄位。
    • ROOT_AUTH_TYPE:新增下列其中一種驗證類型:

      • none:不使用驗證
      • token:使用使用者名稱和密碼存取私人 Helm 存放區。
      • gcenode:使用 Compute Engine 預設服務帳戶存取 Artifact Registry 中的映像檔。只有在叢集未啟用 GKE 的工作負載身分聯盟時,才選取這個選項。
      • gcpserviceaccount:使用 Google 服務帳戶存取圖片。

      這是必填欄位。

    • ROOT_EMAIL:如果您新增 gcpserviceaccount 做為ROOT_AUTH_TYPE,請新增 Google 服務帳戶電子郵件地址。例如:acm@PROJECT_ID.iam.gserviceaccount.com

    • ROOT_SECRET_NAME:如果 tokenROOT_AUTH_TYPE,請新增密鑰名稱。這是選填欄位。

    • ROOT_CA_CERT_SECRET_NAME:新增 Secret 名稱。如果設定這個欄位,您的 Helm 提供者必須使用這個憑證授權單位 (CA) 核發的憑證。密鑰必須包含名為 cert 的金鑰底下的 CA 憑證。這是選填欄位。

    如要進一步瞭解如何設定 CA 憑證的 Secret 物件,請參閱「設定憑證授權單位

    如要瞭解欄位,以及可新增至 spec 欄位的完整欄位清單,請參閱「RootSync 欄位」。

    這個資訊清單會建立以 Helm 為來源的 RootSync 物件。

  4. 套用變更:

    kubectl apply -f root-sync.yaml
    

確認根存放區的同步狀態

您可以使用 nomos status 指令檢查根存放區的同步狀態:

nomos status

您會看到類似以下範例的輸出內容:

my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4

驗證 RootSync 安裝作業

建立 RootSync 物件時,Config Sync 會建立前置字元為 root-reconciler 的協調器。Reconciler 是以 Deployment 形式部署的 Pod。可將資訊清單從 Git 存放區同步到叢集。

您可以檢查 root-reconciler Deployment 的狀態,確認 RootSync 物件是否正常運作:

kubectl get -n config-management-system deployment \
    -l configsync.gke.io/sync-name=ROOT_SYNC_NAME

ROOT_SYNC_NAME 替換為 RootSync 的名稱。

您會看到類似以下範例的輸出內容:

NAME              READY   UP-TO-DATE   AVAILABLE   AGE
root-reconciler   1/1     1            1           3h42m

如要進一步瞭解如何查看 RootSync 物件的狀態,請參閱「監控 RootSync 和 RepoSync 物件」。

完成根存放區的設定後,您可以選擇設定從多個存放區同步處理。如果您希望存放區包含命名空間範圍的設定,並同步至叢集中的特定命名空間,這些存放區就非常實用。

升級 Config Sync

升級 Config Sync 的步驟取決於升級前後的版本。從 1.20.0 版開始,Config Sync 會以獨立安裝的形式提供,不含 ConfigManagement Operator。如果您要從 1.20.0 之前的版本升級至 1.20.0 以上版本,請務必先解除安裝 ConfigManagement Operator,再進行升級。

如果從不支援的版本升級,請逐步升級,每次增量不超過三個子版本。舉例來說,如果目前的 Config Sync 版本是 1.14.0,請先升級至 1.17.0 版,再升級至 1.20.0 版。

解除安裝 ConfigManagement Operator

如果從 1.20.0 之前的版本升級至 1.20.0 以上版本,請務必先解除安裝 ConfigManagement Operator,再進行升級。

如要檢查叢集是否已安裝 Config Management,請執行下列指令:

kubectl get configmanagement

如果輸出內容不為空白,表示叢集已安裝 Config Management。 如要解除安裝 Config Management,請完成下列步驟,解除安裝 Config Management,但保留叢集上安裝的 Config Sync。建議使用 nomos CLI 解除安裝 ConfigManagement Operator,因為這個工具的介面更豐富,錯誤處理機制也更完善。只有在無法存取 nomos CLI 時,才應使用殼層指令碼。

  1. 確認 nomos CLI 為最新版本。

  2. 執行下列指令,更新目前 kubectl 環境中的叢集:

    nomos migrate --remove-configmanagement
    

殼層指令碼

將下列殼層指令碼複製到檔案中,然後執行該檔案,更新目前 kubectl 環境中的叢集。

 #!/bin/bash

 set -euox pipefail

 hnc_enabled="$(kubectl get configmanagements.configmanagement.gke.io config-management -o=jsonpath="{.spec.hierarchyController.enabled}" --ignore-not-found)"

 if [[ "${hnc_enabled}" == "true" ]]; then
   echo "Hierarchy Controller is enabled on the ConfigManagement object. It must be disabled before migrating."
   echo "This can be done by unsetting the spec.hierarchyController field on ConfigManagement."
   exit 1
 fi

 kubectl delete deployment -n config-management-system config-management-operator --ignore-not-found --cascade=foreground

 if kubectl get configmanagement config-management &> /dev/null ; then
   kubectl patch configmanagement config-management --type="merge" -p '{"metadata":{"finalizers":[]}}'
   kubectl delete configmanagement config-management --cascade=orphan --ignore-not-found
 fi

 kubectl delete clusterrolebinding config-management-operator --ignore-not-found
 kubectl delete clusterrole config-management-operator --ignore-not-found
 kubectl delete serviceaccount -n config-management-system config-management-operator --ignore-not-found
 kubectl delete customresourcedefinition configmanagements.configmanagement.gke.io --ignore-not-found

安裝新版 Config Sync

如要升級 Config Sync,請針對每個已註冊的叢集完成下列步驟:

1.20.0 以上版本

  1. 下載新版本的 Config Sync 資訊清單和 nomos 指令。

  2. 解壓縮封存檔:

    tar -xzvf config-sync.tar.gz
  3. 在先前步驟中解壓縮的封存檔中,按照提供的 README 中的操作說明編輯自訂項目。

  4. 如要更新 Config Sync 安裝作業,請套用按照 README 指示建構的已算繪資訊清單:

    kubectl apply -f CONFIG_SYNC_MANIFEST
    

    CONFIG_SYNC_MANIFEST 替換為已算繪資訊清單的名稱。

  5. 將所有用戶端的 nomos 指令替換為新版本。這項變更可確保 nomos 指令一律能取得所有已註冊叢集的狀態,並驗證這些叢集的設定。

1.19.2 以下版本

  1. 下載新版本的 Config Sync 資訊清單和 nomos 指令。

  2. 套用 Config Sync 資訊清單:

    kubectl apply -f config-management-operator.yaml
    

    這項指令會更新 ConfigManagement Operator 映像檔。Kubernetes 會擷取新版本,並使用新版本重新啟動 Config Sync Pod。Config Sync 啟動時,會執行協調迴圈,套用新映像檔中綁定的資訊清單集。這會更新並重新啟動每個元件 Pod。

  3. 建立名為 config-management.yaml 的檔案,然後將下列 YAML 檔案複製到該檔案中:

    # config-management.yaml
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      # The `enableMultiRepo` field is set to true to enable RootSync and RepoSync APIs.
      enableMultiRepo: true
      preventDrift: PREVENT_DRIFT
    

    更改下列內容:

    • PREVENT_DRIFT:如果設為 true,系統會啟用 Config Sync 許可控制 Webhook,防止發生差異,方法是拒絕將衝突變更推送至實際叢集。預設為 false。無論這個欄位的值為何,Config Sync 一律會修正差異。
  4. 套用變更:

    kubectl apply -f config-management.yaml
    
  5. 將所有用戶端的 nomos 指令替換為新版本。這項變更可確保 nomos 指令一律能取得所有已註冊叢集的狀態,並驗證這些叢集的設定。

解除安裝 Config Sync

如要解除安裝 Config Sync,請完成下列步驟:

  1. 中央管理員應移除根存放區:

    1. 如果您已啟用 Webhook,且想保留資源,請針對已捨棄的資源停用漂移防護機制。如果尚未啟用 Webhook,則無需採取任何額外步驟來保留資源。

    2. 執行下列指令,刪除 RootSync 物件:

      kubectl delete -f root-sync.yaml
      
  2. 移除所有存放區

  3. 您也可以使用安裝 Config Sync 時使用的資訊清單解除安裝 Config Sync。

       kubectl delete -f CONFIG_SYNC_MANIFEST --ignore-not-found
    

後續步驟