Azure Resource Manager şablonlarıyla uzantıyı Desired State Configuration

Makale
06/01/2023

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, Desired State Configuration (DSC) uzantı işleyicisinin özelliklerini, Azure Otomasyonu State Configuration ve müşteri geri bildirimlerinden en sık istenen özellikleri birleştirir. Makine yapılandırması, Arc özellikli sunucular aracılığıyla hibrit makine desteği de içerir.

Bu makalede Desired State Configuration (DSC) uzantı işleyicisi için Azure Resource Manager şablonu açıklanmaktadır. Örneklerin çoğu RegistrationURL (Dize olarak sağlanır) ve RegistrationKey (Azure Otomasyonu eklemek için 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ına 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 şablonunda 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	string	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	string	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 belirtilmemişse uzantı, Konum 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	string	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ımlandığında bu özellik gereklidir. Bu özellikler için değer belirtilmemişse, 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	string	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 belirtilmemişse, 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	string	DSC yapılandırmanız için giriş olarak kullanmak üzere 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	string	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	string	settings.configuration.url dosyasının tanımladığı URL'ye erişmek için kullanılacak SAS belirtecini belirtir. Bu özellik şifrelenir.
protectedSettings.configurationDataUrlSasToken	string	settings.configurationData.url dosyasının 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. Yerel Configuration Manager temel ayarları. Yalnızca aşağıdaki tabloda listelenen LCM özelliklerini yapılandırmak için DSC uzantısı varsayılan yapılandırma betiğini 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	string	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	string	Gerekli özellik. Düğüme atanacak Otomasyon hesabında düğüm yapılandırmasını belirtir.
settings.configurationArguments.ConfigurationMode	string	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ştirmeler için 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ı doğrulama sıklıkları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 false'tur.
settings.configurationArguments.ActionAfterReboot	string	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 false'tur.

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. Yapılandırma bağımsız değişkenleri, LCM meta verilerini ayarlamak için 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 örnekte uzantıyı dağıtmak için cmdlet'ler yerine Resource Manager şablonları kullanılı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ı sağlar:

"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 Properties 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ğıda anlatlanmıştı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 (\\' öncesinde)
settings.configuration.function	Ayarların ikinci bölümü. ConfigurationFunction (\\)
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 is '{0}'. Yalnızca olası değerler... ve 'en son'" yazın.

Sorun: Sağlanan 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 is '{0}'. Bu geçerli bir URL değil" "DataBlobUri is ''{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ümlenmesine 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ümlenemez.

Çö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ı configurationArguments içinde '{0}' yinelenen bağımsız değişkenleri bulundu"

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, settings.configuration.function öğesinin belirtildiğini gerektiriyor"

"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ği gerektiren ö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 bilgileri yönetimi hakkında daha fazla bilgi edinin.
Azure DSC uzantı işleyicisine giriş edinin.
PowerShell DSC hakkında daha fazla bilgi için PowerShell belge merkezine gidin.

Aracılığıyla paylaş