custom_ssm_setup

Customized AWS Systems Manager Setup with AWS CloudFormation

Please refer to the Installing the CloudWatch agent using Systems Manager Distributor and State Manager section in the Designing and implementing logging and monitoring with Amazon CloudWatch APG guide for context.

This CloudFormation template can be deployed as a stack for single region, single account deployment or as a StackSet for multi-account, multi-region deployment for S3 based deployment and update of CloudWatch Agent configurations for Amazon EC2 and on-premises servers.

This template is based on the AWS Systems Manager Quick Setup process. You should review the template carefully to understand the permissions and resources that are contained and the changes implement from a traditional AWS Systems Manager Setup.

Prerequisites:

• Amazon S3 bucket for centralized CloudWatch agent configuration storage accessible by AWS Organization accounts - You must have an S3 bucket that contains your CloudWatch configurations. The InstallAndManageCloudWatchDocument SSM automation runbook defined in the CloudFormation template, points to this S3 bucket to download and configure Amazon CloudWatch.
• The S3 bucket must contain your common CloudWatch configurations. At a minimum, you should create a standard configuration for Linux or Windows or both if you use these operating systems. For example, you can copy the cloudinit-logging-linux.json file to the /config/standard/linux/ec2 S3 prefix to standardize logging for cloud init logs for your linux instances.
• If you are deploying the template across multiple regions and multiple accounts as a service-managed StackSet then you should deploy in the AWS Organizations management account or you should have Delegated Administrator permissions in the account with preference to Delegated Administrator. Refer to the Customized Quick Setup in multiple Regions and multiple accounts with AWS CloudFormation StackSets section of the APG guide.

Changes to AWS SSM Quick Setup

In general, the following changes have been made from the standard AWS SSM Quick Setup process:

• The default option to periodically update the Systems Manager agent, collect inventory, and scan for patches is changed from true to false. This helps avoid potential collisions with existing Systems Manager associations and setups that you may have deployed. You can change these to true if you want to enable these features and you haven't already configured them in your account(s).
• The default option to install and periodically update the CloudWatch agent is changed from false to true. This enables the CloudWatch installation, configuration, and update by default.
• The Name property for the Systems Manager documents is commented out so that the names are dynamically generated by AWS CloudFormation. This enables you to more easily update the documents with AWS CloudFormation without having to perform renaming operations. Naming Systems Manager documents in AWS CloudFormation prevents you from updating them with CloudFormation because a change in the document results in a replacement of the existing document.
• The CloudWatchConfigS3BucketPolicy customer-managed IAM policy is added to provide read access to the S3 bucket containing the CloudWatch configurations.
• The RoleForAutomation IAM role permissions are updated to include permissions to attach the CloudWatchAgentServerPolicy, the S3 customer managed policy, and refinements for least privileged access.
• Additional steps are added to the CreateAndAttachIAMToInstance Systems Manager document to include the CloudWatchAgentServerPolicy AWS managed IAM policy and the customer-managed policy for Amazon S3 access. An extra parameter has been added to identify if you provided an existing standard EC2 AWS IAM profile that you are using. If an existing IAM profile was provided then the profile will be attached to your EC2 instances when run instead of creating a new IAM role and profile.
• The SystemAssociationForManagingInstances SSM Association for CreateAndAttachIAMToInstance has been updated to pass an existing IAM profile, if provided at deployment.
• Additional steps are added to the UpdateExistingInstanceProfile Systems Manager document to include the CloudWatchAgentServerPolicy AWS managed IAM policy and the customer-managed policy for Amazon S3 access. The InstanceId parameter has been commented out as it is not needed.
• The SystemAssociationForUpdateManagingInstances SSM Association for UpdateExistingInstanceProfile has been updated to remove periodic update. It will the necessary IAM policy updates to the provided IAM role once upon deployment. The EC2 instance targeting has been removed, this isn't used by the SSM document since only updates to an IAM role are performed.
• The UpdateCloudWatchDocument SSM document and related SSM association has been commented out. This is handled collectively by the InstallAndManageCloudWatchDocument SSM document and SystemAssociationForInstallAndConfigureCloudWatchAgent SSM association.
• The InstallAndManageCloudWatchDocument SSM document has been updated with additional steps to download CloudWatch configuration files from the S3 bucket containing your standard CloudWatch configurations. Steps are added to stop and restart the CloudWatch agent after the configuration files are downloaded.
• The SystemAssociationForInstallAndConfigureCloudWatchAgent SSM association to the InstallAndManageCloudWatchDocument SSM document has been updated to include parameters specifying the CloudWatch S3 configuration bucket.

Individual Custom SSM documents

These customized versions of the SSM documents created by Quick Setup can be used separately if you don't want to use the AWS-QuickSetup-SSMHostMgmt.yaml CloudFormation template.

SSM automation document to create / update standard SSM & CloudWatch IAM instance profile - CreateAndAttachIAMToInstance.yaml

This customized SSM document is created by SSM Quick Setup to deploy an IAM instance profile to provide the necessary permissions for SSM. This updated version of the document includes the necessary permissions for Amazon CloudWatch as well as a common CloudWatch S3 configuration bucket.

You will need to update the placeholder, <Include ARN for S3 IAM policy here> with an IAM policy that will provide access to your CloudWatch S3 configuration bucket. You can use the example policy defined in the AWS-QuickSetup-SSMHostMgmt.yaml CloudFormation template.

Updated IAM instance profile SSM document - InstallAndManageCloudWatchDocument.yaml

This customized SSM document is created by SSM Quick Setup to deploy and configure the CloudWatch agent. This updated version of the document includes customizations to deploy and configure standard CloudWatch configurations from an S3 bucket.