使用 DM Convert 轉換 Deployment Manager 設定

本頁說明如何使用 DM Convert，將 Deployment Manager 設定轉換為 Kubernetes 資源模型 (KRM) 或 Terraform。

設定環境

設定環境變數

儲存下列環境變數，本指南的其餘部分會使用這些變數：

export PROJECT_ID=$(gcloud config get-value project) \
export DM_CONVERT_IMAGE="us-central1-docker.pkg.dev/\
dm-convert-host/deployment-manager/dm-convert:public-preview"

設定工具

您必須能存取下列工具：

  • gcloud

  • docker

  • kubectl

  • bq

  • jq

如果您使用 Cloud Shell 執行 DM Convert，則已具備存取權。

在 Cloud Shell 開啟

轉換設定

整體來說，您可以透過下列方式將 Deployment Manager 設定遷移至 Terraform 或 KRM：

  1. 準備要轉換的 Deployment Manager 部署作業。

  2. 將設定轉換為 HCL (HashiCorp 設定語言，適用於 Terraform) 或 KRM (Kubernetes 資源模型) 格式。

  3. 使用 Terraform 或 Config Connector 套用轉換後的設定。

  4. 放棄現有的 Deployment Manager 部署作業。

準備現有的部署作業

DM Convert 會處理 Deployment Manager 設定檔和範本。在本指南中，這些檔案會建立並儲存在本機，做為 DM Convert 工具的輸入內容。

您可以自行建立設定檔，也可以從實際部署作業取得設定。

轉換設定檔

您可以使用下列設定範例試用轉換器。將 PROJECT_ID 替換為您的 Google Cloud 專案 ID，然後將下列內容儲存至名為 deployment.yaml 的檔案：

  resources:
  - name: bigquerydataset
    type: bigquery.v2.dataset
    properties:
      datasetReference:
        datasetId: bigquerydataset
        projectId: PROJECT_ID
      defaultTableExpirationMs: 36000000
      location: us-west1
  - type: bigquery.v2.table
    name: bigquerytable
    properties:
      datasetId: bigquerydataset
      labels:
        data-source: external
        schema-type: auto-junk
      tableReference:
        projectId: PROJECT_ID
        tableId: bigquerytable
    metadata:
      dependsOn:
      - bigquerydataset

  • 從實際部署作業取得設定

    如要取得及轉換即時部署的設定，您可以執行下列指令來擷取展開的設定，並將其儲存至磁碟，請將 DEPLOYMENT_NAME 替換為部署的名稱。

    # Configure your project/deployment
DEPLOYMENT_NAME=DEPLOYMENT_NAME
PROJECT_ID=PROJECT_ID

# Fetch the latest manifest for the given deployment
gcloud deployment-manager deployments describe $DEPLOYMENT_NAME \
  --project $PROJECT_ID --format="value(deployment.manifest)"
https://www.googleapis.com/deploymentmanager/v2/projects/$PROJECT_ID/global/deployments/bq/manifests/manifest-1618872644848

# The manifest name is the last path segment from the URI
# in the above command output
MANIFEST_NAME="manifest-1618872644848"
# Save the expanded manifest to deployment.yaml
gcloud deployment-manager manifests describe $MANIFEST_NAME \
  --deployment $DEPLOYMENT_NAME --project $PROJECT_ID \
  --format="value(expandedConfig)" > deployment.yaml

轉換部署作業

如要將 deployment.yaml 中的資源轉換為 HCL 或 KRM 格式，並儲存為轉換後的輸出內容，請在 deployment.yaml 所在的目錄中執行下列指令，並進行所需的替換：

CONVERTED_RESOURCES=OUTPUT_FILE

docker run --rm -it --workdir=/convert \
--volume=$(pwd):/convert \
$DM_CONVERT_IMAGE \
--config deployment.yaml \
--output_format OUTPUT_FORMAT \
--output_file OUTPUT_FILE \
--output_tf_import_file OUTPUT_IMPORT_FILE \
--deployment_name DEPLOYMENT_NAME \
--project_id $PROJECT_ID

請進行下列替換：

  • OUTPUT_FORMAT：轉換的輸出格式。 可以是 Terraform 的 TF，也可以是 KRM 的 KRM。

  • OUTPUT_FILE：轉換後的輸出內容儲存檔案名稱。

  • (僅限 Terraform) OUTPUT_IMPORT_FILE：儲存 Terraform 匯入指令的檔案名稱。如果指定 project_id 旗標，系統就會根據該旗標產生匯入指令。如果未指定 project_id 旗標，系統會根據資源設定中的 projectId 屬性產生匯入指令。

  • DEPLOYMENT_NAME：部署作業的名稱。如果您在 Deployment Manager 設定中使用範本，且也使用 deployment 環境變數，這項資訊就非常重要。詳情請參閱「使用環境變數」。

查看轉換

# Print output file
cat OUTPUT_FILE

套用轉換後的設定

Terraform

設定 Terraform

# Configure default project
cat <<EOF > echo > main.tf
provider "google" {
  project = "$PROJECT_ID"
}
EOF

將 Deployment Manager 資源轉換為 Terraform 後，您可以直接部署轉換後的設定，藉此使用 Terraform 建立資源。

使用 Terraform 部署轉換後的設定

# NOTE: if Terraform state gets corrupted during testing,
# use init --reconfigure to reset backend
terraform init
echo "***************  TERRAFORM PLAN  ******************"
terraform plan
echo "**************  TERRAFORM APPLY  ******************"
terraform apply

(選用) 匯入現有資源

如果您要轉換現有部署作業，並使用 Terraform 管理資源，但不想重新部署，可以透過 Terraform 匯入功能達成目的。

在本節中，您將使用 deployment.yaml 進行匯入程序。

初始化 Terraform：

# NOTE: if Terraform state gets corrupted during testing,
# use init --reconfigure to reset backend
terraform init

系統會產生匯入指令，並儲存至 OUTPUT_IMPORT_FILE。 如要查看內容，請執行下列指令：

cat OUTPUT_IMPORT_FILE

如要匯入 deployment.yaml 的資源，請執行下列指令：

# Make the import file executable
chmod +x OUTPUT_IMPORT_FILE
# Perform the import
./OUTPUT_IMPORT_FILE

將資源匯入 Terraform 狀態後，您可以執行 Terraform plan 指令，確認狀態與產生的 Terraform 設定之間是否有任何變更：

terraform plan

這會產生下列輸出內容：

Terraform will perform the following actions:

# google_bigquery_dataset.bigquerydataset will be updated in-place
~ resource "google_bigquery_dataset" "bigquerydataset" {
    ...
    ~ labels = {
        # the label value will be based on the deployment name and may not
        # match
        - "goog-dm" = "bq-for-import" -> null
      }
    ...
  }

# google_bigquery_table.bigquerytable will be updated in-place
~ resource "google_bigquery_table" "bigquerytable" {
    ...
    ~ labels = {
        # the label value will be based on the deployment name and may not
        # match
        - "goog-dm" = "bq-for-import" -> null
      }
    ...
  }

Plan: 0 to add, 2 to change, 0 to destroy.

接受 Terraform 方案中的這項變更，因為這項變更會移除 Deployment Manager 專屬標籤 (即 goog-dm)，資源由 Terraform 管理後就不需要這些標籤。

如要套用 Terraform 設定，請執行下列指令：

# Accept changes by entering yes when prompted
terraform apply

現在 deployment.yaml 中定義的所有資源都由 Terraform 管理。

舉例來說，如要確認 Terraform 確實管理已轉換的資源，可以稍微變更 Terraform 設定，修改 google_bigquery_dataset.bigquerydataset 資源中的預設資料表到期時間：

...
# change from 10 hrs to 12 hrs
default_table_expiration_ms = 43200000
...

變更完成後，您可以套用 Terraform 設定，並使用 bq 指令列介面 (CLI) 驗證變更：

# Accept changes by entering yes when prompted
terraform apply
# Access the dataset properties via bq to verify the changes
bq show --format=prettyjson bigquerydataset | jq '.defaultTableExpirationMs'

您收到的輸出內容應與更新後的 Terraform 設定中提供的值相符，確認 Terraform 現在管理這些資源。

KRM

設定 Config Connector

如要啟動 KRM 設定檔中的資源，您需要安裝 Config Connector 的 Kubernetes 叢集。如要建立測試叢集，請參閱「使用 GKE 外掛程式安裝」。

在 Cloud Shell 中，確認 kubectl 憑證已針對要使用的 GKE 叢集設定。將 GKE_CLUSTER 替換為叢集名稱，然後執行下列指令：

gcloud container clusters get-credentials GKE_CLUSTER

使用 kubectl 部署轉換後的 KRM 設定

如要使用 kubectl 部署轉換後的 KRM 設定，請執行下列指令：

# Ensure that the namespace is annotated to create resources in the correct
# project/folder/organization. https://cloud.google.com/config-connector/docs/how-to/install-upgrade-uninstall#specify
kubectl apply -n CONFIG_CONNECTOR_NAMESPACE \
  -f OUTPUT_FILE

# Wait for the resources to become healthy
kubectl wait -n CONFIG_CONNECTOR_NAMESPACE \
  --for=condition=Ready \
  --timeout=5m -f OUTPUT_FILE

清除所用資源

清除範例資料集和資料表

Terraform

# NOTE: if Terraform state gets corrupted during testing,
# use init --reconfigure to reset backend
echo "***************  TERRAFORM INIT  ******************"
terraform init
# Remove delete protection on BigQuery table
sed -i "/resource \"google_bigquery_table\"/a deletion_protection=\"false\"" \
OUTPUT_FILE
terraform apply
echo "***************  TERRAFORM DESTROY ****************"
terraform destroy

KRM

如要清除範例設定中的 BigQuery 資料集和資料表，請執行下列指令：

# If the resource was created via Config Connector:
kubectl delete -n CONFIG_CONNECTOR_NAMESPACE \
  -f OUTPUT_FILE

捨棄範例 Deployment Manager 部署作業

如要放棄已成功轉換為 KRM 或 Terraform 的即時部署作業，請執行下列指令：

gcloud deployment-manager deployments delete DEPLOYMENT_NAME --delete-policy ABANDON

支援轉換的資源

Terraform

如要列出 Terraform 支援的資源，請執行下列指令：

docker run --rm -it \
us-central1-docker.pkg.dev/dm-convert-host/deployment-manager/dm-convert:public-preview \
--output_format tf \
--list_supported_types

KRM

如要列出 KRM 支援的資源，請執行下列指令：

docker run --rm -it \
us-central1-docker.pkg.dev/dm-convert-host/deployment-manager/dm-convert:public-preview \
--output_format krm \
--list_supported_types

後續步驟

請參閱最佳做法和建議，瞭解轉換後的設定。