Terraform AWS Session Manager

A Terraform module to setup AWS Systems Manager Session Manager.

This module creates the a SSM document to support encrypted session manager communication and logs. It also creates a KMS key, S3 bucket, and CloudWatch Log group to store logs. In addition, for EC2 instances without a public IP address it can create VPC endpoints to enable private session manager communication. However, the VPC endpoint creation can also be facilitated by other modules such as this. Be aware of the AWS PrivateLink pricing before deployment.

Usage

Update version to the latest release here: https://github.com/bridgecrewio/terraform-aws-session-manager/releases

Instances with Public IPs do not need VPC endpoints

module "ssm" {
  source                    = "bridgecrewio/session-manager/aws"
  version                   = "0.2.0"
  bucket_name               = "my-session-logs"
  access_log_bucket_name    = "my-session-access-logs"
  enable_log_to_s3          = true
  enable_log_to_cloudwatch  = true
  linux_shell_profile       = "date"
}

Private instances with VPC endpoints for S3 and CloudWatch logging

module "ssm" {
  source                    = "bridgecrewio/session-manager/aws"
  version                   = "0.2.0"
  bucket_name               = "my-session-logs"
  access_log_bucket_name    = "my-session-access-logs"
  vpc_id                    = "vpc-0dc9ef19c0c23aeaa"
  tags                      = {
                                Function = "ssm"
                              }
  enable_log_to_s3          = true
  enable_log_to_cloudwatch  = true
  vpc_endpoints_enabled     = true
}

This module does not create any IAM policies for access to session manager. To do that, look at example policies in the AWS Documentation

Requirements

Name	Version
terraform	>=0.14.8
aws	>= 4.6.0

Providers

Name	Version
aws	>= 4.6.0

Modules

No modules.

Resources

Name	Type
aws_cloudwatch_log_group.session_manager_log_group	resource
aws_iam_instance_profile.ssm_profile	resource
aws_iam_policy.ssm_s3_cwl_access	resource
aws_iam_role.ssm_role	resource
aws_iam_role_policy_attachment.SSM-role-policy-attach	resource
aws_iam_role_policy_attachment.SSM-s3-cwl-policy-attach	resource
aws_kms_alias.ssmkey	resource
aws_kms_key.ssmkey	resource
aws_s3_bucket.access_log_bucket	resource
aws_s3_bucket.session_logs_bucket	resource
aws_s3_bucket_acl.access_log_bucket	resource
aws_s3_bucket_acl.session_logs_bucket	resource
aws_s3_bucket_lifecycle_configuration.access_log_bucket	resource
aws_s3_bucket_lifecycle_configuration.session_logs_bucket	resource
aws_s3_bucket_logging.session_logs_bucket	resource
aws_s3_bucket_public_access_block.access_log_bucket	resource
aws_s3_bucket_public_access_block.session_logs_bucket	resource
aws_s3_bucket_server_side_encryption_configuration.access_log_bucket	resource
aws_s3_bucket_server_side_encryption_configuration.session_logs_bucket	resource
aws_s3_bucket_versioning.access_log_bucket	resource
aws_s3_bucket_versioning.session_logs_bucket	resource
aws_security_group.ssm_sg	resource
aws_ssm_document.session_manager_prefs	resource
aws_vpc_endpoint.ec2messages	resource
aws_vpc_endpoint.kms	resource
aws_vpc_endpoint.logs	resource
aws_vpc_endpoint.s3	resource
aws_vpc_endpoint.ssm	resource
aws_vpc_endpoint.ssmmessages	resource
aws_vpc_endpoint_route_table_association.private_s3_route	resource
aws_vpc_endpoint_route_table_association.private_s3_subnet_route	resource
aws_caller_identity.current	data source
aws_iam_policy.AmazonSSMManagedInstanceCore	data source
aws_iam_policy_document.kms_access	data source
aws_iam_policy_document.ssm_s3_cwl_access	data source
aws_partition.current	data source
aws_region.current	data source
aws_route_table.selected	data source
aws_subnet_ids.selected	data source
aws_vpc.selected	data source

Inputs

Name	Description	Type	Default	Required
access_log_bucket_name	Name prefix of S3 bucket to store access logs from session logs bucket	`string`	n/a	yes
access_log_expire_days	Number of days to wait before deleting access logs	`number`	`30`	no
bucket_name	Name prefix of S3 bucket to store session logs	`string`	n/a	yes
cloudwatch_log_group_name	Name of the CloudWatch Log Group for storing SSM Session Logs	`string`	`"/ssm/session-logs"`	no
cloudwatch_logs_retention	Number of days to retain Session Logs in CloudWatch	`number`	`30`	no
enable_log_to_cloudwatch	Enable Session Manager to Log to CloudWatch Logs	`bool`	`true`	no
enable_log_to_s3	Enable Session Manager to Log to S3	`bool`	`true`	no
kms_key_alias	Alias prefix of the KMS key. Must start with alias/ followed by a name	`string`	`"alias/ssm-key"`	no
kms_key_deletion_window	Waiting period for scheduled KMS Key deletion. Can be 7-30 days.	`number`	`7`	no
linux_shell_profile	The ShellProfile to use for linux based machines.	`string`	`""`	no
log_archive_days	Number of days to wait before archiving to Glacier	`number`	`30`	no
log_expire_days	Number of days to wait before deleting	`number`	`365`	no
subnet_ids	Subnet Ids to deploy endpoints into	`set(string)`	`[]`	no
tags	A map of tags to add to all resources	`map(string)`	`{}`	no
vpc_endpoint_private_dns_enabled	Enable private dns for endpoints	`bool`	`true`	no
vpc_endpoints_enabled	Create VPC Endpoints	`bool`	`false`	no
vpc_id	VPC ID to deploy endpoints into	`string`	`null`	no
windows_shell_profile	The ShellProfile to use for windows based machines.	`string`	`""`	no

Outputs

Name	Description
access_log_bucket_name	n/a
cloudwatch_log_group_arn	n/a
iam_profile_name	n/a
iam_role_arn	n/a
kms_key_arn	n/a
session_logs_bucket_name	n/a
ssm_security_group	n/a
vpc_endpoint_ec2messages	n/a
vpc_endpoint_kms	n/a
vpc_endpoint_logs	n/a
vpc_endpoint_s3	n/a
vpc_endpoint_ssm	n/a
vpc_endpoint_ssmmessages	n/a

SSM Usage Example

Launch an instance using the ssm_profile created by Terraform
Install the session-manager-plugin and start a session

cd /tmp
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac/sessionmanager-bundle.zip" -o "sessionmanager-bundle.zip"
unzip sessionmanager-bundle.zip
sudo ./sessionmanager-bundle/install -i /usr/local/sessionmanagerplugin -b /usr/local/bin/session-manager-plugin

# Verify
session-manager-plugin

cd -

# Start an SSM session - Note the instance must have a public IP if you have not created VPC endpoints
aws ssm start-session --target <EC2 Instance ID>

Review session logs in your CloudWatch logs group
Review session logs in your S3 bucket

bridgecrewio / terraform-aws-session-manager