Membuat runbook modular di Automation

  • Artikel

Ini adalah praktik yang baik di Azure Automation untuk menulis runbook modular yang dapat digunakan kembali dengan fungsi unik yang dipanggil oleh runbook lain. Runbook induk sering memanggil satu atau beberapa runbook turunan untuk melakukan fungsionalitas yang diperlukan.

Ada dua cara untuk memanggil runbook turunan: inline atau melalui cmdlet. Tabel berikut merangkum perbedaan untuk membantu Anda memutuskan cara yang lebih baik untuk skenario Anda.

Inline Cmdlet
Tugas Runbook turunan berjalan dalam pekerjaan yang sama dengan induk. Pekerjaan terpisah dibuat untuk runbook turunan.
Eksekusi Runbook induk menunggu runbook turunan selesai sebelum melanjutkan. Runbook induk dilanjutkan segera setelah runbook turunan dimulai, atau runbook induk menunggu pekerjaan turunan selesai.
Hasil Runbook induk dapat langsung mendapatkan output dari runbook turunan. Runbook induk harus mengambil output dari pekerjaan runbook turunan, atau runbook induk dapat langsung mendapatkan output dari runbook turunan.
Parameter Nilai untuk parameter runbook turunan ditentukan secara terpisah dan dapat menggunakan jenis data apa pun. Nilai untuk parameter runbook turunan harus digabungkan menjadi satu hashtable. Hashtable ini hanya dapat mencakup jenis data sederhana, array, dan objek yang menggunakan serialisasi JSON.
Akun Automation Runbook induk hanya dapat menggunakan runbook turunan di akun Automation yang sama. Runbook induk dapat menggunakan runbook turunan dari akun Automation apa pun, dari langganan Azure yang sama, dan bahkan dari langganan lain yang memiliki koneksi Anda.
Menerbitkan Runbook turunan harus dipublikasikan sebelum runbook induk dipublikasikan. Runbook turunan dipublikasikan kapan saja sebelum runbook induk dimulai.

Memanggil runbook turunan menggunakan eksekusi inline

Untuk memanggil inline runbook dari runbook lain, gunakan nama runbook dan berikan nilai untuk parameternya, seperti saat akan menggunakan aktivitas atau cmdlet. Semua runbook dalam akun Automation yang sama tersedia untuk semua yang lain untuk digunakan dengan cara ini. Runbook induk menunggu runbook turunan selesai sebelum berpindah ke baris berikutnya, dan output apa pun langsung kembali ke induk.

Saat Anda memanggil inline runbook, runbook ini berjalan dalam pekerjaan yang sama dengan runbook induk. Tidak ada indikasi dalam riwayat pekerjaan runbook turunan. Setiap pengecualian dan output streaming apa pun dari runbook turunan dikaitkan dengan induknya. Perilaku ini menghasilkan lebih sedikit pekerjaan dan membuatnya lebih mudah dilacak dan untuk memecahkan masalah.

Ketika runbook diterbitkan, setiap buku yang dijalankan turunan yang dipanggilnya harus sudah diterbitkan. Alasannya adalah bahwa Azure Automation membangun keterkaitan dengan setiap runbook turunan ketika mengompilasi runbook. Jika runbook turunan belum dipublikasikan, runbook induk tampaknya diterbitkan dengan benar tetapi menghasilkan pengecualian ketika dimulai.

Jika pengecualian ini terjadi, Anda dapat memublikasikan ulang runbook induk untuk mereferensikan runbook turunan dengan benar. Anda tidak perlu menerbitkan ulang runbook induk jika ada runbook turunan yang diubah karena asosiasi telah dibuat.

Parameter runbook turunan yang dipanggil inline dapat dari jenis data apa pun, termasuk objek kompleks. Tidak ada serialisasi JSON, seperti saat Anda memulai runbook menggunakan portal Azure atau dengan cmdlet Start-AzAutomationRunbook.

Jenis runbook

Saat ini, PowerShell 5.1 didukung dan hanya jenis runbook tertentu yang dapat saling memanggil:

  • Runbook PowerShell dan runbook grafis dapat saling memanggil inline karena keduanya berbasis PowerShell.
  • Runbook Alur Kerja PowerShell dan runbook Alur Kerja PowerShell grafis dapat saling memanggil inline karena keduanya berbasis PowerShell Workflow.
  • Jenis PowerShell dan jenis Alur Kerja PowerShell tidak dapat saling memanggil inline. Keduanya harus menggunakan Start-AzAutomationRunbook.

Penting

Menjalankan skrip turunan yang menggunakan .\child-runbook.ps1 tidak didukung di PowerShell 7.1 dan Solusi PowerShell 7.2: Gunakan Start-AutomationRunbook (cmdlet internal) atau Start-AzAutomationRunbook (dari modul Az.Automation) untuk memulai runbook lain dari runbook induk.

Urutan publikasi runbook hanya diperlukan untuk runbook Alur Kerja PowerShell dan Alur Kerja PowerShell grafis.

Saat runbook Anda memanggil runbook turunan Alur Kerja PowerShell atau grafis menggunakan eksekusi inline, runbook ini menggunakan nama runbook. Nama harus dimulai dengan .\\ untuk menentukan bahwa skrip terletak di direktori lokal.

Contoh

Contoh berikut memulai runbook turunan pengujian yang menerima objek kompleks, nilai bilangan bulat, dan nilai Boolean. Output dari runbook turunan ditetapkan ke variabel. Dalam hal ini, runbook turunan adalah runbook PowerShell Workflow.

$vm = Get-AzVM -ResourceGroupName "LabRG" -Name "MyVM"
$output = PSWF-ChildRunbook -VM $vm -RepeatCount 2 -Restart $true

Berikut adalah contoh yang sama tetapi menggunakan runbook PowerShell sebagai elemen turunan.

$vm = Get-AzVM -ResourceGroupName "LabRG" -Name "MyVM"
$output = .\PS-ChildRunbook.ps1 -VM $vm -RepeatCount 2 -Restart $true

Memulai runbook turunan menggunakan cmdlet

Penting

Jika runbook Anda memanggil runbook turunan dengan menggunakan cmdlet Start-AzAutomationRunbook dengan parameter Wait dan runbook turunan menghasilkan hasil objek, operasi mungkin mengalami kesalahan. Untuk mengatasi kesalahan, lihat Runbook turunan dengan output objek. Artikel itu menunjukkan kepada Anda cara menerapkan logika untuk melakukan jajak pendapat untuk hasil dengan menggunakan cmdlet Get-AzAutomationJobOutputRecord.

Anda dapat menggunakan Start-AzAutomationRunbook untuk memulai runbook, seperti yang dijelaskan di Memulai runbook dengan Windows PowerShell. Ada dua mode penggunaan untuk cmdlet ini:

  • Cmdlet menampilkan ID pekerjaan saat pekerjaan dibuat untuk runbook turunan.
  • Cmdlet menunggu hingga pekerjaan turunan selesai dan menampilkan output dari runbook turunan. Skrip Anda mengaktifkan mode ini dengan menentukan parameter Wait.

Pekerjaan dari runbook turunan dimulai dengan cmdlet berjalan terpisah dari pekerjaan runbook induk. Perilaku ini menghasilkan lebih banyak pekerjaan daripada memulai inline runbook, dan membuat pekerjaan lebih sulit dilacak. Induk dapat memulai lebih dari satu runbook turunan secara asinkron tanpa menunggu masing-masing selesai. Untuk eksekusi paralel ini memanggil runbook turunan sebaris, runbook induk harus menggunakan kata kunci paralel.

Output runbook elemen anak tidak kembali ke runbook induk dengan lancar karena waktu. Selain itu, variabel $VerbosePreference, $WarningPreference, dan variabel lainnya mungkin tidak disebarkan ke runbook turunan. Untuk menghindari masalah ini, Anda dapat memulai runbook turunan sebagai pekerjaan Automation terpisah menggunakan Start-AzAutomationRunbook dengan parameter Wait. Teknik ini memblokir runbook induk hingga runbook turunan selesai.

Jika tidak ingin runbook induk diblokir saat menunggu, Anda dapat memulai runbook turunan menggunakan Start-AzAutomationRunbook tanpa parameter Wait. Dalam hal ini, runbook Anda harus menggunakan Get-AzAutomationJob untuk menunggu penyelesaian pekerjaan. Ini juga harus menggunakan Get-AzAutomationJobOutput dan Get-AzAutomationJobOutputRecord untuk mengambil hasilnya.

Parameter untuk runbook turunan yang dimulai dengan cmdlet tersedia sebagai hashtable, seperti yang dijelaskan dalam Parameter runbook. Anda hanya dapat menggunakan jenis data sederhana. Jika runbook memiliki parameter dengan jenis data yang kompleks, runbook harus dipanggil inline.

Konteks langganan mungkin hilang saat Anda memulai runbook turunan sebagai pekerjaan terpisah. Agar runbook turunan dapat menjalankan cmdlet modul Az terhadap langganan Azure tertentu, turunan harus mengautentikasi langganan ini secara terpisah dari runbook induk.

Jika pekerjaan dalam akun Automation yang sama berfungsi dengan lebih dari satu langganan, memilih langganan dalam satu pekerjaan dapat mengubah konteks langganan yang saat ini dipilih untuk pekerjaan lain. Untuk menghindari situasi ini, gunakan Disable-AzContextAutosave -Scope Process di awal setiap runbook. Tindakan ini hanya menyimpan konteks untuk eksekusi runbook tersebut.

Contoh

Contoh berikut memulai runbook turunan dengan parameter lalu menunggunya selesai menggunakan cmdlet Start-AzAutomationRunbook dengan parameter Wait. Setelah runbook turunan selesai, contohnya mengumpulkan output cmdlet dari runbook turunan. Untuk menggunakan Start-AzAutomationRunbook, skrip harus mengautentikasi ke langganan Azure Anda.

# Ensure that the runbook does not inherit an AzContext
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext

$params = @{"VMName"="MyVM";"RepeatCount"=2;"Restart"=$true}

Start-AzAutomationRunbook `
    -AutomationAccountName 'MyAutomationAccount' `
    -Name 'Test-ChildRunbook' `
    -ResourceGroupName 'LabRG' `
    -DefaultProfile $AzureContext `
    -Parameters $params -Wait

Jika Anda ingin runbook dijalankan dengan identitas terkelola yang ditetapkan sistem, jangan ubah kodenya. Jika Anda lebih suka menggunakan identitas terkelola yang ditetapkan pengguna:

  1. Dari baris 5, hapus $AzureContext = (Connect-AzAccount -Identity).context,
  2. Ganti dengan $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, dan
  3. Masukkan ID klien.

Langkah berikutnya