ansible/README.md

# 📗 do-ansible-inventory

do-ansible-inventory is a tool that generates an [Ansible inventory](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html) file with your DigitalOcean Droplets. It is an alternative to [dynamic inventories](https://docs.ansible.com/ansible/latest/user_guide/intro_dynamic_inventory.html#intro-dynamic-inventory) as you can run do-ansible-inventory once and receive a static inventory file that you can use anywhere, copy, or modify.

## Installation

1. Download the latest release from [the releases page](https://github.com/do-community/do-ansible-inventory/releases).
2. Extract the downloaded archive and place the binary `do-ansible-inventory` wherever you like. Preferably to any directory in your `$PATH` such as `~/bin` if it exists or `/usr/local/bin` so you can easily access it.

## Usage

To use do-ansible-inventory, run:

```
do-ansible-inventory
```

By default, without setting any options, do-ansible-inventory will attempt to look up the currently configured [doctl](https://github.com/digitalocean/doctl) access token and generate an ansible inventory with:

* All of your Droplets as Ansible hosts
* Each DigitalOcean region as an Ansible group containing any Droplets in that region
* Each Droplet tag as a group containing any Droplets with that tag

If you do not have `doctl` installed or would like to explicitly specify the access token, run `do-ansible-inventory --access-token ACCESS_TOKEN` or use the `DIGITALOCEAN_ACCESS_TOKEN` environment variable.

The resulting inventory will be printed to the console. You can save it to a file instead by passing `--out inventory` or redirecting the output like so: `do-ansible-inventory > inventory`.

### Supported Options

* `-t TOKEN`, `--access-token TOKEN` - DigitalOcean API Token - if unset, do-ansible-inventory attempts to use doctl's stored token of its current default context. Alternatively, use the environment variable `DIGITALOCEAN_ACCESS_TOKEN`
* `--ssh-user USER` - sets the `ansible_user` property on the hosts (Droplets)
* `--ssh-port PORT` - sets the `ansible_port` property on the hosts (Droplets)
* `--tag TAG` - limits the inventory to only Droplets with the specified tag
* `--ignore HOSTNAME` - pass a Droplet's hostname to exclude it from the inventory. **This option can be used multiple times**
* `--group-by-region` - create groups for each DigitalOcean region. Default behavior.
   * `--no-group-by-region` - do not create groups for each DigitalOcean region.
* `--group-by-tag` - create groups for each Droplet tag. Default behavior.
   * `--no-group-by-tag` - do not create groups for each Droplet tag. 
* `--group-by-project` - create groups for each Droplet projects. Default behavior.
   * `--no-group-by-project` - do not create groups for each Droplet project. 
* `--private-ips` - use private Droplet IPs instead of public IPs
* `--out FILE` - write the ansible inventory to this file - if unset, print to stdout
* `--timeout=2m` - timeout for total runtime of the command, defaults to `2m`

## Example

Running:

```
$ do-ansible-inventory --out ./inventory
```

will output:

```
   • no access token provided, attempting to look up doctl's access token
   • using doctl access token  context=default
   • processing                droplet=speedtest-ams2.digitalocean.com
   • processing                droplet=speedtest-nyc2.digitalocean.com
   • processing                droplet=speedtest-sfo1.digitalocean.com
   • processing                droplet=speedtest-ams3.digitalocean.com
   • processing                droplet=speedtest-blr1.digitalocean.com
   • processing                droplet=speedtest-fra1.digitalocean.com
   • processing                droplet=speedtest-lon1.digitalocean.com
   • processing                droplet=speedtest-nyc1.digitalocean.com
   • processing                droplet=speedtest-nyc3.digitalocean.com
   • processing                droplet=speedtest-sfo2.digitalocean.com
   • processing                droplet=speedtest-sgp1.digitalocean.com
   • processing                droplet=speedtest-tor1.digitalocean.com
   • building region group     region=ams1
   • building region group     region=ams2
   • building region group     region=ams3
   • building region group     region=blr1
   • building region group     region=fra1
   • building region group     region=lon1
   • building region group     region=nyc1
   • building region group     region=nyc2
   • building region group     region=nyc3
   • building region group     region=sfo1
   • building region group     region=sfo2
   • building region group     region=sfo3
   • building region group     region=sgp1
   • building region group     region=tor1
   • building tag group        tag=speedtests
   • done!
```

with the resulting file `inventory` containing:

```
speedtest-ams2.digitalocean.com ansible_host=188.226.175.227
speedtest-nyc2.digitalocean.com ansible_host=192.241.184.88
speedtest-sfo1.digitalocean.com ansible_host=107.170.223.15
speedtest-ams3.digitalocean.com ansible_host=178.62.216.76
speedtest-blr1.digitalocean.com ansible_host=139.59.80.215
speedtest-fra1.digitalocean.com ansible_host=46.101.218.147
speedtest-lon1.digitalocean.com ansible_host=46.101.44.214
speedtest-nyc1.digitalocean.com ansible_host=165.227.194.167
speedtest-nyc3.digitalocean.com ansible_host=174.138.51.137
speedtest-sfo2.digitalocean.com ansible_host=165.227.29.84
speedtest-sgp1.digitalocean.com ansible_host=159.89.192.182
speedtest-tor1.digitalocean.com ansible_host=159.203.57.38

[ams1]

[ams2]
speedtest-ams2.digitalocean.com

[ams3]
speedtest-ams3.digitalocean.com

[blr1]
speedtest-blr1.digitalocean.com

[fra1]
speedtest-fra1.digitalocean.com

[lon1]
speedtest-lon1.digitalocean.com

[nyc1]
speedtest-nyc1.digitalocean.com

[nyc2]
speedtest-nyc2.digitalocean.com

[nyc3]
speedtest-nyc3.digitalocean.com

[sfo1]
speedtest-sfo1.digitalocean.com

[sfo2]
speedtest-sfo2.digitalocean.com

[sfo3]

[sgp1]
speedtest-sgp1.digitalocean.com

[tor1]

[speedtests]
speedtest-ams2.digitalocean.com
speedtest-nyc2.digitalocean.com
speedtest-sfo1.digitalocean.com
speedtest-ams3.digitalocean.com
speedtest-blr1.digitalocean.com
speedtest-fra1.digitalocean.com
speedtest-lon1.digitalocean.com
speedtest-nyc1.digitalocean.com
speedtest-nyc3.digitalocean.com
speedtest-sfo2.digitalocean.com
speedtest-sgp1.digitalocean.com
speedtest-tor1.digitalocean.com
```

---

```
usage: do-ansible-inventory [<flags>]

Flags:
  -t, --access-token=ACCESS-TOKEN  
                           DigitalOcean API Token - if unset, attempts to use doctl's stored token of its current default context. env var:
                           DIGITALOCEAN_ACCESS_TOKEN
      --ssh-user=SSH-USER  default ssh user
      --ssh-port=SSH-PORT  default ssh port
      --tag=TAG            filter droplets by tag
      --ignore=IGNORE ...  ignore a Droplet by name, can be specified multiple times
      --group-by-region    group hosts by region, defaults to true
      --group-by-tag       group hosts by their Droplet tags, defaults to true
      --group-by-project   group hosts by their Projects, defaults to true
      --private-ips        use private Droplet IPs instead of public IPs
      --out=OUT            write the ansible inventory to this file - if unset, print to stdout
      --timeout=2m         timeout for total runtime of the command, defaults to 2m
```