{"id":16643412,"url":"https://github.com/sonots/ec2-host","last_synced_at":"2025-06-25T08:40:44.493Z","repository":{"id":36092484,"uuid":"40393437","full_name":"sonots/ec2-host","owner":"sonots","description":"Search and get hosts on AWS EC2 by tags","archived":false,"fork":false,"pushed_at":"2019-05-20T09:39:02.000Z","size":251,"stargazers_count":8,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-11T13:21:02.454Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://sonots.github.io/ec2-host/frames.html","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sonots.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-08T06:09:06.000Z","updated_at":"2019-02-12T07:10:34.000Z","dependencies_parsed_at":"2022-09-09T02:22:59.328Z","dependency_job_id":null,"html_url":"https://github.com/sonots/ec2-host","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/sonots/ec2-host","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonots%2Fec2-host","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonots%2Fec2-host/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonots%2Fec2-host/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonots%2Fec2-host/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sonots","download_url":"https://codeload.github.com/sonots/ec2-host/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonots%2Fec2-host/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260072611,"owners_count":22954914,"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","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":[],"created_at":"2024-10-12T08:08:25.841Z","updated_at":"2025-06-25T08:40:44.470Z","avatar_url":"https://github.com/sonots.png","language":"Ruby","readme":"# ec2-host\n\nSearch hosts on AWS EC2\n\n## Installation\n\n```\ngem install ec2-host\n```\n\n## How it works\n\nThis gems uses [tagging of EC2 resources](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html).\nYou can configure, but basically use `Name` tag for hostname (this is default of EC2) and `Roles` tag for roles.\n\nYou can manage roles of a host, and search hosts having a specified role using thease tags with this gem.\n\n## Configuration\n\nYou can write a configuration file located at `/etc/sysconfig/ec2-host` or `/etc/default/ec2-host` (You can configure this path by `EC2_HOST_CONFIG_FILE` environment variable), or as environment variables:\n\nAWS SDK (CLI) parameters:\n\n* **AWS_ACCESS_KEY_ID**: AWS SDK (CLI) crendentials. Default loads a credentials file\n* **AWS_SECRET_ACCESS_KEY**: AWS SDK (CLI) credentials. Default load a credentials file\n* **AWS_DEFAULT_REGION** (**AWS_REGION**); AWS SDK (CLI) region such as `ap-northeast-1`, `us-east-1`. Default obtains from `$HOME/.aws/config` with profile `AWS_DEFAULT_PROFILE`.\n* **AWS_DEFAULT_PROFILE** (**AWS_PROFILE**): The profile key of the AWS SDK (CLI) credentails file. Default is `default`\n* **AWS_SHARED_CREDENTIALS_FILE** (**AWS_CREDENTIAL_FILE**, **AWS_CREDENTIALS_FILE**): Path of the AWS SDK (CLI) credentails file. Default is `$HOME/.aws/credentials`. See [Configuring the AWS Command Line Interface](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) for details. \n\nec2-host parameters:\n\n* **HOSTNAME_TAG (optional)**: EC2 tag key used to express a hostname. The default is `Name`.\n* **ROLES_TAG (optional)**: EC2 tag keys used to express roles. The default is `Roles`\n  * You can assign multiple roles seperated by `ARRAY_TAG_DELIMITER` (default: `,`)\n  * Also, you can express levels of roles delimited by `ROLE_TAG_DELIMITER` (default `:`)\n  * Example: admin:ami, then `EC2::Host.new(role: 'admin:ami')` and also `EC2::Host.new(role1: 'admin')` returns this host\n* **ROLE_TAG_DELIMITER (optional)**: A delimiter to express levels of roles. Default is `:`\n* **OPTIONAL_STRING_TAGS (optional)**: You may add optional non-array tags. You can specify multiple tags like `Service,Status`. \n* **OPTIONAL_ARRAY_TAGS (optional)**: You may add optional array tags. Array tags allows multiple values delimited by `ARRAY_TAG_DELIMITER` (default: `,`)\n* **ARRAY_TAG_DELIMITER (optional)**: A delimiter to express array. Default is `,`\n* **ROLE_MAX_DEPTH (optional)**: The maximum depth of levels of roles. Default is 3.\n* **LOG_LEVEL (optional)**: Log level such as `info`, `debug`, `error`. The default is `info`. \n\nSee [example.conf](./example/example.conf)\n\n## Tag Example\n\n* **Name**: hostname\n* **Roles**: app:web,app:db\n* **Service**: sugoi\n* **Status**: setup\n\n## CLI Usage\n\n### CLI Example\n\n```\n$ ec2-host -j\n{\"hostname\":\"test\",\"roles\":[\"admin:ami\",\"test\"],\"region\":\"ap-northeast-1\",\"instance_id\":\"i-85900780\",\"private_ip_address\":\"172.31.23.50\",\"public_ip_address\":null,\"launch_time\":\"2013-09-16 06:14:20 UTC\",\"state\":\"running\",\"monitoring\":\"disabled\"}\n{\"hostname\":\"ip-172-31-6-194\",\"roles\":[\"isucon4:qual\"],\"region\":\"ap-northeast-1\",\"instance_id\":\"i-f88cc8e1\",\"private_ip_address\":\"172.31.6.194\",\"public_ip_address\":null,\"launch_time\":\"2014-10-20 15:57:23 UTC\",\"state\":\"running\",\"monitoring\":\"disabled\"}\n```\n\n```\n$ ec2-host\ntest\nip-172-31-6-194 # if Name tag is not available\n```\n\n```\n$ ec2-host --role1 admin\ntest\n```\n\n```\n$ ec2-host --role admin:ami\ntest\n```\n\n```\n$ ec2-host --pretty-json\n[\n  {\n    \"hostname\": \"test\",\n    \"roles\": [\n      \"admin:ami\",\n      \"test\"\n    ],\n    \"region\": \"ap-northeast-1\",\n    \"instance_id\": \"i-85900780\",\n    \"private_ip_address\": \"172.31.23.50\",\n    \"public_ip_address\": null,\n    \"launch_time\": \"2013-09-16 06:14:20 UTC\",\n    \"state\": \"running\",\n    \"monitoring\": \"disabled\"\n  },\n  {\n    \"hostname\": \"ip-172-31-6-194\",\n    \"roles\": [\n      \"isucon4:qual\"\n    ],\n    \"region\": \"ap-northeast-1\",\n    \"instance_id\": \"i-f88cc8e1\",\n    \"private_ip_address\": \"172.31.6.194\",\n    \"public_ip_address\": null,\n    \"launch_time\": \"2014-10-20 15:57:23 UTC\",\n    \"state\": \"running\",\n    \"monitoring\": \"disabled\"\n  }\n]\n```\n\n### CLI Help\n\n```\n$ bin/ec2-host --help\nUsage: ec2-host [options]\n        --hostname one,two,three     name or private_dns_name\n    -r, --role one,two,three         role\n        --r1, --role1 one,two,three  role1, 1th part of role delimited by :\n        --r2, --role2 one,two,three  role2, 2th part of role delimited by :\n        --r3, --role3 one,two,three  role3, 3th part of role delimited by :\n        --instance-id one,two,three  instance_id\n        --state one,two,three        filter with instance state (default: running)\n        --monitoring one,two,three   filter with instance monitoring\n    -a, --all                        list all hosts (remove default filter)\n        --private-ip, --ip           show private ip address instead of hostname\n        --public-ip                  show public ip address instead of hostname\n    -i, --info                       show host info\n    -j, --jsonl                      show host info in line delimited json\n        --json                       show host info in json\n        --pretty-json                show host info in pretty json\n        --debug                      debug mode\n    -h, --help                       show help\n```\n\n## Library Usage\n\n### Library Example\n\n```ruby\nrequire 'ec2-host'\n\nhosts = EC2::Host.new(role: 'admin:ami')\nhosts.each do |host|\n  puts host\nend\n```\n\n### Library Reference\n\nSee http://sonots.github.io/ec2-host/frames.html.\n\n## ChangeLog\n\nSee [CHANGELOG.md](CHANGELOG.md) for details.\n\n## For Developers\n\n### ToDo\n\n* Support assume-roles\n* Use mock/stub to run test (currently, directly accessing to EC2)\n* Should cache a result of describe-instances in like 30 seconds?\n\n### How to Run test\n\nNOTE: Currently, mock is not supported yet. So, you have to create your own AWS account, and instances.\n\nConfigure .env file as\n\n```\nAWS_ACCESS_KEY_ID=\nAWS_SECRET_ACCESS_KEY=\nAWS_DEFAULT_REGION=\nEC2_HOST_CONFIG_FILE=.env\nOPTIONAL_ARRAY_TAGS=Tags\nOPTIONAL_STRING_TAGS=Service,Status\n```\n\nInstall terraform and run to create instances for tests\n\n```\n$ brew install terraform\n$ env $(cat .env) terraform plan\n$ env $(cat .env) terraform apply\n```\n\nRun test\n\n```\n$ bundle exec rspec\n```\n\nAfter working, destory instances by commenting out `terraform.tf` and apply.\n\n### How to Release Gem\n\n1. Update gem.version in the gemspec\n2. Update CHANGELOG.md\n3. git commit \u0026\u0026 git push\n4. Run `bundle exec rake release`\n\n### How to Update doc\n\n1. Run `bundle exec yard`\n2. git commit \u0026\u0026 git push\n\n### Licenses\n\nSee [LICENSE](LICENSE)\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonots%2Fec2-host","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsonots%2Fec2-host","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonots%2Fec2-host/lists"}