Directrices para pilas

Directrices obligatorias

Las siguientes son directrices obligatorias para las pilas que se muestran en Oracle Cloud Infrastructure Marketplace. Se debe seguir cada directriz. Antes de publicarse, cada artefacto de pila se valida según cada una de estas directrices.

1. El artefacto de pila debe ser un archivo zip, incluidos los archivos de configuración de Terraform y un archivo de esquema.
   • Zip debe incluir al menos un archivo de configuración (.tf) en la carpeta raíz.
   • Zip debe incluir el archivo de esquema (.yaml) en la carpeta raíz.
   • Zip no debe incluir un archivo de estado de Terraform en el archivo zip. Los archivos de estado se gestionan mediante Oracle Resource Manager (ORM). Cuando los clientes inician una pila, ORM crea y gestiona los recursos y el archivo de estado pasa a estar disponible solo para descarga.
   • El zip no debe incluir la carpeta de configuración de tiempo de ejecución de Terraform (.terraform).
2. La configuración de Terraform solo debe utilizar imágenes de instancia que sean imágenes de Marketplace aprobadas o publicadas (públicas o privadas). Debe tener una suscripción de Marketplace a cada una de estas imágenes. Debe tener referencias codificadas para estas imágenes de Marketplace. Consulte Configuración de Terraform de ejemplo para una suscripción y uso de imagen de Marketplace para obtener más información.
3. Los binarios no se deben descargar de repositorios externos. Todos los binarios y dependencias deben incluirse en la imagen publicada de Marketplace.
4. El provisionador de ejecución remota de Terraform solo se debe ejecutar en el dominio de Oracle Cloud Infrastructure. No debe descargar archivos en un servidor remoto.
5. El código de terceros o los binarios no se deben descargar mediante cloud-init.
   1. cloud-init es una utilidad de configuración de inicio que se suele utilizar para las instancias informáticas en la nube. Acepta la configuración mediante mecanismos de datos de usuario especificados como parte de la definición de metadatos en el recurso oci_core_instance.
   2. Hay varios formatos de datos de usuario soportados por cloud-init. Consulte https://cloudinit.readthedocs.io/en/latest/topics/format.html.
   3. Independientemente del formato de datos de usuario, cloud-init NO DEBE utilizarse para descargar ningún código binario o de terceros. Todos los binarios necesarios durante el proceso de inicio de la instancia (bootstrap), si no están disponibles en la imagen, deben descargarse mediante un proceso (script) horneado como parte de la distribución de la imagen, no inyectado a través de cloud-init (por ejemplo, aprovechando wget).)
   4. Sin embargo, puede tener una plantilla cloud-init configurada para que los clientes la utilicen en algunos escenarios concretos, por ejemplo, para importar un archivo de clave de licencia o para importar un archivo de configuración. En ese caso, debe proporcionar una variable en el código de plantilla de Terraform para permitir a los clientes introducir algunos datos en el bloque de creación cloud-init, por ejemplo, aprovechando el origen de datos template_file de Terraform.
6. El proveedor de Terraform debe ser Oracle Cloud Infrastructure. Otros proveedores de servicios en la nube o proveedores de aplicaciones de terceros no están soportados.
7. Si se utiliza un módulo de Terraform, se debe cargar desde rutas de acceso relativas locales. No se puede cargar desde un repositorio remoto.
8. La configuración de Terraform debe utilizar la autenticación de principal de instancia.

9. Debe especificar las versiones de Terraform mínimas y máximas soportadas en las que ha probado la pila.

   • Especifique la versión mínima necesaria de Terraform con el formato: ~> <major_version>.<minor_version>.<patch_version>.

     Donde, patch_version siempre se define en 0. Cuando se inicia una pila, Resource Manager comprueba el <major_version>.<minor_version> que ha definido en el código y utiliza la versión de parche más reciente disponible. Por este motivo, debe utilizar el signo ~> en lugar del signo => al especificar la versión mínima necesaria de Terraform.

     Por ejemplo, ~> 0.14.0 indica que las versiones de Terraform soportadas son 0.14.0 o posteriores.

   • Especifique la versión máxima necesaria de Terraform con el formato: < <major_version>.<minor_version>.

     Por ejemplo, < 0.15 indica que las versiones de Terraform soportadas son anteriores a 0.15.

   En el siguiente ejemplo se muestra cómo especificar las versiones de Terraform mínimas y máximas soportadas cuando haya probado la pila solo en Terraform 0.14.

   terraform 
   { required_version = "~> 0.14.0, < 0.15" }

Para obtener más información sobre Terraform, incluido el proveedor de Oracle Cloud Infrastructure, la autenticación de principal de instancia y el aprovisionador de ejecución remoto, consulte la documentación de Terraform para Configuración de proveedor. Para obtener información sobre las versiones soportadas de Terraform, consulte Introducción al proveedor de Terraform en la documentación de Oracle Cloud Infrastructure.

Directrices de codificación para configuraciones de Terraform

Se recomiendan las siguientes directrices para las pilas que se muestran en Oracle Cloud Infrastructure Marketplace. Cada directriz se considera una mejor práctica que debe seguirse si es posible.

• El artefacto de pila debe permitir a los clientes crear todos los recursos de infraestructura o apuntar a los existentes (red, almacenamiento, etc.).
• Se deben seguir las convenciones de nomenclatura y el formato:
  • Casing: utilice lower_snake_case para todos los nombres. Esto se aplica a nombres de variables, nombres de recursos, nombres de módulos, nombres de archivos, nombres mostrados, etc.
  • Especificación del tipo de recurso: no incluya el tipo de recurso u origen de datos en el nombre. En Terraform, <type>.<name>. siempre hace referencia a los recursos y orígenes de datos Como tal, no hay necesidad de incluir el tipo en el nombre en sí.
  • ID frente a OCID: en Oracle Cloud Infrastructure, id suele hacer referencia a un campo que toma un OCID. Como tal, las variables deben utilizar id al hacer referencia a valores de OCID, en lugar de utilizar ocid.
  • Nombres de variables: los nombres de variables para los recursos de Oracle Cloud Infrastructure suelen utilizar el mismo nombre que se utiliza para el recurso de Terraform.
  • Nombres mostrados: los nombres mostrados de los recursos de Oracle Cloud Infrastructure suelen utilizar el mismo nombre que el utilizado para el recurso de Terraform.
  • Nomenclatura de variables y salidas de módulo: al utilizar un módulo, el nombre de la entrada (variables) y las salidas se deben exponer al emisor de la llamada.
  • terraform fmt se debe aplicar a todo Terraform antes de protegerlo.