Skip to content

Commit

Permalink
(AB-327541) Update machine configuration terminology
Browse files Browse the repository at this point in the history
- Fixes AB#327541
- Resolves #267
  • Loading branch information
michaeltlombardi committed Oct 15, 2024
1 parent bf4c119 commit 302d203
Show file tree
Hide file tree
Showing 15 changed files with 46 additions and 53 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -115,8 +115,8 @@ class MyDscResourceReason {
> with the module name. If the name of your embedded class is already unlikely to conflict, you can
> use it without a prefix.
>
> If your DSC Resource is designed for use with Azure Automanage's machine configuration feature,
> always prefix the name of the embedded class you create for the **Reasons** property.
> If your DSC Resource is designed for use with Azure machine configuration, always prefix the name
> of the embedded class you create for the **Reasons** property.
### Public and Private functions

Expand Down
2 changes: 1 addition & 1 deletion dsc/docs-conceptual/dsc-1.1/toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ items:
href: getting-started/nanoDSC.md
- name: Get started with DSC in Azure Automation
href: /azure/automation/automation-dsc-getting-started
- name: Get started with Azure Automanage's machine configuration
- name: Get started with Azure machine configuration
href: /azure/governance/machine-configuration/overview
- name: Quickstarts
expanded: true
Expand Down
4 changes: 2 additions & 2 deletions dsc/docs-conceptual/dsc-2.0/concepts/class-based-resources.md
Original file line number Diff line number Diff line change
Expand Up @@ -500,8 +500,8 @@ for the SimpleConfigUpdateSettings object. The available property is:

### The Reasons property

If your class-based DSC Resource is intended for use with Azure Automanage's machine configuration
feature, your DSC Resource must have **Reasons** property that meets the following requirements:
If your class-based DSC Resource is intended for use with Azure machine configuration, your DSC
Resource must have **Reasons** property that meets the following requirements:

- It must declared with the **NotConfigurable** property on the **DscProperty** attribute.
- It must be an array of objects that have a **String** property named **Code**, a **String**
Expand Down
2 changes: 1 addition & 1 deletion dsc/docs-conceptual/dsc-2.0/concepts/configurations.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ title: DSC Configurations

# DSC Configurations

> Applies To: PowerShell 7, Azure Automanage's machine configuration feature
> Applies To: PowerShell 7, Azure machine configuration
DSC Configurations are PowerShell scripts that define a special kind of command. To define a
Configuration, use the PowerShell keyword `configuration`.
Expand Down
2 changes: 1 addition & 1 deletion dsc/docs-conceptual/dsc-2.0/concepts/import-dscresource.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ title: Using Import-DSCResource

# Using Import-DSCResource

> Applies To: PowerShell 7, Azure Automanage's machine configuration feature
> Applies To: PowerShell 7, Azure machine configuration
`Import-DSCResource` is a dynamic keyword, which can only be used inside a `Configuration` block to
import any resources needed in your DSC Configuration. DSC Resources under `$PSHOME` are imported
Expand Down
18 changes: 9 additions & 9 deletions dsc/docs-conceptual/dsc-2.0/how-tos/configurations/depends-on.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ title: Managing dependencies in DSC Configurations

# Managing dependencies in DSC Configurations

> Applies To: PowerShell 7, Azure Automanage's machine configuration feature
When you write [DSC Configurations][1] for [Azure Automanage's machine configuration feature][2],
you add [Resource blocks][3] to configure aspects of a system. As you continue to add DSC Resource
blocks, your DSC Configurations can grow large and cumbersome to manage. One such challenge is the
applied order of your DSC Resource blocks. By default, DSC Resources are applied in the order
they're defined within the `Configuration` block. As your DSC Configuration grows larger and more
complex, you can use the **DependsOn** meta-property to change the applied order of your DSC
Resources by specifying that one DSC Resource depends on another DSC Resource.
> Applies To: PowerShell 7, Azure machine configuration
When you write [DSC Configurations][1] for [Azure machine configuration][2], you add
[Resource blocks][3] to configure aspects of a system. As you continue to add DSC Resource blocks,
your DSC Configurations can grow large and cumbersome to manage. One such challenge is the applied
order of your DSC Resource blocks. By default, DSC Resources are applied in the order they're
defined within the `Configuration` block. As your DSC Configuration grows larger and more complex,
you can use the **DependsOn** meta-property to change the applied order of your DSC Resources by
specifying that one DSC Resource depends on another DSC Resource.

The **DependsOn** meta-property can be used in any DSC Resource block. It's defined with the same
key/value mechanism as other DSC Resource properties. The **DependsOn** meta-property expects an
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ title: Write and compile a DSC Configuration

# Write and compile a DSC Configuration

> Applies To: PowerShell 7, Azure Automanage's machine configuration feature
> Applies To: PowerShell 7, Azure machine configuration
This exercise walks through creating and compiling a DSC Configuration from start to finish. In the
following example, you'll learn how to write and compile a minimal DSC Configuration to ensure a
Expand All @@ -18,7 +18,7 @@ For an overview of what DSC is and how it works, see [Desired State Configuratio

> [!IMPORTANT]
> Starting in DSC 2.0, there is no supported way to use DSC Configurations directly. They're only
> supported for use with [Azure Automanage's machine configuration feature][2].
> supported for use with [Azure machine configuration][2].
## Requirements

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -108,8 +108,8 @@ class MyDscResourceReason {
> with the module name. If the name of your embedded class is already unlikely to conflict, you can
> use it without a prefix.
>
> If your DSC Resource is designed for use with Azure Automanage's machine configuration feature,
> always prefix the name of the embedded class you create for the **Reasons** property.
> If your DSC Resource is designed for use with Azure machine configuration, always prefix the name
> of the embedded class you create for the **Reasons** property.
### Public and Private functions

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ file with a `.schema.psm1` extension. For more information about DSC Resources,

> [!IMPORTANT]
> Composite DSC Resources don't work with `Invoke-DscResource`. In DSC 2.0 and later, they're only
> supported for use with [Azure Automanage's machine configuration feature][2].
> supported for use with [Azure machine configuration][2].
## Creating the composite resource

Expand Down
15 changes: 6 additions & 9 deletions dsc/docs-conceptual/dsc-2.0/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,21 +29,18 @@ Install-Module -Name PSDesiredStateConfiguration -Repository PSGallery -MaximumV
## Use Case for DSC 2.0

DSC 2.0 is supported for use with [Azure Automanage's machine configuration feature][02]. Other
scenarios, such as directly calling DSC Resources with `Invoke-DscResource`, may be functional but
aren't the primary intended use of this version.
DSC 2.0 is supported for use with [Azure machine configuration][02]. Other scenarios, such as
directly calling DSC Resources with `Invoke-DscResource`, may be functional but aren't the primary
intended use of this version.

If you aren't using Azure Automanage's machine configuration feature, you should use DSC 1.1.

DSC 3.0 is available in public beta and should only be used with Azure machine configuration (which
supports it) or for non-production environments to test migrating away from DSC 1.1.
If you aren't using Azure machine configuration, you should use DSC 1.1.machine

## Changes from DSC 1.1

There are several major changes in DSC 2.0.

The only way to use DSC Resources in 2.0 is with the `Invoke-DscResource` cmdlet and Azure
Automanage's machine configuration feature.
The only way to use DSC Resources in 2.0 is with the `Invoke-DscResource` cmdlet or Azure machine
configuration.

The following cmdlets have been removed:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ comments.

### Resources that don't work in machine configuration

When using Azure Automanage's machine configuration feature, don't use the following resources:
When using Azure machine configuration, don't use the following resources:

- `WindowsFeature`
- `WindowsFeatureSet`
Expand Down
2 changes: 1 addition & 1 deletion dsc/docs-conceptual/dsc-2.0/toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ items:
href: overview.md
- name: Getting Started
items:
- name: Understand the machine configuration feature of Azure Automanage
- name: Understanding Azure Machine Configuration
href: /azure/governance/machine-configuration/overview
- name: Get started with invoking DSC Resources
href: getting-started/invoking-dsc-resources.md
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -906,9 +906,8 @@ First, `Set()` needs to determine whether the DSC Resource needs to be created,
```

`Set()` first calls the `Test()` method to determine if anything actually needs to be done. Some
tools like, Azure Automanage's machine configuration feature, ensure that the `Set()` method is only
called after the `Test()` method. However, there's no such guarantee when you use the
`Invoke-DscResource` cmdlet.
tools like, Azure machine configuration, ensure that the `Set()` method is only called after the
`Test()` method. However, there's no such guarantee when you use the `Invoke-DscResource` cmdlet.

Since the `Test()` method calls `Get()`, which caches the current state, the DSC Resource can access
the cached current state without having to call the `Get()` method again.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,18 +1,17 @@
---
description: >-
Create a class-based DSC Resource for use with Azure Automanage's machine configuration feature
Create a class-based DSC Resource for use with Azure machine configuration
ms.topic: tutorial
ms.date: 03/08/2023
ms.custom: template-tutorial
title: Create a class-based DSC Resource for Machine Configuration
title: Create a class-based DSC Resource for machine configuration
---

# Tutorial: Create a class-based DSC Resource for machine configuration

Get started authoring a class-based DSC Resource to manage a configuration file with
[Azure Automanage's machine configuration feature][01]. Completing this tutorial gives you a
machine-configuration compatible class-based DSC Resource in a module you can use for further
learning and customization.
[Azure machine configuration][01]. Completing this tutorial gives you a machine-configuration
compatible class-based DSC Resource in a module you can use for further learning and customization.

In this tutorial, you learn how to:

Expand Down Expand Up @@ -285,8 +284,8 @@ $UpdateFrequency

### Add the Reasons property

Because this DSC Resource is intended for use with Azure Automanage's machine configuration
feature, it must have **Reasons** property that meets the following requirements:
Because this DSC Resource is intended for use with Azure machine configuration, it must have
**Reasons** property that meets the following requirements:

- It must be declared with the **NotConfigurable** property on the **DscProperty** attribute.
- It must be an array of objects that have a **String** property named **Code**, a **String**
Expand Down Expand Up @@ -712,9 +711,9 @@ The `Get()` method now returns accurate information about the current state of t

### Handling Reasons

For Machine Configuration compatible DSC Resources, the `Get()` method also needs to populate the
**Reasons** property. For this purpose, create the `GetReasons()` method. It should return an array
of **ExampleResourcesReason** objects and take a single **Tailspin** object as input.
For Azure machine configuration compatible DSC Resources, the `Get()` method also needs to populate
the **Reasons** property. For this purpose, create the `GetReasons()` method. It should return an
array of **ExampleResourcesReason** objects and take a single **Tailspin** object as input.

```powershell
[ExampleResourcesReason[]] GetReasons([Tailspin]$CurrentState) {
Expand Down Expand Up @@ -1384,9 +1383,8 @@ First, `Set()` needs to determine whether the DSC Resource needs to be created,
```

`Set()` first calls the `Test()` method to determine if anything actually needs to be done. Some
tools like, Azure Automanage's machine configuration feature, ensure that the `Set()` method is only
called after the `Test()` method. However, there's no such guarantee when you use the
`Invoke-DscResource` cmdlet.
tools like, Azure machine configuration, ensure that the `Set()` method is only called after the
`Test()` method. However, there's no such guarantee when you use the `Invoke-DscResource` cmdlet.

Since the `Test()` method calls `Get()`, which caches the current state, the DSC Resource can access
the cached current state without having to call the `Get()` method again.
Expand Down Expand Up @@ -2428,8 +2426,8 @@ files in it.

1. Read about [class-based DSC Resources][02], learn about how they work, and consider why the DSC
Resource in this tutorial is implemented this way.
1. Read about the [machine configuration feature of Azure Automanage][01] to understand how you can
use it to audit and configure your systems.
1. Read about [Azure machine configuration][01] to understand how you can use it to audit and
configure your systems.
1. Consider how this DSC Resource can be improved. Are there any edge cases or features it doesn't
handle? Update the implementation to handle them.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -70,15 +70,14 @@ Invoke-DscResource @SetParameters

For more information, view the [Invoke-DscResource][01] help.

## The machine configuration feature of Azure Automanage
## Azure machine configuration

For machines hosted in Microsoft Azure, or connected for hybrid management, the machine
configuration feature of Azure Automanage offers the ability to audit or apply configurations. The
feature can be used stand-alone to assign configurations as a machine is deployed, or dynamically
to assign configurations to a machine based on properties defined by the API.

For more information, see the page
[Understand the machine configuration feature of Azure Automanage][02].
For more information, see [Understanding Azure Machine Configuration][02].

## DSC resources with third-party tools

Expand Down

0 comments on commit 302d203

Please sign in to comment.