Utilice el marco de documentos de TOE de AWS componentes para componentes personalizados - EC2 Image Builder
Flujo de trabajo de documentos de componentesRegistro de componentesEncadenamiento de entrada y salidaEsquema y definiciones del documentoEjemplos de documento

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.

Temas

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.

Pasos

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

Registro de componentes

TOE de AWS crea una nueva carpeta de registro en las EC2 instancias 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 mientras se ejecuta 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, lo transfiere 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\

  2. Prefijo del archivo: se trata de un prefijo estándar que se utiliza para todos los componentes: “TOE_”.

  3. Tiempo de ejecución: es una marca de tiempo en formato YYYY-MM-DD _HH-MM-SS_UTC-0.

  4. 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 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 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 Descripción Tipo Obligatorio/a Valor 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:

  • Abortar: se produce un error en el paso después del número máximo de intentos y se detiene la ejecución. Establece el estado de la fase y el documento como Failed.

  • Continuar: se produce un error en el paso después del número máximo de intentos y continúa ejecutando los pasos restantes. Establece el estado de la fase y el documento como Failed.

  • Ignorar: establece el paso como IgnoredFailure después del número máximo de intentos fallidos y continúa ejecutando los pasos restantes. Establece el estado de la fase y el documento como SuccessWithIgnoredFailure.

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://<replaceable>amzn-s3-demo-source-bucket</replaceable>/<replaceable>myapplication</replaceable>
            destination: /tmp/<replaceable>myapplication</replaceable>
      - 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://<replaceable>amzn-s3-demo-source-bucket</replaceable>/<replaceable>myapplication</replaceable>
            destination: /tmp/<replaceable>myapplication</replaceable>
      - 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 }}'