213 lines
7.8 KiB
ReStructuredText
213 lines
7.8 KiB
ReStructuredText
.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
|
|
|
|
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
|
|
International License (the "License"). You may not use this file except in compliance with the
|
|
License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
|
|
|
|
This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
|
|
either express or implied. See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
.. _aws-boto3-ec2-managing-instances:
|
|
|
|
#############################
|
|
Managing Amazon EC2 instances
|
|
#############################
|
|
|
|
This Python example shows you how to:
|
|
|
|
* Get basic information about your Amazon EC2 instances
|
|
|
|
* Start and stop detailed monitoring of an Amazon EC2 instance
|
|
|
|
* Start and stop an Amazon EC2 instance
|
|
|
|
* Reboot an Amazon EC2 instance
|
|
|
|
The scenario
|
|
============
|
|
|
|
In this example, Python code is used perform several basic instance management operations. The code uses the
|
|
AWS SDK for Python to manage the instances by using these methods of the EC2 client class:
|
|
|
|
* `describe_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.describe_instances>`_.
|
|
|
|
* `monitor_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.monitor_instances>`_.
|
|
|
|
* `unmonitor_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.unmonitor_instances>`_.
|
|
|
|
* `start_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.start_instances>`_.
|
|
|
|
* `stop_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.stop_instances>`_.
|
|
|
|
* `reboot_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.reboot_instances>`_.
|
|
|
|
For more information about the lifecycle of Amazon EC2 instances, see
|
|
`Instance Lifecycle <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-lifecycle.html>`_
|
|
in the *Amazon EC2 User Guide for Linux Instances* or `Instance Lifecycle <http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2-instance-lifecycle.html>`_
|
|
in the *Amazon EC2 User Guide for Windows Instances*.
|
|
|
|
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>`_.
|
|
|
|
Prerequisite tasks
|
|
=================
|
|
|
|
To set up and run this example, you must first configure your AWS credentials, as described in :doc:`quickstart`.
|
|
|
|
Describe instances
|
|
==================
|
|
|
|
An EC2 instance is a virtual server in Amazon's Elastic Compute Cloud (EC2) for running applications
|
|
on the Amazon Web Services (AWS) infrastructure.
|
|
|
|
The example below shows how to:
|
|
|
|
* Describe one or more EC2 instances using
|
|
`describe_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.describe_instances>`_.
|
|
|
|
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>`_.
|
|
|
|
Example
|
|
-------
|
|
|
|
.. code-block:: python
|
|
|
|
import boto3
|
|
|
|
ec2 = boto3.client('ec2')
|
|
response = ec2.describe_instances()
|
|
print(response)
|
|
|
|
|
|
Monitor and unmonitor instances
|
|
===============================
|
|
|
|
Enable or disable detailed monitoring for a running instance. If detailed monitoring is not enabled,
|
|
basic monitoring is enabled. For more information, see
|
|
`Monitoring Your Instances and Volumes <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch.html>`_
|
|
in the *Amazon Elastic Compute Cloud User Guide*.
|
|
|
|
The example below shows how to:
|
|
|
|
* Enable detailed monitoring for a running instance using
|
|
`monitor_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.monitor_instances>`_.
|
|
|
|
* Disable detailed monitoring for a running instance using
|
|
`unmonitor_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.unmonitor_instances>`_.
|
|
|
|
Example
|
|
-------
|
|
|
|
.. code-block:: python
|
|
|
|
import sys
|
|
import boto3
|
|
|
|
|
|
ec2 = boto3.client('ec2')
|
|
if sys.argv[1] == 'ON':
|
|
response = ec2.monitor_instances(InstanceIds=['INSTANCE_ID'])
|
|
else:
|
|
response = ec2.unmonitor_instances(InstanceIds=['INSTANCE_ID'])
|
|
print(response)
|
|
|
|
|
|
Start and stop instances
|
|
========================
|
|
|
|
Instances that use Amazon EBS volumes as their root devices can be quickly stopped and started. When
|
|
an instance is stopped, the compute resources are released and you are not billed for hourly instance
|
|
usage. However, your root partition Amazon EBS volume remains, continues to persist your data, and
|
|
you are charged for Amazon EBS volume usage. You can restart your instance at any time. Each time
|
|
you transition an instance from stopped to started, Amazon EC2 charges a full instance hour, even
|
|
if transitions happen multiple times within a single hour.
|
|
|
|
The example below shows how to:
|
|
|
|
* Start an Amazon EBS-backed AMI that you've previously stopped using
|
|
`start_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.start_instances>`_.
|
|
|
|
* Stop an Amazon EBS-backed instance using
|
|
`stop_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.stop_instances>`_.
|
|
|
|
Example
|
|
-------
|
|
|
|
.. code-block:: python
|
|
|
|
import sys
|
|
import boto3
|
|
from botocore.exceptions import ClientError
|
|
|
|
instance_id = sys.argv[2]
|
|
action = sys.argv[1].upper()
|
|
|
|
ec2 = boto3.client('ec2')
|
|
|
|
|
|
if action == 'ON':
|
|
# Do a dryrun first to verify permissions
|
|
try:
|
|
ec2.start_instances(InstanceIds=[instance_id], DryRun=True)
|
|
except ClientError as e:
|
|
if 'DryRunOperation' not in str(e):
|
|
raise
|
|
|
|
# Dry run succeeded, run start_instances without dryrun
|
|
try:
|
|
response = ec2.start_instances(InstanceIds=[instance_id], DryRun=False)
|
|
print(response)
|
|
except ClientError as e:
|
|
print(e)
|
|
else:
|
|
# Do a dryrun first to verify permissions
|
|
try:
|
|
ec2.stop_instances(InstanceIds=[instance_id], DryRun=True)
|
|
except ClientError as e:
|
|
if 'DryRunOperation' not in str(e):
|
|
raise
|
|
|
|
# Dry run succeeded, call stop_instances without dryrun
|
|
try:
|
|
response = ec2.stop_instances(InstanceIds=[instance_id], DryRun=False)
|
|
print(response)
|
|
except ClientError as e:
|
|
print(e)
|
|
|
|
|
|
Reboot instances
|
|
================
|
|
Request a reboot of one or more instances. This operation is asynchronous; it only queues a request
|
|
to reboot the specified instances. The operation succeeds if the instances are valid and belong to
|
|
you. Requests to reboot terminated instances are ignored.
|
|
|
|
The example below shows how to:
|
|
|
|
* Request a reboot of one or more instances using
|
|
`reboot_instances <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.reboot_instances>`_.
|
|
|
|
Example
|
|
-------
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
import boto3
|
|
from botocore.exceptions import ClientError
|
|
|
|
|
|
ec2 = boto3.client('ec2')
|
|
|
|
try:
|
|
ec2.reboot_instances(InstanceIds=['INSTANCE_ID'], DryRun=True)
|
|
except ClientError as e:
|
|
if 'DryRunOperation' not in str(e):
|
|
print("You don't have permission to reboot instances.")
|
|
raise
|
|
|
|
try:
|
|
response = ec2.reboot_instances(InstanceIds=['INSTANCE_ID'], DryRun=False)
|
|
print('Success', response)
|
|
except ClientError as e:
|
|
print('Error', e)
|