Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Utilice el marco de documentos de TOE de AWS componentes para componentes personalizados Para crear un componente mediante el marco de componentes Ejecutor y orquestador de tareas de AWS (TOE de AWS), debes proporcionar un documento basado en YAML que represente las fases y los pasos que se aplican al componente que crees. Servicios de AWS utilice su componente cuando creen una nueva imagen de máquina de Amazon (AMI) o imagen de contenedor. **Topics** + [Flujo de trabajo de documentos de componentes](#component-doc-workflow) + [Registro de componentes](#component-logging) + [Encadenamiento de entrada y salida](#document-chaining) + [Esquema y definiciones del documento](#document-schema) + [Ejemplos de documento](#document-example) + [Uso de variables en su documento de componentes personalizados](toe-user-defined-variables.md) + [Utilice construcciones condicionales en TOE de AWS](toe-conditional-constructs.md) + [Utilice operadores de comparación en los documentos TOE de AWS de componentes](toe-comparison-operators.md) + [Utilice operadores lógicos en los documentos TOE de AWS de componentes](toe-logical-operators.md) + [Utilice construcciones en bucle en TOE de AWS](toe-looping-constructs.md) ## Flujo de trabajo de documentos de componentes El documento del TOE de AWS componente utiliza fases y pasos para agrupar las tareas relacionadas y organizar esas tareas en un flujo de trabajo lógico para el componente. **sugerencia** El servicio que usa su componente para crear una imagen puede implementar reglas sobre qué fases usar en su proceso de compilación y cuándo se permite la ejecución de esas fases. Es importante tener esto en cuenta a la hora de diseñar el componente. **Fases** Las fases representan la progresión del flujo de trabajo a lo largo del proceso de compilación de imágenes. Por ejemplo, el servicio Generador de Imágenes utiliza las fases `build` y `validate` durante la *etapa de compilación* para las imágenes que produce. Utiliza las fases `test` y `container-host-test` durante la *etapa de prueba* para garantizar que la instantánea de la imagen o la imagen del contenedor generen los resultados esperados antes de crear la AMI final o distribuir la imagen del contenedor. Cuando se ejecuta el componente, los comandos asociados a cada fase se aplican en el orden en el que aparecen en el documento del componente. **Reglas para las fases** + Cada nombre de fase debe ser único dentro de un documento. + Puede definir muchas fases en el documento. + Debe incluir al menos una de las siguientes fases en su documento: + **compilación**: en el caso de Generador de Imágenes, esta fase se suele utilizar durante la *etapa de compilación*. + **validación**: en el caso de Generador de Imágenes, esta fase se suele utilizar durante la *etapa de compilación*. + **prueba**: en el caso de Generador de Imágenes, esta fase se suele utilizar durante la *etapa de prueba*. + Las fases siempre se ejecutan en el orden en que están definidas en el documento. El orden en el que se especifican para TOE de AWS los comandos del no AWS CLI tiene ningún efecto. **Steps** Los pasos son unidades de trabajo individuales que definen el flujo de trabajo dentro de cada fase. Los pasos se ejecutan en orden secuencial. Sin embargo, la entrada o salida de un paso también puede introducirse a un paso posterior como entrada. Esto se llama “encadenamiento”. **Reglas para los pasos** + El nombre del paso debe ser único para la fase. + El paso debe usar una acción compatible (módulo de acción) que devuelva un código de salida. Para obtener una lista completa de los módulos de acción compatibles, su funcionamiento, input/output valores y ejemplos, consulte[Módulos de acción compatibles con el administrador de TOE de AWS componentes](toe-action-modules.md). ## Registro de componentes TOE de AWS crea una nueva carpeta de registro en las instancias de EC2 que se utilizan para crear y probar una nueva imagen cada vez que se ejecuta el componente. En el caso de las imágenes del contenedor, la carpeta de registro se almacena en el contenedor. Para ayudar a solucionar problemas en caso de que algo vaya mal durante el proceso de creación de la imagen, el documento de entrada y todos los archivos de salida que se TOE de AWS crean al ejecutar el componente se almacenan en la carpeta de registro. El nombre de la carpeta de registro consta de las siguientes partes: 1. **Directorio de registro**: cuando un servicio ejecuta un TOE de AWS componente, pasa al directorio de registro junto con otras configuraciones del comando. En los siguientes ejemplos, mostramos el formato de archivo de registro que utiliza Generador de Imágenes. + **Linux y macOS**: `/var/lib/amazon/toe/` + **Windows**: `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\` 1. **Prefijo del archivo**: se trata de un prefijo estándar que se utiliza para todos los componentes: “`TOE_`”. 1. Tiempo de **ejecución: es una marca de tiempo** en formato YYYY-MM-DD \_HH-MM-SS\_UTC-0. 1. **ID de ejecución: es el GUID** que se asigna cuando se ejecutan uno o más componentes. TOE de AWS Ejemplo: `{{/var/lib/amazon/toe/}}TOE_{{2021-07-01_12-34-56_UTC-0}}_{{a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4}}` TOE de AWS almacena los siguientes archivos principales en la carpeta de registro: **Archivos de entrada** + **document.yaml**: el documento que se utiliza como entrada para el comando. Una vez ejecutado el componente, este archivo se almacena como un artefacto. **Archivos de salida** + **application.log**: el registro de la aplicación contiene información a nivel de depuración con marca de tiempo de TOE de AWS sobre lo que ocurre mientras se ejecuta el componente. + **detailedoutput.json**: este archivo JSON contiene información detallada sobre el estado de la ejecución, las entradas, las salidas y los errores de todos los documentos, fases y pasos que se aplican al componente a medida que se ejecuta. + **console.log**: el registro de la consola contiene toda la información de salida estándar (stdout) y de error estándar (stderr) que TOE de AWS se graba en la consola mientras el componente está en ejecución. + **chaining.json**: este archivo JSON representa las optimizaciones que se aplicaron para resolver las expresiones de encadenamiento. TOE de AWS **nota** Es posible que la carpeta de registro también contenga otros archivos temporales que no se incluyen aquí. ## Encadenamiento de entrada y salida La aplicación TOE de AWS de gestión de la configuración proporciona una función para encadenar entradas y salidas mediante la escritura de referencias en los siguientes formatos: `{{ phase_name.step_name.inputs/outputs.variable }}` o `{{ phase_name.step_name.inputs/outputs[index].variable }}` La característica de encadenamiento permite reciclar el código y mejorar la capacidad de mantenimiento del documento. **Reglas de encadenamiento** + Las expresiones encadenadas solo se pueden usar en la sección de entradas de cada paso. + Las declaraciones con expresiones encadenadas deben ir entre comillas. Por ejemplo: + **Expresión no válida**: `echo {{ phase.step.inputs.variable }}` + **Expresión válida**: `"echo {{ phase.step.inputs.variable }}"` + **Expresión válida**: `'echo {{ phase.step.inputs.variable }}'` + Las expresiones encadenadas pueden hacer referencia a variables de otros pasos y fases del mismo documento. Sin embargo, el servicio que lleva a cabo las llamadas puede tener reglas que requieran que las expresiones encadenadas funcionen solo en el contexto de una sola etapa. Por ejemplo, Generador de Imágenes no admite el encadenamiento de la *etapa de compilación* a la *etapa de prueba*, ya que ejecuta cada etapa de forma independiente. + Los índices de las expresiones encadenadas siguen la indexación basada en cero. El índice comienza con cero (0) para hacer referencia al primer elemento. **Ejemplos** Para hacer referencia a la variable de origen en la segunda entrada del siguiente paso de ejemplo, el patrón de encadenamiento es `{{ build.{{SampleS3Download}}.inputs[1].source }}`. ``` phases: - name: 'build' steps: - name: {{SampleS3Download}} action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://{{sample-bucket}}/{{sample1}}.ps1' destination: 'C:\{{sample1}}.ps1' - source: 's3://{{sample-bucket}}/{{sample2}}.ps1' destination: 'C:\{{sample2}}.ps1' ``` Para hacer referencia a la variable de salida (igual a “Hola”) en el siguiente paso de ejemplo, el patrón de encadenamiento es `{{ build.{{SamplePowerShellStep}}.outputs.stdout }}`. ``` phases: - name: 'build' steps: - name: {{SamplePowerShellStep}} action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Write-Host "Hello"' ``` ## Esquema y definiciones del documento El siguiente es el esquema YAML de un documento. ``` name: (optional) description: (optional) schemaVersion: "string" phases: - name: "string" steps: - name: "string" action: "string" timeoutSeconds: integer onFailure: "Abort|Continue|Ignore" maxAttempts: integer inputs: ``` Las definiciones de esquema de un documento son las siguientes: | Campo | Description (Descripción) | Tipo | Obligatorio/a | | --- | --- | --- | --- | | Nombre | Nombre del documento. | Cadena | No | | description | Descripción del documento. | Cadena | No | | schemaVersion | versión esquemática del documento, actualmente 1.0. | Cadena | Sí | | phases | Una lista de fases con sus pasos. | Enumeración | Sí | Las definiciones de esquema de una fase son las siguientes. | Campo | Description (Descripción) | Tipo | Obligatorio/a | | --- | --- | --- | --- | | Nombre | Nombre de la fase. | Cadena | Sí | | pasos | Lista de los pasos de la fase. | Enumeración | Sí | Las definiciones de esquema de un paso son las siguientes. | Campo | Description (Descripción) | Tipo | Obligatorio/a | Predeterminado | | --- | --- | --- | --- | --- | | Nombre | Nombre definido por el usuario para el paso. | Cadena | | | | acción | Palabra clave relacionada con el módulo que ejecuta el paso. | Cadena | | | | timeoutSeconds | Número de segundos que dura el paso antes de fallar o volver a intentar.
Además, admite el valor -1, que indica un tiempo de espera infinito. No se admiten valores 0 ni otros valores negativos. | Entero | No | 7200 segundos (120 minutos) | | onFailure | Especifica lo que debe hacer el paso en caso de error. Los valores válidos son los siguientes: [See the AWS documentation website for more details](http://docs.aws.amazon.com/es_es/imagebuilder/latest/userguide/toe-use-documents.html) | Cadena | No | Anular | | maxAttempts | Número máximo de intentos permitidos antes del fallo del paso. | Entero | No | 1 | | inputs | Contiene los parámetros requeridos por el módulo de acción para ejecutar el paso. | Dict | Sí | | ## Ejemplos de documento Los siguientes ejemplos muestran los documentos de los AWSTOE componentes que realizan tareas para el sistema operativo de destino. ------ #### [ Linux ] **Ejemplo 1: ejecución de un archivo binario personalizado** El siguiente es un ejemplo de documento que descarga y ejecuta un archivo binario personalizado en una instancia Linux. ``` name: LinuxBin description: Download and run a custom Linux binary file. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ Windows ] **Ejemplo 1: instalación de actualizaciones de Windows** El siguiente es un ejemplo de documento que instala todas las actualizaciones disponibles de Windows, ejecuta un script de configuración, valida los cambios antes de crear la AMI y prueba los cambios después de crear la AMI. ``` name: RunConfig_UpdateWindows description: 'This document will install all available Windows updates and run a config script. It will then validate the changes before an AMI is created. Then after AMI creation, it will test all the changes.' schemaVersion: 1.0 phases: - name: build steps: - name: DownloadConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/config.ps1' destination: 'C:\config.ps1' - name: RunConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: RebootAfterConfigApplied action: Reboot inputs: delaySeconds: 60 - name: InstallWindowsUpdates action: UpdateOS - name: validate steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: test steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{test.DownloadTestConfigScript.inputs[0].destination}}' ``` **Ejemplo 2: Instálelo AWS CLI en una instancia de Windows** El siguiente es un ejemplo de documento que lo instala AWS CLI en una instancia de Windows mediante el archivo de configuración. ``` name: InstallCLISetUp description: Install &CLI; using the setup file schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLISetup.exe destination: C:\Windows\temp\AWSCLISetup.exe - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '/install' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` **Ejemplo 3: Instálelo AWS CLI con el instalador MSI** El siguiente es un ejemplo de documento que lo instala AWS CLI con el instalador MSI. ``` name: InstallCLIMSI description: Install &CLI; using the MSI installer schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLI64PY3.msi destination: C:\Windows\temp\AWSCLI64PY3.msi - name: Install action: ExecuteBinary onFailure: Continue inputs: path: 'C:\Windows\System32\msiexec.exe' arguments: - '/i' - '{{ build.Download.inputs[0].destination }}' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ macOS ] **Ejemplo 1: ejecución de un archivo binario de macOS personalizado** El siguiente es un ejemplo de documento que descarga y ejecuta un archivo binario personalizado en una instancia de macOS. ``` name: macOSBin description: Download and run a binary file on macOS. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------