{"id":16107216,"url":"https://github.com/neonwatty/easy_ec2","last_synced_at":"2026-05-09T02:06:38.044Z","repository":{"id":180197613,"uuid":"664770432","full_name":"neonwatty/easy_ec2","owner":"neonwatty","description":"Easily create, connect, and manage ec2 instances right from VS Code.","archived":false,"fork":false,"pushed_at":"2024-05-26T14:18:13.000Z","size":212,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-10T22:32:21.317Z","etag":null,"topics":["aws","boto3","configuration-as-code","ec2","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neonwatty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-10T17:55:06.000Z","updated_at":"2024-08-22T16:20:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"edf0b790-f444-474c-831f-050ca4072f7d","html_url":"https://github.com/neonwatty/easy_ec2","commit_stats":null,"previous_names":["jermwatt/easy_boto3","jermwatt/easy_ec2","neonwatty/easy_ec2"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/neonwatty/easy_ec2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neonwatty%2Feasy_ec2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neonwatty%2Feasy_ec2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neonwatty%2Feasy_ec2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neonwatty%2Feasy_ec2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neonwatty","download_url":"https://codeload.github.com/neonwatty/easy_ec2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neonwatty%2Feasy_ec2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005463,"owners_count":26083902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","boto3","configuration-as-code","ec2","python"],"created_at":"2024-10-09T19:15:36.323Z","updated_at":"2025-10-10T22:32:48.799Z","avatar_url":"https://github.com/neonwatty.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Upload Python Package](https://github.com/jermwatt/easy_ec2/actions/workflows/python-publish.yml/badge.svg)](https://github.com/jermwatt/easy_ec2/actions/workflows/python-publish.yml)\n[![Python application](https://github.com/jermwatt/easy_ec2/actions/workflows/python-app.yml/badge.svg)](https://github.com/jermwatt/easy_ec2/actions/workflows/python-app.yml)\n\n# easy `ec2` setup, remote usage, and teardown with vscode\n\n`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.\n\nA demonstration of quickly setting up and tearing down an instance using `easy_ec2` is shown in the gif below.\n\n\u003cimg align=\"center\" src=\"https://github.com/jermwatt/readme_gifs/blob/main/easy_ec2.gif\" height=\"325\"\u003e\n\n\n### Contents\n- [`ec2` made easy](#ec2-made-easy)\n    - [Contents](#contents)\n  - [Installation](#installation)\n  - [Using `easy_ec2` CLI](#using-easy_ec2-cli)\n    - [Managing ec2 instances](#managing-ec2-instances)\n      - [Creating an ec2 instance with cloudwatch alarm](#creating-an-ec2-instance-with-cloudwatch-alarm)\n      - [Show instance cloud\\_init logs](#show-instance-cloud_init-logs)\n      - [Show instance syslog logs](#show-instance-syslog-logs)\n      - [Listing ec2 instances](#listing-ec2-instances)\n      - [Stopping an ec2 instance](#stopping-an-ec2-instance)\n      - [Starting a stopped an ec2 instance](#starting-a-stopped-an-ec2-instance)\n      - [Termianting ec2 instances by id](#termianting-ec2-instances-by-id)\n    - [Managing AWS profiles](#managing-aws-profiles)\n      - [List all AWS profiles in `~/.aws/credentials`](#list-all-aws-profiles-in-awscredentials)\n      - [List active AWS profile (currently used by `easy_ec2`)](#list-active-aws-profile-currently-used-by-easy_ec2)\n      - [Set active AWS profile (currently used by `easy_ec2`)](#set-active-aws-profile-currently-used-by-easy_ec2)\n  - [Using `easy_ec2`'s Python API](#using-easy_ec2-python-api)\n    - [Creating an ec2 instance](#creating-an-ec2-instance)\n\n## Installation and setup\n\nYou can install `easy_ec2` via `pip` as\n\n```bash\npip install easy-ec2\n```\n\nTo use in tandem with VScode install the [ssh-Remote extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) as well.\n\n\n## Using `easy_ec2` CLI\n\n### Managing ec2 instances\n\n#### Creating an ec2 instance with cloudwatch alarm\n\n`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 \n\n```python\nimport boto3\n\n# read in aws_access_key_id and aws_secret_access_key based on input profile_name using boto3\nsession = boto3.Session(profile_name=profile_name)\n\n# create ec2 controller from session\nec2_controller = session.resource('ec2')\n\n# read in startup script\nwith open(startup_script_path, 'r') as file:\n    startup_script = file.read()\n\n# create a new EC2 instance\ninstances = ec2_controller.create_instances(\n    ImageId='ami-03f65b8614a860c29',\n    InstanceName='example_worker',\n    NetworkInterfaces=[{\n        'DeviceIndex': 0,\n        'Groups': ['sg-1ed8w56f12347f63d'],\n        'AssociatePublicIpAddress': True}],\n    UserData=startup_script,\n    TagSpecifications=[{'ResourceType': 'instance',\n                        'Tags': [{'Key': 'Name', 'Value': 'example_worker'}]}],\n    InstanceType='t2.micro',\n    KeyName=\u003cssh_key_name\u003e,\n    )\n\n# wait for the instance to enter running state\ninstances[0].wait_until_running()\ninstance_id = instances[0].id\n\n# create cloud watch client\ncloudwatch_client = session.client('cloudwatch')\n\n# enable detailed monitoring for the instance\nec2_client.monitor_instances(InstanceIds=[instance_id])\n\n# create alarm\nresult = cloudwatch_client.put_metric_alarm(\n        AlarmName=cpu_alarm_name,\n        ComparisonOperator='GreaterThanOrEqualToThreshold',\n        EvaluationPeriods=1,\n        MetricName='CPUUtilization',\n        Namespace='AWS/EC2',\n        Period=60,\n        Statistic='Average',\n        Threshold=threshold_value,\n        Dimensions=[\n            {\n                'Name': 'InstanceId',\n                'Value': instance_id\n            },\n        ],\n    )\n```\n\ninto 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:\n\n```yaml\naws_profile: \u003cyour profile name in config/credentials of ~/.aws\u003e\n\nec2_instance:\n  instance_details:\n    InstanceName: example_worker\n    InstanceType: t2.micro\n    ImageId: ami-03f65b8614a860c29\n    BlockDeviceMappings: \n      DeviceName: /dev/sda1\n      Ebs: \n        DeleteOnTermination: true\n        VolumeSize: 8\n        VolumeType: gp2\n    Groups:\n      - \u003cyour security group\u003e\n\n  ssh_details: \n    Config:\n      User: ubuntu\n      IdentityFile: \u003cpath to ssh key\u003e\n      ForwardAgent: yes\n    Options:\n      add_to_known_hosts: true\n      test_connection: true\n\n  script_details: \n    filepath: \u003cpath_to_startup\u003e\n    inject_aws_creds: true\n    ssh_forwarding: true\n    github_host: true\n\nalarm_details:\n  ComparisonOperator: GreaterThanOrEqualToThreshold\n  EvaluationPeriods: 1\n  MetricName: CPUUtilization\n  Namespace: AWS/EC2\n  Period: 60\n  Statistic: Average\n  Threshold: 0.99\n```\n\nThis example configuration - along with a simple startup script - can be found in the examples directory.\n\nUsing `easy_ec2` and this configuration `config.yaml` the same task - instantiating an `ec2` instance - can be accomplished via the command line as follows:\n\n```bash\neasy_ec2 ec2 create config.yaml\n```\n\n#### Show instance cloud_init logs\n\n```bash\neasy_ec2 ec2 check_cloud_init_logs \u003cinstance_id\u003e\n```\n\n#### Show instance syslog logs\n\n```bash\neasy_ec2 ec2 check_syslog \u003cinstance_id\u003e\n```\n\n#### Listing ec2 instances \n\nYou can use `easy_ec2` to easy see (all/ running / stopped / terminated) instances in your AWS account as follows.\n\nSee all instances\n\n```bash\neasy_ec2 ec2 list_all\n```\n\n\nSee just running instances \n\n```bash\neasy_ec2 ec2 list_running\n```\n\nThe output of this command gives the instance id, name, type, and state of each instance in your account - looking like this\n\n```bash\n{'instance_id': 'instance_id', 'instance_state': 'running', 'instance_type': 't2.micro'}\n```\n\nYou can filter by state - running, stopped, terminated - as follows\n\n```bash\neasy_ec2 ec2 list_running\n```\n\n```bash\neasy_ec2 ec2 list_stopped\n```\n\n```bash\neasy_ec2 ec2 list_terminated\n```\n\n#### Stopping an ec2 instance\n```bash\neasy_ec2 ec2 stop \u003cinstance_id\u003e\n```\n\n#### Starting a stopped an ec2 instance\n```bash\neasy_ec2 ec2 start \u003cinstance_id\u003e\n```\n\n\n#### Termianting ec2 instances by id  \n\nYou can use `easy_ec2` CLI to terminate an ec2 instance by id as follows\n\n```bash\neasy_ec2 ec2 terminate \u003cinstance_id\u003e\n```\n\nNote: by default this will delete any cloudwatch alarms associated with the instance.\n\n### Managing AWS profiles\n\nYou can use `easy_ec2` CLI to manage AWS profiles as follows\n\n\n#### List all AWS profiles in `~/.aws/credentials`\n\n```bash\neasy_ec2 profile list_all\n```\n\n#### List active AWS profile (currently used by `easy_ec2`)\n\n```bash\neasy_ec2 profile list_active \n```\n\n#### Set active AWS profile (currently used by `easy_ec2`)\n\n```bash\neasy_ec2 profile set \u003cprofile_name\u003e\n```\n\n\n## Using `easy_ec2`'s Python API\n\nIn 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.\n\n### Creating an ec2 instance \n\nIn this example an ec2 instance of user-specified type and AMI is created.\n\nNote `block_device_mappings` and `UserData` startup bash script are optional.\n\n```python\nfrom easy_ec2 import set_profile\nfrom easy_ec2.startup_script_management import read_startup_script\nfrom easy_ec2.ec2_instance_management import launch_instance\n\n# set aws profile - optional - set to 'default' profile by default\nset_profile.set('my_aws_profile') # -\u003e returns None if profile is valid\n\n# read in startup script from file\nUserData = read_startup_script('./path/to/startup.sh')\n\n# build ec2 launch instance command\nInstanceName = 'example_worker'\nInstanceType = 't2.micro'\nImageId = 'ami-03f65b8614a860c29'\nGroups = ['my_security_group_id']\nBlockDeviceMappings = [\n    {\n        'DeviceName': '/dev/sda1',\n        'Ebs': {\n            'VolumeSize': 300,\n            'VolumeType': 'gp2'\n        }\n    }\n]\nKeyName = 'my_ssh_key_name'\n\n# launch instance\nlaunch_result = launch_instance(KeyName=KeyName,\n                                InstanceName=InstanceName,\n                                InstanceType=InstanceType,\n                                ImageId=ImageId,\n                                Groups=Groups,\n                                BlockDeviceMappings=BlockDeviceMappings,\n                                UserData=UserData)\n\n# wait for the instance to enter running state\nlaunch_result.wait_until_running()\n\n# get instance id\ninstance_id = launch_result[0].id\n```\nFurther uses of the Python API can be found in the `examples/python_api` directory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneonwatty%2Feasy_ec2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneonwatty%2Feasy_ec2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneonwatty%2Feasy_ec2/lists"}