Ekstensi Konfigurasi Status yang Diinginkan dengan templat Azure Resource Manager

Artikel
06/01/2023

Catatan

Sebelum Anda mengaktifkan ekstensi DSC, kami ingin Anda mengetahui bahwa versi DSC yang lebih baru sekarang tersedia secara umum, dikelola oleh fitur Azure Automange bernama konfigurasi komputer. Fitur konfigurasi mesin menggabungkan fitur handler ekstensi Desired State Configuration (DSC), Azure Automation State Configuration, dan fitur yang paling umum diminta dari umpan balik pelanggan. Konfigurasi komputer juga mencakup dukungan komputer hibrid melalui server yang diaktifkan Arc.

Artikel ini menjelaskan templat Azure Resource Manager untuk Handler ekstensi Konfigurasi Status Yang Diinginkan (DSC). Banyak contoh menggunakan RegistrationURL (disediakan sebagai String) dan RegistrationKey (disediakan sebagai PSCredential untuk onboarding dengan Azure Automation. Untuk detail tentang mendapatkan nilai tersebut, lihat Menggunakan metakonfirasi DSC untuk mendaftarkan mesin hibrid.

Catatan

Anda mungkin menemukan contoh skema yang agak berbeda. Perubahan skema terjadi pada rilis Oktober 2016. Untuk detailnya, lihat Memperbarui dari format sebelumnya.

Contoh templat untuk VM Windows

Cuplikan berikut ini masuk di bagian Sumber Daya pada templat. Ekstensi DSC mewarisi properti ekstensi asali. Untuk informasi selengkapnya, lihat Kelas VirtualMachineExtension.

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "[concat(parameters('VMName'), '/Microsoft.Powershell.DSC')]",
  "apiVersion": "2018-06-01",
  "location": "[parameters('location')]",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', parameters('VMName'))]"
  ],
  "properties": {
    "publisher": "Microsoft.Powershell",
    "type": "DSC",
    "typeHandlerVersion": "2.77",
    "autoUpgradeMinorVersion": true,
    "protectedSettings": {
      "Items": {
        "registrationKeyPrivate": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-06-30').Keys[0].value]"
      }
    },
    "settings": {
      "Properties": [
        {
          "Name": "RegistrationKey",
          "Value": {
            "UserName": "PLACEHOLDER_DONOTUSE",
            "Password": "PrivateSettingsRef:registrationKeyPrivate"
          },
          "TypeName": "System.Management.Automation.PSCredential"
        },
        {
          "Name": "RegistrationUrl",
          "Value": "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
          "TypeName": "System.String"
        },
        {
          "Name": "NodeConfigurationName",
          "Value": "[parameters('nodeConfigurationName')]",
          "TypeName": "System.String"
        }
      ]
    }
  }
}

Contoh templat untuk set skala komputer virtual Windows

Node set skala komputer virtual memiliki bagian properti yang memiliki atribut VirtualMachineProfile, extensionProfile. Di ekstensi, tambahkan detail untuk Ekstensi DSC.

Ekstensi DSC mewarisi properti ekstensi asali. Untuk informasi selengkapnya, lihat Kelas VirtualMachineScaleSetExtension.

"extensionProfile": {
    "extensions": [
      {
        "name": "Microsoft.Powershell.DSC",
        "properties": {
          "publisher": "Microsoft.Powershell",
          "type": "DSC",
          "typeHandlerVersion": "2.77",
          "autoUpgradeMinorVersion": true,
          "protectedSettings": {
            "Items": {
              "registrationKeyPrivate": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-06-30').Keys[0].value]"
            }
          },
          "settings": {
            "Properties": [
              {
                "Name": "RegistrationKey",
                "Value": {
                  "UserName": "PLACEHOLDER_DONOTUSE",
                  "Password": "PrivateSettingsRef:registrationKeyPrivate"
                },
                "TypeName": "System.Management.Automation.PSCredential"
              },
              {
                "Name": "RegistrationUrl",
                "Value": "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
                "TypeName": "System.String"
              },
              {
                "Name": "NodeConfigurationName",
                "Value": "[parameters('nodeConfigurationName')]",
                "TypeName": "System.String"
              }
            ]
          }
        }
      }
    ]
  }

Informasi pengaturan terperinci

Gunakan skema berikut ini di bagian pengaturan ekstensi Azure DSC pada templat Resource Manager.

Untuk daftar argumen yang tersedia untuk skrip konfigurasi default, lihat Skrip konfigurasi default.

"settings": {
    "wmfVersion": "latest",
    "configuration": {
        "url": "http://validURLToConfigLocation",
        "script": "ConfigurationScript.ps1",
        "function": "ConfigurationFunction"
    },
    "configurationArguments": {
        "argument1": "Value1",
        "argument2": "Value2"
    },
    "configurationData": {
        "url": "https://foo.psd1"
    },
    "privacy": {
        "dataCollection": "enable"
    },
    "advancedOptions": {
        "downloadMappings": {
            "customWmfLocation": "http://myWMFlocation"
        }
    }
},
"protectedSettings": {
    "configurationArguments": {
        "parameterOfTypePSCredential1": {
            "userName": "UsernameValue1",
            "password": "PasswordValue1"
        },
        "parameterOfTypePSCredential2": {
            "userName": "UsernameValue2",
            "password": "PasswordValue2"
        }
    },
    "configurationUrlSasToken": "?g!bber1sht0k3n",
    "configurationDataUrlSasToken": "?dataAcC355T0k3N"
}

Detail

Nama properti	Jenis	Deskripsi
settings.wmfVersion	string	Menentukan versi Windows Management Framework (WMF) yang harus diinstal pada VM Anda. Pengaturan properti ini ke terbaru akan menginstal versi WMF terbaru. Saat ini, satu-satunya nilai yang mungkin untuk properti ini adalah 4.0, 5.0, 5.1, dan terbaru. Nilai yang mungkin dapat diperbarui. Nilai defaultnya adalah terbaru.
settings.configuration.url	string	Menentukan lokasi URL dari mana untuk mengunduh file .zip konfigurasi DSC Anda. Jika URL yang disediakan memerlukan token SAS untuk akses, atur properti protectedSettings.configurationUrlSasToken ke nilai token SAS Anda. Properti ini diperlukan jika settings.configuration.script atau settings.configuration.function ditentukan. Jika tidak ada nilai yang diberikan untuk properti ini, ekstensi akan memanggil skrip konfigurasi default untuk mengatur metadata Location Configuration Manager (LCM), dan argumen harus diberikan.
settings.configuration.script	string	Menentukan nama file skrip yang memuat definisi konfigurasi DSC Anda. Skrip ini harus berada di folder akar dari file .zip yang diunduh dari URL yang ditentukan oleh properti settings.configuration.url. Properti ini diperlukan jika settings.configuration.url atau settings.configuration.script ditentukan. Jika tidak ada nilai yang diberikan untuk properti ini, ekstensi akan memanggil skrip konfigurasi default untuk mengatur metadata LCM, dan argumen harus diberikan.
settings.configuration.function	string	Menentukan nama konfigurasi DSC Anda. Konfigurasi yang diberi nama harus disertakan dalam skrip yang menentukan settings.configuration.script. Properti ini diperlukan jika settings.configuration.url atau settings.configuration.function ditentukan. Jika tidak ada nilai yang diberikan untuk properti ini, ekstensi akan memanggil skrip konfigurasi default untuk mengatur metadata LCM, dan argumen harus diberikan.
settings.configurationArguments	Koleksi	Menentukan parameter apa pun yang ingin Anda berikan ke konfigurasi DSC Anda. Properti ini tidak terenkripsi.
settings.configurationData.url	string	Menentukan URL tempat mengunduh file data konfigurasi (.psd1) Anda untuk digunakan sebagai input bagi konfigurasi DSC Anda. Jika URL yang disediakan memerlukan token SAS untuk akses, atur properti protectedSettings.configurationDataUrlSasToken ke nilai token SAS Anda.
settings.privacy.dataCollection	string	Mengaktifkan atau menonaktifkan koleksi telemetri. Satu-satunya nilai yang mungkin untuk properti ini adalah Aktifkan, Nonaktifkan, '' , atau $null. Membiarkan properti ini kosong atau null akan mengaktifkan telemetri. Nilai defaultnya adalah “ . Untuk informasi selengkapnya, lihat Pengumpulan data ekstensi Azure DSC.
settings.advancedOptions.downloadMappings	Koleksi	Menentukan lokasi alternatif untuk mengunduh WMF. Untuk informasi selengkapnya, lihat Ekstensi Azure DSC 2.8 dan cara memetakan unduhan dependensi ekstensi ke lokasi Anda sendiri.
protectedSettings.configurationArguments	Koleksi	Menentukan parameter apa pun yang ingin Anda berikan ke konfigurasi DSC Anda. Properti ini terenkripsi.
protectedSettings.configurationUrlSasToken	string	Menentukan token SAS yang akan digunakan untuk mengakses URL yang ditentukan settings.configuration.url. Properti ini terenkripsi.
protectedSettings.configurationDataUrlSasToken	string	Menentukan token SAS yang akan digunakan untuk mengakses URL yang ditentukan settings.configurationData.url. Properti ini terenkripsi.

Konfigurasi skrip default

Untuk informasi selengkapnya tentang nilai berikut ini, lihat Pengaturan dasar Local Configuration Manager. Anda dapat menggunakan skrip konfigurasi default ekstensi DSC untuk mengonfigurasi hanya properti LCM yang tercantum dalam tabel berikut.

Nama properti	Jenis	Deskripsi
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Properti wajib diisi. Menentukan kunci yang digunakan untuk node agar mendaftar ke layanan Azure Automation sebagai kata sandi objek kredensial PowerShell. Nilai ini dapat ditemukan secara otomatis menggunakan metode listkeys terhadap akun Automation. Lihat contoh.
settings.configurationArguments.RegistrationUrl	string	Properti wajib diisi. Menentukan URL titik akhir Automation tempat node mencoba mendaftar. Nilai ini dapat ditemukan secara otomatis menggunakan metode reference terhadap akun Automation.
settings.configurationArguments.NodeConfigurationName	string	Properti wajib diisi. Menentukan konfigurasi node dalam akun Automation untuk ditetapkan ke node.
settings.configurationArguments.ConfigurationMode	string	Menentukan mode untuk LCM. Opsi yang valid meliputi ApplyOnly, ApplyandMonitor, dan ApplyandAutoCorrect. Nilai defaultnya adalah ApplyandMonitor.
settings.configurationArguments.RefreshFrequencyMins	uint32	Menentukan seberapa sering LCM mencoba memeriksa akun Automation terhadap pembaruan. Nilai defaultnya adalah 30. Nilai minimumnya adalah 15.
settings.configurationArguments.ConfigurationModeFrequencyMins	uint32	Menentukan seberapa sering LCM memvalidasi konfigurasi saat ini. Nilai defaultnya adalah 15. Nilai minimumnya adalah 15.
settings.configurationArguments.RebootNodeIfNeeded	boolean	Menentukan apakah sebuah node dapat di-reboot secara otomatis jika operasi DSC memintanya. Nilai defaultnya adalah false.
settings.configurationArguments.ActionAfterReboot	string	Menentukan apa yang terjadi setelah reboot saat menerapkan konfigurasi. Opsi yang valid adalah ContinueConfiguration dan StopConfiguration. Nilai defaultnya adalah ContinueConfiguration.
settings.configurationArguments.AllowModuleOverwrite	boolean	Menentukan apakah LCM menimpa modul yang sudah ada pada node. Nilai defaultnya adalah false.

ssttings vs. protectedSettings

Semua pengaturan disimpan dalam file teks pengaturan pada VM. Properti yang tercantum pada settings adalah properti publik. Properti publik tidak dienkripsi dalam file teks pengaturan. Properti yang tercantum pada protectedSettings dienkripsi dengan sertifikat dan tidak ditampilkan dalam teks biasa pada file pengaturan di VM.

Jika konfigurasi memerlukan kredensial, Anda dapat menyertakan kredensial dalam protectedSettings:

"protectedSettings": {
    "configurationArguments": {
        "parameterOfTypePSCredential1": {
               "userName": "UsernameValue1",
               "password": "PasswordValue1"
        }
    }
}

Contoh konfigurasi skrip

Contoh berikut menunjukkan perilaku default untuk ekstensi DSC, yaitu menyediakan pengaturan metadata ke LCM dan mendaftar dengan layanan Automation DSC. Argumen konfigurasi wajib diisi. Argumen konfigurasi diteruskan ke skrip konfigurasi default untuk mengatur metadata LCM.

"settings": {
    "configurationArguments": {
        "RegistrationUrl" : "[parameters('registrationUrl1')]",
        "NodeConfigurationName" : "nodeConfigurationNameValue1"
    }
},
"protectedSettings": {
    "configurationArguments": {
        "RegistrationKey": {
            "userName": "NOT_USED",
            "Password": "registrationKey"
        }
    }
}

Contoh menggunakan skrip konfigurasi di Azure Storage

Contoh berikut adalah dari ringkasan handler ekstensi DSC. Contoh ini menggunakan templat Resource Manager sebagai ganti cmdlet untuk menyebarkan ekstensi. Simpan konfigurasi IisInstall.ps1, letakkan dalam file .zip (misalnya: iisinstall.zip), lalu unggah file dalam URL yang dapat diakses. Contoh ini menggunakan penyimpanan Blob Azure, tetapi Anda dapat mengunduh .zip dari lokasi arbitrer mana pun.

Dalam templat Resource Manager, kode berikut menginstruksikan VM agar mengunduh file yang tepat, lalu menjalankan fungsi PowerShell yang sesuai:

"settings": {
    "configuration": {
        "url": "https://demo.blob.core.windows.net/iisinstall.zip",
        "script": "IisInstall.ps1",
        "function": "IISInstall"
    }
},
"protectedSettings": {
    "configurationUrlSasToken": "odLPL/U1p9lvcnp..."
}

Contoh menggunakan nilai pendaftaran Azure Automation yang direferensikan

Contoh berikut mendapatkan RegistrationUrl dan RegistrationKey dengan merujuk pada properti akun Azure Automation dan menggunakan metode listkeys untuk mengambil Kunci Utama (0). Dalam contoh ini, parameter automationAccountName dan NodeConfigName tersedia bagi templat.

"settings": {
    "RegistrationUrl" : "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
    "NodeConfigurationName" : "[parameters('NodeConfigName')]"
},
"protectedSettings": {
    "configurationArguments": {
        "RegistrationKey": {
            "userName": "NOT_USED",
            "Password": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-01-15').Keys[0].value]"
        }
    }
}

Memperbarui dari format sebelumnya

Setiap pengaturan dalam format ekstensi sebelumnya (dan yang memiliki properti publik ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken, atau Properties) secara otomatis beradaptasi dengan format ekstensi saat ini. Properti ini berjalan seperti sebelumnya.

Skema berikut menunjukkan seperti apa skema pengaturan sebelumnya:

"settings": {
    "WMFVersion": "latest",
    "ModulesUrl": "https://UrlToZipContainingConfigurationScript.ps1.zip",
    "SasToken": "SAS Token if ModulesUrl points to private Azure Blob Storage",
    "ConfigurationFunction": "ConfigurationScript.ps1\\ConfigurationFunction",
    "Properties": {
        "ParameterToConfigurationFunction1": "Value1",
        "ParameterToConfigurationFunction2": "Value2",
        "ParameterOfTypePSCredential1": {
            "UserName": "UsernameValue1",
            "Password": "PrivateSettingsRef:Key1"
        },
        "ParameterOfTypePSCredential2": {
            "UserName": "UsernameValue2",
            "Password": "PrivateSettingsRef:Key2"
        }
    }
},
"protectedSettings": {
    "Items": {
        "Key1": "PasswordValue1",
        "Key2": "PasswordValue2"
    },
    "DataBlobUri": "https://UrlToConfigurationDataWithOptionalSasToken.psd1"
}

Berikut adalah cara format sebelumnya beradaptasi dengan format saat ini:

Nama Properti Saat Ini	Setara skema sebelumnya
settings.wmfVersion	settings.WMFVersion
settings.configuration.url	settings.ModulesUrl
settings.configuration.script	Bagian pertama dari settings.ConfigurationFunction (sebelum \\)
settings.configuration.function	Bagian kedua dari settings.ConfigurationFunction (setelah \\)
settings.configuration.module.name	settings.ModuleSource
settings.configuration.module.version	settings.ModuleVersion
settings.configurationArguments	settings.Properties
settings.configurationData.url	protectedSettings.DataBlobUri (tanpa token SAS)
settings.privacy.dataCollection	settings.Privacy.dataCollection
settings.advancedOptions.downloadMappings	settings.AdvancedOptions.DownloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	settings.SasToken
protectedSettings.configurationDataUrlSasToken	Token SAS dari protectedSettings.DataBlobUri

Pemecahan Masalah

Berikut adalah beberapa kesalahan yang mungkin Anda alami dan cara Anda dapat memperbaikinya.

Nilai tidak valid

"Privacy.dataCollection adalah '{0}'. Satu-satunya nilai yang mungkin adalah '', 'Enable', dan 'Disable'". "WmfVersion adalah '{0}'. Satu-satunya nilai yang memungkinkan adalah … dan 'terbaru'".

Masalah: Nilai yang diberikan tidak diperbolehkan.

Solusi: Ubah nilai yang tidak valid ke nilai yang valid. Untuk informasi selengkapnya, lihat tabel pada Detail.

URL tidak valid

"ConfigurationData.url adalah '{0}'. Ini bukan URL yang valid" "DataBlobUri adalah '{0}'. Ini bukan URL yang valid" "Configuration.url adalah '{0}'. Ini bukan URL yang valid"

Masalah: URL yang disediakan tidak valid.

Solusi: Periksa semua URL yang Anda sediakan. Pastikan bahwa semua URL teratasi di lokasi yang valid yang dapat diakses ekstensi pada komputer jarak jauh.

Jenis RegistrationKey tidak valid

"Jenis tidak valid untuk parameter RegistrationKey dari jenis PSCredential."

Masalah: Nilai RegistrationKey dalam protectedSettings.configurationArguments tidak dapat disediakan sebagai jenis apa pun selain PSCredential.

Solusi: Ubah entri protectedSettings.configurationArguments Anda untuk RegistrationKey ke jenis PSCredential menggunakan format berikut:

"configurationArguments": {
    "RegistrationKey": {
        "userName": "NOT_USED",
        "Password": "RegistrationKey"
    }
}

Jenis ConfigurationArgument tidak valid

"Jenis configurationArguments tidak valid {0}"

Masalah: Properti ConfigurationArguments tidak dapat mengatasi objek tabel Hash.

Solusi: Jadikan properti ConfigurationArguments Anda sebagai tabel Hash. Ikuti format yang disediakan dalam contoh sebelumnya. Perhatikan kutipan, koma, dan kurung.

Duplikat ConfigurationArguments

"Ditemukan argumen duplikat '{0}' dalam configurationArguments publik dan yang dilindungi"

Masalah: ConfigurationArguments pada pengaturan publik dan ConfigurationArguments pada pengaturan yang dilindungi memiliki properti dengan nama yang sama.

Solusi: Hapus salah satu properti duplikat.

Properti hilang

"settings.Configuration.function mewajibkan agar settings.configuration.url settings.configuration.module ditentukan"

"settings.Configuration.url mewajibkan agar settings.configuration.script ditentukan"

"settings.Configuration.script mewajibkan agar settings.configuration.url ditentukan"

"settings.Configuration.url mewajibkan agar settings.configuration.function ditentukan"

"protectedSettings.ConfigurationUrlSasToken mewajibkan agar settings.configuration.url ditentukan"

"protectedSettings.ConfigurationDataUrlSasToken mewajibkan agar settings.configurationData.url ditentukan"

Masalah: Properti yang ditentukan memerlukan properti lain, yang hilang.

Solusi:

Masukkan properti yang hilang.
Hapus properti yang membutuhkan properti yang hilang.

Langkah berikutnya

Pelajari tentang menggunakan Set Skala Komputer Virtual dengan ekstensi Azure DSC.
Temukan detail selengkapnya tentang manajemen kredensial aman DSC.
Dapatkan pengantar handler ekstensi Azure DSC.
Untuk informasi selengkapnya tentang PowerShell DSC, kunjungi Pusat dokumentasi PowerShell.