升級指南

本指南提供一般指引，說明如何使用 Terraform 升級現有的 Manufacturing Data Engine (MDE) 安裝項目。

如果您修改過 Terraform 指令碼，可能需要執行其他步驟。這是通用升級指南，因此請務必詳閱您部署的特定版本版本資訊，因為其中可能包含您需要考量的資訊。

注意： 如果從 v1.4.x 升級至 v1.5，程序會重新建立部分內部 Pub/Sub 訂閱項目。請務必先排空現有的 MDE 執行個體，並確認 Pub/Sub 訂閱項目中沒有任何內部訊息，再執行升級指令碼。如要達成這個目標，請停止傳送至 input-message 訂閱項目的訊息。�

注意： MDE 僅支援循序升級。如果您執行的主要版本早於 1.4.x，則必須一次升級一個主要版本的 MDE。

事前準備

注意： 升級 MDE 部署作業前，請先參閱「已知問題」頁面。

升級前，請先手動停止部分 Dataflow 工作。如要瞭解升級至特定版本時必須手動停止的作業，請參閱版本資訊。

本指南需要下列必備條件：

1. 您使用的是預設部署套件。

2. 您的用戶端環境已安裝必要 CLI 工具的最新版本：

   • Google Cloud CLI，並安裝下列額外元件：

     • kubectl
     • cbt
     • Terraform CLI (1.9.x 以上版本)
     • Helm CLI (3.9.x 以上版本)

   您可以使用任何用戶端環境部署 MDE，但從 Cloud Shell 部署可節省時間，因為 Cloud Shell 已安裝大部分必要工具。

   啟用 Cloud Shell

3. 您擁有 MDE Google Cloud 專案的完整存取權，以及原始部署作業所用設定檔的存取權：

   • 服務帳戶 JSON 金鑰檔案：mde-imgs-service-account-key.json。
   • Terraform：input.tfvars。
   • Terraform：backend.conf。
   注意： MDE 1.5 版不需要服務帳戶 JSON 金鑰檔案。

   本指南中的所有 gcloud 指令都假設預設專案已設為 MDE 部署專案。您可以使用下列指令設定預設專案：

   gcloud config set project PROJECT_ID
   

   將 PROJECT_ID 替換為 MDE 部署專案 ID。

4. 您已取得 MDE GKE 叢集的憑證。如果尚未執行，請使用下列指令：

   export CLUSTER_NAME="mde-gke"
   export CLUSTER_LOCATION=$(gcloud container clusters list --filter="name:$CLUSTER_NAME" --format="value(LOCATION)" )
   
   # when upgrading to 1.5.2 we need to enable DNS endpoint on GKE cluster to allow Terraform connect to it
   gcloud container clusters update $CLUSTER_NAME --region $CLUSTER_LOCATION --enable-dns-access
   
   export KUBE_CONFIG_PATH=~/.kube/config
   gcloud container clusters get-credentials $CLUSTER_NAME --region $CLUSTER_LOCATION --dns-endpoint
   

   如果變更了預設名稱 (mde-gke)，請將 CLUSTER_NAME 替換為叢集名稱。如果 kubeconfig 不在預設路徑上，請變更 KUBE_CONFIG_PATH。

升級

本節提供使用 Terraform 升級的指南。

1. 更新 Terraform 服務帳戶權限，新增 MDE 1.4.0 以上版本的新必要權限。您可以使用下列指令新增這些項目：

   export PROJECT_ID=$(gcloud config get-value project)
   export SA_TERRAFORM="mde-tf"
   
   gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member="serviceAccount:$SA_TERRAFORM@$PROJECT_ID.iam.gserviceaccount.com" \
   --role='roles/file.editor'
   

2. 使用下列指令備份舊的部署資料夾：

   cp -r MDE_FOLDER MDE_FOLDER_BACKUP
   

   將 MDE_FOLDER 和 MDE_FOLDER_BACKUP 替換為 MDE 資料夾和備份資料夾的名稱。

3. 下載並解壓縮最新版 MDE 解決方案發布套件：

   注意： 如要存取 MDE 部署資產，必須先獲得 Google Cloud 團隊核准。如果您有興趣測試或部署 MDE，建議盡快與他們聯絡。如果您不知道自己的 Google Cloud 帳戶團隊是誰，請使用畫面右上方的「Contact Us」按鈕，我們很快就會與您聯絡。
   1. 下載解決方案套件。
   2. 將套件解壓縮到用戶端環境。
   3. 使用 cd 指令移至新發布資料夾。

4. 如要升級至 1.4.x 版，請使用下列指令，將備份中的檔案複製到新資料夾 (檔案路徑可能有所不同)：

   cp ../MDE_FOLDER_BACKUP/mde-imgs-service-account-key.json .
   cd deployment/terraform
   cp ../../../MDE_FOLDER_BACKUP/deployment/terraform/input.tfvars .
   cp ../../../MDE_FOLDER_BACKUP/deployment/terraform/backend.conf .
   

   如要升級至 1.5.1 版，請只複製下列檔案：

   cd deployment/terraform
   cp ../../../MDE_FOLDER_BACKUP/deployment/terraform/input.tfvars .
   cp ../../../MDE_FOLDER_BACKUP/deployment/terraform/backend.conf .
   

   將 MDE_FOLDER_BACKUP 替換為 MDE 備份資料夾名稱。

5. 如要從 v1.4.x 升級至 v1.5.x，或從 v1.5.0 升級至 v1.5.1，請執行發布套件中隨附的升級前指令碼：

   注意： 請務必在所有 Pub/Sub 訂閱項目排空後執行這項指令碼。您可以透過「/configuration/v1/processing:stop」API 或 MDE 使用者介面中的 Messages processing 切換鈕停止處理程序，讓系統排空，再執行這項指令碼。

   # Execute script from the upgrade/1.5 directory and return to the terraform directory
   cd ../../upgrade/1.5
   export BQ_PROJECT_ID=$(gcloud config get-value project)
   export PUBSUB_PROJECT_ID=$(gcloud config get-value project)
   sh migrate-metadata-instance-bq-table.sh "$BQ_PROJECT_ID" "$PUBSUB_PROJECT_ID"
   cd ../../deployment/terraform
   

6. 如要升級至 1.5.2，您需要切換 Kubernetes 供應商，使用 providers.tf 檔案中的本機 kubeconfig，方法是執行下列指令：

   provider "kubernetes" {
   config_path            = "~/.kube/config"
   # host                   = "https://${local.gke_host}"
   # token                  = data...
   # cluster_ca_certificate = local.gke_ca_cert
   }
   
   provider "helm" {
   kubernetes {
       config_path            = "~/.kube/config"
       # host                   = "https://${local.gke_host}"
       # token                  = data...
       # cluster_ca_certificate = local.gke_ca_cert
   }
   }
   

   注意： 完成升級 (步驟 10 之後) 後，可以還原這項變更，繼續在 Terraform 中使用動態 Kubernetes 設定。

7. 使用下列指令重新載入 Terraform 狀態：

   terraform init -backend-config=backend.conf -reconfigure
   

8. 建立 Terraform 計畫。

   輸入參數準備就緒後，您必須使用下列指令建立 Terraform 計畫。您可以透過方案驗證專案中會建立哪些構件和設定。

   注意： 自 1.5.x 版起，服務帳戶金鑰已不再必要，因此您可能會看到有關 mde_artifact_registry_sa_path 的 Terraform 警告。您可以放心忽略這項警告，或從 input.tfvars 檔案中註解掉或刪除這個變數。

   terraform plan -var-file=./input.tfvars -out=./tfplan
   

   您可以使用下列指令瀏覽預計變更：

   terraform show -no-color ./tfplan > tfplan.txt
   more tfplan.txt
   

   重要事項： 如果 Terraform 在規劃階段顯示錯誤，指出某些以 -materialization 後置字串結尾的 Pub/Sub 訂閱項目因含有 lifecycle.prevent_destroy 旗標而無法刪除，您就必須手動刪除所有以 -materialization 後置字串結尾的 Pub/Sub 主題，以及附加至該主題的訂閱項目。您需要先執行這個步驟，再開始部署作業，確保 MDE 會在部署作業完成後自動建立主題。

9. 使用下列指令套用 Terraform 計畫：

   terraform apply ./tfplan
   

10. 確認部署作業是否成功。

    terraform apply 指令執行完畢後，您應該會看到類似以下的成功訊息 (實際數字取決於具體的部署選項和版本)：

    Apply complete! Resources: 1 added, 34 changed, 0 destroyed.
    

升級後

升級完成後，請根據先前 MDE 部署作業的狀態，執行下列一或多個步驟。

現有類型的 BigQuery 檢視區塊

如果您是從 1.4.x 之前的版本升級，系統不會為建立的類型建立 Analytics 檢視畫面，因為這項功能是在 1.4.0 版中推出。您必須再次啟用現有類型，才能重新建立 Analytics 檢視畫面。您可以在隨版本發布的 Postman 套件中查看 /activate 端點。

GKE 叢集 Filestore 驅動程式

如果 GKE 叢集 Pod 啟動或停滯在 ContainerCreating 狀態，可能是因為 Filestore 驅動程式未啟用。如要啟用這項功能，請按照部署指南中的步驟操作。