As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Use a estrutura de documentos de AWSTOE componentes para componentes personalizados Para criar um componente usando a estrutura de componentes AWS Task Orchestrator and Executor (AWSTOE), você deve fornecer um documento baseado em YAML que represente as fases e etapas que se aplicam ao componente criado. Serviços da AWS use seu componente ao criar uma nova Amazon Machine Image (AMI) ou imagem de contêiner. **Topics** + [Fluxo de trabalho do documento de componente](#component-doc-workflow) + [Registro em log do componente](#component-logging) + [Encadeamento de entrada e saída](#document-chaining) + [Esquema e definições do documento](#document-schema) + [Documentos de exemplo](#document-example) + [Usar variáveis em seu documento de componente personalizado](toe-user-defined-variables.md) + [Use construções condicionais em AWSTOE](toe-conditional-constructs.md) + [Use operadores de comparação em documentos de AWSTOE componentes](toe-comparison-operators.md) + [Use operadores lógicos em documentos de AWSTOE componentes](toe-logical-operators.md) + [Use construções em loop em AWSTOE](toe-looping-constructs.md) ## Fluxo de trabalho do documento de componente O documento do AWSTOE componente usa fases e etapas para agrupar tarefas relacionadas e organizar essas tarefas em um fluxo de trabalho lógico para o componente. **dica** O serviço que usa seu componente para criar uma imagem pode implementar regras sobre quais fases usar no processo de criação e quando essas fases podem ser executadas. É importante considerar isso ao projetar seu componente. **Fases** As fases representam a progressão do seu fluxo de trabalho por meio do processo de compilação da imagem. Por exemplo, o serviço Image Builder usa as fases `build` e `validate` durante seu *estágio de compilação* para as imagens que ele produz. Ele usa as fases `test` e `container-host-test` durante o *estágio de teste* para garantir que o snapshot da imagem ou a imagem do contêiner produza os resultados esperados antes de criar a AMI final ou distribuir a imagem do contêiner. Quando o componente é executado, os comandos associados a cada fase são aplicados na ordem em que aparecem no documento do componente. **Regras para as fases** + Cada nome de fase deve ser exclusivo dentro de um documento. + Você pode definir várias fases em seu documento. + Você deve incluir pelo menos uma das fases a seguir em seu documento: + **compilação**: para o Image Builder, essa fase geralmente é usada durante o *estágio de compilação*. + **validação**: para o Image Builder, essa fase geralmente é usada durante o *estágio de compilação*. + **teste**: para o Image Builder, essa fase geralmente é usada durante o *estágio de teste*. + As fases sempre são executadas na ordem em que são definidas no documento. A ordem na qual eles são especificados para AWSTOE os comandos no não AWS CLI tem efeito. **Etapas** As etapas são unidades individuais de trabalho que definem o fluxo de trabalho em cada fase. As etapas são executadas em ordem sequencial. No entanto, a entrada ou saída de uma etapa também pode alimentar uma etapa subsequente como entrada. Isso é chamado de “encadeamento”. **Regras para as etapas** + O nome da etapa deve ser exclusivo para a fase. + A etapa deve usar uma ação compatível (módulo de ação) que retorne um código de saída. Para obter uma lista completa dos módulos de ação compatíveis, como eles funcionam, input/output valores e exemplos, consulte[Módulos de ação suportados pelo gerenciador de AWSTOE componentes](toe-action-modules.md). ## Registro em log do componente AWSTOE cria uma nova pasta de log nas instâncias do EC2 que é usada para criar e testar uma nova imagem sempre que seu componente é executado. Para imagens de contêiner, a pasta de log é armazenada no contêiner. Para ajudar na solução de problemas se algo der errado durante o processo de criação da imagem, o documento de entrada e todos os arquivos de saída AWSTOE criados durante a execução do componente são armazenados na pasta de registro. O nome da pasta de log é composto pelas seguintes partes: 1. **Diretório de log** — quando um serviço executa um AWSTOE componente, ele passa para o diretório de log, junto com outras configurações do comando. Nos exemplos a seguir, mostramos o formato de arquivo de log usado pelo Image Builder. + **Linux e macOS**: `/var/lib/amazon/toe/` + **Windows**: `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\` 1. **Prefixo do arquivo**: esse é um prefixo padrão usado para todos os componentes: “`TOE_`”. 1. **Tempo de execução** — Este é um timestamp no formato YYYY-MM-DD \_HH-MM-SS\_UTC-0. 1. **ID de execução** — Esse é o GUID atribuído ao AWSTOE executar um ou mais componentes. Exemplo: `{{/var/lib/amazon/toe/}}TOE_{{2021-07-01_12-34-56_UTC-0}}_{{a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4}}` AWSTOE armazena os seguintes arquivos principais na pasta de log: **Arquivos de entrada** + **document.yaml**: o documento usado como entrada para o comando. Depois que o componente é executado, esse arquivo é armazenado como um artefato. **Arquivos de saída** + **application.log**: O log do aplicativo contém informações de nível de depuração com o timestamp do AWSTOE sobre o que está acontecendo enquanto o componente está sendo executado. + **detailedoutput.json**: esse arquivo JSON tem informações detalhadas sobre o status de execução, entradas, saídas e falhas de todos os documentos, fases e etapas que se aplicam ao componente enquanto ele é executado. + **console.log** — O log do console contém todas as informações de saída padrão (stdout) e erro padrão (stderr) que são AWSTOE gravadas no console enquanto o componente está em execução. + **chaining.json — Esse arquivo JSON** representa otimizações aplicadas para resolver expressões de encadeamento. AWSTOE **nota** A pasta de log também pode conter outros arquivos temporários que não são abordados aqui. ## Encadeamento de entrada e saída O aplicativo de gerenciamento de AWSTOE configuração fornece um recurso para encadear entradas e saídas escrevendo referências nos seguintes formatos: `{{ phase_name.step_name.inputs/outputs.variable }}` or `{{ phase_name.step_name.inputs/outputs[index].variable }}` O atributo de encadeamento permite que você recicle o código e melhore a capacidade de manutenção do documento. **Regras para o encadeamento** + Expressões de encadeamento só podem ser usadas na seção de entradas de cada etapa. + Instruções com expressões encadeadas devem estar entre aspas. Por exemplo: + **Expressão inválida**: `echo {{ phase.step.inputs.variable }}` + **Expressão válida**: `"echo {{ phase.step.inputs.variable }}"` + **Expressão válida**: `'echo {{ phase.step.inputs.variable }}'` + Expressões de encadeamento podem referenciar variáveis de outras etapas e fases no mesmo documento. No entanto, o serviço de chamada pode ter regras que exijam que as expressões de encadeamento operem somente no contexto de um único estágio. Por exemplo, o Image Builder não é compatível com o encadeamento do *estágio de compilação* até o *estágio de teste*, pois ele executa cada estágio de forma independente. + Os índices em expressões de encadeamento seguem a indexação com base em zero. O índice começa com zero (0) para referenciar o primeiro elemento. **Exemplos** Para se referir à variável de origem na segunda entrada da etapa de exemplo a seguir, o padrão de encadeamento é `{{ 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 se referir à variável de saída (igual a "Hello") da etapa de exemplo a seguir, o padrão de encadeamento é `{{ build.{{SamplePowerShellStep}}.outputs.stdout }}`. ``` phases: - name: 'build' steps: - name: {{SamplePowerShellStep}} action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Write-Host "Hello"' ``` ## Esquema e definições do documento Veja a seguir o esquema YAML para um documento. ``` name: (optional) description: (optional) schemaVersion: "string" phases: - name: "string" steps: - name: "string" action: "string" timeoutSeconds: integer onFailure: "Abort|Continue|Ignore" maxAttempts: integer inputs: ``` As definições de esquema para um documento são as seguintes. | Campo | Description | Tipo | Obrigatório | | --- | --- | --- | --- | | name | O nome do documento. | String | Não | | descrição | Descrição do documento. | String | Não | | schemaVersion | Versão do esquema do documento, atualmente 1.0. | String | Sim | | phases | Uma lista de fases com suas etapas. | Lista | Sim | As definições de esquema para uma fase são as seguintes. | Campo | Description | Tipo | Obrigatório | | --- | --- | --- | --- | | name | Nome da fase. | String | Sim | | steps | Lista das etapas da fase. | Lista | Sim | As definições de esquema para uma etapa são as seguintes. | Campo | Description | Tipo | Obrigatório | Valor padrão | | --- | --- | --- | --- | --- | | name | Nome definido pelo usuário para a etapa. | String | | | | ação | Palavra-chave referente ao módulo que executa a etapa. | String | | | | timeoutSeconds | Número de segundos em que a etapa é executada antes de falhar ou tentar novamente.
Além disso, suporta o valor -1, que indica um tempo limite infinito. 0 e outros valores negativos não são permitidos. | Inteiro | Não | 7.200 segundos (120 minutos) | | onFailure | Especifica o que a etapa deve fazer em caso de falha. Os valores válidos são os seguintes: [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/imagebuilder/latest/userguide/toe-use-documents.html) | String | Não | Anular | | maxAttempts | Número máximo de tentativas permitidas antes de falhar na etapa. | Inteiro | Não | 1 | | inputs | Contém os parâmetros exigidos pelo módulo de ação para executar a etapa. | Dict | Sim | | ## Documentos de exemplo Os exemplos a seguir mostram documentos de AWSTOE componentes que executam tarefas para o sistema operacional de destino. ------ #### [ Linux ] **Exemplo 1: executar um arquivo binário personalizado** Veja a seguir um exemplo de documento para baixar e executar um arquivo binário personalizado em uma instância do 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 ] **Exemplo 1: instalar atualizações do Windows** Veja a seguir um exemplo de documento para instalar todas as atualizações disponíveis do Windows, executar um script de configuração, validar as alterações antes da criação da AMI e testar as alterações após a criação da 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}}' ``` **Exemplo 2: instalar o AWS CLI em uma instância do Windows** Veja a seguir um exemplo de documento que instala o AWS CLI em uma instância do Windows, usando o arquivo de configuração. ``` 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 }}' ``` **Exemplo 3: Instale o AWS CLI com o instalador MSI** A seguir está um exemplo de documento que instala o AWS CLI com o 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 ] **Exemplo 1: executar um arquivo binário personalizado no macOS** Veja a seguir um exemplo de documento para baixar e executar um arquivo binário personalizado em uma instância do 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 }}' ``` ------