AWS Cloud Operations Blog

Automating centralized package management in AWS using AWS Systems Manager Distributor and AWS Systems Manager State Manager

This blog post was jointly contributed by Kanishk Mahajan, AWS and Dominic Medsker, Moody’s

Customers routinely leverage 3rd party agent-based packages and vulnerability management tools, such as CrowdStrike, TrendMicro, and Tenable, to securetheir AWS environments. AWS supports distribution of third-party agents with AWS Systems Manager Distributor (Distributor). Distributor lets you package your own software or finds AWS-provided agent software packages, such as Amazon CloudWatch Agent, to install on AWS Systems Manager managed instances.

A common challenge for customers is to provide the capability of centralizing the publishing and packaging of their custom or 3rd party software to hundreds of nodes spread across multiple regions in multiple AWS accounts. In this blog post we provide an automated solution for a centralized organization wide package management in AWS applicable to custom packages as well as built-in 3rd party and AWS provided packages. Our solution provides automation for both installation and subsequent provisioning of packages to AWS nodes across member accounts and regions in an AWS Organization from a centralized interface.

Solution Overview

In this solution, you can choose any member account in your AWS Organization as a delegated account and run the solution from there using AWS CloudFormation StackSets. This delegated account is the Stackset delegated administrator account which is the centralized account to manage the installation and provisioning of your packages.

When you run the solution from this centralized account, it makes your custom package available throughout the organization under the Owned by me  tab of Systems Manager Distributor of each member account. Once your package has been installed in the member account, the solution then provisions it into targets (i.e. AWS nodes managed by Systems Manager) within member accounts in an organization as an association using AWS Systems Manager State Manager. You can then provision the custom package into AWS nodes in each member account and this is  determined automatically by the schedule and tags provided in your State Manager association document

You can download the CloudFormation template that implements this solution from here. The following diagram provides the architecture of our solution.

Architecture diagram describing automation of centralized package management in AWS using Systems Manager Distributor, Systems Manager State Manager and CloudFormation Stacksets

Figure 1: Solution architecture for automation of centralized package management in AWS using Distributor, State Manager and CloudFormation Stacksets

Prerequisites

You must first complete the following prerequisites:

  1. Complete these steps to register a member account as a stackset delegated administrator account.  AWS member accounts with delegated administrator permissions can create and manage stack sets with service-managed permissions for the organization.
  2. In your delegated AWS account, follow these instructions to create a package for your 3rd party software and upload it to Amazon S3.
    1. In this blog post we use an Amazon S3 bucket named s3-examplepackage-[accountid]-[region]. We demonstrate the solution using the Example Package from the step wise instructions that has been uploaded to our S3 bucket in the example package folder. The example package includes a completed JSON manifest and three .zip files. The following diagram illustrates our custom package uploaded to S3:
Figure illustrating our S3 bucket with uploaded custom package (ExamplePackage) that includes completed JSON manifest and three .zip files

Figure 2. S3 bucket with uploaded custom package (ExamplePackage) that includes completed JSON manifest and three .zip files

Setup

Navigate to the AWS CloudFormation console and follow the instructions here to launch a stackset with service managed permissions using the aws-centralizedssmdistributor-v1 CloudFormation template.

  1.  aws-centralizedssmdistributor-v1 template makes your custom package available as a Systems Manager Automation document under the ‘Owned by me’ tab in the Distributor console in each member account in your AWS Organization. It then provisions a State Manager association in each member account and installs the package in that account as per the schedule and tags specified in the association
  2. The template takes the following parameters.
    1.  PackageName: Name for your package
    2. S3PackageBucket: Name of the S3 Bucket where the package contents are uploaded (for e.g.  s3-examplepackage-[accountid]-[region])
    3. S3PackageBucketFolder: Name of the S3 Bucket Folder where the manifest is uploaded (for e.g. examplepackage)
    4. S3PackageUrl: Https URL of the bucket including prefix where the package contents are uploaded (for e.g. https://s3-examplepackage-[accountid]-[region].s3 [region]. amazonaws.com/examplepackage)
    5. Version: Provide the exact version name from the manifest file (for e.g. 1.0.2)
    6. AssociationName: Name for your association
    7. Action: Specify whether to install or uninstall the package. (for e.g. Install or Uninstall)
    8. InstallationType: Specify the type of installation (for e.g. In-place update)
    9. OutputS3Prefix: The S3 Key Prefix used for AWS Systems Manager Run Command Output (Default ‘’)
    10. ScheduleExpression: The Schedule Expression for the AWS Systems Manager Association. (for e.g. “rate(30 minutes)”)
    11. TargetResourceTagKey: The AWS Systems Manager Tag Key for the target (provide a value here if you like the package to be installed only on those target nodes that have this tag key)
    12. TargetResourceTagValue: The AWS Systems Manager Tag Value for the target (provide a value here if you like the package to be installed only on those target nodes that have this tag value)

Accept the defaults in the template if you are not sure of any of these parameters.

Validate

  1. Navigate to the AWS Systems Manager console of any member account in your AWS Organization and select Distributor from the left panel. Select the Owned by me tab and validate that your examplepackage is available there.  Select the examplepackage and validate the Version from the Details section.
    1. Validate that the Attachments information in the Additional Information section contains the zip files and hash exactly as in the manifest file for your custom package (examplepackage). Here’s our custom package (examplepackage) that is now available in Distributor in one of our member accounts:
Figure illustrating how our custom package is made available in Distributor under the Owned by me tab in each member account

Figure 3. Figure illustrating how our custom package is made available in Distributor under the Owned by me tab in each member account

  1. From the  Systems Manager console of any member account in your AWS Organization, selectelect State Manager from the left panel. Select the association with the SimplePackage-PackageDistributor association name (this is the default association name we provided as a parameter in our cloudformation template).
    1. Validate the Schedule expression from the Description tab.
    2. Select Execution history and click on any execution to validate that the association ran the custom package as per the schedule expression using the AWS-ConfigureAWSPackage automation document.
    3. Here’s our State Manager association that is now provisioned in each member account along with its execution history to configure our custom package:
Figure illustrating that the State Manager association that installs the custom package is provisioned in each member account

Figure 4. Figure illustrating that the State Manager association that installs the custom package is provisioned in each each member account

Figure illustrating execution history of our state manager association that installs our custom package using the AWS-ConfigureAWSPackage automation document

Figure 5: Figure illustrating execution history of our state manager association that installs our custom package using the AWS-ConfigureAWSPackage automation document

Cleanup

To avoid recurring charges, and to clean up your account after trying the solution outlined in this post, perform the following by navigating to the AWS CloudFormation console in your delegated stackset administrator account. Select Stacksets from the left panel and select the stackset created by the aws-centralizedssmdistributor-v1 CloudFormation template.

  1. Follow instructions here to delete stack instances created by the stackset from your member accounts
  2. Delete the stackset
  3. Delete the s3-examplepackage-[accountid]-[region] Amazon S3 bucket that was created for this solution.

Conclusion

Customers routinely leverage 3rd party agent-based packages to secure their AWS environments.  While AWS supports distribution of third-party agents with AWS Systems Manager Distributor (Distributor), a common problem for customers is to provide a centralized mechanism for both installing and provisioning their custom or 3rd party software to hundreds of nodes spread across multiple regions in multiple AWS accounts. In this blog post we provided an automated solution for a centralized organization wide package management in AWS applicable to custom packages as well as built-in 3rd party and AWS provided packages.

About the authors:

Kanishk Mahajan

Kanishk Mahajan is a Principal, Cross Service Solutions Architect at AWS. He leads cloud transformation and solution architecture for partners and customers at AWS. Kanishk specializes in cloud operations, migrations and modernizations, resilience and security and compliance. He is a Technical Field Community (TFC) member in each of those domains at AWS.

Dominic Medsker

Dominic Medsker is a Senior Cloud Engineer at Moody’s. Dominic is focused on self-service, business enablement, high value delivery and fastest time to market as it relates to use of cloud services. He is passionate about simplifying technical concepts to make them more accessible.