Skip to content

Commit 0a74818

Browse files
BethWilkeBethWilke
committed
Adding Az module notes
1 parent 2f9a88a commit 0a74818

File tree

3 files changed

+47
-56
lines changed

3 files changed

+47
-56
lines changed

‎articles/automation/automation-dsc-compile.md

Lines changed: 40 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,7 @@ ms.topic: conceptual
88
---
99
# Compiling DSC configurations in Azure Automation State Configuration
1010

11-
You can compile Desired State Configuration (DSC) configurations in two ways with Azure Automation
12-
State Configuration: in Azure and in Windows PowerShell. The following table helps you
13-
determine when to use which method based on the characteristics of each:
11+
You can compile Desired State Configuration (DSC) configurations in Azure Automation State Configuration in the following ways:
1412

1513
- Azure State Configuration compilation service
1614
- Beginner method with interactive user interface
@@ -32,8 +30,8 @@ For compilation details, see [Desired State Configuration extension with Azure R
3230
1. From your Automation account, click **State configuration (DSC)**.
3331
1. Click on the **Configurations** tab, then click on the configuration name to compile.
3432
1. Click **Compile**.
35-
1. If the configuration has no parameters, you are prompted to confirm that you want to compile it. If the configuration has parameters, the **Compile Configuration** blade opens so that you can provide parameter values.
36-
1. The Compilation Job page is opened so that you can track the compilation job's status. You can also use this page to track the node configurations (MOF configuration documents) that the job places on the Azure Automation State Configuration pull server.
33+
1. If the configuration has no parameters, you're prompted to confirm if you want to compile it. If the configuration has parameters, the **Compile Configuration** blade opens so that you can provide parameter values.
34+
1. The Compilation Job page is opened so that you can track compilation job status. You can also use this page to track the node configurations (MOF configuration documents) placed on the Azure Automation State Configuration pull server.
3735

3836
### Azure PowerShell
3937

@@ -44,10 +42,9 @@ to start compiling with Windows PowerShell. The following sample code begins com
4442
Start-AzAutomationDscCompilationJob -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'MyAutomationAccount' -ConfigurationName 'SampleConfig'
4543
```
4644

47-
**Start-AzAutomationDscCompilationJob** returns a compilation job object that you can use to track its status. You can then use this compilation job object with [Get-AzAutomationDscCompilationJob](/powershell/module/az.automation/get-azautomationdsccompilationjob)
48-
to determine the status of the compilation job, and with
45+
**Start-AzAutomationDscCompilationJob** returns a compilation job object that you can use to track job status. You can then use this compilation job object with [Get-AzAutomationDscCompilationJob](/powershell/module/az.automation/get-azautomationdsccompilationjob) to determine the status of the compilation job, and
4946
[Get-AzAutomationDscCompilationJobOutput](/powershell/module/az.automation/get-azautomationdscconfiguration)
50-
to view its streams (output). The following sample code starts compilation of the SampleConfig configuration, waits until it has completed, and then displays its streams.
47+
to view its streams (output). The following sample starts compilation of the SampleConfig configuration, waits until it has completed, and then displays its streams.
5148

5249
```powershell
5350
$CompilationJob = Start-AzAutomationDscCompilationJob -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'MyAutomationAccount' -ConfigurationName 'SampleConfig'
@@ -63,13 +60,9 @@ $CompilationJob | Get-AzAutomationDscCompilationJobOutput –Stream Any
6360

6461
### Declare basic parameters
6562

66-
Parameter declaration in DSC configurations, including parameter types and properties, works the
67-
same as in Azure Automation runbooks. See [Starting a runbook in Azure Automation](automation-starting-a-runbook.md)
68-
to learn more about runbook parameters.
63+
Parameter declaration in DSC configurations, including parameter types and properties, works the same as in Azure Automation runbooks. See [Starting a runbook in Azure Automation](automation-starting-a-runbook.md) to learn more about runbook parameters.
6964

70-
The following example uses two parameters called **FeatureName** and **IsPresent**, to determine
71-
the values of properties in the **ParametersExample.sample** node configuration, generated during
72-
compilation.
65+
The following example uses two parameters called *FeatureName* and *IsPresent*, to determine the values of properties in the ParametersExample.sample node configuration, generated during compilation.
7366

7467
```powershell
7568
Configuration ParametersExample
@@ -99,8 +92,7 @@ Configuration ParametersExample
9992
}
10093
```
10194

102-
You can compile DSC Configurations that use basic parameters in the Azure Automation State
103-
Configuration portal or with Azure PowerShell:
95+
You can compile DSC configurations that use basic parameters in the Azure Automation State Configuration portal or with Azure PowerShell.
10496

10597
#### Portal
10698

@@ -110,8 +102,7 @@ In the portal, you can enter parameter values after clicking **Compile**.
110102

111103
#### Azure PowerShell
112104

113-
PowerShell requires parameters in a [hashtable](/powershell/module/microsoft.powershell.core/about/about_hash_tables)
114-
where the key matches the parameter name, and the value equals the parameter value.
105+
PowerShell requires parameters in a [hashtable](/powershell/module/microsoft.powershell.core/about/about_hash_tables), where the key matches the parameter name and the value equals the parameter value.
115106

116107
```powershell
117108
$Parameters = @{
@@ -126,27 +117,21 @@ For information about passing PSCredentials as parameters, see [Credential Asset
126117

127118
### Compile configurations containing composite resources in Azure Automation
128119

129-
The **Composite Resources** feature allows you to use DSC configurations as nested resources inside of a
130-
configuration. This enables you to apply multiple configurations to a single resource. See
131-
[Composite resources: Using a DSC configuration as a resource](/powershell/scripting/dsc/resources/authoringresourcecomposite)
132-
to learn more about composite resources.
120+
The **Composite Resources** feature allows you to use DSC configurations as nested resources inside a configuration. This feature enables the application of multiple configurations to a single resource. See [Composite resources: Using a DSC configuration as a resource](/powershell/scripting/dsc/resources/authoringresourcecomposite) to learn more about composite resources.
133121

134122
> [!NOTE]
135-
> For configurations containing composite resources to compile correctly, you must first ensure that any DSC resources that the composite relies on are imported into Azure Automation.
136-
137-
Adding a DSC composite resource is no different from adding a PowerShell module to Azure Automation. The process is documented in [Manage Modules in Azure Automation](/azure/automation/shared-resources/modules).
123+
> So that configurations containing composite resources compile correctly, you must first import into Azure Automation any DSC resources that the composites rely upon. Adding a DSC composite resource is no different from adding any PowerShell module to Azure Automation. This process is documented in [Manage Modules in Azure Automation](/azure/automation/shared-resources/modules).
138124
139125
### Manage ConfigurationData when compiling configurations in Azure Automation
140126

141-
The **ConfigurationData** feature allows you to separate structural configuration from any environment-specific
142-
configuration while using PowerShell DSC. See [Separating "What" from "Where" in PowerShell DSC](https://blogs.msdn.com/b/powershell/archive/2014/01/09/continuous-deployment-using-dsc-with-minimal-change.aspx)
143-
to learn more about ConfigurationData.
127+
**ConfigurationData** allows you to separate structural configuration from any environment-specific
128+
configuration while using PowerShell DSC. For more information, see [Separating "What" from "Where" in PowerShell DSC](https://blogs.msdn.com/b/powershell/archive/2014/01/09/continuous-deployment-using-dsc-with-minimal-change.aspx).
144129

145130
> [!NOTE]
146-
> You can use ConfigurationData when compiling in Azure Automation State Configuration using Azure PowerShell, but not in the Azure portal.
131+
> When compiling in Azure Automation State Configuration, you can use **ConfigurationData** in Azure PowerShell but not in the Azure portal.
147132
148-
The following example DSC configuration uses ConfigurationData via the $ConfigurationData and $AllNodes keywords. You also need the [xWebAdministration module](https://www.powershellgallery.com/packages/xWebAdministration/)
149-
for this example:
133+
The following example DSC configuration uses **ConfigurationData** via the $ConfigurationData
134+
and $AllNodes keywords. You also need the [xWebAdministration module](https://www.powershellgallery.com/packages/xWebAdministration/) for this example.
150135

151136
```powershell
152137
Configuration ConfigurationDataSample
@@ -167,8 +152,7 @@ Configuration ConfigurationDataSample
167152
}
168153
```
169154

170-
You can compile the preceding DSC configuration with Windows PowerShell. The following script adds two node configurations to the Azure Automation State Configuration pull service:
171-
ConfigurationDataSample.MyVM1 and ConfigurationDataSample.MyVM3.
155+
You can compile the preceding DSC configuration with Windows PowerShell. The following script adds two node configurations to the Azure Automation State Configuration pull service: ConfigurationDataSample.MyVM1 and ConfigurationDataSample.MyVM3.
172156

173157
```powershell
174158
$ConfigData = @{
@@ -207,13 +191,13 @@ following:
207191

208192
#### Credential assets
209193

210-
DSC configurations in Azure Automation can reference Automation credential assets using the
211-
**Get-AutomationPSCredential** cmdlet. If a configuration has a parameter that has a PSCredential type, then you can use **Get-AutomationPSCredential** by passing in the string name of an Azure Automation credential asset to retrieve the credential. You can then use that object for the parameter requiring the PSCredential object. Behind the scenes, the Azure
212-
Automation credential asset with that name is retrieved and passed to the configuration. The example below shows this operation in action.
194+
DSC configurations in Azure Automation can reference Automation credential assets using the **Get-AutomationPSCredential** cmdlet. If a configuration has a parameter that specifies a **PSCredential** object, use **Get-AutomationPSCredential** by passing the string name of an Azure Automation credential asset to the cmdlet to retrieve the credential. Then make use of that object for the parameter requiring the **PSCredential** object. Behind the scenes, the Azure Automation credential asset with that name is retrieved and passed to the configuration. The example below shows this scenario in action.
213195

214-
Keeping credentials secure in a node configuration requires encrypting the credentials in the node configuration MOF file. You must inform PowerShell DSC specifically that it has permission to output credentials in plain text during node configuration MOF generation. PowerShell DSC doesn’t know that Azure Automation encrypts the entire MOF file after its generation via a compilation job.
196+
Keeping credentials secure in node configurations (MOF configuration documents) requires encrypting the credentials in the node configuration MOF file. Currently you must give PowerShell DSC permission to output credentials in plain text during node configuration MOF generation. PowerShell DSC is not aware that Azure Automation encrypts the entire MOF file after its generation through a compilation job.
215197

216-
To give PowerShell DSC permission to output credentials in plain text in the generated node configuration MOFs using configuration data, pass `PSDscAllowPlainTextPassword = $true`. You can pass this information via ConfigurationData for each node block name
198+
You can tell PowerShell DSC that it is okay for credentials to be outputted in plain text in the
199+
generated node configuration MOFs using Configuration Data. You should
200+
pass `PSDscAllowPlainTextPassword = $true` via **ConfigurationData** for each node block name
217201
that appears in the DSC configuration and uses credentials.
218202

219203
The following example shows a DSC configuration that uses an Automation credential asset.
@@ -236,10 +220,7 @@ Configuration CredentialSample
236220
}
237221
```
238222

239-
You can compile the preceding DSC configuration with PowerShell.
240-
241-
The following PowerShell adds two node configurations to the Azure Automation State Configuration pull server:
242-
CredentialSample.MyVM1 and CredentialSample.MyVM2.
223+
You can compile the preceding DSC configuration with PowerShell. The following PowerShell code adds two node configurations to the Azure Automation State Configuration pull server: CredentialSample.MyVM1 and CredentialSample.MyVM2.
243224

244225
```powershell
245226
$ConfigData = @{
@@ -260,22 +241,26 @@ $ConfigData = @{
260241
Start-AzAutomationDscCompilationJob -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'MyAutomationAccount' -ConfigurationName 'CredentialSample' -ConfigurationData $ConfigData
261242
```
262243

263-
>[!NOTE]
264-
>When compilation is complete, you might receive an error stating: **The 'Microsoft.PowerShell.Management' module was not imported because the 'Microsoft.PowerShell.Management' snap-in was already imported.** You can safely ignore this warning.
244+
> [!NOTE]
245+
> When compilation is complete, you might receive the error message "The 'Microsoft.PowerShell.Management' module was not imported because the 'Microsoft.PowerShell.Management' snap-in was already imported." You can safely ignore this message.
265246
266-
## Compiling a DSC configuration in Windows PowerShell
247+
## Compiling your DSC configuration in Windows PowerShell
267248

268-
The process to compile DSC configurations in Windows PowerShell is included in the PowerShell DSC documentation
269-
[Write, Compile, and Apply a Configuration](/powershell/scripting/dsc/configurations/write-compile-apply-configuration#compile-the-configuration).
270-
You can execute the process from a developer workstation or within a build service, such as [Azure DevOps](https://dev.azure.com).
271-
You can then import the MOFs for the resulting node configurations directly into the Azure State Configuration service.
249+
You can also import node configurations (MOFs) that have been compiled outside of Azure. The import includes compilation from a developer workstation or in a service such as
250+
[Azure DevOps](https://dev.azure.com). This approach has multiple advantages, including performance and reliability.
272251

273-
>[!NOTE]
274-
>A node configuration file must be no larger than 1 MB to allow it to be imported into Azure Automation.
252+
Compiling in Windows PowerShell also provides the option to sign configuration content. The DSC agent verifies a signed node configuration locally on a managed node. Verification ensures that the configuration applied to the node comes from an authorized source.
275253

276-
You can also import node configurations (MOFs) that have been compiled outside of Azure. There are multiple advantages to this approach, including performance and reliability.
254+
> [!NOTE]
255+
> A node configuration file must be no larger than 1 MB to allow it to be imported into Azure Automation.
256+
257+
For more information about signing of node configurations, see [Improvements in WMF 5.1 - How to sign configuration and module](/powershell/scripting/wmf/whats-new/dsc-improvements#dsc-module-and-configuration-signing-validations).
258+
259+
### Compile the DSC configuration
277260

278-
Compiling in Windows PowerShell provides the option to sign configuration content, with the DSC agent verifying a signed node configuration locally on a managed node. Verification ensures that the configuration being applied to the node comes from an authorized source. For more information about signing node configurations, see [Improvements in WMF 5.1 - How to sign configuration and module](/powershell/scripting/wmf/whats-new/dsc-improvements#dsc-module-and-configuration-signing-validations).
261+
The process to compile DSC configurations in Windows PowerShell is included in the PowerShell DSC documentation
262+
[Write, Compile, and Apply a Configuration](/powershell/scripting/dsc/configurations/write-compile-apply-configuration#compile-the-configuration).
263+
You can execute this process from a developer workstation or within a build service, such as [Azure DevOps](https://dev.azure.com). You can then import the MOF file(s) produced by compiling the configuration into the Azure State Configuration service.
279264

280265
### Import a node configuration in the Azure portal
281266

@@ -285,7 +270,7 @@ Compiling in Windows PowerShell provides the option to sign configuration conten
285270

286271
![Browse for local file](./media/automation-dsc-compile/import-browse.png)
287272

288-
1. Enter a name in the **Configuration Name** textbox. This name must match the name of the configuration from which the node configuration was compiled.
273+
1. Enter a name in the **Configuration Name** field. This name must match the name of the configuration from which the node configuration was compiled.
289274
1. Click **OK**.
290275

291276
### Import a node configuration with Azure PowerShell
@@ -303,4 +288,4 @@ Import-AzAutomationDscNodeConfiguration -AutomationAccountName 'MyAutomationAcco
303288
- To learn about compiling DSC configurations so that you can assign them to target nodes, see [Compiling configurations in Azure Automation State Configuration](automation-dsc-compile.md).
304289
- For PowerShell cmdlet reference, see [Azure Automation State Configuration cmdlets](/powershell/module/az.automation).
305290
- For pricing information, see [Azure Automation State Configuration pricing](https://azure.microsoft.com/pricing/details/automation/).
306-
- To see an example of using Azure Automation State Configuration in a continuous deployment pipeline, see [Continuous Deployment Using Azure Automation State Configuration and Chocolatey](automation-dsc-cd-chocolatey.md).
291+
- To see an example of using Azure Automation State Configuration in a continuous deployment pipeline, see [Continuous deployment to virtual machines using Azure Automation State Configuration and Chocolatey](automation-dsc-cd-chocolatey.md).

‎articles/automation/automation-runbook-graphical-error-handling.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,10 @@ Often, if there is a non-terminating error that occurs with a runbook activity,
1515

1616
Your graphical runbook should include error handling code to deal with execution issues. To validate the output of an activity or handle an error, you can use a PowerShell code activity, define conditional logic on the output link of the activity, or apply another method.
1717

18-
Azure Automation graphical runbooks have been improved with the capability to include error handling. You can now turn exceptions into non-terminating errors and create error links between activities. The improved process allows your runbook to catch errors and manage realized or unexpected conditions.
18+
Azure Automation graphical runbooks have been improved with the capability to include error handling. You can now turn exceptions into non-terminating errors and create error links between activities. The improved process allows your runbook to catch errors and manage realized or unexpected conditions.
19+
20+
>[!NOTE]
21+
>This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see [Introducing the new Azure PowerShell Az module](https://docs.microsoft.com/powershell/azure/new-azureps-module-az?view=azps-3.5.0). For Az module installation instructions on your Hybrid Runbook Worker, see [Install the Azure PowerShell Module](https://docs.microsoft.com/powershell/azure/install-az-ps?view=azps-3.5.0). For your Automation account, you can update your modules to the latest version using [How to update Azure PowerShell modules in Azure Automation](automation-update-azure-modules.md).
1922
2023
## PowerShell error types
2124

0 commit comments

Comments
 (0)