gce-host

Search hosts on GCP GCE

Installation

gem install gce-host

How it works

This gems uses metadata of GCE resources. You can configure, but basically use roles key for roles.

You can manage roles of a host, and search hosts having a specified role using thease metadata with this gem.

Configuration

You can write a configuration file located at /etc/sysconfig/gce-host or /etc/default/gce-host (You can configure this path by GCE_HOST_CONFIG_FILE environment variable), or as environment variables:

GOOGLE API parameters:

AUTH_METHOD (optional): Authentication method. Currently, compute_engine, service_account, authorized_user, and application_default is available. The default is type in GOOGLE_APPLICATION_CREDENTIALS if it exists, otherwise compute_engine.
GOOGLE_APPLICATION_CREDENTIALS (optional): Specify path of json credential file. The default is ~/.config/gcloud/application_default_credentials.json.
GOOGLE_PROJECT (optional): Specify project name of your GCP account. The default is project_id in GOOGLE_APPLICATION_CREDENTIALS if it exists (typically, available in service acaccount json)

gce-host parameters:

ROLES_KEY (optional): GCE metadata keys used to express roles. The default is roles
- You can assign multiple roles seperated by ARRAY_VALUE_DELIMITER (default: ,)
- Also, you can express levels of roles delimited by ROLE_VALUE_DELIMITER (default :)
- Example: admin:ami, then GCE::Host.new(role: 'admin:ami') and also GCE::Host.new(role1: 'admin') returns this host
ROLE_VALUE_DELIMITER (optional): A delimiter to express levels of roles. Default is :
OPTIONAL_STRING_KEYS (optional): You may add optional non-array metadata keys. You can specify multiple keys like service,status.
OPTIONAL_ARRAY_KEYS (optional): You may add optional array metadata keys. Array allows multiple values delimited by ARRAY_VALUE_DELIMITER (default: ,)
ARRAY_VALUE_DELIMITER (optional): A delimiter to express array. Default is ,
ROLE_MAX_DEPTH (optional): The maximum depth of levels of roles. Default is 3.
LOG_LEVEL (optional): Log level such as info, debug, error. The default is info.

See example.conf

Metadata Example

roles: app:web,app:db
service: awesome
status: setup

CLI Usage

CLI Example

$ gce-host -j
{"hostname":"gce-host-db","roles":["foo","db:test"],"zone":"asia-northeast1-a","service":"gce-host","status":"active","tags":["master"],"instance_id":"4263858691219514807","private_ip_address":"10.240.0.6","public_ip_address":"104.198.89.55","creation_timestamp":"2016-11-22T06:51:04.650-08:00","state":"RUNNING"}
{"hostname":"gce-host-web","roles":["foo","web:test"],"zone":"asia-northeast1-a","service":"gce-host","status":"reserve","tags":["standby"],"instance_id":"8807276062743061943","private_ip_address":"10.240.0.5","public_ip_address":"104.198.87.6","creation_timestamp":"2016-11-22T06:51:04.653-08:00","state":"RUNNING"}

$ gce-host
gce-host-db
gce-host-web

$ gce-host --role1 db
gce-host-db

$ gce-host --role web:test
gce-host-web

$ gce-host --pretty-json
[
  {
    "hostname": "gce-host-db",
    "roles": [
      "foo",
      "db:test"
    ],
    "zone": "asia-northeast1-a",
    "service": "gce-host",
    "status": "active",
    "tags": [
      "master"
    ],
    "instance_id": "4263858691219514807",
    "private_ip_address": "10.240.0.6",
    "public_ip_address": "104.198.89.55",
    "creation_timestamp": "2016-11-22T06:51:04.650-08:00",
    "state": "RUNNING"
  },
  {
    "hostname": "gce-host-web",
    "roles": [
      "foo",
      "web:test"
    ],
    "zone": "asia-northeast1-a",
    "service": "gce-host",
    "status": "reserve",
    "tags": [
      "standby"
    ],
    "instance_id": "8807276062743061943",
    "private_ip_address": "10.240.0.5",
    "public_ip_address": "104.198.87.6",
    "creation_timestamp": "2016-11-22T06:51:04.653-08:00",
    "state": "RUNNING"
  }
]

CLI Help

$ bin/gce-host --help
Usage: gce-host [options]
        --hostname one,two,three     name or private_dns_name
    -r, --role one,two,three         role
        --r1, --role1 one,two,three  role1, 1th part of role delimited by :
        --r2, --role2 one,two,three  role2, 2th part of role delimited by :
        --r3, --role3 one,two,three  role3, 3th part of role delimited by :
        --state one,two,three        filter with instance state (default: running)
    -a, --all                        list all hosts (remove default filter)
        --private-ip, --ip           show private ip address instead of hostname
        --public-ip                  show public ip address instead of hostname
    -i, --info                       show host info
    -j, --jsonl                      show host info in line delimited json
        --json                       show host info in json
        --pretty-json                show host info in pretty json
        --debug                      debug mode
    -h, --help                       show help

Library Usage

Library Example

require 'gce-host'

hosts = GCE::Host.new(role: 'db:test')
hosts.each do |host|
  puts host
end

Library Reference

See http://sonots.github.io/gce-host/frames.html.

ChangeLog

See CHANGELOG.md for details.

For Developers

ToDo

Use mock/stub to run test (currently, directly accessing to GCE)
Should cache a result of list_instances in like 30 seconds?

How to Run test

NOTE: Currently, mock is not supported yet. So, you have to create your own gcloud account, and instances.

Configure .env file as

AUTH_METHOD=service_account
GOOGLE_APPLICATION_CREDENTIALS=service_account.json
GOOGLE_PROJECT=XXXXXXXXXXXXX
OPTIONAL_STRING_KEYS=service,status
OPTIONAL_ARRAY_KEYS=tags
ROLE_MAX_DEPTH=5
STATUS=state

Prepare service_account.json.

Install terraform and run to create instances for tests

$ brew install terraform
$ env $(cat .env) terraform plan
$ env $(cat .env) terraform apply

Run test

$ bundle exec rspec

After working, destory instances by commenting out terraform.tf and apply.

How to Release Gem

Update gem.version in the gemspec
Update CHANGELOG.md
git commit && git push
Run bundle exec rake release

How to Update doc

Run bundle exec yard
git commit && git push

Licenses

See LICENSE