Learning PowerShell DSC

Table of Contents

Learning PowerShell DSC

Credits

About the Author

About the Reviewers

www.PacktPub.com

Support files, eBooks, discount offers, and more

Why subscribe?

Free access for Packt account holders

Instant updates on new Packt books

Preface

What this book covers

What you need for this book

Who this book is for

Conventions

Reader feedback

Customer support

Downloading the example code

Errata

Piracy

Questions

1. Introduction to PowerShell DSC

What is PowerShell DSC?

What is PowerShell?

On to PowerShell DSC

Why do we need Configuration Management?

What is DevOps?

DSC quick wins

A high level overview of DSC

The authoring phase

The staging phase

The execution phase

Why all the abstraction?

How does DSC help me?

The who

The what

The how

Idempotence

Isn't this Group Policy or SCCM?

DSC features

DSC requirements

DSC versions

PowerShell v4 DSC

v4 DSC language extensions

v4 DSC base resources

v4 DSC Cmdlets

The v4 DSC Pull Server

PowerShell v5 DSC

v5 DSC language extensions

v5 DSC base resources

v5 DSC Cmdlets

v5 improvements

The PowerShell ISE

Partial configurations and dependencies

Class-based DSC Resources

DSC built-in support for help

DSC run as credential support

DSC resource side-by-side installation

DSC resource script debugging

The separation of node and configuration IDs

DSC LCM MetaConfig updates

DSC LCM rich state information

DSC LCM RefreshMode values

DSC status from a central location

Summary

2. DSC Architecture

Overview

Push and pull modes

The push management model

The pull management model

The general workflow

Authoring

Syntax

Compilation

Staging

Execution

Push executions

Pull executions

The example workflow

Configuration data

Hardcoded data

Parameter-based data

Hashtable data

Local Configuration Manager

LCM settings

Configuration modes

ApplyOnly

ApplyAndMonitor

ApplyAndAutoCorrect

Refresh modes

The LCM configuration

An example LCM configuration

The DSC Pull Server

What is a DSC Pull Server?

What does the Pull Server do for us?

Automatic and continuous configuration

Repository

Reporting

Security

Setting up a DSC Pull Server

Pull Server settings

Installing the DSC server

Adding MOF files to a Pull Server

Adding DSC Resources to a Pull Server

Deployment considerations

General observations

LCM gotchas

Deployment mode differences

Summary

3. DSC Configuration Files

Defining a DSC configuration script file

Authoring DSC configuration files

DSC automatic variables

AllNodes

Node

ConfigurationData

DSC Resource import declarations

Import-DscResource

The DSC script file syntax

The Configuration keyword

The Node keyword

DSC Resource statements

The script file example

Defining a DSC configuration data file

Authoring DSC configuration data files

Configuration data syntax

The variable syntax

The data file syntax

Allowable DSC configuration content

Creating reusable DSC configurations

Nested DSC configurations

Nested DSC configuration syntax

Nested DSC configuration limitations

DSC composite resources

Why use DSC composite resources?

The DSC composite resource syntax

DSC composite resource folder structure

DSC composite resource drawbacks

Debugging and troubleshooting configuration script files

Using DSC event logs

Enabling verbose logging

What do DSC event logs contain?

Gathering events from a single DSC operation

Event Viewer

PowerShell

Using the xDscDiagnostics module to analyze DSC logs

Get-xDscOperation

Trace-xDscOperation

Resetting the DSC engine cache

Enabling the debug mode

Fixing a stuck DSC run

Summary

4. DSC Resources

What are DSC Resources?

Creating a custom PowerShell v4 DSC Resource

The folder structure of a v4 DSC Resource

The syntax of a v4 DSC Resource

The DSC Resource definition file

Naming

Versioning

Parameters

Qualifiers

The DSC PowerShell module file

Get-TargetResource

Test-TargetResource

Set-TargetResource

Authoring custom DSC Resources

Creating DSC Resources manually

Creating DSC Resources automatically

Creating a custom PowerShell v5 DSC Resource

PowerShell classes

Class-based DSC Resources

The folder structure of v5 DSC Resources

The syntax of v5 DSC Resources

Declaring the class

Schema

Methods

Get

Test

Set

The advantages of a class-based DSC Resource

The disadvantages of a class-based DSC Resource

What makes a good DSC Resource

Idempotent

Do one thing well

Reuse code, but don't go overboard

Contribute back!

Testing custom DSC Resources

Using xDscResourceDesigner

Pester

Microsoft recommendations

How do you find DSC Resources?

Microsoft DSC Resource Kits

Installing DSC Resource Kits

The Microsoft PowerShell DSC GitHub repository

Installing DSC Resources from GitHub

The Microsoft PowerShell Gallery

PackageManagement

Installing PackageManagement

Initializing PackageManagement

Discover DSC Resources in the PowerShell Gallery

Installing DSC Resources in the PowerShell Gallery

Custom hosting options

Local SMB/network share

NuGet IIS

Third-party NuGet servers

Summary

5. Pushing DSC Configurations

Tooling

Setting things up

Test environments

Locally pushing DSC configurations

Setting up the test environment locally

Compiling configurations for local target nodes

Executing configurations for local target nodes

Remotely pushing DSC configurations

Setting up the test environment remotely

Compiling configurations for remote target nodes

Executing configurations for remote target nodes

Things you must consider when pushing DSC configurations

Summary

6. Pulling DSC Configurations

Creating DSC Pull Servers

DSC Pull Server setup considerations

DSC Pull Server types

The Windows Management Framework version

Initial setup tasks

Installing required DSC Resources

SSL certificates

SMB share creation

Preparing DSC Resources for Pull Server distribution

Miscellaneous tasks

Creating a WMF 4 DSC Pull Server

Creating a WMF 5 DSC Pull Server

Validating a DSC Pull Server install

Testing using a web browser

Testing using the command line

Registering target nodes with a DSC Pull Server

Registering a WMF 4 target node

Registering a WMF 5 target node

Pulling DSC configurations with a DSC Pull Server

Pulling DSC configurations using ConfigurationIDs

Pulling DSC configurations using RegistrationKeys

DSC Pull Server and target node status

Checking the current LCM configuration status

Triggering a DSC configuration to run on a target node

Triggering a WMF 4 target node

Triggering a WMF 5 target node

Using DSC logging to check on the status

Reporting on the target node status

Reporting on the target node status with the DSC Pull Server

Summary

7. Example Scenarios

Real life DSC usage

Setting up a common installation base

Installing software

A configuration management refresher

Complicated deployments

Handling change

Summary

Index

Learning PowerShell DSC

Learning PowerShell DSC

Copyright © 2015 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

First published: October 2015

Production reference: 1161015

Published by Packt Publishing Ltd.

Livery Place

35 Livery Street

Birmingham B3 2PB, UK.

ISBN 978-1-78398-070-3

www.packtpub.com

Credits

Author

James Pogran

Reviewers

Marcin Grzywa

Brian Scholer

Sergei Vorobev

Dave Wyatt

Acquisition Editor

Manish Nainani

Content Development Editor

Shali Deeraj

Technical Editor

Mrunmayee Patil

Copy Editor

Lauren Harkins

Project Coordinator

Kinjal Bari

Proofreader

Safis Editing

Indexer

Mariammal Chettiyar

Graphics

Disha Haria

Production Coordinator

Nilesh Mohite

Cover Work

Nilesh Mohite

About the Author

James Pogran has been working with computers in some form or fashion for over 15 years. His first job was systems administration for a large military installation. He then moved on to develop monitoring software and automate large scale Windows environments for a major managed services provider. He is currently a software engineer at Puppet Labs where he helps to make Windows automation even better with Puppet.

Writing a book is no easy task, a technical one about a technology as important and as fast changing as DSC is doubly so. That I was able to do so in a short time was through no small effort by many people. I would first like to thank the PowerShell product team for their awesome work and community outreach, which is truly unique in this industry. I would also like to thank the team at Packt Publishing who worked tirelessly to keep me on schedule and enabled me to be the best I could be. I am also indebted to the technical reviewers who poured over this book and made sure it was the best book possible. I would especially like to thank my wife, Jessica, my mother and father, and Cecil Morris; without their support, I would not have had the courage to write this book at all.

About the Reviewers

Marcin Grzywa is a senior software developer at Objectivity Bespoke Software Specialists. After getting an MSc in computer science degree in 2008, he spent the following years developing and architecting applications in various technologies, including Java EE, MS Business Intelligence, .NET, and JavaScript. Having always been interested in improving development processes, he then focused on using TeamCity and PowerShell in Continuous integration (CI) pipelines, which led him to Configuration as Code and PowerShell DSC.

He is also the author of open source projects PSCI (Powershell Continuous Integration) and PowerShell ISE Project Explorer.

Brian Scholer is a systems engineer with over 13 years of experience across server administration, virtualization, software development, web operations, networking, and more. He is the author of the xPfxImport DSC Resource (pending inclusion in Microsoft's xCertificate module). He blogs at http://www.briantist.com/.

Sergei Vorobev is a software developer at Microsoft. After working on the DSC Azure extension, he concentrate on PowerShell language for PowerShell v5. He is passionate about developer tools and developer experience. You can find him on Twitter at @xvorsx, where he rambles on about languages, frameworks, version control systems, workflows, scripts, and one-liners.

I would like to thank the DSC team development lead Narayanan Lakshmanan for his wise mentorship.

Dave Wyatt has been in the IT industry since 1999, working primarily as a systems administrator and engineer for the Windows Server environments. He has been heavily focused on the scripting and automation of Windows systems since that time, and he became a Microsoft MVP (PowerShell) in 2014.

Currently, he is an operations engineer for DevOpsGuys, focusing mainly on building continuous delivery pipelines for clients, which includes the configuration management of Windows servers using Windows PowerShell Desired State Configuration. He is also on the board of directors for PowerShell.org, a not-for-profit PowerShell community organization.

He is the author of The Big Book of PowerShell Error Handling, and the coauthor of Secrets of PowerShell Remoting, both free e-books available at PowerShell.org.

Thanks to my wife, Kiersten, and daughter, Moira, who bring sunshine into every day of my life (and graciously put up with all of the extra time I spend on these side projects!) Also, thanks to Don Jones, who first recognized my potential for community contributions and invited me to write blog posts for PowerShell.org.

www.PacktPub.com

Support files, eBooks, discount offers, and more

For support files and downloads related to your book, please visit www.PacktPub.com.

Did you know that Packt offers eBook versions of every book published, with PDF and ePub files available? You can upgrade to the eBook version at www.PacktPub.com and as a print book customer, you are entitled to a discount on the eBook copy. Get in touch with us at for more details.

At www.PacktPub.com, you can also read a collection of free technical articles, sign up for a range of free newsletters and receive exclusive discounts and offers on Packt books and eBooks.

https://www2.packtpub.com/books/subscription/packtlib

Do you need instant solutions to your IT questions? PacktLib is Packt's online digital book library. Here, you can search, access, and read Packt's entire library of books.

Why subscribe?

Fully searchable across every book published by Packt

Copy and paste, print, and bookmark content

On demand and accessible via a web browser

Free access for Packt account holders

If you have an account with Packt at www.PacktPub.com, you can use this to access PacktLib today and view 9 entirely free books. Simply use your login credentials for immediate access.

Instant updates on new Packt books

Get notified! Find out when new books are published by following @PacktEnterprise on Twitter or the Packt Enterprise Facebook page.

To my mother Marianne Pogran, who gave me the world when she taught me how to fix my first computer.

Preface

Windows PowerShell was a transformative event for the Windows management ecosystem. It marked a shift from the GUI-based administration of click next, next, finish to a composable command line experience that can be scripted and automated. This methodology was not accepted immediately by the Windows community, but time has proven the approach viable and PowerShell is now an integral part of any systems administrator's toolkit.

Windows PowerShell Desired State Configuration (DSC) marks another shift in Windows administration, but this time, it is a move away from the run-once scripts that cannot detect the existing state to declarative and repeatable automation without side effects. While PowerShell enabled an automation paradigm that was previously unmatched on Windows systems, crafting truly dependable automation took many lines of boilerplate code of exception catching and state checking. DSC handles this boilerplate code and gives you a clean and readable way to declare the expected state of your systems without worrying about how those systems are configured.

Whether you manage a few servers or several thousands of them, the same problems occur repeatedly. How do you ensure that all the servers under your care are configured to the exact specifications? How do you write those specifications down so that not only you and your coworker but also the machine understands them? This seemingly conflicting set of requirements is the purpose of DSC. Using DSC, you can write the human-readable desired state of the system you expect, and DSC ensures that the state of the system is what you desired it to be.

In this book, we will introduce the configuration management concepts that DSC uses to accomplish these feats. We then cover the architecture of DSC, which allows us to specify the state of a target system without having to code the implementation details ourselves. From there, we will cover how to create files that can be read by both DSC and humans to ensure that the state of target systems is what we specify. We will then address how to customize DSC to administer our customized and unique environments, and then walk through the ways in which we can deploy these configurations to the target systems using the different deployment models of DSC. We will wrap up with a walkthrough of a typical deployment cycle of example software using real-world problems and solutions.

What this book covers

Chapter 1, Introduction to PowerShell DSC, introduces you to PowerShell DSC and configuration management concepts. It covers the features included in DSC and briefly introduces the different DSC versions.

Chapter 2, DSC Architecture, covers all three phases of DSC in depth, the two different DSC deployment models, and the considerations to be made when deploying a Pull Server or using a push deployment.

Chapter 3, DSC Configuration Files, covers authoring the DSC configuration scripts and configuration data files from end to end. It also covers how to use them together effectively.

Chapter 4, DSC Resources, covers the DSC Resource syntax and file structure in both PowerShell v4 and v5. It shows how to find DSC Resources on the local system as well as using community and Microsoft-provided online resources.

Chapter 5, Pushing DSC Configurations, gives step-by-step instructions on how to push DSC configurations to remote target nodes. It also covers the extra steps the user must take to make push deployments work and discusses the pros and cons of using push deployments.

Chapter 6, Pulling DSC Configurations, gives step-by-step instructions on how to set up a DSC Pull Server and your environment to best utilize a pull-based deployment. It covers the pros and cons of using pull deployments in comparison to push deployments.

Chapter 7, Example Scenarios, covers the use of DSC in the real world and how to integrate DSC into not only new environments but also with legacy-style deployments. This chapter walks us through the thought processes of handling the changing requests and the requirements of different software deployments using DSC.

What you need for this book

You will need the following operating systems:

Windows 8.1

Windows 2012 R2

You will also need PowerShell v4 or v5 as the software.

Who this book is for

This book is intended for system administrators, developers, or DevOps engineers who are responsible for configuration management and automation and wish to learn PowerShell Desired State Configuration for efficient management, configuration, and deployment of systems and applications.

You are expected to have some basic knowledge of Windows PowerShell and should have experience in installing and configuring operating systems and Windows servers. You also need to understand the basics and principles of configuration management and to apply both to deploying and managing systems and applications using PowerShell DSC.

Conventions

In this book, you will find a number of text styles that distinguish between different kinds of information. Here are some examples of these styles and an explanation of their meaning.

Code words in text, database table names, folder names, filenames, file extensions, pathnames, dummy URLs, user input, and Twitter handles are shown as follows: DSC operates in a push scenario when configurations are manually pushed to target nodes using the Start-DscConfiguration Cmdlet.

Any command-line input or output is written as follows:

PS C:\Examples> .\TestExample.ps1

    Directory: C:\Examples\TestExample

Mode                LastWriteTime    Length Name ----                -------------    ------ ---- -a---        5/20/2015  7:28 PM      1136 localhost.mof

Important words are shown in bold and appear in the text like this: These will typically fail with a generic Access Denied, which will most likely lead you down the wrong path when troubleshooting.

Note

Warnings or important notes appear in a box like this.

Tip

Tips and tricks appear like this.

Reader feedback

Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or disliked. Reader feedback is important for us as it helps us develop titles that you will really get the most out of.

To send us general feedback, simply e-mail <feedback@packtpub.com>, and mention the book's title in the subject of your message.

If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide at www.packtpub.com/authors.

Customer support

Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.

Downloading the example code

You can download the example code files from your account at http://www.packtpub.com for all the Packt Publishing books you have purchased. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

Errata

Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you could report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/submit-errata, selecting your book, clicking on the Errata Submission Form link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded to our website or added to any list of existing errata under the Errata section of that title.

To view the previously submitted errata, go to https://www.packtpub.com/books/content/support and enter the name of the book in the search field. The required information will appear under the Errata section.

Piracy

Piracy of copyrighted material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works in any form on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy.

Please contact us at <copyright@packtpub.com> with a link to the suspected pirated material.

We appreciate your help in protecting our authors and our ability to bring you valuable content.

Questions

If you have a problem with any aspect of this book, you can contact us at <questions@packtpub.com>, and we will do our best to address the problem.

Chapter 1. Introduction to PowerShell DSC

Welcome to PowerShell Desired State Configuration (DSC), the new configuration management platform from Microsoft. We begin with a quote from Alice in Wonderland. Besides pertinent advice for the author, it is apropos of what DSC is at its very core. DSC, by the very simplest definition, allows you to write down the beginning, the middle, and the end of your deployment story. The second quote we see is from The Hitchhiker's Guide to the Galaxy, and is something to remember throughout reading this book. We will cover a lot of new concepts, some old concepts with new importance, and a lot of PowerShell. Don't panic; we'll get through fine.

This book will begin with the basics of PowerShell DSC, covering its architecture and many components. It will familiarize you with the set of Windows PowerShell language extensions and new Windows PowerShell commands that comprise DSC. Then, it will help you create DSC custom resources and work with DSC configurations with the help of practical examples. Finally, it will describe how to deploy a configuration data set using PowerShell DSC.

By the end of this book, you will be able to deploy a real-world application end to end.

In this chapter, we will cover:

What is PowerShell DSC?

Why do we need Configuration Management and what is DevOps?

How does DSC help me?

A high level overview of DSC

DSC requirements

DSC versions

What is PowerShell DSC?

Have some software that needs to be installed in a certain order? With special configuration steps? Some security policies that must be applied to every server? How about ensuring that a set of services are never enabled to start? Have you ever written scripts to handle this kind of work, but found them brittle because of changes in software from release to release? Needed to make these changes on dozens or hundreds of servers repeatedly on schedule? Ever had someone change something and have your script break because the state