How-to: Hetzner Cloud Ansible modules

Introduction

In this how-to you will learn to use the hcloud Ansible modules (see Ansible » Hetzner.Hcloud). This includes how to create resources and how to do more complex scenarios like attaching a volume to a server.

Prerequisites

Hetzner Cloud API Token (see "Generating an API token")
Basic knowledge about the Hetzner Cloud
- Knowing what a server, an image, a server type and a volume is
Latest version of Ansible is installed and you have basic knowledge about it
hcloud-python installed (pip install hcloud)

Step 1 - Basic Usage

In Ansible you can control your infrastructure with YAML files. They describe the state of your infrastructure. These files are called "Roles". Every role can have tasks. A task is something like "create a server", "run a command on the server" or something else. You can control ansible with the ansible command.

To use the module, a task like the following is needed:

hcloud_server:
      api_token: "YOUR_API_TOKEN"
      name: my-server
      server_type: cpx11
      image: ubuntu-24.04
      location: ash
      state: present

Step 2 - Create a server

You have learned something about the basic usage of Ansible. Now we will show you, how you can create a new server with the hcloud_server module. First of all, you should save the following YAML as hcloud-server.yml.

This example includes the module:

hcloud_server

---
- name: Create Basic Server
  hosts: localhost
  connection: local
  gather_facts: False
  user: root
  vars:
    hcloud_token: YOUR_API_TOKEN
  tasks:
    - name: Create a basic server
      hcloud_server:
          api_token: "{{ hcloud_token }}"
          name: my-server
          server_type: cpx11
          image: ubuntu-24.04
          location: ash
          state: present
      register: server

The snippet will create a new server called my-server with the server type cpx11, the image ubuntu-24.04, and the location ash. The state is present so the module will create the server. When you run ansible-playbook -v hcloud-server.yml you should get an output similar to this below:

PLAY [Create Basic Server] *************************************************************************************************************************************************************************************************************

TASK [Create a basic server] ********************************************************************************************************************************************************************************************************************************
changed: [localhost] => {"changed": true, "hcloud_server": {"backup_window": null, "datacenter": "ash-dc1", "delete_protection": false, "id": "2505729", "image": "ubuntu-24.04", "ipv4_address": "<10.0.0.1>", "ipv6": "<2001:db8:1234::/64>", "labels": {}, "location": "ash", "name": "my-server", "placement_group": null, "private_networks": [], "private_networks_info": [], "rebuild_protection": false, "rescue_enabled": false, "server_type": "cpx11", "status": "running"}, "root_password": "xrLvkKwXTxNnECACdCEf"}

PLAY RECAP **************************************************************************************************************************************************************************************************************************************************
localhost                  : ok=1    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Congratulations! You have created your first Hetzner Cloud server with the hcloud_server- Ansible module! You should now see a server in your Hetzner Cloud Console.

Step 3 - Create a volume and attach it to a server

Now we create a server and a attach a volume to it. The following snippet creates a server (the server from Step 2!) and creates a new Volume which will be attached to the server. Save the following snippet as hcloud-server-volume.yml.

This example includes the modules:

hcloud_server

hcloud_volume

---
- name: Create a Server and a Volume with server
  hosts: localhost
  connection: local
  gather_facts: False
  user: root
  vars:
    hcloud_token: YOUR_API_TOKEN
  tasks:
    - name: Create a basic server
      hcloud_server:
          api_token: "{{ hcloud_token }}"
          name: my-server
          server_type: cpx11
          image: ubuntu-24.04
          location: ash
          state: present
      register: server
    - name: Create a volume
      hcloud_volume:
          api_token: "{{ hcloud_token }}"
          name: my-volume
          size: 10
          server: "{{ server.hcloud_server.name }}"
          state: present

When you now run ansible-playbook -v hcloud-server-volume.yml you will get a similar output like this:

PLAY [Create a Server and a Volume with server] *************************************************************************************************************************************************************************************************************

TASK [Create a basic server] ********************************************************************************************************************************************************************************************************************************
ok: [localhost] => {"changed": false, "hcloud_server": {"backup_window": null, "datacenter": "ash-dc1", "delete_protection": false, "id": "2505729", "image": "ubuntu-24.04", "ipv4_address": "<10.0.0.1>", "ipv6": "<2001:db8:1234::/64>", "labels": {}, "location": "ash", "name": "my-server", "placement_group": null, "private_networks": [], "private_networks_info": [], "rebuild_protection": false, "rescue_enabled": false, "server_type": "cpx11", "status": "running"}}

TASK [Create a volume] **************************************************************************************************************************************************************************************************************************************
changed: [localhost] => {"changed": true, "hcloud_volume": {"delete_protection": false, "id": "2489399", "labels": {}, "location": "ash", "name": "my-volume", "server": "my-server", "size": 10}}

PLAY RECAP **************************************************************************************************************************************************************************************************************************************************
localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

You have created a server and an attached volume!

Conclusion

You now have a basic overview of the Hetzner Cloud Ansible modules. We covered how you can create resources and how to do more complex scenarios like attaching a volume to a server. You can find more help on the official documentation. If you need further help, just open an issue in the Github Repository.

How-to: Hetzner Cloud Ansible modules

Author

Published

Time to read

Table of Contents