Temukan penyebab pembuatan gambar yang gagal dengan konteks kegagalan

Saat pembuatan gambar gagal, Image Builder melaporkan kegagalan pada gambarstate. Negara membawa pesan yang menggambarkan kegagalan dalamreason, dan konteks kegagalan terstruktur dalamfailureContext.

Konteks kegagalan adalah sekumpulan bidang yang memberi nama alur kerja, langkah alur kerja, langkah komponen, dan Wilayah tujuan yang terlibat dalam kegagalan. Karena bidang terstruktur, otomatisasi Anda dapat bercabang secara langsung, dan Anda dapat meneruskan nilainya ke operasi Image Builder API lainnya untuk mendapatkan detail lebih lanjut.

Image Builder menampilkan konteks kegagalan dari operasi GetImageListImageBuildVersions,, dan ListImagePipelineImagesAPI, dan menampilkannya di Image Builder Konsol Manajemen AWS.

Apa isi konteks kegagalan

Konteks kegagalan menggambarkan kegagalan pada tiga tingkatan. Setiap anggota adalah opsional, dan Image Builder hanya mengembalikan anggota yang berlaku untuk kegagalan. Untuk anggota, tipe, dan batasan mereka, lihat ImageStatedi Referensi API EC2 Image Builder.

Gambar

Tahap mana gambar berada saat gagal, dan alur kerja dan langkah alur kerja mana yang sedang berjalan. Alur kerja dan pengidentifikasi eksekusi langkah adalah nilai yang sama ListWorkflowStepExecutionsdan GetWorkflowStepExecutiondiambil, sehingga Anda dapat meneruskannya langsung ke operasi tersebut.

Langkah komponen

Untuk kegagalan build atau pengujian yang disebabkan oleh komponen, komponen yang berjalan, fase dan langkah dalam dokumennya, modul AWSTOE tindakan yang dijalankan oleh langkah tersebut, dan kesalahan yang dilaporkan oleh langkah tersebut. Image Builder mengidentifikasi komponen berdasarkan versi build, sehingga menamai revisi persis yang berjalan bahkan ketika resep Anda mereferensikan versi wildcard. Untuk modul aksi, lihatModul aksi didukung oleh AWSTOE manajer komponen.

Daerah tujuan

Untuk kegagalan distribusi atau integrasi, kesalahan ringkasan untuk distribusi secara keseluruhan, dan satu entri untuk setiap tujuan yang gagal. Setiap entri membawa, bagaimana distribusi berakhir di sana, kesalahan dari layanan yang dipanggil Image Builder, dan, untuk distribusi lintas akun, target Akun AWS yang didistribusikan oleh Image Builder. Ketika salinan AMI berhasil tetapi langkah yang mengikutinya tidak, entri juga menyebutkan langkah itu — mengaitkan konfigurasi lisensi, memperbarui templat peluncuran, menempatkan parameter SSM, memperbarui konfigurasi Peluncuran Cepat Amazon EC2, atau mengekspor AMI. Destinasi yang berhasil dihilangkan.

catatan

Anggota mana yang dikembalikan Image Builder bergantung pada seberapa jauh pembangunan berkembang. Kegagalan yang terjadi sebelum Image Builder memulai alur kerja tidak memiliki alur kerja untuk diberi nama. Misalnya, jika gambar induk dalam resep Anda tidak ada lagi, konteks kegagalan mengidentifikasi tahap dan tidak lebih.

Contoh Melihat konteks kegagalan untuk gambar yang gagal menunjukkan anggota yang dikembalikan Image Builder untuk kegagalan komponen dan kegagalan distribusi.

Melihat konteks kegagalan untuk gambar yang gagal

Melihat konteks kegagalan di konsol Image Builder

Image Builder menampilkan rincian kegagalan untuk gambar di mana pun ia menampilkan status Failed gambar.

1. Buka konsol https://console.aws.amazon.com/imagebuilder/EC2 Image Builder di.

2. Pilih Gambar dari panel navigasi, lalu pilih versi pembuatan gambar yang gagal. Anda juga dapat membuka daftar gambar Output untuk pipeline.

3. Pilih status Failed gambar. Image Builder menampilkan detail kegagalan untuk gambar, dan menautkan langkah alur kerja yang gagal ke detail runtime-nya.

Dapatkan konteks kegagalan dengan AWS CLI

Jalankan get-image perintah dengan ARN versi build dari gambar yang gagal.

aws imagebuilder get-image \
    --image-build-version-arn arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0/1 \
    --query "image.state"

Contoh keluaran berikut menunjukkan build yang gagal karena langkah komponen menjalankan skrip yang keluar dengan status bukan nol.

{
    "status": "FAILED",
    "reason": "Workflow Execution ID: 'wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111' failed with reason: Document arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1 failed!",
    "failureContext": {
        "imageStatus": "BUILDING",
        "workflowExecutionId": "wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "workflowArn": "arn:aws:imagebuilder:us-west-2:aws:workflow/build/build-image/x.x.x/x",
        "stepExecutionId": "step-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
        "failedStep": "ApplyBuildComponents",
        "componentFailure": {
            "componentArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1",
            "phaseName": "build",
            "stepName": "InstallPackages",
            "action": "ExecuteBash",
            "errorMessage": "exit status 1"
        }
    }
}

Contoh keluaran berikutnya menunjukkan gambar yang berhasil dibangun dan diuji, lalu gagal saat Image Builder memperbarui template peluncuran di tiga Wilayah tujuan. Pembangunannya berhasil di setiap tujuan lainnya, jadi hanya tiga Wilayah yang gagal yang muncul.

{
    "status": "FAILED",
    "reason": "Integration failed with JobId 'a1b2c3d4-5678-90ab-cdef-EXAMPLE33333', status = 'Failed' for ARN 'arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0/1'. …",
    "failureContext": {
        "imageStatus": "INTEGRATING",
        "distributionFailure": {
            "errorMessage": "In region 'eu-west-1' - 'EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'' …",
            "regionFailures": [
                {
                    "region": "eu-west-1",
                    "status": "FAILED",
                    "imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
                    "errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'"
                },
                {
                    "region": "us-east-1",
                    "status": "FAILED",
                    "imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
                    "errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-1a2b3c4d5EXAMPLE' does not exist'"
                },
                {
                    "region": "us-east-2",
                    "status": "FAILED",
                    "imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
                    "errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-2a3b4c5d6EXAMPLE' does not exist'"
                }
            ]
        }
    }
}

Untuk menemukan build yang gagal di akun tanpa memeriksa masing-masing, buat daftar versi pembuatan gambar dan filter pada status gambar. Contoh berikut mengembalikan build gagal untuk gambar, dengan konteks kegagalan untuk masing-masing.

aws imagebuilder list-image-build-versions \
    --image-version-arn arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0 \
    --query "imageSummaryList[?state.status=='FAILED'].[arn, state.failureContext]"

Melacak kegagalan ke akar penyebabnya

Konteks kegagalan mempersempit kegagalan menjadi satu langkah. Gunakan langkah-langkah berikut untuk beralih dari langkah itu ke bukti yang menjelaskannya.

1. Baca imageStatus untuk menemukan tahap yang gagal. Nilai BUILDING atau TESTING berarti kegagalan terjadi pada instans Amazon EC2 yang diluncurkan Image Builder, sehingga log komponen adalah tempat berikutnya untuk dilihat. Nilai DISTRIBUTING atau INTEGRATING berarti gambar dibangun dan kegagalannya ada di pengaturan distribusi Anda atau di akun tujuan atau.

2. Baca anggota yang menggambarkan kegagalan spesifik. Jika componentFailure ada, ini mengidentifikasi langkah gagal dalam dokumen komponen Anda, bersama dengan tindakan yang dijalankan langkah dan kesalahan yang dilaporkan. Jika distributionFailure ada, setiap entri regionFailures memberi Anda tujuan dan kesalahannya sendiri.

3. Periksa detail runtime alur kerja. Panggil ListWorkflowStepExecutionsdengan workflowExecutionId untuk melihat setiap langkah dalam alur kerja dan di mana langkah gagal jatuh dalam urutan. Hubungi GetWorkflowStepExecutionstepExecutionIduntuk input, output, dan status rollback dari langkah gagal itu sendiri.

   Contoh berikut mencantumkan langkah-langkah untuk eksekusi alur kerja yang gagal.

   aws imagebuilder list-workflow-step-executions \
       --workflow-execution-id wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111

4. Baca log untuk langkah yang gagal. Gunakan workflowExecutionId dan langsung failedStep ke jalur log untuk langkah itu. Untuk informasi selengkapnya, lihat Dapatkan output komponen lengkap dari log.

5. Reproduksi kegagalan jika perlu. Agar instance build tetap berjalan sehingga Anda dapat terhubung dengannya, hapus instans Terminate pada setelan kegagalan dalam konfigurasi infrastruktur yang digunakan pipeline Anda. Untuk informasi selengkapnya, lihat Memecahkan masalah pembangunan pipa.

Dapatkan output komponen lengkap dari log

Konteks kegagalan melaporkan kesalahan yang diangkat oleh langkah komponen, tetapi bukan keluaran standar dan kesalahan standar skrip yang dijalankan langkah tersebut. Image Builder menyimpan output itu di log komponen.

Ketika komponen gagal, AWSTOE tulis detail langkah gagal pertama ke log konsol, diikuti dengan keluaran kesalahan standar lengkap untuk langkah itu.

  Document: MyExampleDocument
  ComponentArn: arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1
  Phase: build
  Step: InstallPackages
  Action: ExecuteBash
  ErrorMessage: exit status 1
  Stderr: the full standard error output of the step

ComponentArnadalah nilai yang sama dengan yang componentFailure.componentArn dilaporkan, jadi gunakan untuk mencocokkan blok log dengan konteks kegagalan untuk gambar. Documentadalah name yang dideklarasikan oleh dokumen komponen, yang dipilih penulis secara independen dari sumber daya komponen, sehingga keduanya dapat berbeda dan Document sendiri tidak mengidentifikasi komponen mana yang gagal.

AWSTOE menulis ErrorMessage dan Stderr hanya ketika langkah gagal menghasilkannya.

Image Builder mengalirkan log komponen ke Amazon CloudWatch Logs saat build selesai. Jika Anda menentukan bucket Amazon S3 dalam konfigurasi infrastruktur, Image Builder juga akan menuliskannya di sana. Untuk nama grup log dan aliran, lihatMemantau log Image Builder dengan Amazon CloudWatch Logs. Untuk file yang AWSTOE menghasilkan dan isi masing-masing, lihatPencatatan komponen.

Gunakan konteks kegagalan dengan agen AI

Konteks kegagalan dirancang untuk dibaca oleh otomatisasi maupun oleh orang-orang. Agen AI yang memecahkan masalah build yang gagal membaca bidang bernama dan menggunakan nilainya sebagai argumen untuk panggilan API berikutnya yang dibuatnya. Itu membuat diagnosis dapat diulang, dan itu membuat agen tidak menebak komponen mana atau untuk diselidiki.

Anda dapat menggunakan konteks kegagalan dengan salah satu cara berikut:

• Pemecahan masalah di Image Builder Konsol Manajemen AWS — Fitur Troubleshoot, yang didukung oleh AWS DevOps Agen, menggunakan konteks kegagalan untuk mencakup penyelidikannya ke langkah alur kerja dan komponen yang gagal sebelum memeriksa log dan sumber daya terkait. Untuk informasi selengkapnya, lihat Memecahkan masalah build yang gagal dengan AI - Pratinjau.

• Agen pengkodean AI Anda sendiri — Agen yang menelepon GetImage menerima konteks kegagalan dalam respons dan dapat mengikutinya dengan cara yang sama. Untuk memberi agen Anda pengetahuan Image Builder yang lebih luas yang diperlukan untuk bertindak berdasarkan apa yang ditemukannya, lihatMemecahkan masalah build dengan agen pengkodean AI.

Jika Anda membangun otomatisasi Anda sendiri pada konteks kegagalan, perlakukan setiap anggota sebagai opsional dan periksa anggota yang Anda gunakan daripada kehadirannya failureContext sendiri. Anggota mana yang dikembalikan Image Builder bergantung pada kegagalannya, dan Image Builder dapat menambahkan anggota dari waktu ke waktu.

Pertimbangan-pertimbangan

Perhatikan hal berikut saat Anda menggunakan konteks kegagalan:

• Image Builder mengembalikan konteks kegagalan hanya untuk gambar yang gagal. Gambar yang sukses dan gambar yang Anda batalkan tidak memilikinya.

• Gambar yang gagal membawa keduanya reason danfailureContext. Gunakan reason untuk ringkasan kegagalan yang dapat dibaca, dan failureContext untuk menemukannya.

• Jika komponen menggunakan ExecuteDocument tindakan untuk menjalankan dokumen bersarang, konteks kegagalan mengidentifikasi komponen yang dijalankan Image Builder dari resep Anda, bukan dokumen bersarang.

• Pesan kesalahan dalam konteks kegagalan dibatasi panjangnya dan dapat dipotong. Log komponen menyimpan output lengkap.

• Konteks kegagalan melaporkan langkah pertama yang gagal. Jika lebih dari satu langkah gagal, tinjau eksekusi langkah alur kerja dan log komponen untuk sisanya.

• Pesan kesalahan dapat berisi teks yang dihasilkan komponen atau AWS layanan lain. Perlakukan mereka sebagai input yang tidak dipercaya jika Anda merendernya atau meneruskannya ke sistem lain.