Converta as suas configurações do Deployment Manager com o DM Convert

Esta página descreve o processo de utilização do DM Convert para converter as suas configurações do Deployment Manager no modelo de recursos do Kubernetes (KRM) ou no Terraform.

Configure o seu ambiente

Configure as variáveis de ambiente

Guarde as seguintes variáveis de ambiente, que o resto deste guia usa:

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"

Configure as suas ferramentas

Tem de ter acesso às seguintes ferramentas:

  • gcloud

  • docker

  • kubectl

  • bq

  • jq

Se usar o Cloud Shell para executar o DM Convert, já tem acesso aos mesmos.

Abra no Cloud Shell

Converta as suas configurações

A um nível elevado, migra a configuração do Deployment Manager para o Terraform ou o KRM da seguinte forma:

  1. Preparar uma implementação do Gestor de Implementações para conversão.

  2. Converter a configuração para o formato HCL (linguagem de configuração da HashiCorp, para o Terraform) ou KRM (modelo de recursos do Kubernetes).

  3. Usando o Terraform ou o Config Connector para aplicar a configuração convertida.

  4. Abandonar a implementação do Deployment Manager existente.

Prepare a implementação existente

O DM Convert funciona com ficheiros de configuração e modelos do Deployment Manager. Ao longo do guia, estes ficheiros são criados e guardados localmente como entrada para a ferramenta DM Convert.

Pode criar um ficheiro de configuração ou adquirir uma configuração a partir de uma implementação em direto.

Converta um ficheiro de configuração

Pode usar a seguinte configuração de exemplo para experimentar o conversor. Substitua PROJECT_ID pelo ID do seu Google Cloud projeto e guarde o conteúdo abaixo num ficheiro denominado 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

  • Adquira uma configuração a partir de uma implementação em direto

    Se quiser adquirir e converter a configuração de uma implementação ativa, pode obter a configuração expandida e guardá-la no disco executando os seguintes comandos, substituindo DEPLOYMENT_NAME pelo nome da implementação.

    # 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

Converta a sua implementação

Para converter recursos em deployment.yaml para o formato HCL ou KRM e guardá-los como resultados convertidos, execute o seguinte comando no mesmo diretório que deployment.yaml com as substituições pretendidas:

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

Faça as seguintes substituições:

  • OUTPUT_FORMAT: o formato de saída da conversão. Pode ser TF para o Terraform ou KRM para o KRM.

  • OUTPUT_FILE: o nome do ficheiro no qual o resultado convertido é guardado.

  • (Apenas Terraform) OUTPUT_IMPORT_FILE: o nome do ficheiro no qual os comandos de importação do Terraform são guardados. Se for especificada uma flag project_id, os comandos de importação são gerados com base nessa flag. Se não for especificado um sinalizador project_id, os comandos de importação são gerados com base no atributo projectId da configuração do recurso.

  • DEPLOYMENT_NAME: o nome da implementação. Isto é relevante se estiver a usar modelos na configuração do Deployment Manager e também estiver a usar a variável de ambiente deployment. Para mais informações, visite o artigo Usar uma variável de ambiente.

Veja as conversões

# Print output file
cat OUTPUT_FILE

Aplique a configuração convertida

Terraform

Configure o Terraform

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

Depois de converter os recursos do Deployment Manager para o Terraform, pode usar o Terraform para criar recursos implementando diretamente a configuração convertida.

Implemente a configuração convertida através do 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) Importe recursos existentes

Se estiver a converter uma implementação existente e quiser usar o Terraform para gerir os respetivos recursos sem reimplementar, pode fazê-lo através da funcionalidade de importação do Terraform.

Para esta secção, vai usar deployment.yaml para o processo de importação.

Inicialize o Terraform:

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

Os comandos de importação são gerados e guardados em OUTPUT_IMPORT_FILE. Para rever o respetivo conteúdo, execute o seguinte comando:

cat OUTPUT_IMPORT_FILE

Para importar os recursos do deployment.yaml, execute o seguinte comando:

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

Depois de importar os recursos para o seu estado do Terraform, pode verificar se existem alterações entre o estado e a configuração do Terraform gerada executando o comando plan do Terraform:

terraform plan

Isto produz o seguinte 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.

Aceite esta alteração no plano do Terraform, uma vez que está a remover etiquetas específicas do Deployment Manager, ou seja, goog-dm, que não são necessárias quando os recursos estão a ser geridos pelo Terraform.

Para aplicar a configuração do Terraform, execute o seguinte comando:

# Accept changes by entering yes when prompted
terraform apply

Agora, todos os recursos definidos em deployment.yaml estão sob a gestão do Terraform.

Por exemplo, se quiser verificar se o Terraform está realmente a gerir os recursos convertidos, pode fazê-lo alterando ligeiramente a configuração do Terraform, modificando o tempo de expiração da tabela predefinido no recurso google_bigquery_dataset.bigquerydataset:

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

Depois de fazer as alterações, pode aplicar a configuração do Terraform e usar a interface de linhas de comando (CLI) bq para validar as alterações:

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

O resultado que recebe deve corresponder aos valores fornecidos na configuração do Terraform atualizada, o que confirma que o Terraform está agora a gerir estes recursos.

KRM

Configure o Config Connector

Para acionar os recursos nos ficheiros de configuração do KRM, precisa de um cluster do Kubernetes com o Config Connector instalado. Para criar um cluster de teste, consulte o artigo Instalar com o suplemento do GKE.

No Cloud Shell, certifique-se de que as suas credenciais kubectl estão configuradas para o cluster do GKE que quer usar. Substitua GKE_CLUSTER pelo nome do cluster e execute o seguinte comando:

gcloud container clusters get-credentials GKE_CLUSTER

Implemente a configuração do KRM convertida através do kubectl

Para implementar a configuração KRM convertida através do kubectl, execute os seguintes 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

Limpar

Limpe o conjunto de dados e a tabela de amostra

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 limpar o conjunto de dados e a tabela do BigQuery da configuração de exemplo, execute o seguinte comando:

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

Abandone a implementação de amostra do Deployment Manager

Para abandonar uma implementação em direto que converteu com êxito para KRM ou Terraform, execute:

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

Recursos suportados para conversão

Terraform

Para apresentar uma lista dos recursos suportados para o Terraform, execute o seguinte 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 apresentar uma lista dos recursos suportados para o KRM, execute o seguinte 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

Passos seguintes

Reveja as práticas recomendadas e as recomendações para a configuração convertida.