Install Agent on AWS EC2 Instances Using Terraform and AWS Systems Manager

This article covers using Terraform to configure AWS Systems Manager to deploy the Lacework Agent to supported EC2 instances.

Lacework maintains the terraform-aws-ssm-agent module, which creates an SSM document for managing the deployment of the Lacework agent to EC2 instances.

If you are new to the Lacework Terraform Provider, or Lacework Terraform Modules, read the Terraform for Lacework Overview article to learn the basics on how to configure the provider, and more.

Overview of Using AWS Systems Manager with Lacework

AWS Systems Manager (formerly known as SSM) is an AWS service that you can use to view and control your infrastructure on AWS. Using the Systems Manager console, you can view operational data from multiple AWS services and automate operational tasks across your AWS resources. Systems Manager helps you maintain security and compliance by scanning your managed instances and reporting on (or taking corrective action on) any policy violations it detects.

For Lacework customers using AWS Systems Manager to manage EC2 instances in their AWS account, the terraform-aws-ssm-agent Terraform Module can be used to create an SM document to install the Lacework agent on EC2 instances.

This installation method creates a agent token, and then installs the latest stable (GA) version of the Lacework Datacollector agent.

Scenario 1: Configuring AWS Systems Manager for Lacework Agent Deployments in a Single Region

The following code example creates a Lacework agent access token, then creates an SSM document to install the Lacework agent on EC2 instances. Additionally, an AWS resource group is created with EC2 instances that have the machine tag environment:testing, and then the SSM document is associated with that AWS Resource group. Once Terraform executes, AWS Systems Manager will be configured and the Lacework Datacollector agent will be installed automatically.

Considerations and items to update:

• Ensure you update the TagFilters stanza to match the applicable tags deployed in your environment. Alternatively, remove it.
• Validate that you have properly configured SSM and the appropriate permissions are in place. This requires that the instance profile has the AmazonSSMManagedInstanceCore policy attached to the instances you want to deploy to. Additional information on the policy can be referenced at Add permissions to a Systems Manager instance profile.

The following example assumes you already have AWS Systems Manager configured on your instances. If you are new to AWS SSM and want to test this install method, read the AWS Systems Manager Quick Setup documentation.

terraform {
  required_providers {
    lacework = {
      source = "lacework/lacework"
      version = "~> 1.0"
    }
  }
}
provider "aws" {
  region = "us-east-1"
}

provider "lacework" {}

# Create an agent access token in Lacework
resource "lacework_agent_access_token" "ssm_deployment" {
  name        = "ssm-deployment"
  description = "Used to deploy agents using AWS System Manager"
}

# Create AWS SSM Document
module "lacework_aws_ssm_agents_install" {
  source = "lacework/ssm-agent/aws"
  version = "~> 0.8"

  lacework_agent_tags = {
    env = "testing"
  }

  aws_resources_tags = {
    billing = "testing"
    owner   = "myself"
  }

  lacework_access_token = lacework_agent_access_token.ssm_deployment.token
}

# Create an AWS Resource group for EC2 Instances with
# the tag 'environment:testing'
resource "aws_resourcegroups_group" "testing" {
  name = "testing"

  resource_query {
    query = jsonencode({
      ResourceTypeFilters = [
        "AWS::EC2::Instance"
      ]

      TagFilters = [
        {
          Key = "environment"
          Values = [
            "testing"
          ]
        }
      ]
    })
  }

  tags = {
    billing = "testing"
    owner   = "myself"
  }
}

# Create an SSM Association group called install-lacework-agents-testing-group
resource "aws_ssm_association" "lacework_aws_ssm_agents_install_testing" {
  association_name = "install-lacework-agents-testing-group"

  name = module.lacework_aws_ssm_agents_install.ssm_document_name

  targets {
    key = "resource-groups:Name"
    values = [
      aws_resourcegroups_group.testing.name,
    ]
  }

  compliance_severity = "HIGH"
}

Scenario 2: Configuring AWS Systems Manager for Lacework Agent Deployments in Multiple Regions

The following code example creates a Lacework agent access token, then creates an SSM document to install the Lacework agent on EC2 instances. Additionally, an AWS resource group is created with EC2 instances that have the machine tag environment:testing, and then the SSM document is associated with that AWS Resource group. Once Terraform executes, AWS Systems Manager will be configured and the Lacework Datacollector agent will be installed automatically.

Additionally, we configure multiple AWS provider blocks, one for each region we want to target within the AWS account. We then create the SSM document twice, one for each region by associating the modules and resources with different providers.

For the modules:

providers = {
    aws = aws.america
}

For the resources:

provider = aws.america

Considerations and items to update:

• Ensure you update the TagFilters stanza to match the applicable tags deployed in your environment. Alternatively, remove it.
• Ensure you configure the necessary AWS provider blocks for each region you want to target.
• Ensure you update the provider aliases for each module and resource to associate them with the correct provider.
• Validate that you have properly configured SSM in all the regions you are targeting and the appropriate permissions are in place. This requires that the instance profile has the AmazonSSMManagedInstanceCore policy attached to the instances you want to deploy to. Additional information on the policy can be referenced at Add permissions to a Systems Manager instance profile.

The following example assumes you already have AWS Systems Manager configured on your instances. If you are new to AWS SSM and want to test this install method, read the AWS Systems Manager Quick Setup documentation.

terraform {
  required_providers {
    lacework = {
      source = "lacework/lacework"
      version = "~> 1.0"
    }
  }
}
provider "aws" {
  alias = "america"
  region = "us-east-1"
}

provider "aws" {
  alias = "europe"
  region = "eu-west-1"
}

provider "lacework" {}

# Create an agent access token in Lacework
resource "lacework_agent_access_token" "ssm_deployment" {
  name        = "ssm-deployment"
  description = "Used to deploy agents using AWS System Manager"
}

# Create AWS SSM document for the us-east-1 region
module "lacework_aws_ssm_agents_install_america" {
  source = "lacework/ssm-agent/aws"
  version = "~> 0.8"

  lacework_agent_tags = {
    env = "testing"
  }

  aws_resources_tags = {
    billing = "testing"
    owner   = "myself"
  }

  lacework_access_token = lacework_agent_access_token.ssm_deployment.token

  providers = {
    aws = aws.america
  }
}

# Create an AWS resource group for EC2 instances in the us-east-1 region with
# the tag 'environment:testing'
resource "aws_resourcegroups_group" "testing_america" {
  name = "testing_america"

  resource_query {
    query = jsonencode({
      ResourceTypeFilters = [
        "AWS::EC2::Instance"
      ]

      TagFilters = [
        {
          Key = "environment"
          Values = [
            "testing"
          ]
        }
      ]
    })
  }

  tags = {
    billing = "testing"
    owner   = "myself"
  }

  provider = aws.america
}

# Create an SSM association group called install-lacework-agents-testing-group
# for the us-east-1 region 
resource "aws_ssm_association" "lacework_aws_ssm_agents_install_testing_america" {
  association_name = "install-lacework-agents-testing-group"

  name = module.lacework_aws_ssm_agents_install.ssm_document_name

  targets {
    key = "resource-groups:Name"
    values = [
      aws_resourcegroups_group.testing.name,
    ]
  }

  compliance_severity = "HIGH"

  provider = aws.america
}

# Create AWS SSM document for the eu-west-1 region
module "lacework_aws_ssm_agents_install_europe" {
  source = "lacework/ssm-agent/aws"
  version = "~> 0.8"

  lacework_agent_tags = {
    env = "testing"
  }

  aws_resources_tags = {
    billing = "testing"
    owner   = "myself"
  }

  lacework_access_token = lacework_agent_access_token.ssm_deployment.token

  providers = {
    aws = aws.europe
  }
}

# Create an AWS resource group for EC2 instances in the eu-west-1 region with
# the tag 'environment:testing'
resource "aws_resourcegroups_group" "testing_europe" {
  name = "testing_europe"

  resource_query {
    query = jsonencode({
      ResourceTypeFilters = [
        "AWS::EC2::Instance"
      ]

      TagFilters = [
        {
          Key = "environment"
          Values = [
            "testing"
          ]
        }
      ]
    })
  }

  tags = {
    billing = "testing"
    owner   = "myself"
  }

  provider = aws.europe
}

# Create an SSM association group called install-lacework-agents-testing-group 
# for the eu-west-1 region
resource "aws_ssm_association" "lacework_aws_ssm_agents_install_testing_europe" {
  association_name = "install-lacework-agents-testing-group"

  name = module.lacework_aws_ssm_agents_install.ssm_document_name

  targets {
    key = "resource-groups:Name"
    values = [
      aws_resourcegroups_group.testing.name,
    ]
  }

  compliance_severity = "HIGH"

  provider = aws.europe
}

Run Terraform

This example shows 3 existing EC2 instances with the machine tag environment:testing

1. Copy and paste the code snippet above into a main.tf file and then save the file.
2. Run terraform plan and review the changes. Four resources should be created.
3. After you have reviewed the changes, run terraform apply -auto-approve to execute Terraform.

Validate Changes

After Terraform executes, open AWS Resource Groups in the region you applied the changes. You should see a new resource group called testing with the instances that have the tag environment:testing.

Open the AWS Systems Manager. Under Node Management, click State Manager, click Association id for the install-lacework-agents-testing-group, and click the Resources tab, where you should see the status of action taken on the instances.

After you install the agent, it takes 10 to 15 minutes for agent data to appear in the Lacework Console under Resources > Agents.