DigitalOcean droplet management tool
Project description
# dobro
Manage your droplets by tag.
## Overview
**dobro** is a tag-centric DigitalOcean droplet management tool. It's not just a
CLI wrapper for the DigitalOcean API -
[doctl](https://github.com/digitalocean/doctl) does that. In fact, dobro
requires doctl - and you'll want to use doctl alongside it.
By 'tag-centric', we mean that it forces you to manage your droplets by tag.
This is a good way of working with droplets if you're planning on doing some
serious automation; if you leave your droplets' names to chance - say, by
naming them after their droplet ID - you can then use DigitalOcean itself as a
dynamic host inventory, with droplet tags indicating which tasks they should
run. Sound good? Read on.
dobro does the following things:
- Creates tagged droplets whose names are their IDs.
- Allows mass tagging, untagging and deletion of droplets by ID, IP or tag.
- Keeps the public key with which you instantiate droplets synced to
DigitalOcean.
- **TODO: Unimplemented:** Runs hooks after any action.
## Installing
### Prerequisites
- Python 2.7+ with pip.
- [doctl](https://github.com/digitalocean/doctl) (follow their instructions).
- Make sure you authorise with `doctl auth login`.
- An SSH key pair.
- If it's not in the usual `~/.ssh/id_rsa`, see **environment
variables** below.
### Install
```
pip install dobro
```
You might need to stick a `sudo` behind this if on OS X. (which, let's face it,
you probably are, you little tart)
## Example: create a droplet
```
$ dobro create db postgres
[dobro - info] ssh-key: create: 'dobro-bro'
[dobro - info] droplet: create: 'bro-new-20160729232127-0'
Identity added: /Users/doug/.ssh/id_rsa (/Users/doug/.ssh/id_rsa)
[dobro - info] droplet: wait for ssh: 'bro-new-20160729232127-0'
[dobro - info] droplet: rename: 'bro-new-20160729232127-0' => 'bro-20957830'
Warning: Permanently added '139.59.189.41' (ECDSA) to the list of known hosts.
Connection to 139.59.189.41 closed.
[dobro - info] tag: create: 'db'
[dobro - info] tag: create: 'postgres'
[dobro - info] droplet: tag: 'bro-20957830' => 'db'
[dobro - info] droplet: tag: 'bro-20957830' => 'postgres'
```
And there you have it, a fresh droplet ready to be SSH'd into using your key and
tagged with `db` and `postgres`.
### What's happening here
By default, dobro will namespace all your droplets under `bro`. You can change
this by setting an environment variable (again see below). This namespace will
be prepended to all of your droplets' names, and it'll be the end of the name of
your SSH public key as stored on DigitalOcean (`dobro-bro`).
As you can see, dobro first checks whether your key exists on DigitalOcean. If
it doesn't, it creates it.*
Then it'll create your droplet, wait for its sshd to listen, and then swiftly
rename it droplet.**
This is because we want droplets to be named after their IDs - for simplicity's
sake - rather than anything else; we just use `<NAMESPACE>-new-<DATETIME>-<N>`
as a placeholder. So, in this example, this rename is from
`bro-new-20160729232127-0` to `bro-20957830`.
Tags are then created (if they don't already exist) and are applied to the
droplet. And that's it!
If you are indeed using automation and are now rearing to run some nifty Ansible
to configure your new droplet, you'll want to read about **default tags** and
**hooks** below.
#### Gotchas
\* DigitalOcean doesn't like storing the same public key under two names - so if
you get an error straight after `[dobro - info] ssh-key: create`, your key is
likely already stored on DigitalOcean. Either delete it or rename it to
`dobro-<NAMESPACE>`.
\*\* dobro makes sure to change your droplet's *hostname* as well as its name on
DigitalOcean. These are separate, annoyingly. Changing the hostname requires
SSH'ing into the droplet, which is why we wait for sshd to listen and then
automatically add it as a known host.
## Default tags
The environment variable `DOBRO_NEW_DROPLET_TAGS` can be set as a list of tags
(separated by whitespace) - eg. `"_new setup-needed"` - that will automatically
be applied to all droplets upon creation.
This is useful if there is any one-time setup you may need to do on a droplet,
such as locking down SSH access from droplets' default root login.
## Hooks
**TODO: Unimplemented.**
## Reference
### CLI
```
dobro create [-n|--droplet-count <NUMBER>] <TAGS>
```
Create droplet(s) with the specified tags.
`-n|--droplet-count <NUMBER>` specifies the number of droplets. By default, only
one is created.
`<TAGS>` specifies tags to apply, separated by whitespace.
---
```
dobro list [-a|--all]
```
Information listing on all droplets in namespace. This is just a filtered
`doctl compute droplet list` that'll also notify you if there are any droplets
*not* in your namespace.
`-a|--all` removes the filter.
---
```
dobro tag -c|--criteria <IDs|IPs|TAGS> -t|--tag <TAGS>
```
Adds the specified tags to all matched droplets.
`-c|--criteria` *(required)* specifies any number of IDs, IPv4 public addresses,
and tags.
- All droplets specified by ID or IP will be matched, regardless of how many
tags are specified (if any).
- Where tags are specified, only droplets with *all* of these tags will be
matched, *in addition* to droplets matched by ID or IP.
`-t|--tag` *(required)* specifies tags to apply, separated by whitespace.
---
```
dobro untag -c|--criteria <IDs|IPs|TAGS> -t|--tag <TAGS>
```
**Currently unimplemented until the fix for [digitalocean/doctl#119](https://github.com/digitalocean/doctl/issues/119) is
released.**
Removes the specified tags from all matched droplets.
Parameters as with `dobro tag`.
---
```
dobro ssh-key
```
Ensures your public key is up-to-date on DigitalOcean. This is done before any
`create` action too.
---
```
dobro delete <IDs|IPs|TAGS>
```
Deletes all matched droplets.
`<IDs|IPs|TAGS>` are criteria as with `dobro tag`.
---
```
dobro version
```
Displays version information.
---
#### Generic flags
`-v|--verbose` includes detailed program breakdown and debugging information in
output.
`-q|--quiet` suppresses all output except warnings and errors.
### Environment variables
Complete with defaults, here's what dobro pays attention to:
```
# Locations of your SSH keys.
DOBRO_SSH_PRIVATE_KEY="$HOME/.ssh/id_rsa"
DOBRO_SSH_PUBLIC_KEY="$DOBRO_SSH_PRIVATE_KEY.pub"
# Tags applied to all new droplets, separated by whitespace (eg. "new db").
DOBRO_NEW_DROPLET_TAGS=""
# Droplet creation flags.
DOBRO_NEW_DROPLET_FLAGS="--region lon1 --size 512mb --image ubuntu-14-04-x64"
```
### Constraints
- Tags must match `/[a-zA-Z][a-zA-Z0-9_-]+/`.
- DigitalOcean droplet IDs are always purely numeric.
Manage your droplets by tag.
## Overview
**dobro** is a tag-centric DigitalOcean droplet management tool. It's not just a
CLI wrapper for the DigitalOcean API -
[doctl](https://github.com/digitalocean/doctl) does that. In fact, dobro
requires doctl - and you'll want to use doctl alongside it.
By 'tag-centric', we mean that it forces you to manage your droplets by tag.
This is a good way of working with droplets if you're planning on doing some
serious automation; if you leave your droplets' names to chance - say, by
naming them after their droplet ID - you can then use DigitalOcean itself as a
dynamic host inventory, with droplet tags indicating which tasks they should
run. Sound good? Read on.
dobro does the following things:
- Creates tagged droplets whose names are their IDs.
- Allows mass tagging, untagging and deletion of droplets by ID, IP or tag.
- Keeps the public key with which you instantiate droplets synced to
DigitalOcean.
- **TODO: Unimplemented:** Runs hooks after any action.
## Installing
### Prerequisites
- Python 2.7+ with pip.
- [doctl](https://github.com/digitalocean/doctl) (follow their instructions).
- Make sure you authorise with `doctl auth login`.
- An SSH key pair.
- If it's not in the usual `~/.ssh/id_rsa`, see **environment
variables** below.
### Install
```
pip install dobro
```
You might need to stick a `sudo` behind this if on OS X. (which, let's face it,
you probably are, you little tart)
## Example: create a droplet
```
$ dobro create db postgres
[dobro - info] ssh-key: create: 'dobro-bro'
[dobro - info] droplet: create: 'bro-new-20160729232127-0'
Identity added: /Users/doug/.ssh/id_rsa (/Users/doug/.ssh/id_rsa)
[dobro - info] droplet: wait for ssh: 'bro-new-20160729232127-0'
[dobro - info] droplet: rename: 'bro-new-20160729232127-0' => 'bro-20957830'
Warning: Permanently added '139.59.189.41' (ECDSA) to the list of known hosts.
Connection to 139.59.189.41 closed.
[dobro - info] tag: create: 'db'
[dobro - info] tag: create: 'postgres'
[dobro - info] droplet: tag: 'bro-20957830' => 'db'
[dobro - info] droplet: tag: 'bro-20957830' => 'postgres'
```
And there you have it, a fresh droplet ready to be SSH'd into using your key and
tagged with `db` and `postgres`.
### What's happening here
By default, dobro will namespace all your droplets under `bro`. You can change
this by setting an environment variable (again see below). This namespace will
be prepended to all of your droplets' names, and it'll be the end of the name of
your SSH public key as stored on DigitalOcean (`dobro-bro`).
As you can see, dobro first checks whether your key exists on DigitalOcean. If
it doesn't, it creates it.*
Then it'll create your droplet, wait for its sshd to listen, and then swiftly
rename it droplet.**
This is because we want droplets to be named after their IDs - for simplicity's
sake - rather than anything else; we just use `<NAMESPACE>-new-<DATETIME>-<N>`
as a placeholder. So, in this example, this rename is from
`bro-new-20160729232127-0` to `bro-20957830`.
Tags are then created (if they don't already exist) and are applied to the
droplet. And that's it!
If you are indeed using automation and are now rearing to run some nifty Ansible
to configure your new droplet, you'll want to read about **default tags** and
**hooks** below.
#### Gotchas
\* DigitalOcean doesn't like storing the same public key under two names - so if
you get an error straight after `[dobro - info] ssh-key: create`, your key is
likely already stored on DigitalOcean. Either delete it or rename it to
`dobro-<NAMESPACE>`.
\*\* dobro makes sure to change your droplet's *hostname* as well as its name on
DigitalOcean. These are separate, annoyingly. Changing the hostname requires
SSH'ing into the droplet, which is why we wait for sshd to listen and then
automatically add it as a known host.
## Default tags
The environment variable `DOBRO_NEW_DROPLET_TAGS` can be set as a list of tags
(separated by whitespace) - eg. `"_new setup-needed"` - that will automatically
be applied to all droplets upon creation.
This is useful if there is any one-time setup you may need to do on a droplet,
such as locking down SSH access from droplets' default root login.
## Hooks
**TODO: Unimplemented.**
## Reference
### CLI
```
dobro create [-n|--droplet-count <NUMBER>] <TAGS>
```
Create droplet(s) with the specified tags.
`-n|--droplet-count <NUMBER>` specifies the number of droplets. By default, only
one is created.
`<TAGS>` specifies tags to apply, separated by whitespace.
---
```
dobro list [-a|--all]
```
Information listing on all droplets in namespace. This is just a filtered
`doctl compute droplet list` that'll also notify you if there are any droplets
*not* in your namespace.
`-a|--all` removes the filter.
---
```
dobro tag -c|--criteria <IDs|IPs|TAGS> -t|--tag <TAGS>
```
Adds the specified tags to all matched droplets.
`-c|--criteria` *(required)* specifies any number of IDs, IPv4 public addresses,
and tags.
- All droplets specified by ID or IP will be matched, regardless of how many
tags are specified (if any).
- Where tags are specified, only droplets with *all* of these tags will be
matched, *in addition* to droplets matched by ID or IP.
`-t|--tag` *(required)* specifies tags to apply, separated by whitespace.
---
```
dobro untag -c|--criteria <IDs|IPs|TAGS> -t|--tag <TAGS>
```
**Currently unimplemented until the fix for [digitalocean/doctl#119](https://github.com/digitalocean/doctl/issues/119) is
released.**
Removes the specified tags from all matched droplets.
Parameters as with `dobro tag`.
---
```
dobro ssh-key
```
Ensures your public key is up-to-date on DigitalOcean. This is done before any
`create` action too.
---
```
dobro delete <IDs|IPs|TAGS>
```
Deletes all matched droplets.
`<IDs|IPs|TAGS>` are criteria as with `dobro tag`.
---
```
dobro version
```
Displays version information.
---
#### Generic flags
`-v|--verbose` includes detailed program breakdown and debugging information in
output.
`-q|--quiet` suppresses all output except warnings and errors.
### Environment variables
Complete with defaults, here's what dobro pays attention to:
```
# Locations of your SSH keys.
DOBRO_SSH_PRIVATE_KEY="$HOME/.ssh/id_rsa"
DOBRO_SSH_PUBLIC_KEY="$DOBRO_SSH_PRIVATE_KEY.pub"
# Tags applied to all new droplets, separated by whitespace (eg. "new db").
DOBRO_NEW_DROPLET_TAGS=""
# Droplet creation flags.
DOBRO_NEW_DROPLET_FLAGS="--region lon1 --size 512mb --image ubuntu-14-04-x64"
```
### Constraints
- Tags must match `/[a-zA-Z][a-zA-Z0-9_-]+/`.
- DigitalOcean droplet IDs are always purely numeric.
