המרת ההגדרות של Deployment Manager באמצעות DM Convert

בדף הזה מוסבר איך להשתמש ב-DM Convert כדי להמיר את ההגדרות של Deployment Manager ל-Kubernetes Resource Model (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 configuration language, ‏ Terraform) או לפורמט KRM ‏ (Kubernetes Resource Model).

  3. שימוש ב-Terraform או ב-Config Connector כדי להחיל את ההגדרה שהומרה.

  4. ביטול הפריסה הקיימת של Deployment Manager.

הכנת הפריסה הקיימת

הכלי DM Convert פועל על קובצי תצורה ותבניות של Deployment Manager. במהלך ההוראות במדריך הזה, הקבצים האלה ייווצרו ויישמרו באופן מקומי כקלט לכלי DM Convert.

אתם יכולים ליצור קובץ הגדרות בעצמכם או להשיג הגדרות מפריסה פעילה.

המרת קובץ תצורה

כדי לנסות את הממיר, אפשר להשתמש בהגדרות לדוגמה הבאות. מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud ושומרים את התוכן שלמטה בקובץ בשם 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)"

# The output should look like this:
# 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: פורמט הפלט של ההמרה. אפשר להשתמש ב-TF ל-Terraform או ב-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
מפורטת רשימה מקיפה של שיטות מומלצות להפעלת Terraform ב-Google Cloud, כולל שימוש ב-Cloud Storage לאחסון ולניהול של מצב Terraform מרחוק.

אחרי שממירים את המשאבים של 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, אפשר להריץ את הפקודה plan של Terraform כדי לבדוק אם יש שינויים בין המצב לבין הגדרות 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 ולהשתמש בממשק שורת הפקודה (CLI) של bq כדי לאמת את השינויים:

# 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, צריך אשכול Kubernetes עם Config Connector מותקן. כדי ליצור אשכול בדיקה, אפשר לעיין במאמר בנושא התקנה באמצעות תוסף GKE.

ב-Cloud Shell, מוודאים שפרטי הכניסה של kubectl מוגדרים לאשכול GKE שבו רוצים להשתמש. מחליפים את GKE_CLUSTER בשם האשכול ומריצים את הפקודה הבאה:

gcloud container clusters get-credentials GKE_CLUSTER

פורסים את ההגדרות האישיות שהומרו בפורמט KRM באמצעות kubectl

כדי לפרוס את הגדרות ה-KRM שהומרו באמצעות kubectl, מריצים את הפקודות הבאות:

# 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

השלבים הבאים

כדאי לעיין בשיטות המומלצות ובהמלצות לגבי ההגדרה שהומרה.