Azure Resource Manager şablonlarıyla istenen Durum Yapılandırması uzantısı

Makale
08/25/2024

Not

DSC uzantısını etkinleştirmeden önce, azure automange adlı makine yapılandırması özelliği tarafından yönetilen daha yeni bir DSC sürümünün genel kullanıma sunulduğundan emin olmak isteriz. Makine yapılandırma özelliği, İstenen Durum Yapılandırması (DSC) uzantı işleyicisinin özelliklerini, durum yapılandırması Azure Otomasyonu ve müşteri geri bildirimlerinden en sık istenen özellikleri birleştirir. Makine yapılandırması, Arc özellikli sunucular aracılığıyla karma makine desteği de içerir.

Bu makalede, İstenen Durum Yapılandırması (DSC) uzantısı işleyicisi için Azure Resource Manager şablonu açıklanmaktadır. Örneklerin çoğu, Azure Otomasyonu eklemek için RegistrationURL (Dize olarak sağlanır) ve RegistrationKey (PSCredential olarak sağlanır) kullanır. Bu değerleri alma hakkında ayrıntılı bilgi için bkz . Karma makineleri kaydetmek için DSC meta yapılandırması kullanma.

Not

Biraz farklı şema örnekleriyle karşılaşabilirsiniz. Şema değişikliği Ekim 2016 sürümünde gerçekleşti. Ayrıntılar için bkz . Önceki biçimden güncelleştirme.

Windows VM için şablon örneği

Aşağıdaki kod parçacığı şablonun Kaynak bölümüne gider. DSC uzantısı varsayılan uzantı özelliklerini devralır. Daha fazla bilgi için bkz . VirtualMachineExtension sınıfı.

{
  "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"
        }
      ]
    }
  }
}

Windows sanal makine ölçek kümeleri için şablon örneği

Sanal makine ölçek kümesi düğümü, VirtualMachineProfile, extensionProfile özniteliğine sahip özellikler bölümüne sahiptir. Uzantılar'ın altında DSC Uzantısının ayrıntılarını ekleyin.

DSC uzantısı varsayılan uzantı özelliklerini devralır. Daha fazla bilgi için bkz . VirtualMachineScaleSetExtension sınıfı.

"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"
              }
            ]
          }
        }
      }
    ]
  }

Ayrıntılı ayarlar bilgileri

Resource Manager şablonundaki Azure DSC uzantısının ayarlar bölümünde aşağıdaki şemayı kullanın.

Varsayılan yapılandırma betiği için kullanılabilen bağımsız değişkenlerin listesi için bkz . Varsayılan yapılandırma betiği.

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

Ayrıntılar

Özellik adı	Türü	Açıklama
settings.wmfVersion	Dize	VM'nize yüklenmesi gereken Windows Management Framework (WMF) sürümünü belirtir. Bu özelliğin en son olarak ayarlanması WMF'nin en son sürümünü yükler. Şu anda bu özelliğin tek olası değerleri 4.0, 5.0, 5.1 ve en son değerleridir. Bu olası değerler güncelleştirmelere tabidir. Varsayılan değer en son değerdir.
settings.configuration.url	Dize	DSC yapılandırma .zip dosyanızın indirildiği URL konumunu belirtir. Sağlanan URL erişim için bir SAS belirteci gerektiriyorsa protectedSettings.configurationUrlSasToken özelliğini SAS belirtecinizin değerine ayarlayın. Settings.configuration.script veya settings.configuration.function tanımlanmışsa bu özellik gereklidir. Bu özellikler için değer verilmezse uzantı, Location Configuration Manager (LCM) meta verilerini ayarlamak için varsayılan yapılandırma betiğini çağırır ve bağımsız değişkenler sağlanmalıdır.
settings.configuration.script	Dize	DSC yapılandırmanızın tanımını içeren betiğin dosya adını belirtir. Bu betik, settings.configuration.url özelliği tarafından belirtilen URL'den indirilen .zip dosyasının kök klasöründe olmalıdır. Settings.configuration.url veya settings.configuration.script tanımlanmışsa bu özellik gereklidir. Bu özellikler için değer verilmezse, uzantı LCM meta verilerini ayarlamak için varsayılan yapılandırma betiğini çağırır ve bağımsız değişkenler sağlanmalıdır.
settings.configuration.function	Dize	DSC yapılandırmanızın adını belirtir. Adlı yapılandırma, settings.configuration.script dosyasının tanımladığı betikte yer almalıdır. Settings.configuration.url veya settings.configuration.function tanımlanmışsa bu özellik gereklidir. Bu özellikler için değer verilmezse, uzantı LCM meta verilerini ayarlamak için varsayılan yapılandırma betiğini çağırır ve bağımsız değişkenler sağlanmalıdır.
settings.configurationArguments	Koleksiyon	DSC yapılandırmanıza geçirmek istediğiniz parametreleri tanımlar. Bu özellik şifrelenmemiş.
settings.configurationData.url	Dize	DSC yapılandırmanız için giriş olarak kullanılacak yapılandırma verileri (.psd1) dosyanızı indirebileceğiniz URL'yi belirtir. Sağlanan URL erişim için bir SAS belirteci gerektiriyorsa protectedSettings.configurationDataUrlSasToken özelliğini SAS belirtecinizin değerine ayarlayın.
settings.privacy.dataCollection	Dize	Telemetri koleksiyonunu etkinleştirir veya devre dışı bırakır. Bu özelliğin tek olası değerleri Etkinleştir, Devre Dışı Bırak, '' veya $null'dır. Bu özelliği boş veya null bırakmak telemetriyi etkinleştirir. Varsayılan değer : ''. Daha fazla bilgi için bkz . Azure DSC uzantısı veri toplama.
settings.advancedOptions.downloadMappings	Koleksiyon	WMF'nin indirildiği alternatif konumları tanımlar. Daha fazla bilgi için bkz . Azure DSC uzantısı 2.8 ve uzantı bağımlılıklarının indirmelerini kendi konumunuza eşleme.
protectedSettings.configurationArguments	Koleksiyon	DSC yapılandırmanıza geçirmek istediğiniz parametreleri tanımlar. Bu özellik şifrelenir.
protectedSettings.configurationUrlSasToken	Dize	settings.configuration.url'nin tanımladığı URL'ye erişmek için kullanılacak SAS belirtecini belirtir. Bu özellik şifrelenir.
protectedSettings.configurationDataUrlSasToken	Dize	settings.configurationData.url'nin tanımladığı URL'ye erişmek için kullanılacak SAS belirtecini belirtir. Bu özellik şifrelenir.

Varsayılan yapılandırma betiği

Aşağıdaki değerler hakkında daha fazla bilgi için bkz . Local Configuration Manager temel ayarları. DSC uzantısı varsayılan yapılandırma betiğini yalnızca aşağıdaki tabloda listelenen LCM özelliklerini yapılandırmak için kullanabilirsiniz.

Özellik adı	Türü	Açıklama
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Gerekli özellik. Bir düğümün powershell kimlik bilgisi nesnesinin parolası olarak Azure Otomasyonu hizmetine kaydolması için kullanılan anahtarı belirtir. Bu değer, Otomasyon hesabında listkeys yöntemi kullanılarak otomatik olarak bulunabilir. Örne bakın.
settings.configurationArguments.RegistrationUrl	Dize	Gerekli özellik. Düğümün kaydetmeye çalıştığı Otomasyon uç noktasının URL'sini belirtir. Bu değer Otomasyon hesabında başvuru yöntemi kullanılarak otomatik olarak bulunabilir.
settings.configurationArguments.NodeConfigurationName	Dize	Gerekli özellik. Düğüme atanacak Otomasyon hesabında düğüm yapılandırmasını belirtir.
settings.configurationArguments.ConfigurationMode	Dize	LCM modunu belirtir. Geçerli seçenekler şunlardır : ApplyOnly, ApplyandMonitor ve ApplyandAutoCorrect. Varsayılan değer ApplyandMonitor'dır.
settings.configurationArguments.RefreshFrequencyMins	uint32	LCM'nin güncelleştirmeleri Otomasyon hesabıyla ne sıklıkta denetlemeye çalışıcaını belirtir. Varsayılan değer 30'dur. En düşük değer 15'tir.
settings.configurationArguments.ConfigurationModeFrequencyMins	uint32	LCM'nin geçerli yapılandırmayı ne sıklıkta doğrulayacaklarını belirtir. Varsayılan değer 15'tir. En düşük değer 15'tir.
settings.configurationArguments.RebootNodeIfNeeded	boolean	DSC işlemi isterse düğümün otomatik olarak yeniden başlatılıp başlatılamayacağını belirtir. Varsayılan değer yanlış'tır.
settings.configurationArguments.ActionAfterReboot	Dize	Yapılandırma uygulanırken yeniden başlatmadan sonra ne olacağını belirtir. Geçerli seçenekler ContinueConfiguration ve StopConfiguration'dır. Varsayılan değer ContinueConfiguration'dır.
settings.configurationArguments.AllowModuleOverwrite	boolean	LCM'nin düğümdeki mevcut modüllerin üzerine yazıp yazmayacağını belirtir. Varsayılan değer yanlış'tır.

ayarlar ve protectedSettings karşılaştırması

Tüm ayarlar VM'deki bir ayarlar metin dosyasına kaydedilir. Ayarlar altında listelenen özellikler genel özelliklerdir. Genel özellikler ayarlar metin dosyasında şifrelenmez. protectedSettings altında listelenen özellikler bir sertifikayla şifrelenir ve VM'deki ayarlar dosyasında düz metin olarak gösterilmez.

Yapılandırma kimlik bilgilerine ihtiyaç duyuyorsa, kimlik bilgilerini protectedSettings'e ekleyebilirsiniz:

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

Örnek yapılandırma betiği

Aşağıdaki örnek, LCM'ye meta veri ayarları sağlamak ve Automation DSC hizmetine kaydolmak için DSC uzantısının varsayılan davranışını gösterir. Yapılandırma bağımsız değişkenleri gereklidir. LCM meta verilerini ayarlamak için yapılandırma bağımsız değişkenleri varsayılan yapılandırma betiğine geçirilir.

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

Azure Depolama'da yapılandırma betiğini kullanma örneği

Aşağıdaki örnek, DSC uzantısı işleyicisine genel bakıştır. Bu örnek, uzantıyı dağıtmak için cmdlet'ler yerine Resource Manager şablonlarını kullanır. IisInstall.ps1 yapılandırmasını kaydedin, .zip bir dosyaya (örnek: iisinstall.zip) yerleştirin ve dosyayı erişilebilir bir URL'ye yükleyin. Bu örnekte Azure Blob depolama kullanılır, ancak .zip dosyaları herhangi bir rastgele konumdan indirebilirsiniz.

Resource Manager şablonunda, aşağıdaki kod VM'ye doğru dosyayı indirmesini ve ardından uygun PowerShell işlevini çalıştırmasını belirtir:

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

Başvuruda Azure Otomasyonu kayıt değerlerinin kullanıldığı örnek

Aşağıdaki örnek, Azure Otomasyonu hesabı özelliklerine başvurarak ve Birincil Anahtarı (0) almak için listkeys yöntemini kullanarak RegistrationUrl ve RegistrationKey değerlerini alır. Bu örnekte şablona automationAccountName ve NodeConfigName parametreleri sağlanmıştır.

"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]"
        }
    }
}

Önceki biçimden güncelleştirme

Uzantının önceki biçimindeki (ve ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken veya Özellikler ortak özelliklerine sahip olan) tüm ayarlar otomatik olarak uzantının geçerli biçimine uyarlanabilir. Daha önce yaptıkları gibi koşuyorlar.

Aşağıdaki şema, önceki ayarlar şemasının nasıl göründüğünü gösterir:

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

Önceki biçimin geçerli biçime nasıl uyum sağladığı aşağıdadır:

Geçerli Özellik adı	Önceki şema eşdeğeri
settings.wmfVersion	Ayarlar. WMFVersion
settings.configuration.url	Ayarlar. ModulesUrl
settings.configuration.script	Ayarların ilk bölümü. ConfigurationFunction (\\'in öncesinde)
settings.configuration.function	Ayarların ikinci bölümü. ConfigurationFunction (\\' sonrasında)
settings.configuration.module.name	Ayarlar. ModuleSource
settings.configuration.module.version	Ayarlar. ModuleVersion
settings.configurationArguments	Ayarlar. Özellikler
settings.configurationData.url	protectedSettings.DataBlobUri (SAS belirteci olmadan)
settings.privacy.dataCollection	Ayarlar. Privacy.dataCollection
settings.advancedOptions.downloadMappings	Ayarlar. AdvancedOptions.DownloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	Ayarlar. SasToken
protectedSettings.configurationDataUrlSasToken	protectedSettings.DataBlobUri'den SAS belirteci

Sorun giderme

Karşılaşabileceğiniz hatalardan bazıları ve bunları nasıl düzeltebileceğiniz aşağıda belirtilmiştir.

Geçersiz değerler

"Privacy.dataCollection is ''{0}. Yalnızca '', 'Enable' ve 'Disable' değerleri kullanılabilir. "WmfVersion: '{0}'. Yalnızca olası değerler... ve 'en son'".

Sorun: Sağlanan bir değere izin verilmiyor.

Çözüm: Geçersiz değeri geçerli bir değerle değiştirin. Daha fazla bilgi için Ayrıntılar'daki tabloya bakın.

Geçersiz URL

"ConfigurationData.url şudur: '{0}'. Bu geçerli bir URL değil" "DataBlobUri şudur: ''{0}. Bu geçerli bir URL değil" "Configuration.url is ''{0}. Bu geçerli bir URL değil"

Sorun: Sağlanan URL geçerli değil.

Çözüm: Sağlanan tüm URL'lerinizi denetleyin. Tüm URL'lerin uzantının uzak makinede erişebileceği geçerli konumlara çözümlediğinden emin olun.

Geçersiz RegistrationKey türü

"PSCredential türünde RegistrationKey parametresi için geçersiz tür."

Sorun: protectedSettings.configurationArguments içindeki RegistrationKey değeri PSCredential dışında bir tür olarak sağlanamaz.

Çözüm: Aşağıdaki biçimi kullanarak RegistrationKey için protectedSettings.configurationArguments girdinizi PSCredential türüne değiştirin:

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

Geçersiz ConfigurationArgument türü

"Geçersiz configurationArguments türü {0}"

Sorun: ConfigurationArguments özelliği Karma tablo nesnesine çözümlenemiyor.

Çözüm: ConfigurationArguments özelliğinizi Karma tablosu yapın. Önceki örneklerde sağlanan biçimi izleyin. Tırnak işaretleri, virgüller ve ayraçlar için dikkat edin.

Yinelenen ConfigurationArguments

"Hem genel hem de korumalı yapılandırmaDa yinelenen{0} bağımsız değişkenler bulunduArguments"

Sorun: Genel ayarlardaki ConfigurationArguments ve korumalı ayarlardaki ConfigurationArguments aynı ada sahip özelliklere sahiptir.

Çözüm: Yinelenen özelliklerden birini kaldırın.

Eksik özellikler

"ayarlar. Configuration.function için settings.configuration.url veya settings.configuration.module belirtilmelidir"

"ayarlar. Configuration.url için settings.configuration.script belirtilmelidir"

"ayarlar. Configuration.script için settings.configuration.url belirtilmelidir"

"ayarlar. Configuration.url için settings.configuration.function belirtilmelidir"

"protectedSettings.ConfigurationUrlSasToken için settings.configuration.url belirtiliyor"

"protectedSettings.ConfigurationDataUrlSasToken için settings.configurationData.url belirtiliyor"

Sorun: Tanımlı bir özelliğin eksik olan başka bir özelliğe ihtiyacı var.

Çözümler:

Eksik özelliği sağlayın.
Eksik özelliğe ihtiyaç duyan özelliği kaldırın.

Sonraki adımlar

Azure DSC uzantısıyla sanal makine ölçek kümelerini kullanma hakkında bilgi edinin.
DSC'nin güvenli kimlik bilgisi yönetimi hakkında daha fazla bilgi edinin.
Azure DSC uzantı işleyicisine giriş alın.
PowerShell DSC hakkında daha fazla bilgi için PowerShell belge merkezine gidin.

Aracılığıyla paylaş