Actualización a una nueva versión de Terraform

Las herramientas IaC de código abierto utilizadas por Schematics evolucionan, con nuevas versiones de Terraform y Helm, y los proveedores de Terraform de soporte. Con el tiempo, es necesario que los entornos de espacio de trabajo de larga duración se actualicen para utilizar la versión más reciente de Terraform, ya que las versiones más antiguas están en desuso y no tienen soporte.

Todos los usuarios de Schematics se animan a actualizar regularmente a la última versión de Terraform para garantizar la continuidad de las operaciones y el soporte. Schematics sigue el modelo de soporte Hashicorp para los releases de Terraform y deja en desuso las versiones en línea con Hashicorp.

Terraform v1.0 era un release principal para Terraform, marcando la transición a un release 1.x estable. Hashicorp ha hecho promesas de compatibilidad para los releases de 1.x, que para las características principales, no son necesarios cambios adicionales para actualizar a través de los releases de 1.x.

En resumen, su objetivo es realizar actualizaciones entre releases de v1.x de forma sencilla, sin requerir cambios en la configuración, sin mandatos para ejecutar pasos de actualización y sin cambios en ninguna automatización que haya configurado alrededor de Terraform.

Para actualizar a los releases de 1.x no es necesario realizar acciones específicas del espacio de trabajo Schematics. Consulte las guías de actualización de Terraform para ver los cambios específicos del release que pueden requerir actualizaciones de TF config/template.

Actualización de la plantilla de Terraform versión 1.x y superior

Desde Terraform 1.0, los espacios de trabajo Schematics se pueden actualizar a releases 1.x más recientes, mediante un simple cambio en la versión del espacio de trabajo. Para actualizar desde los releases de 0.x, consulte la sección Actualización de la versión de plantilla de Terraform 0.x

Schematics da soporte a Terraform_v1.x y tiene previsto hacer que los releases estén disponibles 45-60 days después de la disponibilidad general. Se recomienda que las plantillas de Terraform utilicen una restricción de rango de versiones como, por ejemplo, >, >= o ~> para el parámetro required_version en versions.tf de la plantilla de Terraform, que permite la actualización para releases menores y de parches. Esto permite a Schematics adoptar automáticamente el último parche o release menor de la versión de Terraform tal como establece la versión del espacio de trabajo.

terraform {
required_version = "~> 1.1"
}

Actualización del espacio de trabajo Terraform 1.x versión

La versión en uso de Terraform para un espacio de trabajo se puede actualizar a través del espacio de trabajo Schematics API de actualización.

El parámetro de versión de terraform del espacio de trabajo tiene el formato terraform_v1.4 o terraform_v1.5

Seleccione el espacio de trabajo que se va a actualizar y verifique que está en estado Normal y que una operación de plan no genera ningún cambio de recurso propuesto. Guarde el workspace_id y anote la región en la que se aloja el espacio de trabajo.
Actualice la versión de Terraform del espacio de trabajo utilizando la CLI y la API de IBM Cloud. Estas operaciones de espacio de trabajo son específicas de la región. Anote la región del espacio de trabajo de la interfaz de usuario, ya que es necesaria para los mandatos siguientes:
- Inicie sesión en la CLI de IBM Cloud con ibmcloud login
- Establezca la región de destino de CLI con ibmcloud target -r <region> para que sea la misma que la del espacio de trabajo que está actualizando.
- Genere una señal de IAM oauth para utilizarla con la API Schematics, con el mandato ibmcloud iam oauth-tokens.
- Copie los datos de señal e insértelos en el siguiente texto de mandato, sustituyendo la serie <token-data>, establezca <terraform_version> en la versión de Terraform necesaria y <workspace_id>:
- El espacio de trabajo se actualiza ejecutando un mandato cURL para llamar a la API de actualización de Schematics para actualizar la versión de Terraform. Esta operación es específica de la región y debe especificar el Schematics punto final de región de API deseado para la región de destino del espacio de trabajo. Sustituya el texto <schematics-region-endpoint> en el mandato por el punto final para la región de espacio de trabajo de destino.
```
    curl -X PUT https://<schematics-region-endpoint>.cloud.ibm.com/v1/workspaces/<w_id> \
    -H 'Authorization: Bearer <token>' \
    -H 'refresh_token: <token>' \
    -d '{
    "type": [
        "<terraform_version>"
    ],
    "template_data": [
        {
            "folder": ".",
            "type": "<terraform_version>"
        }
    ]
    }'
```
Verifique en la página de valores del espacio de trabajo que la versión de TF está ahora establecida en la versión deseada.
Ejecute una operación Generar plan en el espacio de trabajo. Valide que el mandato se ejecuta correctamente sin errores y que no se registran mensajes inesperados. El Plan no debería dar lugar a cambios propuestos en los recursos.
Ejecute una operación Aplicar plan en el espacio de trabajo. Valide que el mandato se ejecuta correctamente sin errores y que no se registran mensajes inesperados.
Ahora ha actualizado correctamente.

Actualización de la versión de plantilla de Terraform 0.x a 1.x

En los releases 0.x, la actualización de la versión de Terraform es un proceso por pasos, que se actualiza a través de cada release. La actualización no da soporte a la actualización entre varios releases y se debe realizar, release por release. Algunas actualizaciones requieren la ejecución de mandatos upgrade de Terraform para modificar los archivos de configuración también cambia al archivo de estado de Terraform. Estos pasos no se pueden realizar en Schematics. Las plantillas de Terraform de espacio de trabajo deben actualizarse utilizando una copia local de Terraform. Siga los pasos para actualizar los releases 0.x.

Lista de versiones de Terraform
Versión	Recomendación
`v0.12`	Revise la Guía de actualización dev0.13 y siga las instrucciones Actualización de un espacio de trabajo de Terraform v0.12 a v0.13. Schematics ha quedado en desuso `Terraform v0.12`.
`v0.13`	Para la actualización de `Terraform v0.14`, debe ejecutar `terraform apply` con `Terraform v0.14` para completar sus actualizaciones de formato de estado. Si obtiene algún error, consulte la Guía de actualización dev0.14. Siga las instrucciones upgrade-13-to10
`v0.14`	Puede actualizar directamente a la versión de `Terraform v1.0`. Revise la Guía de actualización dev0.15.
`v0.15`	Puede actualizar directamente a la versión de `Terraform v1.0`. Revise la Guía de actualización dev1.0.

Actualización de un espacio de trabajo de Terraform v0.12 a v0.13

La actualización de un espacio de trabajo de v0.12 para utilizar la versión de v0.13 de Terraform es una tarea de varios pasos. Debe revisar detenidamente la Guía de actualización de Terraform para la actualización de la versión relacionada.

Siga estos pasos para actualizar a la versión actual de Terraform en el espacio de trabajo Schematics.

Actualice los archivos de configuración de Terraform para que utilicen la sintaxis y la semántica más recientes.
Migre el archivo de estado de Terraform para que sea compatible con la versión más reciente. Schematics no admite la modificación integrada del archivo de estado de Terraform. Por lo tanto, debe seguir estos pasos.
1. Prepare la versión actualizada de los archivos de configuración de Terraform y el archivo de estado Terraform, en la máquina local.
2. Cree el nuevo espacio de trabajo de Schematics con los nuevos archivos de configuración de Terraform y el archivo de estado de Terraform.
3. Suprima el espacio de trabajo anterior sin destruir los recursos.

A continuación se muestran los pasos detallados para actualizar de 0.12 a 0.13:

Compruebe si los espacios de trabajo de Schematics en v0.12 tienen recursos, la última aplicación ha sido satisfactoria y el espacio de trabajo está en estado normal. Compruebe que los archivos de configuración de Terraform y el archivo de estado de Terraform se encuentran en un estado coherente para Terraform v0.12.
Descargue o clone el repositorio Git que utiliza su espacio de trabajo Terraform v0.12 Schematics en su máquina local.
Instale Terraform 0.13 en la máquina local.
Cambie el directorio a su repositorio clonado y actualice sus archivos de configuración a Terraform v0.13 ejecutando el comando Terraform v0.13upgrade. Para más información, consulte la documentación sobre la actualización en Terraform v0.13. El mandato de actualización genera un archivo versions.tf con un bloque de configuración terraform.

Edite el archivo versions.tf para establecer el parámetro de origen en source = "IBM-Cloud/ibm" tal como se muestra en el bloque de código.

Archivo versions.tf

terraform {
    required_providers {
    ibm = {
      # TF-UPGRADE-TODO
      #
      # No source detected for this provider. You must add a source address
      # in the following format:
      #
      source = "IBM-Cloud/ibm"
      #
      # For more information, see the provider source documentation:
      #
    }
    }
    required_version = ">= 0.13"
}

Descargue el archivo de estado Terraform del espacio de trabajo Schematics existente utilizando el mandato Schematics state pull.

Cuando se crea el espacio de trabajo con tfstate Schematics lo considera un archivo seguro. Además, no se puede extraer el archivo tfstate creado a través de la interfaz de usuario. Debe utilizar la línea de mandatos para extraer el archivo de estado y crear espacio de trabajo.

Copie el archivo de estado descargado como terraform.tfstate en la carpeta de ejecución de Terraform.
Ejecute el mandato de proveedor de sustitución de estado en la línea de mandatos para actualizar la versión del proveedor IBM Cloud en el archivo de estado.
```
terraform state replace-provider registry.terraform.io/-/ibm registry.terraform.io/ibm-cloud/ibm.
```
Verifique que las actualizaciones se realizan en el archivo terraform.tfstate con la actualización de la versión de Terraform de 1.3 a >= 1.4 y el proveedor que se actualiza como registry.terraform.io/ibm-cloud/ibm.
Envíe los archivos de configuración de TF actualizados y version.tf de nuevo al repositorio Git.
Copie el contenido del archivo terraform.tfstate modificado en el archivo state.json.
Cree o actualice un archivo workspace.json tal como se muestra en el bloque de código.

{
    "name": "gb",
    "type": [
        "terraform_v1.4"
    ],
    "description": "migration workspace",
    "template_repo": {
        "url": "Provide your Git repository link"
    },
    "workspace_status" : {
        "frozen": false
    },
    "template_data": [{
        "folder": ".",
        "type": "terraform_v1.4"
    }]
}

Ejecute estos comandos a través de la línea de comandos para crear un nuevo espacio de trabajo Terraform v0.13:

ibmcloud schematics workspace new --file workspace.json --state state.json.
ibmcloud schematics workspace get --id <workspace-id>. Si el estado de su espacio de trabajo no es inactive, espere unos segundos y vuelva a intentar el comando.
ibmcloud schematics plan id <workspace id>.
ibmcloud schematics job get --id <job-id form plan>. Si el estado de su plan de espacio de trabajo no es success, espere unos segundos y vuelva a intentar el comando.
ibmcloud schematics apply --id <workspace id>.
ibmcloud schematics job get --id <job-id from apply>.

[Opcionalmente] puede eliminar el espacio de trabajo Schematics que utiliza Terraform v0.12.

No destruya los recursos que utiliza el espacio de trabajo antiguo.

Actualizar la plantilla de Terraform de `v0.13` y superior a `v1.0`

Las versiones 0.13 a 0.15 requieren una actualización escalonada, 0.13 to 0.14, 0.14 to 0.15, 0.15 to 1.0.

El proceso es el mismo para cada paso de versión. Es obligatorio que se ejecute una aplicación de Terraform después de cada cambio de versión. Esto actualiza el archivo de estado de Terraform con cambios de esquema relacionados con esa versión y sólo con esa versión. Después de actualizar correctamente una única versión, se puede realizar la siguiente actualización de versión.