Updated README to reflect recent changes

This updates the README to include instructions about installation
with `ansible-galaxy`, and adds several new examples.
This commit is contained in:
Lars Kellogg-Stedman 2018-10-19 16:26:58 -04:00
parent e6edf87208
commit a853a212ab

View file

@ -1,18 +1,98 @@
# ansible-modules-bitwarden
Bitwarden integrations for Ansible
Bitwarden integration for Ansible.
## Installation
The easiest way to install this lookup plugin is to use the
`ansible-galaxy` command:
ansible-galaxy install git+https://github.com/c0sco/ansible-modules-bitwarden
This will place the `ansible-modules-bitwarden` role into
`$HOME/.ansible/roles`, where it will be available to all playbooks
you run on your system.
## Lookup plugin
Use `lookup()` with the `bitwarden` argument, followed by the items you want to retrieve. The default field is `password`, but any other field can be specified. If you need to specify the path to the Bitwarden CLI binary, use the `path` named argument. For example:
To use this plugin, you will need to activate it by including the role
in your play. For example:
- hosts: localhost
roles:
- ansible-modules-bitwarden
Use Ansible's `lookup()` function with the `bitwarden` argument,
followed by the items you want to retrieve. The default field is
`password`, but any other field can be specified using the `field`
named argument. If you need to specify the path to the Bitwarden CLI
binary, use the `path` named argument.
## Examples
### Get a single password
```yaml
# Get username for Slashdot and Google
- debug: msg="{{ lookup('bitwarden', 'Slashdot', 'Google', field='username', path='/not/in/my/path/bw') }}"
# Get password for Google
- debug:
msg: {{ lookup('bitwarden', 'Google') }}
```
If you want to run the plugin directly for testing, you must first specify the field, then list the items to fetch.
The above might result in:
```bash
lib/ansible/plugins/lookup/bitwarden.py username Google Slashdot
```
TASK [debug] *********************************************************
ok: [localhost] => {
"msg": "mysecret"
}
```
### Get a single username
```yaml
# Get username for Google
- debug:
msg: {{ lookup('bitwarden', 'Google', field='username' }}
```
The above might result in:
```
TASK [debug] *********************************************************
ok: [localhost] => {
"msg": "alice"
}
```
### See all available fields
```yaml
# Get all available fields for an entry
- debug:
msg: {{ lookup('bitwarden', 'Google', field='item' }}
```
The above might result in:
```
TASK [debug] *********************************************************
ok: [localhost] => {
"msg": {
"favorite": false,
"folderId": null,
"id": "12345678-0123-4321-0000-a97001342c31",
"login": {
"password": "mysecret",
"passwordRevisionDate": null,
"totp": null,
"username": "alice"
},
"name": "Google",
"notes": null,
"object": "item",
"organizationId": "87654321-1234-9876-0000-a96800ed2b47",
"revisionDate": "2018-10-19T19:20:17.923Z",
"type": 1
}
}
```