Convertir des configurations Deployment Manager avec DM Convert

Cette page décrit le processus d'utilisation de DM Convert pour convertir vos configurations Deployment Manager au modèle de ressources Kubernetes (KRM) ou à Terraform.

Configurer votre environnement

Configurer vos variables d'environnement

Enregistrez les variables d'environnement suivantes, utilisées par la suite de ce guide:

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

# Enable the Cloud Build API
gcloud services enable cloudbuild.googleapis.com

# Grant Cloud Build service account permission to manage Google Cloud Storage
# bucket and DM deployments
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
--member=serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com \
--role=roles/storage.admin

gcloud projects add-iam-policy-binding ${PROJECT_ID} \
--member=serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com \
--role=roles/deploymentmanager.editor

Configurer vos outils

Vous devez avoir accès aux outils suivants:

  • gcloud

  • gsutil

  • docker

  • kubectl

Si vous utilisez Cloud Shell pour exécuter DM Convert, vous y avez déjà accès.

Ouvrir dans Cloud Shell

Convertir vos configurations

En règle générale, vous allez migrer votre configuration Deployment Manager vers Terraform ou KRM en procédant comme suit:

  1. Préparer un déploiement Deployment Manager pour la conversion.

  2. Conversion de la configuration au format HCL (langage de configuration HashiCorp pour Terraform) ou au format KRM (modèle de ressource Kubernetes).

  3. Utiliser Terraform ou Config Connector pour appliquer la configuration convertie

  4. Abandonner le déploiement de Deployment Manager existant

Préparer votre déploiement existant

DM Convert utilise des fichiers et des modèles de configuration Deployment Manager. Pour fournir ces fichiers et modèles à DM Convert, vous devez utiliser un bucket Cloud Storage.

Pour créer un bucket Cloud Storage afin de stocker votre configuration Deployment Manager dans $BUCKET_URI, exécutez les commandes suivantes:

export BUCKET_NAME=$PROJECT_ID-dm-config
export BUCKET_URI=gs://$BUCKET_NAME
gsutil mb $BUCKET_URI

# This is where we will store DM configuration to be converted
export DM_CONFIG_URI=$BUCKET_URI/dm

Vous pouvez ajouter un fichier de configuration directement au bucket Cloud Storage ou acquérir une configuration à partir d'un déploiement en direct.

Convertir un fichier de configuration

Vous pouvez utiliser l'exemple de configuration suivant pour tester le convertisseur. Remplacez PROJECT_ID par l'ID de votre projet Google Cloud et enregistrez le contenu ci-dessous dans un fichier nommé 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

Après avoir enregistré le fichier, copiez-le dans le bucket Cloud Storage que vous avez créé précédemment:

gsutil cp ./deployment.yaml $DM_CONFIG_URI/deployment.yaml

Attribuez le rôle roles/bigquery.dataEditor (Identity and Access Management) à votre compte de service Cloud Build:

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member=serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com \
--role=roles/bigquery.dataEditor

Acquérir une configuration à partir d'un déploiement en direct

Si vous souhaitez acquérir et convertir la configuration d'un déploiement en direct, vous pouvez récupérer la configuration développée et l'enregistrer sur le disque en exécutant les commandes suivantes, en remplaçant DEPLOYMENT_NAME par le nom du déploiement déploiement.

Cloud Build

export DEPLOYMENT_NAME=[DEPLOYMENT_NAME]
export MANIFEST_NAME=$(gcloud deployment-manager deployments \
 describe $DEPLOYMENT_NAME \
  --project $PROJECT_ID --format="value(deployment.manifest)" |\
  grep -oEi "manifest-[0-9]+")
gcloud deployment-manager manifests describe $MANIFEST_NAME \
  --deployment $DEPLOYMENT_NAME --project $PROJECT_ID \
  --format="value(expandedConfig)" > deployment.yaml

# Grant additional roles to allow the Cloud Build service account to manage the
# resources in your deployment. For a list of roles, see
# https://cloud.google.com/iam/docs/understanding-roles.
# For example:
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member=serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com \
--role=roles/pubsub.editor

# Alternatively, you may grant roles/editor for testing purposes:
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member=serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com \
--role=roles/editor

Itinéraire alternatif

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

# 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 file ./$DEPLOYMENT_NAME.yaml
gcloud deployment-manager manifests describe $MANIFEST_NAME \
  --deployment $DEPLOYMENT_NAME --project $PROJECT_ID \
  --format="value(expandedConfig)" > $DEPLOYMENT_NAME.yaml

Après avoir enregistré le fichier, copiez-le dans le bucket Cloud Storage que vous avez créé précédemment:

gsutil cp ./deployment.yaml $DM_CONFIG_URI/deployment.yaml

Convertir un déploiement existant

Ce guide utilise Cloud Build pour le processus de conversion.

La définition de compilation lit la configuration Deployment Manager à partir du bucket Cloud Storage $DM_CONFIG_URI, la convertit au format KRM ou Terraform, puis enregistre le résultat dans le même bucket Cloud Storage.

Copiez le contenu suivant dans un fichier nommé cloudbuild_convert.yaml:

steps:
- id: '[FETCH_DM_CONFIG]'
  name: 'gcr.io/cloud-builders/gsutil'
  entrypoint: 'sh'
  args:
  - '-c'
  - |
      mkdir dm
      gsutil cp "${_BUCKET_URI}/dm/*" dm/.
      mkdir "${_OUTPUT_FORMAT}"

- id: '[CONVERT_DM_CONFIG]'
  name: '${_DM_CONVERT_IMAGE}'
  args: ['--config', './dm/deployment.yaml',
         '--project_id', '${PROJECT_ID}',
          '--project_number', '${PROJECT_NUMBER}',
          '--output_format', '${_OUTPUT_FORMAT}',
          '--output_file', '${_OUTPUT_FORMAT}/${_OUTPUT_FILE}',
          '--deployment_name', '${_DEPLOYMENT_NAME}']

- id: '[EXPORT_OUTPUT_TO_STORAGE_BUCKET]'
  name: 'gcr.io/cloud-builders/gsutil'
  entrypoint: 'sh'
  args:
  - '-c'
  - |
      gsutil cp "${_OUTPUT_FORMAT}/${_OUTPUT_FILE}" \
        "${_BUCKET_URI}/output/${_OUTPUT_FILE}"

Vous pouvez appeler Cloud Build à partir du même dossier que cloudbuild_convert.yaml en fournissant les paramètres suivants:

  • _BUCKET_URI: bucket Cloud Storage dans lequel lire une configuration Deployment Manager et enregistrer la sortie convertie.

  • _OUTPUT_FORMAT: format de sortie de la conversion. Il peut s'agir de KRM pour KRM ou de TF pour Terraform.

  • _OUTPUT_FILE: nom du fichier dans lequel le résultat converti sera enregistré dans le bucket Cloud Storage.

  • _DM_CONVERT_IMAGE: image de conteneur à utiliser.

  • _DEPLOYMENT_NAME: nom du déploiement. Ceci est pertinent si vous utilisez des modèles dans votre configuration Deployment Manager, ainsi que la variable d'environnement deployment. Pour en savoir plus, consultez la page Utiliser une variable d'environnement.

Exemples de conversions

KRM

Pour convertir la configuration au format KRM et l'enregistrer dans $BUCKET_URI/output/krm_resources.yaml, exécutez la commande suivante:

export KRM_RESOURCES=krm_resources.yaml

gcloud builds submit . --config cloudbuild_convert.yaml \
--substitutions=_DM_CONVERT_IMAGE=$DM_CONVERT_IMAGE,_BUCKET_URI=$BUCKET_URI,\
_DEPLOYMENT_NAME=test-conversion-to-krm,\
_OUTPUT_FORMAT=KRM,_OUTPUT_FILE=$KRM_RESOURCES

# Print output file
gsutil cat $BUCKET_URI/output/$KRM_RESOURCES

Terraform

Pour convertir la configuration au format HCL et l'enregistrer en tant que $BUCKET_URI/output/tf_resources.tf, exécutez la commande suivante:

export TF_RESOURCES=tf_resources.tf

gcloud builds submit . --config cloudbuild_convert.yaml \
--substitutions=_DM_CONVERT_IMAGE=$DM_CONVERT_IMAGE,_BUCKET_URI=$BUCKET_URI,\
_DEPLOYMENT_NAME=test-conversion-to-tf,\
_OUTPUT_FORMAT=TF,_OUTPUT_FILE=$TF_RESOURCES

# Print output file
gsutil cat $BUCKET_URI/output/$TF_RESOURCES

Appliquer votre configuration convertie

KRM

Configurer Config Connector

Pour activer les ressources dans les fichiers de configuration KRM, vous devez disposer d'un cluster Kubernetes sur lequel Config Connector est installé. Pour créer un cluster de test, reportez-vous à la section Effectuer l'installation à l'aide du module complémentaire GKE.

Dans Cloud Shell, assurez-vous que vos identifiants kubectl sont configurés pour le cluster GKE que vous souhaitez utiliser. Remplacez GKE_CLUSTER par le nom du cluster, puis exécutez la commande suivante:

gcloud container clusters get-credentials GKE_CLUSTER

Déployer votre configuration KRM convertie à l'aide de kubectl

Pour déployer votre configuration KRM convertie à l'aide de kubectl, exécutez les commandes suivantes:

# Copy the converted configuration from the storage bucket
gsutil cp $BUCKET_URI/output/$KRM_RESOURCES $KRM_RESOURCES

# Replace [CONFIG_CONNECTOR_NAMESPACE] with your namespace
export KCC_NAMESPACE=[CONFIG_CONNECTOR_NAMESPACE]

kubectl apply -n $KCC_NAMESPACE -f $KRM_RESOURCES

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

Terraform

Configurer Terraform

Utilisez le bucket Cloud Storage que vous avez créé précédemment pour configurer Terraform avec votre projet Google Cloud:

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

# Configure Cloud Storage remote backend to store state in gs://$BUCKET_NAME/tfstate
cat <<EOF > echo > backend.tf
terraform {
backend "gcs" {
  bucket = "$BUCKET_NAME"
  prefix = "tfstate"
}
}
EOF

Déployer votre configuration convertie à l'aide de Terraform

Créez un fichier local appelé cloudbuild_tf.yaml dans le même dossier que les fichiers main.tf et backend.tf que vous avez créés précédemment, et copiez-y les éléments suivants:

steps:
- id: '[FETCH_DM_CONFIG]'
  name: 'gcr.io/cloud-builders/gsutil'
  entrypoint: 'sh'
  args:
  - '-c'
  - |
      # Fetch the latest manifest for the given deployment
      gsutil cp $_BUCKET_URI/output/*.tf .

- id: '[APPLY_USING_TERRAFORM]'
  name: 'hashicorp/terraform'
  entrypoint: 'sh'
  args:
  - '-c'
  - |
      echo "***************  TERRAFORM INIT  ******************"
      # 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 --auto-approve

Importer des ressources existantes

Si vous convertissez un déploiement existant, utilisez terraform import RESOURCE_TYPE RESOURCE_ID pour importer les ressources existantes au lieu de les provisionner à nouveau à l'aide de terraform apply.

Par exemple, si votre déploiement existant était:

resources:
  - type: pubsub.v1.topic
    name: sample-pubsub-topic
    properties:
      topic: sample-pubsub-topic
  - type: pubsub.v1.subscription
    name: sample-pubsub-subscription
    properties:
      topic: $(ref.sample-pubsub-topic.name)
      subscription: sample-pubsub-subscription

Selon la section import de la documentation Terraform pour google_pubsub_topic, terraform import peut prendre L'un des formats suivants:

$ terraform import google_pubsub_topic.default projects/PROJECT_NAME/topics/NAME
$ terraform import google_pubsub_topic.default PROJECT_NAME/NAME
$ terraform import google_pubsub_topic.default NAME

Effectuez les substitutions suivantes:

  • PROJECT_NAME est l'ID de votre projet.

  • NAME est le nom de la ressource Deployment Manager, par exemple sample-pubsub-topic.

  • default est le nom de la ressource Terraform, qui est le nom de la ressource Deployment Manager avec tous les caractères - remplacés par _. Vous pouvez également rechercher le nom de la ressource à l'aide de gsutil cat $BUCKET_URI/output/$TF_RESOURCES pour vérifier la configuration Terraform convertie.

Une fois les substitutions effectuées, votre commande doit ressembler à ce qui suit:

$ terraform import google_pubsub_topic.sample_pubsub_topic
$PROJECT_ID/sample-pubsub-topic

La documentation Terraform pour google_pubsub_subscription indique les formats possibles suivants:

$ terraform import google_pubsub_subscription.default projects/PROJECT_NAME/subscriptions/NAME
$ terraform import google_pubsub_subscription.default PROJECT_NAME/NAME
$ terraform import google_pubsub_subscription.default NAME

Voici une commande terraform import possible:

$ terraform import google_pubsub_subscription.sample_pubsub_subscription
$PROJECT_ID/sample-pubsub-subscription

La définition de Cloud Build pour cette commande est la suivante:

steps:
- id: '[FETCH_DM_CONFIG]'
  name: 'gcr.io/cloud-builders/gsutil'
  entrypoint: 'sh'
  args:
  - '-c'
  - |
      # Fetch the latest manifest for the given deployment
      gsutil cp $_BUCKET_URI/output/*.tf .

- id: '[APPLY_USING_TERRAFORM]'
  name: 'hashicorp/terraform'
  entrypoint: 'sh'
  args:
  - '-c'
  - |
      echo "***************  TERRAFORM INIT  ******************"
      # NOTE: if Terraform state gets corrupted during testing,
      # use init --reconfigure to reset backend
      terraform init
      echo "***************  TERRAFORM PLAN  ******************"
      terraform plan
      echo "**************  TERRAFORM IMPORT  ******************"
      terraform import google_pubsub_topic.sample_pubsub_topic $PROJECT_ID/sample-pubsub-topic
      terraform import google_pubsub_subscription.sample_pubsub_subscription $PROJECT_ID/sample-pubsub-subscription

Vous pouvez éventuellement utiliser Deployment Manager pour supprimer le déploiement et le recréer avec Terraform à l'aide de terraform apply.

Vous pouvez appeler Cloud Build à partir du même dossier que le fichier que vous avez créé précédemment en fournissant les paramètres suivants:

  • _BUCKET_URI: bucket de stockage dans lequel vous avez stocké votre configuration Terraform convertie.
gcloud builds submit . --config cloudbuild_tf.yaml \
--substitutions=_BUCKET_URI=$BUCKET_URI

Effectuer un nettoyage

Nettoyer l'ensemble de données et l'exemple de table

KRM

Pour nettoyer l'ensemble de données et la table BigQuery de l'exemple de configuration, exécutez la commande suivante:

# If the resource was created via Config Connector:
kubectl delete -n $KCC_NAMESPACE -f $KRM_RESOURCES

Terraform

Enregistrez la définition Cloud Build suivante dans cloudbuild_tf_destroy.yaml:

# If the resource was created via Terraform, save the following Cloud Build steps into cloudbuild_tf_destroy.yaml:
steps:
- id: '[FETCH_DM_CONFIG]'
  name: 'gcr.io/cloud-builders/gsutil'
  entrypoint: 'sh'
  args:
  - '-c'
  - |
      # Fetch the latest manifest for the given deployment
      gsutil cp $_BUCKET_URI/output/*.tf .

- id: '[DESTROY_USING_TERRAFORM]'
  name: 'hashicorp/terraform'
  entrypoint: 'sh'
  args:
  - '-c'
  - |
      echo "***************  TERRAFORM INIT  ******************"
      terraform init
      # NOTE: if Terraform state gets corrupted during testing,
      # use init --reconfigure to reset backend

      # Remove delete protection on BigQuery table
      sed -i "/resource \"google_bigquery_table\"/a deletion_protection=\"false\"" tf_resources.tf
      terraform apply --auto-approve

      echo "***************  TERRAFORM DESTROY ****************"
      terraform destroy --auto-approve

Après avoir enregistré la définition, exécutez la commande suivante:

gcloud builds submit . --config cloudbuild_tf_destroy.yaml \
--substitutions=_BUCKET_URI=$BUCKET_URI

Nettoyer votre déploiement

Pour abandonner un déploiement actif que vous avez bien converti en KRM ou Terraform, exécutez la commande suivante:

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