Samples for deploying an AWS Systems Manager Association using the 'AWS-ApplyDSCMofs' Document.

AWS-ApplyDSCMofs

# Overview

This Gist provides samples to simplify the usage of the AWS Systems Manager Document, "AWS-ApplyDSCMofs".

CloudFormation-Template.yml

---
AWSTemplateFormatVersion: '2010-09-09'

Description: 'AWS-ApplyDSCMofs'

Parameters:

  AssociationName:
    Type: String
    Description: Systems Manager State Manager Association Name
    Default: 'AWS-ApplyDSCMofs'

  MofsToApply:
    Type: String
    Description: A comma seperated list of MOF files to apply. Files can be from S3 (e.g. s3:bucketName:fileKey or s3:bucketRegion:bucketName:fileKey), HTTP/S (e.g. https://mydomain.com/MyMof.mof) or File System (e.g. \\MyServer\MyShare\MyMof.mof)
    Default: 'https://s3-us-west-1.amazonaws.com/aws-ssm-us-west-1/statemanagerdocumentspayload/AWS-ApplyDSCMofs/HelloWorld.mof'

  ServicePath:
    Type: String
    Description: The prefix used when writing reports and status to S3.
    Default: default

  MofOperationMode:
    Type: String
    Description: The mode to use when applying the MOFs, either 'Apply' (will correct non-compliant resources) or 'ReportOnly' (will not correct non-compliant resources).
    Default: 'Apply'
    AllowedValues:
      - 'Apply'
      - 'ReportOnly'

  ReportBucketName:
    Type: String
    Description: (Optional) The name of the S3 bucket to write compliance reports to. This is the bucket that the JSON formatted reports will be saved in, using the ServicePath as the key prefix. This should be in the format bucketregion:bucketname e.g. us-west-2:mybucket
    Default: ''

  StatusBucketName:
    Type: String
    Description: (Optional) The name of the S3 bucket to write status reports to. These are singleton summaries of the most recent compliance run of an instance. It should be in the format bucketregion:bucketname e.g. us-west-2:mybucket
    Default: ''

  ModuleSourceBucketName:
    Type: String
    Description: (Optional) The name of the S3 bucket containing module files. If no bucket is to be used, specify 'NONE' and ensure the 'AllowPSGalleryModuleSource' parameter is set to 'True'. It should be in the format bucketregion:bucketname e.g. us-west-2:mybucket
    Default: 'NONE'

  AllowPSGalleryModuleSource:
    Type: String
    Description: (Optional) True if modules can be downloaded from PSGallery. If this is false, the 'ModuleSourceBucketName' parameter should be used.
    Default: 'True'
    AllowedValues:
      - 'True'
      - 'False'

  ProxyUri:
    Type: String
    Description: (Optional) The Uri of a proxy server to use
    Default: ''

  RebootBehavior:
    Type: String
    Description: (Optional) The reboot behavior that the script will have should it need to reboot the machine. Default is 'AfterMof'
    Default: AfterMof
    AllowedValues:
      - AfterMof
      - Immediately
      - Never

  UseComputerNameForReporting:
    Type: String
    Description: (Optional) Use the ComputerName for reporting instead of the Instance Id. Default is 'False'
    Default: 'False'
    AllowedValues:
      - 'False'
      - 'True'

  EnableVerboseLogging:
    Type: String
    Description: (Optional) Enables Verbose logging, useful when deploying MOFs for the first time. Make sure you have lifecycle policies enabled on your logging bucket if you use this all the time.
    Default: 'False'
    AllowedValues:
      - 'False'
      - 'True'

  EnableDebugLogging:
    Type: String
    Description: (Optional) Enables Debug logging, useful when troubleshooting a failing MOF. Don't use in day to day operation.
    Default: 'False'
    AllowedValues:
      - 'False'
      - 'True'

  ComplianceType:
    Type: String
    Description: (Optional) The compliance type to use when reporting compliance. Default is 'Custom:DSC'. Each association should have a different ComplianceType value.
    Default: 'Custom:DSC'

  PreRebootScript:
    Type: String
    Description: (Optional) A script to execute prior to the instance rebooting if the configuration has indicated that a reboot is necessary. Your script must be a single line, but can be separated by semi-colons.
    Default: ''

  OutputS3BucketName:
    Type: String
    Description: The S3 Bucket Name used for AWS Systems Manager Run Command Output.
    Default: ''

  OutputS3KeyPrefix:
    Type: String
    Description: The S3 Key Prefix used for AWS Systems Manager Run Command Output.
    Default: ''

  ScheduleExpression:
    Type: String
    Description: 'The Schedule Expression for the AWS Systems Manager Association. Example are "rate(30 minutes)", "rate(1 day)", "rate(7 days)"'
    Default: 'rate(1 day)'

  TargetResourceTagKey:
    Type: String
    Description: The AWS Systems Manager Tag Key for the target

  TargetResourceTagValue:
    Type: String
    Description: The AWS Systems Manager Tag Value for the target

Metadata:

  AWS::CloudFormation::Interface:
    ParameterGroups:
      -
        Label:
          default: DSC MOF Configuration
        Parameters:
          - MofsToApply
          - MofOperationMode
          - RebootBehavior
      -
        Label:
          default: PowerShell Modules
        Parameters:
          - AllowPSGalleryModuleSource
          - ModuleSourceBucketName
      -
        Label:
          default: DSC Reporting
        Parameters:
          - ServicePath
          - ComplianceType
          - ReportBucketName
          - StatusBucketName
          - UseComputerNameForReporting
      -
        Label:
          default: DSC Logging
        Parameters:
          - EnableVerboseLogging
          - EnableDebugLogging
      -
        Label:
          default: Reboot Handling
        Parameters:
          - PreRebootScript
      -
        Label:
          default: Proxy Configuration
        Parameters:
          - ProxyUri
      -
        Label:
          default: Systems Manager Run Command Configuration
        Parameters:
          - AssociationName
          - ScheduleExpression
          - TargetResourceTagKey
          - TargetResourceTagValue
          - OutputS3BucketName
          - OutputS3KeyPrefix
    ParameterLabels:
      AllowPSGalleryModuleSource:
        default: Allow Module installation from the PowerShell Gallery
      AssociationName:
        default: Association Name
      ComplianceType:
        default: Compliance Type for Systems Manager Compliance Reporting
      EnableDebugLogging:
        default: Enable Debug Logging
      EnableVerboseLogging:
        default: Enable Verbose Logging
      ModuleSourceBucketName:
        default: PowerShell Module Source S3 Bucket Name
      MofsToApply:
        default: DSC MOFs to apply
      MofOperationMode:
        default: MOF Operation Mode
      OutputS3BucketName:
        default: Output S3 Bucket Name
      OutputS3KeyPrefix:
        default: Output S3 Key Prefix
      PreRebootScript:
        default: Pre-Reboot PowerShell Script
      ProxyUri:
        default: Proxy Uri
      RebootBehavior:
        default: Reboot Behavior
      ReportBucketName:
        default: Compliance Report S3 Bucket Name
      ScheduleExpression:
        default: Scheduled Expression
      ServicePath:
        default: Service Path
      StatusBucketName:
        default: Status Report S3 Bucket Name
      TargetResourceTagKey:
        default: Tag Key for Association Targeting
      TargetResourceTagValue:
        default: Tag Value for Association Targeting
      UseComputerNameForReporting:
        default: Use Computer Name for Reporting

Resources:

  Association:
    Type: AWS::SSM::Association
    Properties:
      AssociationName: !Ref AssociationName
      Name: AWS-ApplyDSCMofs
      Parameters:
        MofsToApply:
          - !Ref MofsToApply
        ServicePath:
          - !Ref ServicePath
        MofOperationMode:
          - !Ref MofOperationMode
        ReportBucketName:
          - !Ref ReportBucketName
        StatusBucketName:
          - !Ref StatusBucketName
        ModuleSourceBucketName:
          - !Ref ModuleSourceBucketName
        AllowPSGalleryModuleSource:
          - !Ref AllowPSGalleryModuleSource
        ProxyUri:
          - !Ref ProxyUri
        RebootBehavior:
          - !Ref RebootBehavior
        UseComputerNameForReporting:
          - !Ref UseComputerNameForReporting
        EnableVerboseLogging:
          - !Ref EnableVerboseLogging
        EnableDebugLogging:
          - !Ref EnableDebugLogging
        ComplianceType:
          - !Ref ComplianceType
        PreRebootScript:
          - !Ref PreRebootScript
      OutputLocation:
        S3Location:
          OutputS3BucketName: !Ref OutputS3BucketName
          OutputS3KeyPrefix: !Ref OutputS3KeyPrefix
      ScheduleExpression: !Ref ScheduleExpression
      Targets:
        - Key: !Sub 'tag:${TargetResourceTagKey}'
          Values:
            - !Ref TargetResourceTagValue

PowerShell-Script.ps1

$bucketName = '<S3 Bucket Name>'
$mofKey = '<S3 Key to MOF File>'

$reportBucketName = '<S3 Bucket Name for DSC Detailed Reports>'
$statusBucketName = '<S3 Bucket Name for DSC Status Reports>'
$ssmOutputBucketName = '<S3 Bucket Name for SSM Output>'

$newSSMAssociation = @{
    AssociationName = 'DSCDemo'
    Name = 'AWS-ApplyDSCMofs' # For reference, this is "DocumentName" on Send-SSMCommand
    Target = @(
        @{
            Key = 'tag:ConfigurationName'
            Values = @( 'DSCDemo' )
        }
    )
    Parameter = @{
        MofsToApply = 's3:{0}:{1}' -f $bucketName, $mofKey
        ServicePath = 'dscdemo'
        MofOperationMode = 'Apply'
        ReportBucketName = $reportBucketName
        StatusBucketName = $statusBucketName
        ModuleSourceBucketName = 'NONE' # This MUST BE NONE if you don't want to use it.
        AllowPSGalleryModuleSource = 'False'
        #ProxyUri = ''
        RebootBehavior = 'AfterMof'
        UseComputerNameForReporting = 'False' # This is not a [Boolean], it is a [String] and MUST be "True" or "False" (not "true" or "false")
        EnableVerboseLogging = 'True'
        EnableDebugLogging = 'False'
        ComplianceType = 'Custom:DSCDemo'
        PreRebootScript = ''
    }
    S3Location_OutputS3BucketName = $ssmOutputBucketName # This is OutputS3BucketName on Send-SSMCommand
    S3Location_OutputS3KeyPrefix = 'dscdemo' # This is OutputS3KeyPrefix on Send-SSMCommand
    MaxConcurrency = 2
    MaxError = 1
    ScheduleExpression = 'cron(0/30 * * * ? *)'
}
New-SSMAssociation @newSSMAssociation