4.1. Access Systems Manager From The Console.
From the AWS console, select ‘Systems Manager’.
When you get to the front page of the service, use the left hand panel and go down to the bottom of the menu to select Documents from the Shared Resources as follows:
.
4.2. Create Automation Document
In this section we will go through steps to create the automation document, explaining the automation document configuration detail interactively as we walk through. To ensure that you get the formatting correct when you insert the automation document we have provided a full copy for you to download here.
4.2.1.
Firstly access Systems Manager from the AWS Console.
4.2.2.
When you get to the front page of the service, use the left hand panel and go down to the bottom of the menu to select Documents from the Shared Resources as follows:
.
4.2.3.
From the main page, select the Create Automation button to build an automation document.
4.2.4.
Enter the name of the automation document and select the Editor option to enter a the document directly into the console.
4.2.5.
Next we need to add the document specification below into the editor. Add the document which you downloaded at the start of section 4.2.. The following steps will explain the document configuration in stages.
4.2.6.
Firstly, we need to specify the schemaVersion and parameters which our document will take as an Input.
In this case we will take the ImageBuilderPipeline ARN as well as the name of the Application Stack (default: pattern3-app)
description: CreateImage
schemaVersion: '0.3'
parameters:
ImageBuilderPipelineARN:
description: (Required) Corresponding EC2 Image Builder Pipeline to execute.
type: String
ApplicationStack:
description: (Required) Corresponding Application Stack to Deploy the Image to.
type: String
4.2.7.
Next we will specify the first step which is to execute image builder pipeline we created in previous section. Passing the parameter inputs we specified before. This execution is achieved by calling the AWS service API directly leveraging aws:executeAwsApi action type in SSM Automation Document.
mainSteps:
- name: ExecuteImageCreation
action: aws:executeAwsApi
maxAttempts: 10
timeoutSeconds: 3600
onFailure: Abort
inputs:
Service: imagebuilder
Api: StartImagePipelineExecution
imagePipelineArn: '{{ ImageBuilderPipelineARN }}'
outputs:
- Name: imageBuildVersionArn
Selector: $.imageBuildVersionArn
Type: String
4.2.8.
In the next we will specify aws:waitForAwsResourceProperty action wait for the Image to complete building.
- name: WaitImageComplete
action: aws:waitForAwsResourceProperty
maxAttempts: 10
timeoutSeconds: 3600
onFailure: Abort
inputs:
Service: imagebuilder
Api: GetImage
imageBuildVersionArn: '{{ ExecuteImageCreation.imageBuildVersionArn }}'
PropertySelector: image.state.status
DesiredValues:
- AVAILABLE
4.2.9.
Once the wait is complete, and the Image is ready, we will then call another aws:executeAwsApi to capture the AMI Id and pass the value into the next step.
- name: GetBuiltImage
action: aws:executeAwsApi
maxAttempts: 10
timeoutSeconds: 3600
onFailure: Abort
inputs:
Service: imagebuilder
Api: GetImage
imageBuildVersionArn: '{{ ExecuteImageCreation.imageBuildVersionArn }}'
outputs:
- Name: image
Selector: $.image.outputResources.amis[0].image
Type: String
4.2.10.
With the AMI id we received in previous step, we will then pass the id to our Application CloudFormation Stack and trigger an update using aws:executeAwsApi action.
- name: UpdateCluster
action: aws:executeAwsApi
maxAttempts: 10
timeoutSeconds: 3600
onFailure: Abort
inputs:
Service: cloudformation
Api: UpdateStack
StackName: '{{ ApplicationStack }}'
UsePreviousTemplate: true
Parameters:
- ParameterKey: BaselineVpcStack
UsePreviousValue: true
- ParameterKey: AmazonMachineImage
ParameterValue: '{{ GetBuiltImage.image }}'
Capabilities:
- CAPABILITY_IAM
4.2.11.
Once the update executes we will once again wait for the Cloudformation update to complete, and return with the UPDATE_COMPLETE status.
- name: WaitDeploymentComplete
action: aws:waitForAwsResourceProperty
maxAttempts: 10
timeoutSeconds: 3600
onFailure: Abort
inputs:
Service: cloudformation
Api: DescribeStacks
StackName: '{{ ApplicationStack }}'
PropertySelector: Stacks[0].StackStatus
DesiredValues:
- UPDATE_COMPLETE
4.2.12.
We have provided commentary above, to give you a picture of what is being executed in this automation document. As a whole your Automation Document should look as below. Please copy and paste below, and make that the indentation is correct as this document is specified in YAML format. Alternatively you can download the file here
description: CreateImage
schemaVersion: '0.3'
parameters:
ImageBuilderPipelineARN:
description: (Required) Corresponding EC2 Image Builder Pipeline to execute.
type: String
ApplicationStack:
description: (Required) Corresponding Application Stack to Deploy the Image to.
type: String
mainSteps:
- name: ExecuteImageCreation
action: aws:executeAwsApi
maxAttempts: 10
timeoutSeconds: 3600
onFailure: Abort
inputs:
Service: imagebuilder
Api: StartImagePipelineExecution
imagePipelineArn: '{{ ImageBuilderPipelineARN }}'
outputs:
- Name: imageBuildVersionArn
Selector: $.imageBuildVersionArn
Type: String
- name: WaitImageComplete
action: aws:waitForAwsResourceProperty
maxAttempts: 10
timeoutSeconds: 3600
onFailure: Abort
inputs:
Service: imagebuilder
Api: GetImage
imageBuildVersionArn: '{{ ExecuteImageCreation.imageBuildVersionArn }}'
PropertySelector: image.state.status
DesiredValues:
- AVAILABLE
- name: GetBuiltImage
action: aws:executeAwsApi
maxAttempts: 10
timeoutSeconds: 3600
onFailure: Abort
inputs:
Service: imagebuilder
Api: GetImage
imageBuildVersionArn: '{{ ExecuteImageCreation.imageBuildVersionArn }}'
outputs:
- Name: image
Selector: $.image.outputResources.amis[0].image
Type: String
- name: UpdateCluster
action: aws:executeAwsApi
maxAttempts: 10
timeoutSeconds: 3600
onFailure: Abort
inputs:
Service: cloudformation
Api: UpdateStack
StackName: '{{ ApplicationStack }}'
UsePreviousTemplate: true
Parameters:
- ParameterKey: BaselineVpcStack
UsePreviousValue: true
- ParameterKey: AmazonMachineImage
ParameterValue: '{{ GetBuiltImage.image }}'
Capabilities:
- CAPABILITY_IAM
- name: WaitDeploymentComplete
action: aws:waitForAwsResourceProperty
maxAttempts: 10
timeoutSeconds: 3600
onFailure: Abort
inputs:
Service: cloudformation
Api: DescribeStacks
StackName: '{{ ApplicationStack }}'
PropertySelector: Stacks[0].StackStatus
DesiredValues:
- UPDATE_COMPLETE
4.2.13.
Once that’s done click Create Automation
Now that we have created the Automation Document, let’s go ahead and execute it.
4.3. Start The Monitor Script.
Before we execute the document, we have provided a simple script for you to continuously query the Application Load Balancer http address during the document execution. This is to show that the load balancer remains available throughout the deployment.
4.3.1.
Firstly, download the monitor script here.
4.3.2.
Now change permissions of the script if required and execute passing in the application load balancer DNS address. Note that the DNS address is provided in the output of the application CloudFormation stack in section 2.2 under OutputPattern3ALBDNSName.
Execute the script as follows:
./watchscript.sh http://<enter DNS address for the Application Load Balancer>
As mentioned above, the script will run a continuous poll of the ALB throughout the next few steps to demonstrate that there is no interruption to traffic during the patch process.
For clarity, you might want to run this in a separate dedicated terminal as it will continue to poll the ALB in a loop.
You can leave this script running, and monitor to see if there is any failed response to the application. Your output should look similar to this:
4.4 Start the Automation Document.
Once your monitor script is running a continous poll of the ALB, you can execute the SSM automation document.
To Execute the automation document, you can run the following command:
aws ssm start-automation-execution \
--document-name "<enter_document_name>" \
--parameters "ApplicationStack=<enter_application_stack_name>,imageBuilderPipeline=<enter_image_builder_pipeline_arn>"
Note:
- The value of <enter_document_name> is provided as output to the CloudFormation template which you noted in section 4.1.1, or in section 4.2 if you are building it manually.
- The value of <enter_application_stack_name> is the name that you provided to the application stack in Section 2 (default is pattern3-app).
- The value of <enter_image_builder_pipeline_arn> is the ARN of the Image Builder Pipeline. You can get this from the output to the pipeline stack from Section 3.1.2 or 3.2.6 if you are building it manually via the console..
When you have successfully executed the command you will be provided with an AutomationExecutionID.
To check the status of the currently running automation executions, you can use the following command:
aws ssm describe-automation-executions
Note that you can pass a filter to the command with the AutomationExecutionID which you were provided from the automation execution as follows:
aws ssm describe-automation-executions --filter "Key=ExecutionId,Values=<enter_execution_id>"
4.5. Confirm that the AMI has been Updated Via the Load Balancer DNS Name.
When the automation execution is completed, use your web browser to access your application load balancer DNS name, together with the ‘details.php’ script added to the end of the address. You will now find that the AMI-ID has been updated with a new one, indicating that your original autoscaling group has been replaced with an updated group which is configured to use the patched AMI. as follows:
This concludes our lab.
