Convertir las configuraciones de Deployment Manager con DM Convert

En esta página se describe el proceso para usar DM Convert y convertir tus configuraciones de Deployment Manager a Kubernetes Resource Model (KRM) o Terraform.

Configurar un entorno

Configurar las variables de entorno

Guarda las siguientes variables de entorno, que se usan en el resto de esta guía:

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"

Configurar las herramientas

Debes tener acceso a las siguientes herramientas:

  • gcloud

  • docker

  • kubectl

  • bq

  • jq

Si usas Cloud Shell para ejecutar DM Convert, ya tienes acceso a ellos.

Abrir en Cloud Shell

Convertir configuraciones

A grandes rasgos, para migrar la configuración de Deployment Manager a Terraform o KRM, debes hacer lo siguiente:

  1. Preparar un despliegue de Deployment Manager para la conversión.

  2. Convierte la configuración al formato HCL (lenguaje de configuración de HashiCorp, para Terraform) o KRM (modelo de recursos de Kubernetes).

  3. Usar Terraform o Config Connector para aplicar la configuración convertida.

  4. Abandonar el despliegue de Deployment Manager.

Preparar una implementación

DM Convert funciona con archivos de configuración y plantillas de Deployment Manager. A lo largo de la guía, estos archivos se crearán y se guardarán de forma local como entrada para la herramienta DM Convert.

Puedes crear un archivo de configuración o adquirir una configuración de una implementación activa.

Convertir un archivo de configuración

Puedes usar la siguiente configuración de ejemplo para probar el convertidor. Sustituye PROJECT_ID por el ID de tu proyecto Google Cloud y guarda el contenido siguiente en un archivo llamado 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

  • Adquirir una configuración de una implementación activa

    Si quieres obtener y convertir la configuración de un despliegue activo, puedes recuperar la configuración ampliada y guardarla en el disco ejecutando los siguientes comandos. Sustituye DEPLOYMENT_NAME por el nombre del despliegue.

    # 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

Convertir un despliegue

Para convertir los recursos de deployment.yaml al formato HCL o KRM y guardarlos como resultados convertidos, ejecuta el siguiente comando en el mismo directorio que deployment.yaml con las sustituciones que quieras:

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

Haz las siguientes sustituciones:

  • OUTPUT_FORMAT: el formato de salida de la conversión. Puede ser TF para Terraform o KRM para KRM.

  • OUTPUT_FILE: Nombre del archivo en el que se guarda el resultado convertido.

  • (Solo Terraform) OUTPUT_IMPORT_FILE: nombre del archivo en el que se guardan los comandos de importación de Terraform. Si se especifica una marca project_id, los comandos de importación se generarán en función de esa marca. Si no se especifica ninguna marca project_id, los comandos de importación se generan en función del atributo projectId de la configuración del recurso.

  • DEPLOYMENT_NAME: el nombre del despliegue. Esto es importante si usas plantillas en tu configuración de Deployment Manager y también usas la variable de entorno deployment. Para obtener más información, consulta Usar una variable de entorno.

Ver las conversiones

# Print output file
cat OUTPUT_FILE

Aplicar la configuración convertida

Terraform

Configurar Terraform

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

Una vez que hayas convertido tus recursos de Deployment Manager a Terraform, puedes usar Terraform para crear recursos desplegando directamente la configuración convertida.

Desplegar la configuración convertida con 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

(Opcional) Importar recursos

Si vas a convertir una implementación que ya tienes y quieres usar Terraform para gestionar sus recursos sin volver a implementarla, puedes hacerlo con la función de importación de Terraform.

En esta sección, usarás deployment.yaml para el proceso de importación.

Inicializa Terraform:

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

Los comandos de importación se generan y se guardan en OUTPUT_IMPORT_FILE. Para revisar su contenido, ejecuta el siguiente comando:

cat OUTPUT_IMPORT_FILE

Para importar los recursos de deployment.yaml, ejecuta el siguiente comando:

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

Una vez que hayas importado los recursos a tu estado de Terraform, puedes verificar si hay algún cambio entre el estado y la configuración de Terraform generada ejecutando el comando plan de Terraform:

terraform plan

Se obtiene el siguiente resultado:

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.

Acepta este cambio en el plan de Terraform, ya que elimina las etiquetas específicas de Deployment Manager, como goog-dm, que no son necesarias cuando Terraform gestiona los recursos.

Para aplicar la configuración de Terraform, ejecuta el siguiente comando:

# Accept changes by entering yes when prompted
terraform apply

Ahora, todos los recursos definidos en deployment.yaml están gestionados por Terraform.

Por ejemplo, si quieres verificar que Terraform está gestionando los recursos convertidos, puedes hacerlo modificando ligeramente la configuración de Terraform. Para ello, cambia el tiempo de vencimiento predeterminado de la tabla en el recurso google_bigquery_dataset.bigquerydataset:

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

Después de hacer los cambios, puedes aplicar la configuración de Terraform y usar la bq interfaz de línea de comandos (CLI) para verificar los cambios:

# 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'

El resultado que recibas debe coincidir con los valores proporcionados en la configuración de Terraform actualizada, lo que confirma que Terraform ahora gestiona estos recursos.

KRM

Configurar Config Connector

Para activar los recursos de los archivos de configuración de KRM, necesitas un clúster de Kubernetes con Config Connector instalado. Para crear un clúster de prueba, consulta el artículo Instalar con el complemento de GKE.

En Cloud Shell, comprueba que tus credenciales de kubectl estén configuradas para el clúster de GKE que quieras usar. Sustituye GKE_CLUSTER por el nombre del clúster y ejecuta el siguiente comando:

gcloud container clusters get-credentials GKE_CLUSTER

Implementa la configuración de KRM convertida con kubectl.

Para implementar la configuración de KRM convertida con kubectl, ejecuta los siguientes comandos:

# 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

Limpieza

Limpiar el conjunto de datos y la tabla de muestra

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

Para limpiar el conjunto de datos y la tabla de BigQuery de la configuración de ejemplo, ejecuta lo siguiente:

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

Abandonar el despliegue de ejemplo de Deployment Manager

Para abandonar una implementación activa que hayas convertido correctamente a KRM o Terraform, ejecuta el siguiente comando:

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

Recursos admitidos para la conversión

Terraform

Para enumerar los recursos compatibles con Terraform, ejecuta el siguiente comando:

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

Para enumerar los recursos admitidos de KRM, ejecuta el siguiente comando:

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

Pasos siguientes

Consulta las prácticas recomendadas para la configuración convertida.