Skip to content

bridgecrewio/terraform-aws-session-manager

Repository files navigation

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