Modernisation Platform Terraform SSM Patching

Usage

To use this module, instances must have the SSM agent installed (installed by default with many AMI'S). To use the module default schedule, you must also have a tag of "patch-manager: group1" on an instance to associate it to the patch schedule. The tag name, values and associated schedules can all be customised as required. The tag value drives the naming suffix which is important when multiple patch groups are defined.

Version 4 is essentially a re-write with many improvements and required changes to input arguments to fully integrate multiple patch groups, OSes and shared resources to reduce the amount of duplicate resources required with only a single module call needed per account. If upgrading be sure to review the Inputs section / release notes.

By default the module will create 1 patch group and associated schedule, the classifications by OS need to be specified.

# Basic Example

module "ssm-patching" {
  source                = "github.com/ministryofjustice/modernisation-platform-terraform-ssm-patching.git?ref="
  providers             = { aws.bucket-replication = aws }
  count                 = local.environment == "development" ? 1 : 0
  providers             = { aws.bucket-replication = aws }
  account_number        = local.environment_management.account_ids[terraform.workspace]
  environment           = "development"
  application_name      = local.application_name
  patch_classifications = {
    WINDOWS = ["SecurityUpdates", "CriticalUpdates", "DefinitionUpdates"]
  }
  tags                  = merge(local.tags, { Name = "ssm-patching-module" }, )
}

However, it is expected you may want to add multiple patch groups with your own schedules, the example below shows 2 groups.

# Example with 2 patch groups with associated schedules and 2 supported OSes with associated classifications.

locals {
  patch_manager = {
    patch_schedules = {
      group1 = "cron(00 03 ? * WED *)"
      group2 = "cron(00 03 ? * THU *)"
    }
    maintenance_window_duration = 4
    maintenance_window_cutoff   = 2
    daily_definition_update     = true
    patch_classifications = {
      REDHAT_ENTERPRISE_LINUX = ["Security", "Bugfix"]
      WINDOWS                 = ["SecurityUpdates", "CriticalUpdates", "DefinitionUpdates"]
    }
  }
}  

module "patch_manager" {
  source                      = "github.com/ministryofjustice/modernisation-platform-terraform-ssm-patching.git?ref="
  providers                   = { aws.bucket-replication = aws }
  account_number              = local.environment_management.account_ids[terraform.workspace] # Required
  application_name            = local.application_name                                        # Required
  environment                 = local.environment                                             # Required
  patch_schedules             = local.patch_manager.patch_schedules
  maintenance_window_cutoff   = local.patch_manager.maintenance_window_cutoff
  maintenance_window_duration = local.patch_manager.maintenance_window_duration
  patch_classifications       = local.patch_manager.patch_classifications                     # Required
  daily_definition_update     = local.patch_manager.daily_definition_update
  tags                        = merge(local.tags, { Name = "ssm-patching-module" },)
}

This v4 removes the archiving of reports to S3 bucket to reduce complexity and cost, as all results and Patch compliance findings are exported to Security Hub by default.

Looking for issues?

If you're looking to raise an issue with this module, please create a new issue in the Modernisation Platform repository.

Requirements

Name	Version
terraform	~> 1.0
aws	~> 6.0
http	~> 3.4

Providers

Name	Version
aws	~> 6.0

Modules

No modules.

Resources

Name	Type
aws_iam_policy.patch_manager	resource
aws_iam_role.patch_manager	resource
aws_iam_role_policy_attachment.patch_manager	resource
aws_resourcegroups_group.patch_manager	resource
aws_ssm_default_patch_baseline.patch_manager	resource
aws_ssm_maintenance_window.definition_updates	resource
aws_ssm_maintenance_window.patch_manager	resource
aws_ssm_maintenance_window_target.definition_updates	resource
aws_ssm_maintenance_window_target.patch_manager	resource
aws_ssm_maintenance_window_task.definition_updates	resource
aws_ssm_maintenance_window_task.patch_task	resource
aws_ssm_patch_baseline.patch_manager	resource
aws_iam_policy_document.patch-manager-policy-doc	data source

Inputs

Name	Description	Type	Default	Required
account_number	Account number of current environment	string	n/a	yes
application_name	Name of application	string	n/a	yes
approval_days	A map of environment and number of days before the package is approved, used by the approval rule only, and is not required for the automation script	map(number)	{ "development": 0, "preproduction": 5, "production": 7, "test": 3 }	no
compliance_level	Select the level of compliance, used by the approval rule only, and is not required for the automation script. By default it's CRITICAL	string	"CRITICAL"	no
daily_definition_update	Create an additional schedule for Windows instances to update definitions every day (no reboot required), Uses tag:os-type = Windows as targets.	bool	false	no
environment	Current environment, used to drive the default approval days	string	n/a	yes
maintenance_window_cutoff	The number of hours before the end of the Maintenance Window that Systems Manager stops scheduling new tasks for execution.	number	2	no
maintenance_window_duration	The duration of the Maintenance Window in hours.	number	4	no
patch_classifications	Maps an OS against a list of patch classification catagories	map(list(string))	n/a	yes
patch_schedules	A map of target group(s) to crontab schedule(s) to define the maintenance window(s) where the patch process will run.	map(any)	{ "group1": "cron(00 22 ? * MON *)" }	no
patch_tag_key	Defaults as tag:patch-manager, but can be customised to use a different tag	string	"patch-manager"	no
product	The specific product the patch is applicable for e.g. RedhatEnterpriseLinux8.5, WindowsServer2022	list(string)	[ "*" ]	no
rejected_patches	List of patches to be rejected	list(string)	[]	no
severity	Severity of the patch e.g. Critical, Important, Medium, Low	list(string)	[ "*" ]	no
tags	Common tags to be used by all resources	map(string)	n/a	yes

Outputs

Name	Description
iam_policy_arn	The policy arn for the IAM policy used by the automation script
maintenance_window_ids	The maintenance window id(s)
maintenance_window_target_ids	The target id(s) for the maintenance window
patch_resource_group_arns	The resource group arn(s) for patching