Skip to main content

Upload Python Package Python application

easy ec2 setup, remote usage, and teardown with vscode

easy_ec2 simplifies remote ec2 usage in vscode by adding a command line interface (CLI) and abridged Python API that allows you to easily create, manage, and tear-down AWS ec2 instances and associated resources using ec2 and awscli in a simple, easy to use, and easy to refactor .yaml configuration file.

Contents

Installation

You can install easy_ec2 via pip as

pip install easy-ec2

Using easy_ec2 CLI

Managing ec2 instances

Creating an ec2 instance with cloudwatch alarm

easy_ec2 allows you to translate a standard ec2 pythonic infrastructure task like instantiating an ec2 instance with an attached cloudwatch cpu usage alarm from complex pythonic implementation like the following

import boto3

# read in aws_access_key_id and aws_secret_access_key based on input profile_name using boto3
session = boto3.Session(profile_name=profile_name)

# create ec2 controller from session
ec2_controller = session.resource('ec2')

# read in startup script
with open(startup_script_path, 'r') as file:
    startup_script = file.read()

# create a new EC2 instance
instances = ec2_controller.create_instances(
    ImageId='ami-03f65b8614a860c29',
    InstanceName='example_worker',
    NetworkInterfaces=[{
        'DeviceIndex': 0,
        'Groups': ['sg-1ed8w56f12347f63d'],
        'AssociatePublicIpAddress': True}],
    UserData=startup_script,
    TagSpecifications=[{'ResourceType': 'instance',
                        'Tags': [{'Key': 'Name', 'Value': 'example_worker'}]}],
    InstanceType='t2.micro',
    KeyName=<ssh_key_name>,
    )

# wait for the instance to enter running state
instances[0].wait_until_running()
instance_id = instances[0].id

# create cloud watch client
cloudwatch_client = session.client('cloudwatch')

# enable detailed monitoring for the instance
ec2_client.monitor_instances(InstanceIds=[instance_id])

# create alarm
result = cloudwatch_client.put_metric_alarm(
        AlarmName=cpu_alarm_name,
        ComparisonOperator='GreaterThanOrEqualToThreshold',
        EvaluationPeriods=1,
        MetricName='CPUUtilization',
        Namespace='AWS/EC2',
        Period=60,
        Statistic='Average',
        Threshold=threshold_value,
        Dimensions=[
            {
                'Name': 'InstanceId',
                'Value': instance_id
            },
        ],
    )

into easier to re / use and refactor .yaml configuration file using the same boto3 option syntax for to declaration of the same task. So for example the above task can be accomplished using the analogous .yaml configuration file carrying over the same boto3 option syntax as follows:

aws_profile: <your profile name in config/credentials of ~/.aws>

ec2_instance:
  instance_details:
    InstanceName: example_worker
    InstanceType: t2.micro
    ImageId: ami-03f65b8614a860c29
    BlockDeviceMappings: 
      DeviceName: /dev/sda1
      Ebs: 
        DeleteOnTermination: true
        VolumeSize: 8
        VolumeType: gp2
    Groups:
      - <your security group>

  ssh_details: 
    Config:
      User: ubuntu
      IdentityFile: <path to ssh key>
      ForwardAgent: yes
    Options:
      add_to_known_hosts: true
      test_connection: true

  script_details: 
    filepath: <path_to_startup>
    inject_aws_creds: true
    ssh_forwarding: true
    github_host: true

alarm_details:
  ComparisonOperator: GreaterThanOrEqualToThreshold
  EvaluationPeriods: 1
  MetricName: CPUUtilization
  Namespace: AWS/EC2
  Period: 60
  Statistic: Average
  Threshold: 0.99

Using easy_ec2 and this configuration config.yaml the same task - instantiating an ec2 instance - can be accomplished via the command line as follows:

easy_ec2 ec2 create config.yaml

Show instance cloud_init logs

easy_ec2 ec2 check_cloud_init_logs <instance_id>

Show instance syslog logs

easy_ec2 ec2 check_syslog <instance_id>

Listing ec2 instances

You can use easy_ec2 to easy see (all/ running / stopped / terminated) instances in your AWS account as follows.

See all instances

easy_ec2 ec2 list_all

See just running instances

easy_ec2 ec2 list_running

The output of this command gives the instance id, name, type, and state of each instance in your account - looking like this

{'instance_id': 'instance_id', 'instance_state': 'running', 'instance_type': 't2.micro'}

You can filter by state - running, stopped, terminated - as follows

easy_ec2 ec2 list_running
easy_ec2 ec2 list_stopped
easy_ec2 ec2 list_terminated

Stopping an ec2 instance

easy_ec2 ec2 stop <instance_id>

Starting a stopped an ec2 instance

easy_ec2 ec2 start <instance_id>

Termianting ec2 instances by id

You can use easy_ec2 CLI to terminate an ec2 instance by id as follows

easy_ec2 ec2 terminate <instance_id>

Note: by default this will delete any cloudwatch alarms associated with the instance.

Managing AWS profiles

You can use easy_ec2 CLI to manage AWS profiles as follows

List all AWS profiles in ~/.aws/credentials

easy_ec2 profile list_all

List active AWS profile (currently used by easy_ec2)

easy_ec2 profile list_active 

Set active AWS profile (currently used by easy_ec2)

easy_ec2 profile set <profile_name>

Using easy_ec2's Python API

In addition to config driven command line use, easy_ec2 also offers a simplified python API that makes creating and managing AWS resources with ec2 easier.

Creating an ec2 instance

In this example an ec2 instance of user-specified type and AMI is created.

Note block_device_mappings and UserData startup bash script are optional.

from easy_ec2 import set_profile
from easy_ec2.startup_script_management import read_startup_script
from easy_ec2.ec2_instance_management import launch_instance

# set aws profile - optional - set to 'default' profile by default
set_profile.set('my_aws_profile') # -> returns None if profile is valid

# read in startup script from file
UserData = read_startup_script('./path/to/startup.sh')

# build ec2 launch instance command
InstanceName = 'example_worker'
InstanceType = 't2.micro'
ImageId = 'ami-03f65b8614a860c29'
Groups = ['my_security_group_id']
BlockDeviceMappings = [
    {
        'DeviceName': '/dev/sda1',
        'Ebs': {
            'VolumeSize': 300,
            'VolumeType': 'gp2'
        }
    }
]
KeyName = 'my_ssh_key_name'

# launch instance
launch_result = launch_instance(KeyName=KeyName,
                                InstanceName=InstanceName,
                                InstanceType=InstanceType,
                                ImageId=ImageId,
                                Groups=Groups,
                                BlockDeviceMappings=BlockDeviceMappings,
                                UserData=UserData)

# wait for the instance to enter running state
launch_result.wait_until_running()

# get instance id
instance_id = launch_result[0].id

Further uses of the Python API can be found in the examples/python_api directory.

Metadata

Release files for easy-ec2 0.1.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for easy-ec2 0.1.9
File Size Uploaded Provenance Actions
easy_ec2-0.1.9.tar.gz 22.6 kB Without provenance Details for easy_ec2-0.1.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for easy-ec2 0.1.9
File Interpreter ABI Platform Actions
easy_ec2-0.1.9-py3-none-any.whl Python 3 none any Details for easy_ec2-0.1.9-py3-none-any.whl

Total release size: 53.1 kB

Release files / easy_ec2-0.1.9.tar.gz

Download URL easy_ec2-0.1.9.tar.gz
Size 22.6 kB
Tags Source
SHA-256 checksum
How to use checksums
0b23540860d75d0184f6fe8c7589e13faa5916fc29e1b64325e309dd7e90e168
BLAKE2b-256 checksum
How to use checksums
9e1183d42bf6b750234e63edd466da8f287bae5ddd4a5a990a69cc481da16b67
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.0.0 CPython/3.9.19

Release files / easy_ec2-0.1.9-py3-none-any.whl

Download URL easy_ec2-0.1.9-py3-none-any.whl
Size 30.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b46ad4f4a4b1d655364bf1522e481c77803539e5c3316472fcb51d4c5532d7d4
BLAKE2b-256 checksum
How to use checksums
dba7639c5b6f010423660646984f45a38735527518592e5e61f40cf70397172e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.0.0 CPython/3.9.19

Security for easy-ec2 0.1.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.9 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page