terraform-aws-ssm

Purpose

This module manages AWS SSM Session Manager default preferences, allowing you to centrally configure session logging, encryption, and shell profiles. It is designed to:

• Set organization-wide defaults for Session Manager sessions (logging, encryption, shell profiles)
• Enable the use of the runAs feature, so sessions can start as a specific user (e.g., ec2-user) instead of the default ssm-user
• Help avoid the security risk of ssm-user always having sudo privileges
• Support secure, non-root/non-sudo access for SSM sessions

Avoiding Root/Sudo Access with SSM Session Manager

To prevent all SSM sessions from using root/sudo by default:

1. Create a non-root user (e.g., ssm-basic) and an admin user (e.g., ssm-admin) on your EC2 instances.
2. Tag IAM roles/users needing admin/root access with SSMSessionRunAs = ssm-admin.
3. Enable SSM RunAs and set the default session user to your non-root user in Session Manager preferences.

This ensures most users get non-root access, while only tagged admins can use sudo/root.

Importing an Existing SSM Document

If you have already created the SSM document in the AWS Console or elsewhere, you can import it into Terraform state before running terraform apply:

terraform import aws_ssm_document.session_manager_prefs SSM-SessionManagerRunShell

This will allow Terraform to manage the existing document without recreating it.

Example Usage

See examples/complete/main.tf for a full example of how to use this module.

Requirements

No requirements.

Providers

Name	Version
aws	n/a

Modules

No modules.

Resources

Name	Type
aws_ssm_document.session_manager_prefs	resource

Inputs

Name	Description	Type	Default	Required
cloudwatch_encryption_enabled	Encrypt log data.	bool	true	no
cloudwatch_log_group_name	The name of the log group to upload session logs to. Specifying this enables sending session output to CloudWatch Logs.	string	""	no
cloudwatch_streaming_enabled	Stream session log data to CloudWatch. Defaults to true. If false logs will be uploaded at the end of the session.	bool	true	no
idle_session_timeout	Time until a session is closed when left idle.	number	20	no
kms_key_id	The KMS key used to to encrypt SSM sessions.	string	null	no
linux_shell_profile	A set of Linux commands to run when a Linux session is started.	string	""	no
max_session_duration	The longest a session can stay open before it will be closed.	number	null	no
run_as_default_user	The name of the user account to start sessions with on Linux managed nodes when the runAsEnabled input is set to true. The user account you specify for this input must exist on the managed nodes you will be connecting to; otherwise, sessions will fail to start.	string	""	no
run_as_enabled	Enables the option to start sessions using the credentials of a specified operating system user.	bool	false	no
s3_bucket_name	The name of bucket to store session logs. Specifying this enables writing session output to an Amazon S3 bucket.	string	""	no
s3_encryption_enabled	Encrypt log data.	bool	true	no
s3_key_prefix	To write output to a sub-folder, enter a sub-folder name.	string	""	no
ssm_document_name	The name for SSM Document	string	"SSM-SessionManagerRunShell"	no
windows_shell_profile	A set of Windows commands to run when a Windows session is started.	string	""	no

Outputs

Name	Description
document_arn	ARN of the created document. You can use this to create IAM policies that prevent changes to Session Manager preferences.
document_type	The type of the document
name	Name of the created document.