Debian Codegraph @

docs/source/guide/cw-example-using-alarms.rst

raw
1 .. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2
3 This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
4 International License (the "License"). You may not use this file except in compliance with the
5 License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
6
7 This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
8 either express or implied. See the License for the specific language governing permissions and
9 limitations under the License.
10
11 .. _aws-boto3-cw-using-alarms:
12
13 ########################################
14 Using alarm actions in Amazon CloudWatch
15 ########################################
16
17 This Python example shows you how to:
18
19 * Create a CloudWatch alarm and enable actions
20
21 * Disable a CloudWatch alarm action
22
23 The scenario
24 ============
25
26 Using alarm actions, you can create alarms that automatically stop, terminate, reboot, or recover
27 your Amazon EC2 instances. You can use the stop or terminate actions when you no longer need an EC2
28 instance to be running. You can use the reboot and recover actions to automatically reboot those instances.
29
30 In this example, Python code is used to define an alarm action in CloudWatch that
31 triggers the reboot of an Amazon EC2 instance. The code uses the AWS SDK for Python to manage
32 Amazon EC2 instances using these methods of the CloudWatch client class:
33
34 * `put_metric_alarm <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudwatch.html#CloudWatch.Client.put_metric_alarm>`_.
35
36 * `disable_alarm_actions <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudwatch.html#CloudWatch.Client.disable_alarm_actions>`_.
37
38
39 For more information about CloudWatch alarm actions, see
40 `Create Alarms to Stop, Terminate, Reboot, or Recover an Instance <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/UsingAlarmActions.html>`_
41 in the *Amazon CloudWatch User Guide*.
42
43 All the example code for the Amazon Web Services (AWS) SDK for Python is available `here on GitHub <https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/python/example_code>`_.
44
45 Prerequisite tasks
46 =================
47
48 * Configure your AWS credentials, as described in :doc:`quickstart`.
49
50 * Create an IAM role whose policy grants permission to describe, reboot, stop, or terminate an Amazon
51 EC2 instance. For more information about creating an IAM role, see
52 `Creating a Role to Delegate Permissions to an AWS Service <http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html>`_
53 in the *IAM User Guide*.
54
55 Use the following role policy when creating the IAM role.
56
57 .. code-block:: python
58
59 {
60 "Version": "2012-10-17",
61 "Statement": [
62 {
63 "Effect": "Allow",
64 "Action": [
65 "cloudwatch:Describe*",
66 "ec2:Describe*",
67 "ec2:RebootInstances",
68 "ec2:StopInstances*",
69 "ec2:TerminateInstances"
70 ],
71 "Resource": [
72 "*"
73 ]
74 }
75 ]
76 }
77
78 Create and enable actions on an alarm
79 =====================================
80
81 Create or update an alarm and associate it with the specified metric. Optionally, this operation
82 can associate one or more Amazon SNS resources with the alarm.
83
84 When this operation creates an alarm, the alarm state is immediately set to :code:`INSUFFICIENT_DATA`.
85 The alarm is evaluated and its state is set appropriately. Any actions associated with the state are
86 then executed.
87
88 When you update an existing alarm, its state is left unchanged, but the update completely overwrites
89 the previous configuration of the alarm.
90
91 The example below shows how to:
92
93 * Create an alarm and enable actions using
94 `put_metric_alarm <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudwatch.html#CloudWatch.Client.put_metric_alarm>`_.
95
96 Example
97 -------
98
99 .. code-block:: python
100
101 import boto3
102
103 # Create CloudWatch client
104 cloudwatch = boto3.client('cloudwatch')
105
106 # Create alarm with actions enabled
107 cloudwatch.put_metric_alarm(
108 AlarmName='Web_Server_CPU_Utilization',
109 ComparisonOperator='GreaterThanThreshold',
110 EvaluationPeriods=1,
111 MetricName='CPUUtilization',
112 Namespace='AWS/EC2',
113 Period=60,
114 Statistic='Average',
115 Threshold=70.0,
116 ActionsEnabled=True,
117 AlarmActions=[
118 'arn:aws:swf:us-west-2:{CUSTOMER_ACCOUNT}:action/actions/AWS_EC2.InstanceId.Reboot/1.0'
119 ],
120 AlarmDescription='Alarm when server CPU exceeds 70%',
121 Dimensions=[
122 {
123 'Name': 'InstanceId',
124 'Value': 'INSTANCE_ID'
125 },
126 ],
127 Unit='Seconds'
128 )
129
130 Disable actions on an alarm
131 ===========================
132
133 Disable the actions for the specified alarms. When an alarm's actions are disabled, the alarm actions
134 do not execute when the alarm state changes.
135
136 The example below shows how to:
137
138 * Disable metric alarm actions using
139 `disable_alarm_actions <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudwatch.html#CloudWatch.Client.disable_alarm_actions>`_.
140
141 Example
142 -------
143
144 .. code-block:: python
145
146 import boto3
147
148 # Create CloudWatch client
149 cloudwatch = boto3.client('cloudwatch')
150
151 # Disable alarm
152 cloudwatch.disable_alarm_actions(
153 AlarmNames=['Web_Server_CPU_Utilization'],
154 )
155
156