Deploy AWS Systems Manager Quick Setup programmatically across your AWS Organization

AWS Systems Manager Quick Setup simplifies setting up AWS services, including Systems Manager, by automating common or recommended tasks in your AWS Organization across AWS accounts and Regions. These tasks include, creating required AWS Identity and Access Management (IAM) instance profile roles and setting up operational best practices, such as periodic patch scans and inventory collection.

We are excited to announce the release of the Systems Manager Quick Setup API which enables you to deploy Quick Setup configurations programmatically using AWS CloudFormation, the AWS Command Line Interface (AWS CLI), or your preferred SDK. You no longer are required to deploy Quick Setup configurations using the AWS Management Console and can now include Quick Setup configuration deployments in infrastructure deployment scripts. By using the Quick Setup API, you can incorporate Quick Setup configurations into your existing infrastructure-as-code and speed up deployments.

You can use Quick Setup in an individual AWS account or across multiple AWS accounts and Regions by integrating with AWS Organizations. Using Quick Setup across multiple accounts helps to ensure that your organization maintains consistent configurations. When new AWS accounts are added to the AWS Organization and to a targeted Organization Unit (OU), Quick Setup will automatically deploy the configuration into the account and Regions specified. Additionally, Quick Setup periodically checks for configuration drift in the deployment and attempts to remediate it to ensure the desired state is maintained.

Thus, you can easily deploy, track, manage, and update your Quick Setup configurations as code. To get started, you create a configuration manager for the Quick Setup configuration type of interest which in turn deploys the configuration definition. Configuration definitions contain all of the necessary information to deploy a particular configuration type.

Prerequisites

In order to deploy Quick Setup configurations across your AWS Organization, you must complete Quick Setup onboarding. For more information, see Getting started with Quick Setup.

For the Default Host Management Configuration (DHMC) Quick Setup configuration, you must first identify the AWS Organizations root unit ID, for example r-1abc. You can find this value by navigating to the AWS Organization console. You will need to pass this value when deploying the DHMC Quick Setup configuration later on.

Install and configure the AWS Command Line Interface (AWS CLI), if you haven’t already. For information, see Installing or updating the latest version of the AWS CLI.

Walkthrough

In this post, we will walkthrough deploying three Quick Setup configurations using the AWS CLI. If you prefer to deploy resources using CloudFormation, you can find sample CloudFormation templates on GitHub: DHMC sample template, Host Management sample template, Patch Policy sample template.

By deploying these three configurations, our AWS Organization will be enabled to register EC2 instances with Systems Manager by default, enable Inventory metadata gathering, and perform patch scan and install operations during scheduled periods. Below are the three Quick Setup configurations we will deploy:

• Default Host Management Configuration – Activates Default Host Management Configuration (DHMC) for all accounts and Regions that have been added to your organization in AWS Organizations. This ensures that SSM Agent is kept up to date on all Amazon Elastic Compute Cloud (EC2) instances in the organization, and that they can connect to Systems Manager.
• Host Management best practices – Enables Inventory metadata collection. Optionally, you can also choose to enable installing, configuring, and updating the Amazon CloudWatch agent using Host Management.
• Patch Manager organization patching configuration – Enables scheduled patch scan and install operations during defined periods and enforces centralized patch criteria to be used during patching operations.

To create a consistent configuration, Quick Setup uses AWS CloudFormation StackSets to deploy Quick Setup configurations across your organization. Quick Setup also enables automatic deployment so that StackSets automatically deploys to accounts that are added to the target organization or organizational units (OUs) in the future.

Here is how the process works when using Quick Setup:

1. You create a configuration manager using the CreateConfigurationManager Quick Setup API and the parameters specified are sent to CloudFormation.
2. CloudFormation creates a stack set with the defined parameters and defined target accounts and Regions.
3. CloudFormation creates stack instances in each target account and Region.
4. The stack instances create resources specific to the Quick Setup configuration. In this post, CloudFormation creates several State Manager associations to update SSM agent, gather software inventory, run patch scans and install operations, and update the Systems Manager service setting for default host management configuration.

Deploy Default Host Management configuration

In this post, we will make use of the --cli-input-yaml functionality of the AWS CLI. For more information, see AWS CLI skeletons and input files.

First, we will review the names of all supported Quick Setup configuration types using the list-quick-setup-types CLI command.

aws ssm-quicksetup list-quick-setup-types \
    --region us-east-1

To retrieve details for the Default Host Management Quick Setup configuration specifically, we can use the following CLI command:

aws ssm-quicksetup list-quick-setup-types \
    --region us-east-1 \
    --query 'QuickSetupTypeList[?Type==`AWSQuickSetupType-DHMC`]'
[
    {
        "Type": "AWSQuickSetupType-DHMC",
        "LatestVersion": "1.0"
    }
]

Additionally, for this Quick Setup configuration, there is only one parameter we need to define: UpdateSSMAgent. This determines if you want to enable automatic updates for the AWS Systems Manager agent (SSM agent) every two weeks. For our deployment, we will enable this option.

Using these two values, we can create our configuration definition and store these parameters in a local YAML file, named dhmc-cli-input.yaml, to be used during deployment. Note: Replace the TargetOrganizationalUnits value with your AWS Organization root unit ID retrieved earlier in the Prerequisites section.

---
Name: qs-dhmc
Description: Enable Default Host Management configuration for the AWS Organization
ConfigurationDefinitions:
- Type: AWSQuickSetupType-DHMC
  Parameters:
    UpdateSSMAgent: 'true'
    TargetOrganizationalUnits: r-1abc
    TargetRegions: eu-north-1, ap-south-1, eu-west-3, us-east-2, eu-west-1, eu-central-1,
      sa-east-1, us-east-1, ap-northeast-2, eu-west-2, ap-northeast-1, us-west-2,
      us-west-1, ap-southeast-1, ap-southeast-2, ca-central-1

Using the local YAML file, run the following command to deploy the Default Host Management configuration and enable automatic updates for SSM agent:

aws ssm-quicksetup create-configuration-manager \
    --cli-input-yaml file://dhmc-cli-input.yaml

You can check the configuration status of the deployment using the list-configuration-managers CLI command.

aws ssm-quicksetup list-configuration-managers \
    --region us-east-1

In the resulting output, note the Status listed in the StatusSummaries property. When the deployment status code changes to SUCCEEDED, continue with the next steps to deploy additional Quick Setup configurations.

Deploy host management best practices to gather Inventory metadata

Similar to the previous section, we will retrieve the name of the Quick Setup configuration using the list-quick-setup-types CLI command.

aws ssm-quicksetup list-quick-setup-types \
    --region us-east-1 \
    --query 'QuickSetupTypeList[?Type==`AWSQuickSetupType-SSMHostMgmt`]'
[
    {
        "Type": "AWSQuickSetupType-SSMHostMgmt",
        "LatestVersion": "4.0"
    }
]

In the results returned, note the name, AWSQuickSetupType-SSMHostMgmt, and the latest version (4.0 at the time of writing) for the Host Management configuration.

For this Quick Setup configuration, there are several parameters available for which you can customize the deployment. In this post, we will define that we want to collect inventory metadata and to target all managed instances. We will disable updating SSM agent, as we enabled this option in our Default Host Management configuration, and we will disable scanning managed nodes for patches, as this will be enabled in the next section.

Additionally, for this Quick Setup configuration, you can define which Organization Units (OUs) IDs you want to target and which Regions to deploy into. For the purpose of this walk through, we will deploy to one OU and two Regions so we will store our configuration definition in a local YAML file to be used during deployment:

---
Name: qs-host-management
Description: Enable Host Management for the AWS Organization
ConfigurationDefinitions:
- Type: AWSQuickSetupType-SSMHostMgmt
  Parameters:
    CollectInventory: 'true'
    ScanInstances: 'false'
    UpdateSsmAgent: 'false'
    TargetType: "*"
    TargetOrganizationalUnits: ou-ab12-cdefgh34
    TargetRegions: us-east-1,us-east-2

Run the following command to deploy the Host Management configuration:

aws ssm-quicksetup create-configuration-manager \
    --cli-input-yaml file://host-mgmt-cli-input.yaml

You can check the configuration status of the deployment using the list-configuration-managers CLI command.

aws ssm-quicksetup list-configuration-managers \
    --region us-east-1 \
    --query 'ConfigurationManagersList[?Name==`qs-host-management`].[Name, StatusSummaries]'

In the resulting output, note the Status listed in the StatusSummaries property. When the deployment status code changes to SUCCEEDED, continue with the next steps to deploy additional Quick Setup configurations.

Deploy patch scan and install operations for the AWS Organization

For this final section, we will deploy routine patch scan and install operations using Quick Setup. First, we will retrieve the name of the Quick Setup configuration using the list-quick-setup-types CLI command.

aws ssm-quicksetup list-quick-setup-types \
    --region us-east-1 \
    --query 'QuickSetupTypeList[?Type==`AWSQuickSetupType-PatchPolicy`]'
[
    {
        "Type": "AWSQuickSetupType-PatchPolicy",
        "LatestVersion": "2.0"
    }
]

In the results returned, note the name, AWSQuickSetupType-PatchPolicy, and the latest version (2.0 at the time of writing) for the Patch Policy configuration.

For this Quick Setup configuration, there are several parameters available for which you can customize the deployment. You can modify the parameter values as required for your environment, as an example, we will define that we want to:

1. Scan for missing patches daily at 01:00 UTC.
2. Installing missing patches on the first Saturday of the month at 02:00 UTC.
3. Reboot if needed during the patch installation. For more information about reboot behavior, see Parameter name: RebootOption.
4. Perform patch operations with a concurrency of 5% and an error threshold of 0%. For more information, see About targets and rate controls in State Manager associations.
5. Target managed nodes with the tag key-value pair: Patch:true.
6. Use custom patch baselines for Amazon Linux 2, Ubuntu, and Windows managed nodes.
7. Allow Quick Setup to attach required IAM policies to existing EC2 instance profiles.

Note: In addition to the above configuration, with Patch Policies, you can optionally specify a S3 bucket used to store command output logs. You can also choose to target instances using Resource Groups or instance IDs instead of tags.

To retrieve the list of patch baselines required for the parameter in item 6 above, you can run the following AWS CLI command. This will return the patch baselines marked as default in the account and Region.

aws ssm describe-patch-baselines |jq '.BaselineIdentities | map({ (.OperatingSystem): (.value = .BaselineId | .label = .BaselineName | .description = .BaselineDescription | .disabled=false | del(.BaselineId, .BaselineName, .OperatingSystem, .BaselineDescription, .DefaultBaseline)) }) | add'

You can take the resulting output of the CLI command above and include it within your configuration definition for the parameter SelectedPatchBaselines. To see the sample output of the above command, open the following link on GitHub:

https://github.com/aws-samples/aws-management-and-governance-samples/blob/master/AWSSystemsManager/Quick-Setup-API/patch-policy-examples/default-patch-baselines.txt

For this Quick Setup configuration, you can define which Organization Units (OUs) IDs you want to target and which Regions to deploy into. For the purpose of this walk through, we will deploy to one OU and two Regions so we will store our configuration definition in a local YAML file to be used during deployment.

To see the local YAML file configuration definition, open the following link to see an example on GitHub:

https://github.com/aws-samples/aws-management-and-governance-samples/blob/master/AWSSystemsManager/Quick-Setup-API/patch-policy-examples/patch-policy-cli-input.yaml

Run the following command to deploy the Patch Policy configuration:

aws ssm-quicksetup create-configuration-manager \
    --cli-input-yaml file://patch-policy-cli-input.yaml

You can check the configuration status of the deployment using the list-configuration-managers CLI command.

aws ssm-quicksetup list-configuration-managers \
    --region us-east-1 \
    --query 'ConfigurationManagersList[?Name==`qs-patch-policy`].[Name, StatusSummaries]'

In the resulting output, note the Status listed in the StatusSummaries property. When the deployment status code changes to SUCCEEDED, continue with the next steps to review the Quick Setup configurations deployed in this walk through.

Review Quick Setup configurations

In the AWS Management Console, you can now see the three configuration managers we created using the AWS CLI. Here, you can see the configuration type, the organizational units (OUs) and Regions targeted for deployment, the status of the deployment, and the status of the State Manager associations.

Figure 1: Reviewing the Quick Setup console to see configuration managers deployed using the AWS CLI.

Review deployment in a target member account

You can review the resources deployed by Quick Setup by logging into one of the member accounts and Regions you targeted previously when deploying the Quick Setup configuration managers. First, navigate to the CloudFormation console in a targeted Region and review the stacks deployed. Quick Setup deployed stacks are prefixed with StackSet-AWS-QuickSetup-*. For example, here is a screenshot of the resources for the DHMC Quick Setup configuration previously deployed.

Figure 2: Reviewing the resources created by CloudFormation for the DHMC Quick Setup configuration.

Next, navigate to the Systems Manager console and select State Manager in the navigation pane. In the list of associations, Quick Setup created associations are prefixed with AWS-QuickSetup-*. For example, in figure 3, you can see the association created by the DHMC Quick Setup Configuration to update SSM agent. In the screenshot, you can see the action is to run the document AWS-UpdateSSMAgent once every 14 days and the association is named AWS-QuickSetup-DHMC-UpdateSSMAgent-${GUID}.

Figure 3: Reviewing the State Manager association to update SSM agent created by Quick Setup.

You can select the Targets tab to view the managed instances targeted by this association, select the Resources tab to view managed instances which have applied the association, or the Execution history tab to see previous runs of the association.

Optionally, review the other associations created by the three Quick Setup configurations to see the actions performed against the targeted managed instances.

By using Quick Setup to deploy the three configurations for DHMC, Host Management, and Patch Policies, we have configured the targeted AWS accounts and Regions for several best practices and enabled automated actions to update SSM agent, gather Inventory metadata, performing patch scans and installs and more.

Clean-up

To delete the Quick Setup configurations created in this post, first use the command list-configuration-managers to retrieve the ManagerArn for the Quick Setup configuration. After, use the command delete-configuration-manager to remove the configuration. For example:

aws ssm-quicksetup list-configuration-managers
{
    "ConfigurationManagersList": [
        {
            "ManagerArn": "arn:aws:ssm-quicksetup:us-east-1:012345678912:configuration-manager/4c52f90f-6bda-4fd7-8301-97e1e7bccfba",
            ...
}

aws ssm-quicksetup delete-configuration-manager \
    --manager-arn arn:aws:ssm-quicksetup:us-east-1:012345678912:configuration-manager/4c52f90f-6bda-4fd7-8301-97e1e7bccfba

Optionally, repeat this process three times in total to remove the Quick Setup configurations for Default Host Management Configuration, Host Management, and Patch Policy.

Conclusion

In this post, we showed you how you can quickly deploy Quick Setup configurations across AWS accounts and Regions using the AWS CLI. By using the AWS CLI, or your preferred AWS SDK, to deploy Quick Setup configurations, you can programmatically deploy AWS services and features with recommended best practices. You can also use AWS CloudFormation to create a configuration manager resource that deploys configurations.

We recommend that you review other supported Quick Setup configurations to learn more about other AWS services and features you can deploy.

About the authors: