[New Resource]: SSM (Systems Manager) - Patch Policy

[thetestlabs]

Description

Add support for patch policies. Beginning December 22, 2022, Patch Manager offers a new, recommended method to configure patching for your organization and AWS accounts through the use of patch policies.

https://docs.aws.amazon.com/systems-manager/latest/userguide/patch-policies-about.html

Requested Resource(s) and/or Data Source(s)

aws_ssm_patch_policy

Potential Terraform Configuration

resource "aws_ssm_patch_policy" "example" {
  name        = "example-patch-policy"
  description = "A patch policy with default configuration"

  patch_operation = "scan"         # The options here should be either `scan` or `install`
  patch_baseline  = "default"      # The options here should be `default` or `custom`. `custom` will require either a configuration block or separate resource
  s3_bucket       = "bucket-id"    # S3 Bucket for logging patching operations
  targets         = "organization" # The options here should be `organization`, `custom`, or `current_account`. `custom` will require either a configuration block or separate resource

  scan_schedule {
    # `patch_operation` has options for recommended defaults or a custom scan schedule. This block should configure the custom scan schedule.
    # The first option is to configure a daily schedule
    daily_time = "02:00"
    # The second option is to use a custom CRON expression
    cron_expression = "cron(0 12 * * ? *)"
    # There is also an option to wait to scan targets until first CRON interval.
    wait = true
  }

  rate_control {
    # Rate controls can be expressed as either number of nodes or percentage of nodes
    concurrency     = 10
    error_threshold = 10
  }

  add_iam_policies = true # The options here should be `true` or `false`

}

References

https://docs.aws.amazon.com/systems-manager/latest/userguide/patch-policies-about.html

https://docs.aws.amazon.com/systems-manager/latest/userguide/quick-setup-patch-manager.html

https://aws.amazon.com/blogs/mt/centrally-deploy-patching-operations-across-your-aws-organization-using-systems-manager-quick-setup/

Would you like to implement a fix?

No

[github-actions]

Community Note

Voting for Prioritization

• Please vote on this issue by adding a 👍 reaction to the original post to help the community and maintainers prioritize this request.
• Please see our prioritization guide for information on how we prioritize.
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request.

Volunteering to Work on This Issue

• If you are interested in working on this issue, please leave a comment.
• If this would be your first contribution, please review the contribution guide.

[HenriBlacksmith]

Is there a defined schedule to implement this resource?

[jar-b]

Hello - In researching this issue we've determined there are currently no public API's for managing SSM patch policies. AWS has confirmed this via a support case, stating at this time the only method for utilizing Quick Setup (and therefore managing patch policies) is the AWS console.

For users interested in this functionality for Terraform, raising a feature request with AWS is the best course of action at this time. Until APIs are available and exposed to the AWS SDK for Go we unfortunately won't be able to take any action.

[HenriBlacksmith]

Hey, in my understanding Quick Setup are pre-configured CloudFormation StackSets.

I assume those can be found through CloudFormation APIs?

[srversent]

@breathingdust @justinretzolk Do you have updates around delivery timeline of this resource?

[fogers777]

any update?

[AnItalianMan]

Hello everyone,

It seems that the API for configuring a Patch Policy through Quick Setup has been released. You can find an example here and the official documentation here.

Please let us know if this will be implemented in a future AWS Terraform provider release.
@breathingdust @justinretzolk

Thanks!

[aristosvo]

Hi @jar-b 👋!

I saw your PR on the client, will you continue with the resources as well? Otherwise I would happily contribute, but your PRs would probably go through a bit faster 🤣

[jar-b]

Hey @aristosvo - thanks for checking!

Yes, I meant to assign myself yesterday and missed that step. I'm planning to implement a aws_ssmquicksetup_configuration_manager resource next. Patch policies are one of the configuration types which can be managed with this resource.

[tommydot]

Keen for this one too. We are looking into ways to set up a Patch policy for our AWS organization and would love to do it with Terraform if we can.

[github-actions]

Warning

This issue has been closed, meaning that any additional comments are hard for our team to see. Please assume that the maintainers will not see them.

Ongoing conversations amongst community members are welcome, however, the issue will be locked after 30 days. Moving conversations to another venue, such as the AWS Provider forum, is recommended. If you have additional concerns, please open a new issue, referencing this one where needed.

[jar-b]

For those following this issue we'd like to provide some additional context on how to provision patch policies since the final implementation differs a bit from the originally proposed design.

The aws_ssmquicksetup_configuration_manager resource can provision the "Patch Policy" configuration type as follows:

data "aws_caller_identity" "current" {}
data "aws_partition" "current" {}
data "aws_region" "current" {}

data "aws_ssm_patch_baselines" "example" {
  default_baselines = true
}

locals {
  # transform the output of the aws_ssm_patch_baselines data source
  # into the format expected by the SelectedPatchBaselines parameter
  selected_patch_baselines = jsonencode({
    for baseline in data.aws_ssm_patch_baselines.example.baseline_identities : baseline.operating_system => {
      "value" : baseline.baseline_id
      "label" : baseline.baseline_name
      "description" : baseline.baseline_description
      "disabled" : !baseline.default_baseline
    }
  })
}

resource "aws_ssmquicksetup_configuration_manager" "example" {
  name = "example"

  configuration_definition {
    local_deployment_administration_role_arn = "arn:${data.aws_partition.current.partition}:iam::${data.aws_caller_identity.current.account_id}:role/AWS-QuickSetup-PatchPolicy-LocalAdministrationRole"
    local_deployment_execution_role_name     = "AWS-QuickSetup-PatchPolicy-LocalExecutionRole"
    type                                     = "AWSQuickSetupType-PatchPolicy"

    parameters = {
      "ConfigurationOptionsPatchOperation" : "Scan",
      "ConfigurationOptionsScanValue" : "cron(0 1 * * ? *)",
      "ConfigurationOptionsScanNextInterval" : "false",
      "PatchBaselineRegion" : data.aws_region.current.name,
      "PatchBaselineUseDefault" : "default",
      "PatchPolicyName" : "example",
      "SelectedPatchBaselines" : local.selected_patch_baselines,
      "OutputLogEnableS3" : "false",
      "RateControlConcurrency" : "10%",
      "RateControlErrorThreshold" : "2%",
      "IsPolicyAttachAllowed" : "false",
      "TargetAccounts" : data.aws_caller_identity.current.account_id,
      "TargetRegions" : data.aws_region.current.name,
      "TargetType" : "*"
    }
  }
}

The administration and execution roles (AWS-QuickSetup-PatchPolicy-LocalAdministrationRole and AWS-QuickSetup-PatchPolicy-LocalExecutionRole, respectively) may already exist in accounts where patch policies were previously configured via the console (AWS will create these automatically if pre-existing customer managed roles are not selected). Alternatively, customer managed roles can be created with equivalent permissions.

The AWS documentation contains a full description of all the keys which can be provided to the parameters argument and their function. In the example above, the patch policy is provisioned only to the current account and region in which the provider is configured.

Lastly, the aws_ssm_patch_baselines data source provides a way to fetch patch baseline IDs in a given account rather than hardcoding copied values from the console or CLI. The transformation in the locals block converts the data source output into the format expected by the SelectedPatchBaselines parameter. This may need to be adjusted for policies which apply to something other than the default baselines in a given account.

[github-actions]

This functionality has been released in v5.74.0 of the Terraform AWS Provider. Please see the Terraform documentation on provider versioning or reach out if you need any assistance upgrading.

For further feature requests or bug reports with this functionality, please create a new GitHub issue following the template. Thank you!

[pcastro-handover]

@jar-b I tried to use your example but got an error message

AccessDeniedException: Role AWS-QuickSetup-PatchPolicy-LocalAdministrationRole can't be accessed.

and if I remove the setting it throws this other error

The required parameter LocalDeploymentAdministrationRoleArn is missing.

[jar-b]

Hey @pcastro-handover 👋 - If you haven't previously created patch policies via the AWS console, these roles may not yet exist. Here's a relevant snippet from above:

The administration and execution roles (AWS-QuickSetup-PatchPolicy-LocalAdministrationRole and AWS-QuickSetup-PatchPolicy-LocalExecutionRole, respectively) may already exist in accounts where patch policies were previously configured via the console (AWS will create these automatically if pre-existing customer managed roles are not selected). Alternatively, customer managed roles can be created with equivalent permissions.

I have a TODO item to update the registry example with customer managed IAM roles, but have not yet gotten to it. In the meantime you can create a patch policy once in the console to get the roles generated and then re-use them in your Terraform configuration, or create your own roles following the AWS Quick Setup documentation:
https://docs.aws.amazon.com/systems-manager/latest/userguide/quick-setup-patch-manager.html

[pcastro-handover]

thank you very much @jar-b ! yeah, that is what I ended up doing. I was under the impression that the TF module would do it for us as well (triggering the same cloudformation that AWS does behind the scenes).

if there is a place where I can open a PR to add the example to the docs pls let me know. more than happy to help.
cheers

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.