aws_ssm_connection: add support for SSM document

changelogs/fragments/876-aws_ssm_connection_ssm_document.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- aws_ssm_connection - add support for custom SSM document (https://github.com/ansible-collections/community.aws/pull/876)

plugins/connection/aws_ssm.py

@@ -82,6 +82,11 @@
     version_added: 2.2.0
     vars:
     - name: ansible_aws_ssm_bucket_sse_kms_key_id
+  ssm_document:
+    description: SSM document to use when connecting.
+    vars:
+    - name: ansible_aws_ssm_document
+    version_added: 3.1.0
 '''
 
 EXAMPLES = r'''
@@ -188,6 +193,19 @@
       yum:
         name: nginx
         state: present
+
+# Install a Nginx Package on Linux Instance; with dedicated SSM document
+- name: Install a Nginx Package
+  vars:
+    ansible_connection: aws_ssm
+    ansible_aws_ssm_bucket_name: nameofthebucket
+    ansible_aws_ssm_region: us-west-2
+    ansible_aws_ssm_document: nameofthecustomdocument
+  tasks:
+    - name: Install a Nginx Package
+      yum:
+        name: nginx
+        state: present
 '''
 
 import os
@@ -343,7 +361,11 @@ def start_session(self):
         ssm_parameters = dict()
         client = self._get_boto_client('ssm', region_name=region_name, profile_name=profile_name)
         self._client = client
-        response = client.start_session(Target=self.instance_id, Parameters=ssm_parameters)
+        start_session_args = dict(Target=self.instance_id, Parameters=ssm_parameters)
+        document_name = self.get_option('ssm_document')
+        if document_name is not None:
+            start_session_args['DocumentName'] = document_name
+        response = client.start_session(**start_session_args)
         self._session_id = response['SessionId']
 
         cmd = [

tests/integration/targets/connection_aws_ssm/aws_ssm_integration_test_setup/templates/inventory-combined.aws_ssm.j2

@@ -26,6 +26,7 @@ ansible_python_interpreter=/usr/bin/env python
 local_tmp=/tmp/ansible-local-
 ansible_aws_ssm_bucket_sse_mode='aws:kms'
 ansible_aws_ssm_bucket_sse_kms_key_id=alias/{{ resource_prefix }}-kms
+ansible_aws_ssm_document=SSM-SessionManagerRunShell
 
 # support tests that target testhost
 [testhost:children]