Community Sops Collection

The community.sops collection allows integrating mozilla/sops in Ansible.

mozilla/sops is a tool for encryption and decryption of files using secure keys (GPG, KMS). It can be leveraged in Ansible to provide an easy to use and flexible to manage way to manage ecrypted secrets' files.

Tested with Ansible

• devel
• latest 2.9 release
• latest 2.10 release

External requirements

You will need to install sops manually before using plugins provided by this collection.

Included content

This collection provides:

• a lookup plugin that allows looking up a sops-encrypted file content
• a vars plugin that allows loading Ansible vars from a sops-encrypted file

Using this collection

lookup plugin

The lookup plugin can be accessed with the community.sops.sops key.

Examples:

tasks:
  - name: Output secrets to screen (BAD IDEA!)
    debug:
        msg: "Content: {{ lookup('community.sops.sops', '/path/to/sops-encrypted-file.enc.yaml') }}"

  - name: Add SSH private key
    copy:
        content: "{{ lookup('community.sops.sops', user + '-id_rsa') }}"
        dest: /home/{{ user }}/.ssh/id_rsa
        owner: "{{ user }}"
        group: "{{ user }}"
        mode: 0600
    no_log: true  # avoid content to be written to log

See Lookup Plugins for more details on lookup plugins

vars plugin

Vars plugins only work in ansible >= 2.10 and require explicit enabling. One way to enable the plugin is by adding the following to the default section of your ansible.cfg:

vars_plugins_enabled = host_group_vars,community.sops.sops

See VARIABLE_PLUGINS_ENABLED for more details.

After the plugin is enabled, correctly named group and host vars files will be transparently decrypted with sops.

The files must end with one of these extensions:

• .sops.yaml
• .sops.yml
• .sops.json

Here is an example file structure

├── inventory/
│   ├── group_vars/
│   │   └── all.sops.yml
│   ├── host_vars/
│   │   └── server1.sops.yml
│   └── hosts
├── playbooks/
│   └── setup-server.yml
└── ansible.cfg

You could execute the playbook in this example with the following command. The sops vars files would be decrypted and used.

$ ansible-playbook playbooks/setup-server.yml -i inventory/hosts

Contributing to this collection

See CONTRIBUTING.md

Release notes

See CHANGELOG.rst.

Roadmap

Ansible Collections are required to adhere to Semantic Versioning. More details on versioning can be found in the Ansible docs.

TODO

• add a role providing sops installation (with version pinning)
• a full test suite
• testing on multiple Ansible versions

More information

• Ansible Collection overview
• Ansible User guide
• Ansible Developer guide
• Ansible Community code of conduct

Licensing

GNU General Public License v3.0 or later.

See COPYING to see the full text.