Skip to content

Instantly share code, notes, and snippets.

@austoonz
Last active December 30, 2021 16:17
Show Gist options
  • Save austoonz/14ad194db6e55dcee96bf97ea07adb45 to your computer and use it in GitHub Desktop.
Save austoonz/14ad194db6e55dcee96bf97ea07adb45 to your computer and use it in GitHub Desktop.
Samples for deploying an AWS Systems Manager Association using the 'AWS-ApplyDSCMofs' Document.
# Overview
This Gist provides samples to simplify the usage of the AWS Systems Manager Document, "AWS-ApplyDSCMofs".
---
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
$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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment