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

Gunakan kerangka dokumen AWSTOE komponen untuk komponen kustom

Untuk membangun komponen menggunakan framework komponen 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 AWS gunakan 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, input/output nilai, dan contoh, lihatModul aksi didukung oleh manajer AWSTOE komponen.

Pencatatan komponen

AWSTOE membuat folder log baru pada EC2 instance 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 sebuah 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 dan macOS: /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

AWSTOE menyimpan 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. Misalnya:
- 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	Wajib
name	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	Wajib
name	Nama fase.	Tali	Ya
langkah	Daftar langkah-langkah dalam fase.	Daftar	Ya

Definisi skema untuk suatu langkah adalah sebagai berikut.

Bidang	Deskripsi	Tipe	Wajib	Nilai default
name	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.	Bilangan 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.	Bilangan Bulat	Tidak	1
masukan	Berisi parameter yang diperlukan oleh modul tindakan untuk menjalankan langkah.	Dikte	Ya

Contoh dokumen

Contoh berikut menunjukkan dokumen AWSTOE komponen yang melakukan tugas untuk sistem operasi target.

Linux

Contoh 1: Jalankan file biner kustom

Berikut ini adalah contoh dokumen yang men-download dan menjalankan file biner kustom pada instance 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

Contoh 1: Instal pembaruan Windows

Berikut ini adalah contoh dokumen yang 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}}'

Contoh 2: Instal AWS CLI pada instance Windows

Berikut ini adalah contoh dokumen yang 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 }}'

Contoh 3: Instal AWS CLI dengan installer MSI

Berikut ini adalah contoh dokumen yang menginstal AWS CLI dengan 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 }}'

macOS

Contoh 1: Jalankan file biner macOS kustom

Berikut ini adalah contoh dokumen yang mengunduh dan menjalankan file biner kustom pada instance 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 }}'

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

Variabel