Alur kerja dokumen komponen Pencatatan komponen Rantai input dan output Skema dan definisi dokumen Skema contoh dokumen

Gunakan dokumen komponen di AWSTOE

Untuk membuat komponen menggunakan AWS Task Orchestrator and Executor (AWSTOE), Anda harus menyediakan dokumen berbasis YAML yang mewakili fase dan langkah yang berlaku untuk komponen yang Anda buat. Layanan AWSgunakan komponen Anda saat mereka membuat Amazon Machine Image (AMI) atau image container baru.

Topik

Alur kerja dokumen komponen

Dokumen AWSTOE komponen menggunakan fase dan langkah untuk mengelompokkan tugas terkait, dan mengatur tugas-tugas tersebut ke dalam alur kerja logis untuk komponen.

Tip

Layanan yang menggunakan komponen Anda untuk membuat image mungkin menerapkan aturan tentang fase apa yang akan digunakan untuk proses pembuatannya, dan kapan fase tersebut diizinkan untuk dijalankan. Ini penting untuk dipertimbangkan ketika Anda mendesain komponen Anda.

Fase

Fase mewakili perkembangan alur kerja Anda melalui proses pembuatan gambar. Misalnya, layanan Image Builder menggunakan build dan melakukan validate fase selama tahap build untuk gambar yang dihasilkannya. Ini menggunakan container-host-test fase test dan selama tahap pengujian untuk memastikan bahwa snapshot gambar atau gambar kontainer menghasilkan hasil yang diharapkan sebelum membuat AMI akhir atau mendistribusikan gambar kontainer.

Ketika komponen berjalan, perintah terkait untuk setiap fase diterapkan dalam urutan yang muncul dalam dokumen komponen.

Aturan untuk fase

Setiap nama fase harus unik dalam dokumen.
Anda dapat menentukan banyak fase dalam dokumen Anda.
Anda harus menyertakan setidaknya satu dari tahapan berikut dalam dokumen Anda:
- build — untuk Image Builder, fase ini umumnya digunakan selama tahap build.
- validate — untuk Image Builder, fase ini umumnya digunakan selama tahap build.
- test — untuk Image Builder, fase ini umumnya digunakan selama tahap pengujian.
Fase selalu berjalan dalam urutan yang didefinisikan dalam dokumen. Urutan di mana mereka ditentukan untuk AWSTOE perintah di tidak AWS CLI berpengaruh.

Langkah-langkah

Langkah-langkah adalah unit kerja individu yang menentukan alur kerja dalam setiap fase. Langkah-langkah berjalan secara berurutan. Namun, input atau output untuk satu langkah juga dapat dimasukkan ke langkah berikutnya sebagai input. Ini disebut “rantai”.

Aturan untuk langkah-langkah

Nama langkah harus unik untuk fase tersebut.
Langkah harus menggunakan tindakan yang didukung (modul tindakan) yang mengembalikan kode keluar.

Untuk daftar lengkap modul tindakan yang didukung, cara kerjanya, nilai input/output, dan contoh, lihat. Modul aksi didukung oleh manajer AWSTOE komponen

Pencatatan komponen

AWSTOEmembuat folder log baru pada instance EC2 yang digunakan untuk membangun dan menguji gambar baru, setiap kali komponen Anda berjalan. Untuk gambar kontainer, folder log disimpan dalam wadah.

Untuk membantu pemecahan masalah jika terjadi kesalahan selama proses pembuatan gambar, dokumen input dan semua file output yang AWSTOE dibuat saat menjalankan komponen disimpan di folder log.

Nama folder log terdiri dari bagian-bagian berikut:

Direktori log — ketika layanan menjalankan AWSTOE komponen, ia melewati direktori log, bersama dengan pengaturan lain untuk perintah. Untuk contoh berikut, kami menunjukkan format file log yang digunakan Image Builder.
- Linux: /var/lib/amazon/toe/
- Windows: $env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\
Awalan file — Ini adalah awalan standar yang digunakan untuk semua komponen: "”TOE_.
Run time - Ini adalah stempel waktu dalam format YYYY-MM-DD_HH-MM-SS_UTC-0.
Execution ID — Ini adalah GUID yang ditetapkan ketika AWSTOE menjalankan satu atau beberapa komponen.

Contoh: /var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4

AWSTOEmenyimpan file inti berikut di folder log:

Berkas masukan

document.yaml — Dokumen yang digunakan sebagai input untuk perintah. Setelah komponen berjalan, file ini disimpan sebagai artefak.

Berkas keluaran

application.log - Log aplikasi berisi informasi tingkat debug stempel waktu dari AWSTOE tentang apa yang terjadi saat komponen sedang berjalan.
detailedoutput.json — File JSON ini memiliki informasi rinci tentang status run, input, output, dan kegagalan untuk semua dokumen, fase, dan langkah-langkah yang berlaku untuk komponen saat berjalan.
console.log - Log konsol berisi semua informasi standar keluar (stdout) dan kesalahan standar (stderr) yang AWSTOE menulis ke konsol saat komponen sedang berjalan.
chaining.json - File JSON ini mewakili pengoptimalan yang diterapkan untuk menyelesaikan ekspresi rantai. AWSTOE

catatan

Folder log mungkin juga berisi file sementara lainnya yang tidak tercakup di sini.

Rantai input dan output

Aplikasi manajemen AWSTOE konfigurasi menyediakan fitur untuk merantai input dan output dengan menulis referensi dalam format berikut:

{{ phase_name.step_name.inputs/outputs.variable }}

atau

{{ phase_name.step_name.inputs/outputs[index].variable }}

Fitur chaining memungkinkan Anda untuk mendaur ulang kode dan meningkatkan pemeliharaan dokumen.

Aturan untuk rantai

Ekspresi rantai hanya dapat digunakan di bagian input dari setiap langkah.
Pernyataan dengan ekspresi rantai harus dilampirkan dalam tanda kutip. Sebagai contoh:
- Ekspresi tidak valid: echo {{ phase.step.inputs.variable }}
- Ekspresi yang valid: "echo {{ phase.step.inputs.variable }}"
- Ekspresi yang valid: 'echo {{ phase.step.inputs.variable }}'
Ekspresi rantai dapat mereferensikan variabel dari langkah dan fase lain dalam dokumen yang sama. Namun, layanan panggilan mungkin memiliki aturan yang memerlukan ekspresi rantai untuk beroperasi hanya dalam konteks satu tahap. Misalnya, Image Builder tidak mendukung chaining dari tahap build ke tahap pengujian, karena Image Builder menjalankan setiap tahap secara independen.
Indeks dalam ekspresi rantai mengikuti pengindeksan berbasis nol. Indeks dimulai dengan nol (0) untuk referensi elemen pertama.

Contoh

Untuk merujuk ke variabel sumber pada entri kedua dari langkah contoh berikut, pola rantai adalah{{ 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'

Untuk merujuk ke variabel output (sama dengan “Halo”) dari langkah contoh berikut, pola rantai adalah{{ build.SamplePowerShellStep.outputs.stdout }}.


phases:
  -
    name: 'build'
    steps:
      -
        name: SamplePowerShellStep
        action: ExecutePowerShell
        timeoutSeconds: 120
        onFailure: Abort
        maxAttempts: 3
        inputs:
          commands:
            - 'Write-Host "Hello"'

Skema dan definisi dokumen

Berikut ini adalah skema YAMM untuk dokumen.


name: (optional)
description: (optional)
schemaVersion: "string"

phases:
  - name: "string"
    steps:
        - name: "string"
          action: "string"
          timeoutSeconds: integer
          onFailure: "Abort|Continue|Ignore"
          maxAttempts: integer
          inputs:

Definisi skema untuk dokumen adalah sebagai berikut.

Bidang	Deskripsi	Tipe	Diperlukan
nama	Nama dokumen.	String	Tidak
deskripsi	Deskripsi dokumen.	String	Tidak
schemaVersion	Versi skema dokumen, saat ini 1.0.	Tali	Ya
fase	Daftar fase dengan langkah-langkahnya.	Daftar	Ya

Definisi skema untuk suatu fase adalah sebagai berikut.

Bidang	Deskripsi	Tipe	Diperlukan
nama	Nama fase.	Tali	Ya
langkah	Daftar langkah-langkah dalam fase.	Daftar	Ya

Definisi skema untuk suatu langkah adalah sebagai berikut.

Bidang	Deskripsi	Tipe	Diperlukan	Nilai default
nama	Nama yang ditentukan pengguna untuk langkah tersebut.	String
tindakan	Kata kunci yang berkaitan dengan modul yang menjalankan langkah.	String
timeoutSeconds	Jumlah detik langkah berjalan sebelum gagal atau mencoba lagi. Juga, mendukung -1 nilai, yang menunjukkan batas waktu tak terbatas. 0 dan nilai negatif lainnya tidak diperbolehkan.	Bulat	Tidak	7.200 detik (120 menit)
onFailure	Menentukan apa yang harus dilakukan langkah jika terjadi kegagalan. Nilai yang valid adalah sebagai berikut: Batalkan — Gagal langkah setelah jumlah upaya maksimum, dan berhenti berjalan. Menetapkan status untuk fase dan dokumen ke`Failed`. Lanjutkan — Gagal langkah setelah jumlah upaya maksimum, dan terus menjalankan langkah-langkah yang tersisa. Menetapkan status untuk fase dan dokumen ke`Failed`. Abaikan - Tetapkan langkah ke `IgnoredFailure` setelah jumlah maksimum upaya yang gagal, dan terus menjalankan langkah-langkah yang tersisa. Menetapkan status untuk fase dan dokumen ke`SuccessWithIgnoredFailure`.	String	Tidak	Batalkan
maxAttempts	Jumlah maksimum upaya yang diizinkan sebelum gagal langkah.	Bulat	Tidak	1
masukan	Berisi parameter yang diperlukan oleh modul tindakan untuk menjalankan langkah.	Dikte	Ya

Skema contoh dokumen

Berikut ini adalah contoh skema dokumen untuk menginstal semua pembaruan Windows yang tersedia, menjalankan skrip konfigurasi, memvalidasi perubahan sebelum AMI dibuat, dan menguji perubahan setelah AMI dibuat.


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}}'

Berikut ini adalah contoh skema dokumen untuk men-download dan menjalankan file biner Linux kustom.


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>mybucket</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 }}'

Berikut ini adalah contoh skema dokumen untuk menginstal AWS CLI pada instance Windows, menggunakan file setup.


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 }}'

Berikut ini adalah contoh skema dokumen untuk menginstal AWS CLI menggunakan installer 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 }}'

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Verifikasi tanda tangan

Tentukan variabel