Handling Home Assistant Configurations with Ansible

Mon Jan 3, 2022 · 426 words · 3 min

---

I have just recently published a lightweight Ansible role that I use to manage my Home Assistant config files. I have a code repository where I keep my config files (like automations.yaml, for example), but sometimes I just like to change things manually in the Home Assistant UI. Then I want to make sure that my local files and those that are actually active are in sync. I had a couple of Ansible playbooks for this, which I have condensed into a role now.

Assumptions

I assume that you have some basic knowledge about Ansible. If not, you might want to have a look at our very introductory words on Ansible. From there, you'll find the way.

Example

Imagine a directory layout like this:

.
├── files
│└── home_assistant
│     └── automations.yaml
├── inventory
├── playbook-hass-control.yml
└── templates
    └── secrets.yaml.j2

automations.yaml - Your Home Assistant automations

---
# awesome automations go here

inventory - Your Ansible inventory

home_assistant ansible_host=your-home-assistant-url

secrets.yaml.j2 - A template that will be rendered to secrets.yaml

---
# secrets might go here

The playbook-hass-control.yml

This is the actual playbook that will execute the role. Make sure that you install the role on your machine beforehand by running ansible-galaxy role install bellackn.hass_control. You will also need an API token to use your Home Assistant's API. You can get one by logging in to Home Assistant, clicking on your profile and then scrolling down to the bottom of the page. There you can create long-lived tokens.

---
- name: Set or get various Home Assistant configurations
  hosts: home_assistant
  gather_facts: no
  vars:
    hass_control_config_files:
      - automations
    hass_control_config_templates:
      - secrets
    hass_control_home_assistant_auth_token: token-you-have-grabbed-from-home-assistant

  roles:
    - bellackn.hass_control

There are some defaults in the role that you might want to override, just check the project's README.

If you run the playbook above, it will download the current automations.yaml from your Home Assistant host and update the file in your repository. If you didn't specify anything else, the path will be files/home_assistant/automations.yaml.

If you run the playbook with -e hass_control_mode=set, it will upload the automations.yaml config file to Home Assistant. Also it will render the secrets.yaml.j2 template and upload it. If there are changes on the remote host, the role will restart Home Assistant to make sure the changes take effect. Using templates like secrets.yaml is a handy tool if you have configurations that will be composed on Ansible execution by collecting various variables. For example, my secrets.yaml.j2 looks like this:

---
telegram_bot_api_key: { { home_assistant_telegram_bot_api_key } }

This way, I don't have to commit credentials to my repository in clear text since I can encrpyt them using Ansible Vault.

That's it already. This role helps me to keep track of my configuration files, and I'd be happy if it seems useful to you, too.