Documentación de Oracle Cloud Infrastructure

Uso de la detección de recursos

La función de detección de recursos del proveedor de Terraform de Oracle Cloud Infrastructure (OCI) utiliza terraform-exec de HashiCorp para importar los recursos de OCI detectados a archivos de estado y configuración de Terraform.

Requisitos

Terraform-exec requiere que la CLI de Terraform esté presente en el sistema. Consulte Descarga e instalación de Terraform para obtener más información sobre la instalación.

Nota

Si utiliza la versión v0.11 de Terraform, esta herramienta no puede generar un archivo de estado. En la versión v0.11, solo se soportan configuraciones. Por defecto, las configuraciones se generan en la versión v0.12.

Si utiliza la versión v0.13.* de la CLI de Terraform, asegúrese de que la versión sea compatible con la sintaxis de v0.12.

Además, debe haber descargado e instalado el proveedor de Terraform de OCI. Consulte Descarga e instalación del proveedor para obtener instrucciones de descarga.

Adición de las herramientas a su ruta de acceso

Para ejecutar el proveedor de Terraform de OCI como un ejecutable y utilizar la detección de recursos, puede:

  • Agregar terraform-provider-oci a la ruta de acceso del sistema.
  • Ejecutar el proveedor desde el directorio en el que se encuentra.
  • Especificar la ruta completa al proveedor al ejecutar comandos de la detección de recursos.

Como los comandos de la detección de recursos utilizan terraform-exec para llamar a Terraform en su nombre, su sistema debe especificar la ubicación de la CLI de Terraform mediante uno de los siguientes métodos:

  • Proporcione la ruta de acceso completa, incluido el nombre de la CLI de Terraform, mediante la variable de entorno terraform_bin_path. Consulte Variables de entorno para obtener más información sobre la configuración de variables.
  • Agregue la CLI de Terraform a la ruta de acceso del sistema.

Autenticación

Para detectar recursos en el compartimento, el proveedor de Terraform de OCI necesita información de autenticación sobre el usuario, el arrendamiento y la región con la que detectar los recursos. Se recomienda especificar un usuario que tenga acceso para inspeccionar y leer los recursos que desea detectar.

Puede utilizar la autenticación de clave de API y las variables de entorno o la autorización de principal de instancia para proporcionar la información necesaria.

Exportación de recursos

Después de especificar la ubicación de la CLI de Terraform y los valores de autenticación, puede utilizar uno de los siguientes comandos para exportar los recursos de un compartimento:

terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>
terraform-provider-oci -command=export -compartment_id=<compartment_OCID> -output_path=<output_path>

Estos comandos detectan todos los recursos soportados del compartimento y generan archivos de configuración de Terraform en el output_path proporcionado. Los archivos .tf generados contienen la configuración de Terraform con los recursos que ha detectado el comando.

Atención

Asegúrese de que output_path esté vacío antes de ejecutar la detección de recursos.
Nota

El parámetro compartment_id es necesario si se utiliza la autorización de principal de instancia.

Las siguientes combinaciones de parámetros comunes exportan los recursos descritos:

  • compartment_id=<OCID_de_arrendamiento_o_vacío> services=<vacío_o_no_especificado>: todos los recursos de ámbito de compartimento y arrendamiento.
  • compartment_id=<OCID_de_arrendamiento_o_vacío> services=<lista_separada_por_comas>: recursos de ámbito de compartimento y arrendamiento para los servicios especificados.
  • compartment_id=<OCID_no_raíz> services=<vacío_o_no_especificado>: todos los recursos de ámbito de compartimento.
  • compartment_id=<OCID_no_raíz> services=<lista_separada_por_comas>: recursos de ámbito de compartimento para los servicios especificados. Los recursos de ámbito de arrendamiento no se detectan incluso si se han especificado servicios con dichos recursos.
Nota

La exportación de los recursos de un compartimento solo soporta el compartimento de destino. Los recursos de los compartimentos secundarios no se detectan.

Parámetros

Puede utilizar los siguientes parámetros para controlar el comportamiento de la herramienta de detección de recursos.

Parámetro Detalles
command Comando que ejecutar. Entre los comandos soportados se incluyen:
  • export: detecta los recursos de OCI en el compartimento y genera archivos de configuración de Terraform para los mismos
  • list_export_resources: muestra los tipos de recursos de OCI de Terraform que detecta el comando export
  • list_export_services: muestra los valores permitidos para los argumentos de los servicios junto con el ámbito en formato JSON
compartment_id OCID del compartimento que desea exportar. Si no se especifica compartment_id ni compartment_name, se utiliza el compartimento raíz. Es necesario si se utiliza la autorización de principal de instancia.
compartment_name Nombre de un compartimento que desea exportar. Si no se especifica compartment_id ni compartment_name, se utiliza el compartimento raíz.
exclude_services Lista separada por comas de recursos de servicio que se excluirán de la exportación. Se excluye cualquier servicio presente en los argumentos services y exclude_services.
filter Permite filtrar los recursos detectados por los criterios especificados. Para obtener más información, consulte Filtrado de Recursos.
generate_state Proporcione este indicador para importar los recursos detectados a un archivo de estado además de a los archivos de configuración de Terraform.
ids Una lista separada por comas de tuplas <resource_type:resource_ID> (por ejemplo, oci_core_instance:ocid.....) para los recursos que se van a exportar. El ID puede ser un OCID o un ID de importación de Terraform. Por defecto, se exportan todos los recursos.
list_export_services_path Ruta de acceso completa, incluido el nombre de archivo, que se utilizará como salida para la lista de servicios soportados, en formato JSON.
output_path Ruta de acceso absoluta en la que generar las configuraciones y los archivos de estado generados del compartimento exportado.
parallelism Número de threads para detectar recursos en paralelo. El valor por defecto es 1.
retry_timeout Tiempo en segundos durante el cual las llamadas de API esperan y vuelven a intentar la operación en caso de errores de API. Por defecto, el tiempo de espera para el reintento es 15 segundos.
services Lista separada por comas de recursos de servicios que se desean exportar. Si no se especifica, se exportan todos los recursos del compartimento proporcionado (con excepción de los recursos de IAM).

Consulte Servicios soportados para conocer los valores aceptados y Exportación de recursos de identidad para obtener información relacionada.
tf_version Versión de la sintaxis de Terraform que se desea utilizar al generar archivos de configuración. Por defecto es la v0.12. Los valores permitidos son:
  • 0.11
  • 0.12

Si especifica 0.11 como la versión de la sintaxis, utilice la versión v0.11 de la CLI de Terraform para detectar los recursos.

Si utiliza la versión v0.13 o posterior de la CLI de Terraform para detectar recursos, asegúrese de que la versión sea compatible con la sintaxis de v0.12.

Los archivos de estado se generan en la sintaxis de Terraform que coincida con la versión de la CLI de Terraform utilizada para detectar los recursos. El parámetro tf_version no se aplica a los archivos de estado.
variables_global_level

Lista de los atributos de nivel superior para exportar como variables, en el formato attribute1,attribute2. Los atributos de nivel de recurso (variables_resource_level) no se incluyen en esta lista.
variables_resource_level

Lista de los atributos de nivel de recurso para exportar como variables, en el formato resourceType.attribute. Los atributos de nivel superior (variables_global_level) no se incluyen en esta lista.

Filtrado de recursos

Filtrar los recursos detectados por los criterios especificados:

  • Filtro de tipo de recurso: Type<operator><provider-resource-type>

    <operator> es = (igual que) o != (no igual que)

  • Filtro de atributo: AttrName=<attribute-name>;Value<operator><value> Buscar todos los recursos con atributo y valor coincidentes
  • Hasta 10 filtros (los recursos deben cumplir todos)
Filtro de tipo de recurso: solo VCN
--filter="Type=oci_core_vcn"
Filtro de tipo de recurso: todo menos la VCN
--filter="Type!=oci_core_vcn"
Filtro de atributo: valor de etiqueta definido
--filter="AttrName=defined_tags.example-namespace.example-key;Value=example-value"
Varios filtros: solo la VCN debe tener el atributo dns_label definido para probar
--filter="Type=oci_core_vcn" --filter="AttrName=dns_label;Value=test"

Para obtener más información sobre el filtrado de recursos detectados, consulte Filtrado de recursos detectados mediante la detección de recursos.

Registro detallado

Para obtener una salida de consola detallada cuando el proveedor se esté ejecutando, preceda al comando de detección de recursos con los indicadores TF_LOG o OCI_TF_LOG. Por ejemplo:

TF_LOG=DEBUG terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>
OCI_TF_LOG=DEBUG terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>

El nivel TF_LOG y los indicadores OCI_TF_LOG también se pueden definir como variables de entorno.

Para redireccionar la salida de consola detallada a un archivo log, defina la variable de entorno OCI_TF_LOG_PATH y proporcione la ruta de acceso.

Estado de salida

Para cualquier error relacionado con las API de OCI o la falta de disponibilidad del servicio al detectar recursos, la herramienta pasa a encontrar el siguiente recurso. Todos los errores encontrados se muestran una vez finalizada la detección.

  • Código de salida 0: operación correcta.
  • Código de salida 1: fallo debido a errores como variables de entorno, argumentos o configuración incorrectos.
  • Código de salida 64: operación parcialmente correcta. La detección de recursos no ha encontrado todos los recursos debido a fallos del servicio.

Exportación de recursos de identidad

Algunos recursos, como los recursos de identidad, existen solo en el nivel del arrendamiento y no se pueden detectar en un compartimento específico. Para descubrir dichos recursos, utilice el siguiente comando, que omite cualquier parámetro de compartimento:
terraform-provider-oci -command=export -output_path=<output_path> -services=identity
Nota

Al exportar recursos de identidad, se ignora el valor compartment_id, si se proporciona.

Exportación de recursos a otro compartimento

Una vez que haya revisado los archivos de configuración de Terraform generados y realizado los cambios necesarios, la configuración se puede utilizar con Terraform. Uno de esos casos de uso es el nuevo despliegue de esos recursos en un nuevo compartimento o arrendamiento mediante Terraform.

Para ello, especifique las siguientes variables de entorno:

export TF_VAR_tenancy_ocid=<target_tenancy_OCID>
export TF_VAR_compartment_ocid=<target_compartment_OCID>

A continuación, ejecute el siguiente comando:

terraform apply

Generación de un archivo de estado de Terraform

Atención

El archivo de estado contiene todos los atributos de recursos especificados como parte de los archivos de configuración. Si gestiona datos confidenciales con Terraform, como contraseñas de bases de datos o de usuarios o claves privadas de instancias, debe tratar el archivo de estado como datos confidenciales. Consulte Almacenamiento de datos confidenciales para obtener más información.

También se puede generar un archivo de estado de Terraform para gestionar los recursos detectados. Para ello, ejecute el siguiente comando, que incluye el indicador -generate_state:

terraform-provider-oci -command=export -compartment_id=<compartment_OCID> -output_path=<output_path> -generate_state

Los resultados de este comando son tanto los archivos .tf que representan la configuración de Terraform como un archivo terraform.tfstate que representa el estado. Consulte el artículo sobre el estado para obtener más información.

Nota

El archivo de estado de Terraform que genera este comando solo es compatible con Terraform v0.12.4 y versiones posteriores.