Skip to content

Latest commit

 

History

History
204 lines (162 loc) · 13.5 KB

README.md

File metadata and controls

204 lines (162 loc) · 13.5 KB
Raw

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

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