> ## Documentation Index
> Fetch the complete documentation index at: https://www.1password.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Ansible
The [1Password Connect Ansible collection ](https://github.com/1Password/ansible-onepasswordconnect-collection) contains modules that allow you to interact with your 1Password Connect deployment from [Ansible ](https://docs.ansible.com/ansible/latest/getting_started/basic_concepts.html) playbooks. The modules communicate with the [Connect API](/connect/api-reference/) to support managing 1Password vaults and items through create, read, update, and delete operations.
## Requirements
You must complete the following requirements before you can use the 1Password Connect Ansible collection:
* [Create and deploy a Connect server.](/connect/get-started/#step-1)
* Install [Ansible ](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) version 7.x or later.
* Install [Ansible Core ](https://docs.ansible.com/core.html) version 2.14 or later.
* Install [Python ](https://www.python.org/downloads/) version 3.8 or later.
## Get started
Use the following instructions to get started with the 1Password Ansible collection:
1. [Install the 1Password collection.](#step-1-install-the-collection)
2. [Use the 1Password collection in an Ansible playbook.](#step-2-use-the-collection-in-an-ansible-task)
3. Explore the [example playbooks](#examples).
### Step 1: Install the collection
Install the `onepassword.connect` collection from [Ansible Galaxy. ](https://galaxy.ansible.com/onepassword/connect)
```shell theme={null}
ansible-galaxy collection install onepassword.connect
```
The 1Password Ansible collection is also available for the [Red Hat Ansible Automation Platform. ](https://www.redhat.com/en/technologies/management/ansible)
### Step 2: Use the collection in an Ansible task
Use the `onepassword.connect` collection in an Ansible task:
1. Add `onepassword.connect` to the task `collections`.
```yaml playbook.yaml highlight={2} theme={null}
collections:
- onepassword.connect # Specify the 1Password collection
```
2. Provide the [Connect server access token](/connect/concepts#connect-server-access-token) using the `token` variable in the Ansible task or the `OP_CONNECT_TOKEN` environment variable. You must set this value in each Ansible task.
It's [best practice](#sensitive-data) to use a local variable to provide the Connect server access token because it's [more secure. ](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_environment.html#working-with-language-specific-version-managers) The following example sets the `connect_token` variable to the Connect token value, then references it for the `token` field.
```yaml playbook.yaml highlight={2,7} theme={null}
vars:
connect_token: "" # Set the Connect server access token
collections:
- onepassword.connect # Specify the 1Password collection
tasks:
- onepassword.connect.generic_item:
token: "{{ connect_token }}"
```
3. Provide the Connect server hostname, IP address, or URL through the `hostname` variable in the Ansible task or the `OP_CONNECT_HOST` environment variable. You must set this value in each Ansible task.
```yaml playbook.yaml highlight={2} theme={null}
environment:
OP_CONNECT_HOST: # Set the Connect server hostname
collections:
- onepassword.connect # Specify the 1Password collection
```
## Examples
Explore the following examples to learn how to perform specific tasks:
* [Create an item.](#create-an-item)
* [Update an item.](#update-an-item)
* [Find an item by name.](#find-an-item-by-name)
* [Get the value of a field.](#get-the-value-of-a-field)
### Create an item
The following example uses the [`generic_item` module](#generic_item) to create a 1Password item. It also creates the `Random Code` value with a custom `generator_recipe`.
```yaml playbook.yaml theme={null}
- name: Create 1Password Secret
hosts: localhost
vars:
connect_token: "" # Set the Connect server access token
environment:
OP_CONNECT_HOST: # Set the Connect server hostname
collections:
- onepassword.connect # Specify the 1Password collection
tasks:
- onepassword.connect.generic_item:
token: "{{ connect_token }}" # Pass the Connect server access token variable
vault_id: "" # Set the 1Password vault ID
title: Club Membership
state: present
fields:
- label: Codeword
value: "hunter2"
section: "Personal Info"
field_type: concealed
- label: Random Code
generate_value: on_create # Generate the value on creation
generator_recipe:
length: 16
include_symbols: no
no_log: true # Turn off logs to avoid logging sensitive data
register: op_item # Note: register is Ansible syntax
```
### Update an item
The following example uses the [`generic_item` module](#generic_item) to update a 1Password item. It also sets the `generate_value` setting to `always`, which means 1Password generates a new value for the field each time you run the playbook.
The update operation completely replaces the item matching the `title` or `uuid` field. You will lose any properties that you don't provide in the task definition.
To avoid losing data, store the items created by Ansible in a vault that's scoped in a way that only the Connect server can access it.
```yaml playbook.yaml theme={null}
- name: Update a 1Password Secret
hosts: localhost
vars:
connect_token: "" # Set the Connect server access token
environment:
OP_CONNECT_HOST: # Set the Connect server hostname
OP_VAULT_ID: "" # Set the 1Password vault ID
collections:
- onepassword.connect # Specify the 1Password collection
tasks:
- onepassword.connect.generic_item:
token: "{{ connect_token }}" # Pass the Connect server access token variable
title: Club Membership
# uuid: 1ff75fa9fexample -- or use an Item ID to locate an item instead
state: present
fields:
- label: Codeword
field_type: concealed
- label: Dashboard Password
generate_value: always # Generate a new value every time the playbook runs
generator_recipe: # Provide a custom password recipe
length: 16
include_symbols: no
no_log: true # Turn off logs to avoid logging sensitive data
```
### Find an item by name
The following example uses the [`item_info` module](#item_info) to find a 1Password item by name.
```yaml playbook.yaml theme={null}
hosts: localhost
vars:
connect_token: "" # Set the Connect server access token
environment:
OP_CONNECT_HOST: # Set the Connect server hostname
collections:
- onepassword.connect # Specify the 1Password collection
tasks:
- name: Find the item with the label "Staging Database" in the vault "Staging Env"
item_info:
token: "{{ connect_token }}"
item: Staging Database
vault: Staging Env
no_log: true # Turn off logs to avoid logging sensitive data
register: op_item
```
### Get the value of a field
The following example uses the [`field_info` module](#field_info) to get the value of a specific field in a 1Password item.
```yaml playbook.yaml theme={null}
hosts: localhost
vars:
connect_token: "" # Set the Connect server access token
environment:
OP_CONNECT_HOST: # Set the Connect server hostname
collections:
- onepassword.connect # Specify the 1Password collection
tasks:
- name: Find a field labeled "username" in an item named "MySQL Database" in a specific vault
field_info:
token: "{{ connect_token }}" # Pass the Connect token variable
item: MySQL Database
field: username
vault: # Set the 1Password vault ID
no_log: true # Turn off logs to avoid logging sensitive data
register: op_item
- name: Print the field definition
ansible.builtin.debug:
msg: "{{ op_item.field }}"
```
## Reference
Refer to the following sections to learn about the available [variables](#variables) and [modules](#modules).
### Variables
All [modules](#modules) support the following variable definitions. You can either explicitly define the value on the Ansible task or let Ansible fall back to an environment variable to use the same value across all tasks.
| Module variable | Environment variable | Description |
| --------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
| `hostname` | `OP_CONNECT_HOST` | Specifies the hostname, IP address, or URL where your Connect server is deployed. |
| `token` | `OP_CONNECT_TOKEN` | Specifies the string value of your Connect server access token. |
| `vault_id` | `OP_VAULT_ID` | (Optional) The UUID of a 1Password vault. It must be a vault the Connect server token has access to. |
Module variables take precedence over environment variables. If you plan to use an environment variable, make sure the corresponding module variable is absent.
### Modules
The 1Password Ansible collection has the following modules:
* [`generic_item` module](#generic_item)
* [`item_info` module](#item_info)
* [`field_info` module](#field_info)
#### `generic_item`
You can use the `generic_item` module to create, update, and delete 1Password items.
**State is important**
The `generic_item` module follows [Ansible's `present`/`absent` state pattern. ](https://docs.ansible.com/ansible/2.8/user_guide/playbooks_best_practices.html#always-mention-the-state)
Behavior when the state is `present` (`state: present`):
* If the module can't find a matching item by its `uuid` or `title`, it creates a new item with the defined values.
* If the module finds a matching item on the server, it completely replaces the old item with a new item defined by the playbook values.
Behavior when the state is `absent` (`state: absent`):
* If the module can't find the item by its `uuid` or `title`, no action is taken.
* If the module finds an item matching the `uuid` or `title`, it deletes the item. Otherwise, no action is taken.
When you use the `generic_item` module to create or update a 1Password item, you can have 1Password generate a field's value. You can specify one of three settings for `generate_value`:
| `generate_value` setting | Effect |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `never` **(Default)** | Don't generate the field value. Use the `value` parameter instead. |
| `on_create` | Generate the value when creating the field. |
| `always` | Generate a new value for the field every time the playbook is run. Overwrites the `value` parameter. |
The following example generates a value (with a custom recipe) for the `Random Code` field by using the `on_create` setting and supplying a custom `generator_recipe`.
```yaml playbook.yaml highlight={20-24} theme={null}
- name: Create 1Password Secret
hosts: localhost
vars:
connect_token: "" # Set the Connect server access token
environment:
OP_CONNECT_HOST: # Set the Connect server hostname
collections:
- onepassword.connect # Specify the 1Password collection
tasks:
- onepassword.connect.generic_item:
token: "{{ connect_token }}" # Pass the Connect token variable
vault_id: "" # Set the 1Password vault ID (optional)
title: Club Membership
state: present
fields:
- label: Codeword
value: "hunter2"
section: "Personal Info"
field_type: concealed
- label: Random Code
generate_value: on_create # Generate the field value on creation
generator_recipe: # Provide a custom password recipe
length: 16
include_digits: no
no_log: true # Turn off logs to avoid logging sensitive data
register: op_item
```
#### `item_info`
Use the `item_info` module to search for or get information about a 1Password item (such as the fields or metadata).
When you search for an item, 1Password first searches for the `uuid` (if it's provided), then searches for the `title`. When searching for an item by its `title`, the module uses a case-sensitive, exact-match query.
#### `field_info`
Use the `onepassword.connect.field_info` module to get the value of an item field.
The `field_info` module first finds the item by title or UUID, then searches for the requested field by name. If you provide a `section`, the module only searches within that item section. If you don't provide a section, the field name must be unique within the item.
The search method compares field names using the [`unicodedata.normalize` ](https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) function and the `NKFD` form.
## Best practices
Consider the following best practices when using the 1Password Ansible collection.
* [Turn off task logging.](#turn-off-task-logging)
* [Avoid using environment variables for sensitive information.](#sensitive-data)
### Turn off task logging
It's best practice to turn off task logging for any tasks that interact with 1Password Connect. Ansible might print sensitive information if `no_log` is unset or set to `false`.
To turn off logging, set `no_log` to `true`:
```yaml playbook.yaml highlight={9} theme={null}
collections:
- onepassword.connect # Specify the 1Password collection
tasks:
- name: Find the item with the label "Staging Database" in the vault "Staging Env"
item_info:
token: "{{ connect_token }}" # Pass the Connect token variable
item: Staging Database
vault: Staging Env
no_log: true # Turn off logs to avoid logging sensitive data
register: op_item
```
Avoid using environment variables for sensitive information
It's best practice to use a local variable to set sensitive information, such as the Connect server access token, because [Ansible environment variables ](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_environment.html) are normally passed in plain text.