terraform-aws-ssm

Terraform module to compose AWS Systems Manager (SSM) configurations.

Usage

module "ssm" {
  source = "areguera/ssm/aws"

  name = var.name

  operating_system                     = "AMAZON_LINUX_2"
  approved_patches_compliance_level    = "CRITICAL"
  approved_patches_enable_non_security = false

  approval_rules = [{
    approve_after_days  = 7
    compliance_level    = "CRITICAL"
    enable_non_security = false
    patch_filters = [
      { key = "PRODUCT", values = ["AmazonLinux2"] },
      { key = "CLASSIFICATION", values = ["Security", "Bugfix"] },
      { key = "SEVERITY", values = ["Critical", "Important"] }
    ]
  }]

  maintenance_window = {
    enabled           = true
    schedule          = "cron(0 9 */7 * ?)"
    schedule_timezone = "UTC"
    cutoff            = 0
    duration          = 1
  }
}

Patch baseline

This module creates one patch baseline named ${var.name}. this patch baseline applies to all Amazon Linux 2 EC2 instances tagged with the Patch Group tag name and value ${var.name}. These instances will approve all operating system patches that are classified as "Security" and have a severity level of "Critical" or "Important". Patches are auto-approved seven days after release. Also approves all patches with a classification of "Bugfix" seven days after release.

       *       *       *       *       *
       |       |       |       |       |
------>|------>|------>|------>|------>|
       |       |       |       |       |
       *       *       *       *       *

This module configures the ${var.name} patch baseline to reboot instances during maintenance window automatically, if needed. To prevent down-time, you need to design your infrastructure to keep your application up-and-running in spite of system reboots or unexpected application failures because of patching itself. For example, you could use the SSM configuration this module provides in combination with other AWS technologies like load balancer and auto-scaling groups with the health checks enabled and properly configured on them.

To know more about patch baseline, see AWS Systems Manager Patch Manager documentation.

Maintenance window

This module creates a maintenance window that runs every seven days at 9 AM UTC. This maintenance window is configured with two tasks that run in order. The first task installs new patches and reboots the target operating systems if needed. The second task applies configuration playbooks on target operating system to grantee their desired state after patching. The second task also executes simple tests to validate the application is running as expected. In case any of these two tasks fail, the maintenance window will fail and the patching action stops from being propagated to remaining target systems.

This module schedules the maintenance window to run every seven days at 9 A.M. The schedule was set in alignment with the patch baseline approval time frame, which is also seven days. So, that's the moment in time when system patching will happen.

This module only supports one maintenance window per module instantiation. To create more than one maintenance window for your infrastructure, create one unique configuration for each one of them. Avoid one unique configuration with several maintenance windows inside if possible. Having several configurations with only one maintenance window allows you to manage different configurations easier. For example, in cases where each configuration represents a specific level of risk (e.g., dev, stage, prod).

To know more about maintenance window, see AWS Systems Manager Maintenance Windows documentation.

Associations

This module creates the following associations:

Name	Recurrency	Description
${var.name}-UpdateSSMAgent	14 days	Update SSM agent when a new version is available.
${var.name}-ApplyAnsiblePlaybooks	30 minutes	Apply ansible playbooks available in ${path.root}/ansible/ directory.
${var.name}-GatherSoftwareInventory	30 minutes	Collect system information.
${var.name}-RunPatchBaseline	24 hours	Applies the ${var.name} patch baseline in Scan mode to identify available patching.

To know more about associations, see AWS System Manger State Manager documentation.

Documents

This module creates the ${var.name}-ApplyAnsiblePlaybooks document that you can use to download ansible playbooks from a private S3 bucket and apply them on SSM managed nodes. This document is a modified version of the AWS-ApplyAnsiblePlaybooks document, which doesn't support private communication with an S3 bucket.

The ${var.name}-ApplyAnsiblePlaybooks document synchronizes the ${path.root}/ansible/ directory structure from S3 to /opt/${var.name}-ssm/ansible directory, locally, in the SSM managed node file system, where the associations or maintenance window tasks are configured to run at. Finally, the document creates a list of all playbooks found in the first level of /opt/${var.name}-ssm/ansible directory, and executes them one by one, in alphabetic order, using the ansible-playbook command.

To know more about documents, see AWS Systems Manager documents documentation.

Desired state

This module implements the desired state of SSM managed nodes using the ansible playbooks you provide in the ${path.root}/ansible/ directory. To apply these playbooks on SSM managed nodes, the terraform-aws-ssm module deploys a private S3 bucket named ${var.name}-ssm, uploads the ${path.root}/ansible/ directory up to it, and uses the ${var.name}-ApplyAnsiblePlaybooks document to apply them, when it is executed from either associations or maintenance window tasks.

Examples

• Simple SSM configurations

Requirements

Name	Version
aws	~> 4.0

Providers

Name	Version
aws	~> 4.0

Modules

Name	Source	Version
s3_bucket	terraform-aws-modules/s3-bucket/aws	~> 3.0

Resources

Name	Type
aws_cloudwatch_log_group.this	resource
aws_iam_instance_profile.this	resource
aws_iam_policy.AmazonEC2SSMCloudwatch	resource
aws_iam_policy.AmazonEC2SSMS3Logs	resource
aws_iam_policy.AmazonEC2SSMS3Playbooks	resource
aws_iam_role.this	resource
aws_iam_role_policy_attachment.AmazonEC2SSMCloudwatch	resource
aws_iam_role_policy_attachment.AmazonEC2SSMS3Logs	resource
aws_iam_role_policy_attachment.AmazonEC2SSMS3Playbooks	resource
aws_iam_role_policy_attachment.AmazonSSMManagedInstanceCore	resource
aws_iam_role_policy_attachment.AmazonSSMPatchAssociation	resource
aws_s3_object.this	resource
aws_ssm_association.ApplyAnsiblePlaybooks	resource
aws_ssm_association.GatherSoftwareInventory	resource
aws_ssm_association.RunPatchBaseline	resource
aws_ssm_association.UpdateSSMAgent	resource
aws_ssm_document.ApplyAnsiblePlaybooks	resource
aws_ssm_maintenance_window.this	resource
aws_ssm_maintenance_window_target.this	resource
aws_ssm_maintenance_window_task.ApplyAnsiblePlaybooks	resource
aws_ssm_maintenance_window_task.SystemPatches	resource
aws_ssm_patch_baseline.this	resource
aws_ssm_patch_group.this	resource
aws_iam_policy_document.this	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
approval_rules	(Required) Specify the set of rules used to include patches in the baseline. Up to 10 approval rules can be specified.	list(object({ approve_after_days = number compliance_level = string enable_non_security = bool patch_filters = list(object({ key = string values = list(string) })) }))	n/a	yes
approved_patches_compliance_level	(Optional) Defines the compliance level for approved patches. This means that if an approved patch is reported as missing, this is the severity of the compliance violation. Valid compliance levels include the following: CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL, UNSPECIFIED.	string	"UNSPECIFIED"	no
approved_patches_enable_non_security	(Optional) Indicates whether the list of approved patches includes non-security updates that should be applied to the instances.	bool	false	no
description	(Optional) The project description.	string	""	no
maintenance_window	(Required) Specify the set of rules used to configure the maintenance window.	object({ schedule = string schedule_timezone = string cutoff = number duration = number enabled = bool })	n/a	yes
max_concurrency	(Optional) Specify the number of managed nodes that run a command simultaneously. Posible values can be integers (e.g., '5', '10') or percentages (e.g., '10%', '20%'). In both cases the values must be passed as string.	string	"10%"	no
max_errors	(Optional) Specify how many errors are allowed before the system stops sending the command to additional managed nodes. Posible values can be integers (e.g., '5', '10') or percentages (e.g., '10%', '20%'). In both cases the values must be passed as string.	string	"1"	no
name	(Required) The project name. This value is prefixed to SSM configuration resources.	string	n/a	yes
operating_system	(Optional) Defines the operating system the patch baseline applies to. Supported operating systems include AMAZON_LINUX_2.	string	"AMAZON_LINUX_2"	no

Outputs

Name	Description
iam_instantace_profile_name	n/a