授予 Config Sync Git 存放區存取權

本頁說明如何向 Git 存放區驗證 Config Sync。Config Sync 需要可靠來源的唯讀權限，才能讀取設定、將設定套用至叢集，並保持同步。

選擇驗證方式

您使用的驗證方法取決於來源類型支援的方法。

下表列出可與 Config Sync 搭配使用的驗證方法：

方法 支援的來源 說明 限制
無驗證 Git、OCI、Helm 不需要額外設定。 只有在資訊來源公開時才能運作。
安全殼層金鑰組 Git 大多數 Git 供應商都支援這項功能。 需要金鑰管理。不支援 OCI 或 Helm。
權杖 Git、Helm 大多數 Git 供應商都支援這項功能。如果貴機構不允許使用安全殼層金鑰，可以選擇使用權杖。支援 Helm 的使用者名稱和密碼。 需要權杖管理。權杖可能會過期。不支援離線轉換匯入功能。
Kubernetes 服務帳戶 OCI、Helm 使用 IAM 直接授予 Kubernetes 服務帳戶 Artifact Registry 存取權。您必須在叢集上啟用 Workload Identity Federation for GKE。 不支援 Git。
Google 服務帳戶 Git 使用 IAM，避免將憑證儲存在 Kubernetes Secret 中。建議用於 Secure Source Manager 和 Cloud Source Repositories。您必須在叢集上啟用 Workload Identity Federation for GKE。 您必須先在叢集上安裝 Config Sync，然後再進行設定。不支援在 Secure Source Manager 或 Cloud Source Repositories 以外代管的存放區。
GitHub 應用程式 Git 直接與 GitHub 整合。允許精細權限。 僅適用於 GitHub 代管的存放區。僅支援 Config Sync 1.19.1 以上版本。

Config Sync 也支援下列驗證方法，但如果無法使用上表列出的選項，才建議採用這些方法：

  • cookiefile：部分 Git 供應商可能不支援這項功能。不支援 OCI 或 Helm。
  • Compute Engine 預設服務帳戶 (gcenode)：不建議使用，因為只有在停用 Workload Identity Federation for GKE 時，這個方法才有效。支援 Git、OCI 和 Helm。
  • Helm 和 OCI 的 Google 服務帳戶：支援，但不建議使用，因為 Kubernetes 服務帳戶方法需要的設定較少。

使用機群套件進行驗證

如果您使用車隊套件，就不需要完成本頁的指示。Fleet 套件會使用 Cloud Build 向 Git 進行驗證，因此您只需要為每個專案驗證一次，不必在叢集上安裝 Config Sync 時授予存取權。

事前準備

授予 Config Sync Git 存放區的唯讀權限前，請先完成下列工作：

使用安全殼層金鑰組

安全殼層金鑰組包含兩個檔案：一個公開金鑰和一個私密金鑰。Config Sync 不支援建立通關密語。您可以將單一金鑰組用於所有叢集，或是針對每個叢集使用專屬的金鑰組，全視您的安全性與法規遵循要求而定。

如要使用 SSH 金鑰配對授予 Config Sync Git 存放區的唯讀權限，請完成下列步驟：

  1. 建立安全殼層金鑰組，或請安全管理員提供。如需建立 SSH 金鑰組，請執行下列指令來建立 4096 位元的 RSA 金鑰：

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

    更改下列內容：

    • GIT_REPOSITORY_USERNAME：您希望 Config Sync 用來向存放區進行驗證的使用者名稱。如果您使用第三方 Git 存放區主機 (例如 GitHub)，或是想搭配 Secure Source Manager 使用服務帳戶，建議您使用不同的帳戶進行驗證。
    • /path/to/KEYPAIR_FILENAME：金鑰組檔案的路徑。

  2. 設定存放區來辨識您剛才建立的公開金鑰。請參閱您 Git 主機供應商的說明文件。以下列出幾個常見的 Git 主機供應商，並提供操作說明：

  3. 使用私密金鑰建立 git-creds 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 替換為私密金鑰的名稱。

  4. 選用，但建議：如要在使用 SSH 驗證時設定已知主機檢查，請將已知主機金鑰新增至 git_creds Secret 中的 data.known_hosts 欄位。

    1. 如要新增已知主機金鑰，請執行下列指令：

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

    2. 如要在 data 下方新增 known_hosts 項目，請執行下列指令：

        known_hosts: KNOWN_HOSTS_KEY

      將 KNOWN_HOSTS_KEY 替換為已知主機金鑰。

    如要停用 known_hosts 檢查，請從 Secret 中移除 known_hosts 欄位。

安裝 Config Sync 時，請使用 SSH 金鑰組 (ssh) 做為驗證類型。

輸入 Git 存放區的網址時，網址必須採用 SSH 通訊協定格式。 網址格式會因 Git 供應商而異。

使用 cookiefile

取得 cookiefile 的程序取決於您存放區的設定。一般而言，憑證會儲存在主目錄的 .gitcookies 檔案中，或是由安全性管理員提供。

如要使用 cookiefile 授予 Config Sync 對 Git 存放區的唯讀存取權，請完成下列步驟：

建立或取得 cookiefile 後，請將其新增至叢集中的新 Secret。基於安全考量，我們建議您使用 HTTPS：

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

將 /path/to/COOKIEFILE 替換成您的路徑和檔案名稱。

安裝 Config Sync 時，請使用 cookiefile (cookiefile) 做為驗證類型。

使用權杖

如果貴機構不允許使用安全殼層金鑰，可以選擇使用權杖。

如要使用權杖授予 Config Sync Git 存放區的唯讀權限，請完成下列步驟：

  1. 從 Git 供應商產生權杖。如需操作說明，請參閱 Git 主機供應商的說明文件。以下列出幾個常見的 Git 主機供應商，並提供操作說明：

  2. 建立或取得權杖後，請將權杖新增至叢集中的新 Secret。基於安全考量，我們建議您使用 HTTPS：

    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：您在上一步驟中建立的權杖。

安裝 Config Sync 時，請使用權杖 (token) 做為驗證類型。

使用 Google 服務帳戶

您可以使用 Google 服務帳戶，授予 Config Sync 權限，允許存取代管叢集所在專案中的存放區。你必須符合下列規定：

如要使用 Google 服務帳戶授予 Config Sync Git 存放區的唯讀權限，請完成下列步驟：

  1. 如要取得建立政策繫結所需的權限，請要求管理員授予您服務帳戶的「服務帳戶管理員」 (roles/iam.serviceAccountAdmin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

    您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

  2. 如果您還沒有服務帳戶，請建立服務帳戶。

  3. 根據您使用的存放區類型，將 IAM 角色授予 Google 服務帳戶：

    Secure Source Manager

    將 Secure Source Manager 執行個體存取者 (roles/securesourcemanager.instanceAccessor) 和 Secure Source Manager 存放區讀取者 (roles/securesourcemanager.repoReader) IAM 角色授予 Google 服務帳戶：

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

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/securesourcemanager.instanceAccessor \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/securesourcemanager.repoReader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      更改下列內容：

      • PROJECT_ID：您的專案 ID。
      • GSA_NAME：要連結至 Secure Source Manager 的 Google 服務帳戶名稱。

    • 如要授予存放區專屬權限，請參閱 Secure Source Manager 文件，瞭解如何授予使用者存放區層級角色。

    安裝 Config Sync 時，請使用 Workload Identity (gcpserviceaccount) 做為驗證類型。您也必須新增服務帳戶電子郵件地址。

    Secure Source Manager 存放區網址必須採用特定格式：https://SSM_INSTANCE_ID-PROJECT_NUMBER-git.INSTANCE_LOCATION.sourcemanager.dev/PROJECT_ID/REPO_NAME.git。

    Cloud Source Repositories

    將 Cloud Source Repositories 讀者 (roles/source.reader) IAM 角色授予 Google 服務帳戶：

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

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

      更改下列內容：

      • PROJECT_ID：您的專案 ID。
      • GSA_NAME：要連結至 Cloud Source Repositories 的 Google 服務帳戶名稱。

    • 如要讓服務帳戶在專案中對每個存放區擁有不同層級的存取權，請授予存放區專屬權限：

      gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID

      更改下列內容：

      • PROJECT_ID：您的專案 ID。
      • REPOSITORY：存放區名稱。
      • POLICY_FILE：包含 Identity and Access Management 政策的 JSON 或 YAML 檔案。

    安裝 Config Sync 時，請使用 Workload Identity (gcpserviceaccount) 做為驗證類型。您也必須新增服務帳戶電子郵件地址。

您必須先設定 Config Sync，才能完成下列步驟，因為系統會等到您完成 Config Sync 初次設定之後，再建立 Kubernetes 服務帳戶。每個車隊只需要執行一次這項操作。 如要建立繫結，讓 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

更改下列內容：

  • FLEET_HOST_PROJECT_ID：如果您使用 Workload Identity Federation for GKE，這個值與 PROJECT_ID 相同。如果您使用 GKE 適用的機群 Workload Identity Federation，請使用叢集註冊的機群專案 ID 做為值。
  • GSA_NAME：要用來連線至 Secure Source Manager 或 Cloud Source Repositories 的自訂 Google 服務帳戶。
  • KSA_NAME：調解器的 Kubernetes 服務帳戶。在大多數情況下，這個值是 root-sync，因為透過 Google Cloud 主控台或 Google Cloud CLI 安裝時，Config Sync 會自動建立名為 root-sync 的 RootSync 物件。否則，請使用 root-reconciler-ROOT_SYNC_NAME 做為值。

如果無法透過 Google 服務帳戶連線至 Config Sync，請參閱「排解 Google 服務帳戶的權限問題」。

使用 Compute Engine 預設服務帳戶

如果未啟用 GKE 的 Workload Identity Federation，除了使用 Google 服務帳戶，您也可以使用 Compute Engine 服務帳戶進行驗證。這個方法僅適用於 Secure Source Manager 和 Cloud Source Repositories 中的存放區。

如要使用 Compute Engine 預設服務帳戶，授予 Config Sync 存放區的唯讀存取權，請將 roles/source.reader 角色授予預設服務帳戶：

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：您的專案編號。

安裝 Config Sync 時，請使用 Google Cloud Repository (gcenode) 做為驗證類型。

使用 GitHub 應用程式

如果存放區位於 GitHub，您可以使用 GitHub 應用程式將存放區連結至 Config Sync：

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

  2. 使用用戶端或應用程式 ID，將 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/。

安裝 Config Sync 時，請使用 GitHub 應用程式 (githubapp) 做為驗證類型。

疑難排解

如要排解將 Config Sync 連線至真實現源的問題，請參閱下列疑難排解主題：

後續步驟