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:
---
- 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:
---
- 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.