本頁面說明如何使用 kubectl
指令安裝 Config Sync。
事前準備
本節說明使用 kubectl
安裝 Config Sync 前必須滿足的必要條件。
準備本機環境
安裝 Config Sync 前,請先完成下列工作,準備好本機環境:
建立或存取單一可靠資料來源。
安裝並初始化 Google Cloud CLI,其中提供這些操作說明中使用的
gcloud
、kubectl
和nomos
指令。如果使用 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,請完成下列步驟:
- 部署 Config Sync
- 授予 Config Sync 對下列項目的唯讀存取權:
- 設定 Config Sync
部署 Config Sync
確認符合所有先決條件後,即可下載並套用 YAML 資訊清單,部署 Config Sync。
1.20.0 以上版本
使用下列指令下載最新版本的 Config Sync 資訊清單。如要下載特定版本,請參閱「下載」一文。
gcloud storage cp gs://config-management-release/released/latest/config-sync.tar.gz config-sync.tar.gz
解壓縮封存檔:
tar -xzvf config-sync.tar.gz
在先前步驟中解壓縮的封存檔中,按照提供的
README
中的操作說明編輯自訂項目。如要更新 Config Sync 安裝作業,請套用按照
README
指示建構的已算繪資訊清單:kubectl apply -f CONFIG_SYNC_MANIFEST
將
CONFIG_SYNC_MANIFEST
替換為已算繪資訊清單的名稱。將所有用戶端的
nomos
指令替換為新版本。這項變更可確保nomos
指令一律能取得所有已註冊叢集的狀態,並驗證這些叢集的設定。
1.19.2 以下版本
下載新版本的 Config Sync 資訊清單和
nomos
指令。套用 Config Sync 資訊清單:
kubectl apply -f config-management-operator.yaml
建立名為
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 一律會修正差異。
套用變更:
kubectl apply -f config-management.yaml
將所有用戶端的
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 網址:
列出所有存放區:
gcloud source repos list
從輸出內容中,複製要使用的存放區網址。 例如:
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
。
如要使用安全殼層金鑰組,請完成下列步驟:
建立 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 使用服務帳戶,建議您使用不同的帳戶。
設定存放區來辨識您剛才建立的「公開金鑰」。請參閱您 Git 主機供應商的說明文件。為方便起見,以下提供幾個熱門 Git 主機供應商的操作說明:
- Cloud Source Repositories
- Bitbucket
- GitHub 建議您建立個別的部署金鑰, 提供單一 GitHub 存放區的唯讀存取權。
- GitLab
將「私密金鑰」新增到叢集的新 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
後置字串者)。(建議) 如要使用 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
將私密金鑰從本機磁碟中刪除,或是保護該金鑰。
設定 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 CloudREPO_NAME
:存放區名稱
Cookiefile
取得 cookiefile
的程序取決於您存放區的設定。如需範例,請參閱 Cloud Source Repositories 說明文件中的「產生靜態憑證」。憑證通常儲存在主目錄的 .gitcookies
檔案中,或是由安全性管理員提供給您。
如要使用 cookiefile
,請完成下列步驟:
建立並取得
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 網址
如果本機仍須使用
cookiefile
,請妥善保管,否則請將其刪除。
權杖
如果貴機構不允許使用安全殼層金鑰,可以選擇使用權杖。有了 Config Sync,您就能使用 GitHub 的個人存取權杖 (PAT)、GitLab 的 PAT 或部署金鑰,或是 Bitbucket 的應用程式密碼做為權杖。
如要使用權杖建立 Secret,請完成下列步驟:
使用 GitHub、GitLab 或 Bitbucket 建立權杖:
建立並取得權杖後,請將權杖新增至叢集中的新 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 連同
username
和token
一併新增至 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 代理伺服器網址。
如果本機仍須使用權杖,請妥善保管,否則請刪除。
Google 服務帳戶
如果存放區位於 Cloud Source Repositories,且叢集使用 GKE 適用的工作負載身分聯盟或車隊適用的工作負載身分聯盟,您可以使用 Google 服務帳戶,授予 Config Sync 權限,允許存取代管叢集所在專案中的存放區。
如果您還沒有服務帳戶,請建立服務帳戶。
將 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
如果您使用 Google Cloud 主控台設定 Config Sync,請選取「Workload Identity Federation for GKE」做為「Authentication Type」,然後新增服務帳戶電子郵件地址。
如果您使用 Google Cloud CLI 設定 Config Sync,請將
gcpserviceaccount
新增為secretType
,然後將服務帳戶電子郵件地址新增至gcpServiceAccountEmail
。設定 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 應用程式,請完成下列步驟:
按照 GitHub 上的操作說明,佈建 GitHub 應用程式並授予從存放區讀取資料的權限。
將 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 並新增 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 Federation 或 Fleet 適用的 Workload Identity Federation,則可使用 Kubernetes 服務帳戶做為驗證類型。
將 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 的讀取權。
執行下列指令,授予 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
擷取用於核發 Git 伺服器憑證的 CA 憑證,並儲存到檔案中。
如果是
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設定 Config Sync 時,請將
RootSync
物件中caCertSecretRef.name
欄位的值設為 ROOT_CA_CERT_SECRET_NAME。
RepoSync
擷取用於核發 Git 伺服器憑證的 CA 憑證,並儲存到檔案中。
如果是
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設定
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 GKE 或 Fleet 適用的 Workload Identity Federation for GKE,則可使用 Kubernetes 服務帳戶做為驗證類型。
將 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
存取權範圍,才能授予唯讀權限來提取圖片。
授予 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 物件,將根存放區同步至叢集。每個叢集只能建立一個根存放區,且根存放區可以是非結構化存放區或階層式存放區。
如果您使用 Config Sync 許可控制器 Webhook (預設會停用許可控制器 Webhook),並在私人叢集中安裝 Config Sync,請新增防火牆規則,允許使用
10250
連接埠。Config Sync 准入 Webhook 會使用通訊埠10250
來防止差異。等待
RootSync
和RepoSync
CRD 可用:until kubectl get customresourcedefinitions rootsyncs.configsync.gke.io reposyncs.configsync.gke.io; do date; sleep 1; echo ""; done
將下列其中一個資訊清單儲存為
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
標記提取圖片,但您也可以改用TAG
或DIGEST
提取圖片。 在PACKAGE_NAME
中指定TAG
或DIGEST
:- 如要透過
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
:如果token
是ROOT_AUTH_TYPE
,請新增密鑰名稱。這是選填欄位。ROOT_CA_CERT_SECRET_NAME
:新增 Secret 名稱。如果設定這個欄位,您的 Helm 提供者必須使用這個憑證授權單位 (CA) 核發的憑證。密鑰必須包含名為cert
的金鑰底下的 CA 憑證。這是選填欄位。
如要進一步瞭解如何設定 CA 憑證的 Secret 物件,請參閱「設定憑證授權單位」
如要瞭解欄位,以及可新增至
spec
欄位的完整欄位清單,請參閱「RootSync 欄位」。這個資訊清單會建立以 Helm 為來源的
RootSync
物件。套用變更:
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
時,才應使用殼層指令碼。
nomos (建議)
確認 nomos CLI 為最新版本。
執行下列指令,更新目前 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 以上版本
下載新版本的 Config Sync 資訊清單和
nomos
指令。解壓縮封存檔:
tar -xzvf config-sync.tar.gz
在先前步驟中解壓縮的封存檔中,按照提供的
README
中的操作說明編輯自訂項目。如要更新 Config Sync 安裝作業,請套用按照
README
指示建構的已算繪資訊清單:kubectl apply -f CONFIG_SYNC_MANIFEST
將
CONFIG_SYNC_MANIFEST
替換為已算繪資訊清單的名稱。將所有用戶端的
nomos
指令替換為新版本。這項變更可確保nomos
指令一律能取得所有已註冊叢集的狀態,並驗證這些叢集的設定。
1.19.2 以下版本
下載新版本的 Config Sync 資訊清單和
nomos
指令。套用 Config Sync 資訊清單:
kubectl apply -f config-management-operator.yaml
這項指令會更新 ConfigManagement Operator 映像檔。Kubernetes 會擷取新版本,並使用新版本重新啟動 Config Sync Pod。Config Sync 啟動時,會執行協調迴圈,套用新映像檔中綁定的資訊清單集。這會更新並重新啟動每個元件 Pod。
建立名為
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 一律會修正差異。
套用變更:
kubectl apply -f config-management.yaml
將所有用戶端的
nomos
指令替換為新版本。這項變更可確保nomos
指令一律能取得所有已註冊叢集的狀態,並驗證這些叢集的設定。
解除安裝 Config Sync
如要解除安裝 Config Sync,請完成下列步驟:
中央管理員應移除根存放區:
如果您已啟用 Webhook,且想保留資源,請針對已捨棄的資源停用漂移防護機制。如果尚未啟用 Webhook,則無需採取任何額外步驟來保留資源。
執行下列指令,刪除
RootSync
物件:kubectl delete -f root-sync.yaml
您也可以使用安裝 Config Sync 時使用的資訊清單解除安裝 Config Sync。
kubectl delete -f CONFIG_SYNC_MANIFEST --ignore-not-found
後續步驟
- 瞭解如何設定從多個存放區同步處理。