Debian Codegraph @

docs/source/guide/ec2-example-managing-instances.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-ec2-managing-instances:
12
13 #############################
14 Managing Amazon EC2 instances
15 #############################
16
17 This Python example shows you how to:
18
19 * Get basic information about your Amazon EC2 instances
20
21 * Start and stop detailed monitoring of an Amazon EC2 instance
22
23 * Start and stop an Amazon EC2 instance
24
25 * Reboot an Amazon EC2 instance
26
27 The scenario
28 ============
29
30 In this example, Python code is used perform several basic instance management operations. The code uses the
31 AWS SDK for Python to manage the instances by using these methods of the EC2 client class:
32
33 * `describe_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.describe_instances>`_.
34
35 * `monitor_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.monitor_instances>`_.
36
37 * `unmonitor_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.unmonitor_instances>`_.
38
39 * `start_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.start_instances>`_.
40
41 * `stop_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.stop_instances>`_.
42
43 * `reboot_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.reboot_instances>`_.
44
45 For more information about the lifecycle of Amazon EC2 instances, see
46 `Instance Lifecycle <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-lifecycle.html>`_
47 in the *Amazon EC2 User Guide for Linux Instances* or `Instance Lifecycle <http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2-instance-lifecycle.html>`_
48 in the *Amazon EC2 User Guide for Windows Instances*.
49
50 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>`_.
51
52 Prerequisite tasks
53 =================
54
55 To set up and run this example, you must first configure your AWS credentials, as described in :doc:`quickstart`.
56
57 Describe instances
58 ==================
59
60 An EC2 instance is a virtual server in Amazon's Elastic Compute Cloud (EC2) for running applications
61 on the Amazon Web Services (AWS) infrastructure.
62
63 The example below shows how to:
64
65 * Describe one or more EC2 instances using
66 `describe_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.describe_instances>`_.
67
68 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>`_.
69
70 Example
71 -------
72
73 .. code-block:: python
74
75 import boto3
76
77 ec2 = boto3.client('ec2')
78 response = ec2.describe_instances()
79 print(response)
80
81
82 Monitor and unmonitor instances
83 ===============================
84
85 Enable or disable detailed monitoring for a running instance. If detailed monitoring is not enabled,
86 basic monitoring is enabled. For more information, see
87 `Monitoring Your Instances and Volumes <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch.html>`_
88 in the *Amazon Elastic Compute Cloud User Guide*.
89
90 The example below shows how to:
91
92 * Enable detailed monitoring for a running instance using
93 `monitor_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.monitor_instances>`_.
94
95 * Disable detailed monitoring for a running instance using
96 `unmonitor_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.unmonitor_instances>`_.
97
98 Example
99 -------
100
101 .. code-block:: python
102
103 import sys
104 import boto3
105
106
107 ec2 = boto3.client('ec2')
108 if sys.argv[1] == 'ON':
109 response = ec2.monitor_instances(InstanceIds=['INSTANCE_ID'])
110 else:
111 response = ec2.unmonitor_instances(InstanceIds=['INSTANCE_ID'])
112 print(response)
113
114
115 Start and stop instances
116 ========================
117
118 Instances that use Amazon EBS volumes as their root devices can be quickly stopped and started. When
119 an instance is stopped, the compute resources are released and you are not billed for hourly instance
120 usage. However, your root partition Amazon EBS volume remains, continues to persist your data, and
121 you are charged for Amazon EBS volume usage. You can restart your instance at any time. Each time
122 you transition an instance from stopped to started, Amazon EC2 charges a full instance hour, even
123 if transitions happen multiple times within a single hour.
124
125 The example below shows how to:
126
127 * Start an Amazon EBS-backed AMI that you've previously stopped using
128 `start_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.start_instances>`_.
129
130 * Stop an Amazon EBS-backed instance using
131 `stop_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.stop_instances>`_.
132
133 Example
134 -------
135
136 .. code-block:: python
137
138 import sys
139 import boto3
140 from botocore.exceptions import ClientError
141
142 instance_id = sys.argv[2]
143 action = sys.argv[1].upper()
144
145 ec2 = boto3.client('ec2')
146
147
148 if action == 'ON':
149 # Do a dryrun first to verify permissions
150 try:
151 ec2.start_instances(InstanceIds=[instance_id], DryRun=True)
152 except ClientError as e:
153 if 'DryRunOperation' not in str(e):
154 raise
155
156 # Dry run succeeded, run start_instances without dryrun
157 try:
158 response = ec2.start_instances(InstanceIds=[instance_id], DryRun=False)
159 print(response)
160 except ClientError as e:
161 print(e)
162 else:
163 # Do a dryrun first to verify permissions
164 try:
165 ec2.stop_instances(InstanceIds=[instance_id], DryRun=True)
166 except ClientError as e:
167 if 'DryRunOperation' not in str(e):
168 raise
169
170 # Dry run succeeded, call stop_instances without dryrun
171 try:
172 response = ec2.stop_instances(InstanceIds=[instance_id], DryRun=False)
173 print(response)
174 except ClientError as e:
175 print(e)
176
177
178 Reboot instances
179 ================
180 Request a reboot of one or more instances. This operation is asynchronous; it only queues a request
181 to reboot the specified instances. The operation succeeds if the instances are valid and belong to
182 you. Requests to reboot terminated instances are ignored.
183
184 The example below shows how to:
185
186 * Request a reboot of one or more instances using
187 `reboot_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.reboot_instances>`_.
188
189 Example
190 -------
191
192 .. code-block:: python
193
194
195 import boto3
196 from botocore.exceptions import ClientError
197
198
199 ec2 = boto3.client('ec2')
200
201 try:
202 ec2.reboot_instances(InstanceIds=['INSTANCE_ID'], DryRun=True)
203 except ClientError as e:
204 if 'DryRunOperation' not in str(e):
205 print("You don't have permission to reboot instances.")
206 raise
207
208 try:
209 response = ec2.reboot_instances(InstanceIds=['INSTANCE_ID'], DryRun=False)
210 print('Success', response)
211 except ClientError as e:
212 print('Error', e)