hetzner.hcloud.server module – Create and manage cloud servers on the Hetzner Cloud.

Note

This module is part of the hetzner.hcloud collection (version 4.2.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install hetzner.hcloud. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: hetzner.hcloud.server.

Synopsis

  • Create, update and manage cloud servers on the Hetzner Cloud.

Aliases: hcloud_server

Requirements

The below requirements are needed on the host that executes this module.

  • python-dateutil >= 2.7.5

  • requests >=2.20

Parameters

Parameter

Comments

api_endpoint

aliases: endpoint

string

The API Endpoint for the Hetzner Cloud.

You can also set this option by using the HCLOUD_ENDPOINT environment variable.

Default: "https://api.hetzner.cloud/v1"

api_token

string / required

The API Token for the Hetzner Cloud.

You can also set this option by using the HCLOUD_TOKEN environment variable.

backups

boolean

Enable or disable Backups for the given Server.

Choices:

  • false

  • true

datacenter

string

Hetzner Cloud Datacenter (name or ID) to create the server in.

Required if no location is given and server does not exist.

Only used during the server creation.

delete_protection

boolean

Protect the Server for deletion.

Needs to be the same as rebuild_protection.

Choices:

  • false

  • true

enable_ipv4

boolean

Enables the public ipv4 address.

Choices:

  • false

  • true ← (default)

enable_ipv6

boolean

Enables the public ipv6 address.

Choices:

  • false

  • true ← (default)

firewalls

list / elements=string

List of Hetzner Cloud Firewalls (name or ID) that should be attached to the server.

force

aliases: force_upgrade

boolean

Force the update of the server.

May power off the server if update is applied.

Choices:

  • false ← (default)

  • true

id

integer

ID of the Hetzner Cloud Server to manage.

Only required if no server name is given

image

string

Hetzner Cloud Image (name or ID) to create the server from.

Required if server does not exist or when state=rebuild.

image_allow_deprecated

aliases: allow_deprecated_image

boolean

Allows the creation of servers with deprecated images.

Choices:

  • false ← (default)

  • true

ipv4

string

Hetzner Cloud Primary IPv4 (name or ID) to use.

If omitted and enable_ipv4=true, a new ipv4 Primary IP will automatically be created.

ipv6

string

Hetzner Cloud Primary IPv6 (name or ID) to use.

If omitted and enable_ipv6=true, a new ipv6 Primary IP will automatically be created.

labels

dictionary

User-defined labels (key-value pairs).

location

string

Hetzner Cloud Location (name or ID) to create the server in.

Required if no datacenter is given and server does not exist.

Only used during the server creation.

name

string

Name of the Hetzner Cloud Server to manage.

Only required if no server id is given or a server does not exist.

placement_group

string

Hetzner Cloud Placement Group (name or ID) to create the server in.

private_networks

list / elements=string

List of Hetzner Cloud Networks (name or ID) the server should be attached to.

If None, private networks are left as they are (e.g. if previously added by hcloud_server_network), if it has any other value (including []), only those networks are attached to the server.

rebuild_protection

boolean

Protect the Server for rebuild.

Needs to be the same as delete_protection.

Choices:

  • false

  • true

rescue_mode

string

Add the Hetzner rescue system type you want the server to be booted into.

server_type

string

Hetzner Cloud Server Type (name or ID) of the server.

Required if server does not exist.

ssh_keys

list / elements=string

List of Hetzner Cloud SSH Keys (name or ID) to create the server with.

Only used during the server creation.

state

string

State of the server.

Choices:

  • "absent"

  • "present" ← (default)

  • "restarted"

  • "started"

  • "stopped"

  • "rebuild"

upgrade_disk

boolean

Resize the disk size, when resizing a server.

If you want to downgrade the server later, this value should be False.

Choices:

  • false ← (default)

  • true

user_data

string

User Data to be passed to the server on creation.

Only used during the server creation.

volumes

list / elements=string

List of Hetzner Cloud Volumes (name or ID) that should be attached to the server.

Only used during the server creation.

See Also

See also

Documentation for Hetzner Cloud API

Complete reference for the Hetzner Cloud API.

Examples

- name: Create a basic server
  hetzner.hcloud.server:
    name: my-server
    server_type: cx22
    image: ubuntu-22.04
    state: present

- name: Create a basic server with ssh key
  hetzner.hcloud.server:
    name: my-server
    server_type: cx22
    image: ubuntu-22.04
    location: fsn1
    ssh_keys:
      - me@myorganisation
    state: present

- name: Resize an existing server
  hetzner.hcloud.server:
    name: my-server
    server_type: cx32
    upgrade_disk: true
    state: present

- name: Ensure the server is absent (remove if needed)
  hetzner.hcloud.server:
    name: my-server
    state: absent

- name: Ensure the server is started
  hetzner.hcloud.server:
    name: my-server
    state: started

- name: Ensure the server is stopped
  hetzner.hcloud.server:
    name: my-server
    state: stopped

- name: Ensure the server is restarted
  hetzner.hcloud.server:
    name: my-server
    state: restarted

- name: Ensure the server is will be booted in rescue mode and therefore restarted
  hetzner.hcloud.server:
    name: my-server
    rescue_mode: linux64
    state: restarted

- name: Ensure the server is rebuild
  hetzner.hcloud.server:
    name: my-server
    image: ubuntu-22.04
    state: rebuild

- name: Add server to placement group
  hetzner.hcloud.server:
    name: my-server
    placement_group: my-placement-group
    force: true
    state: present

- name: Remove server from placement group
  hetzner.hcloud.server:
    name: my-server
    placement_group:
    state: present

- name: Add server with private network only
  hetzner.hcloud.server:
    name: my-server
    enable_ipv4: false
    enable_ipv6: false
    private_networks:
      - my-network
      - 4711
    state: present

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

hcloud_server

complex

The server instance

Returned: Always

backup_window

boolean

Time window (UTC) in which the backup will run, or null if the backups are not enabled

Returned: always

Sample: "22-02"

created

string

Point in time when the Server was created (in ISO-8601 format)

Returned: always

Sample: "2023-11-06T13:36:56+00:00"

datacenter

string

Name of the datacenter of the server

Returned: always

Sample: "fsn1-dc14"

delete_protection

boolean

added in hetzner.hcloud 0.1.0

True if server is protected for deletion

Returned: always

Sample: false

id

integer

Numeric identifier of the server

Returned: always

Sample: 1937415

ipv4_address

string

Public IPv4 address of the server

Returned: always

Sample: "116.203.104.109"

ipv6

string

IPv6 network of the server

Returned: always

Sample: "2a01:4f8:1c1c:c140::/64"

labels

dictionary

User-defined labels (key-value pairs)

Returned: always

location

string

Name of the location of the server

Returned: always

Sample: "fsn1"

name

string

Name of the server

Returned: always

Sample: "my-server"

placement_group

string

added in hetzner.hcloud 1.5.0

Placement Group of the server

Returned: always

Sample: "4711"

private_networks

list / elements=string

List of private networks the server is attached to (name or ID)

Returned: always

Sample: ["my-network", "another-network", "4711"]

private_networks_info

list / elements=dictionary

List of private networks the server is attached to (dict with name and ip)

Returned: always

Sample: [{"ip": "192.168.1.1", "name": "my-network"}, {"ip": "10.185.50.40", "name": "another-network"}]

rebuild_protection

boolean

added in hetzner.hcloud 0.1.0

True if server is protected for rebuild

Returned: always

Sample: false

rescue_enabled

boolean

True if rescue mode is enabled, Server will then boot into rescue system on next reboot

Returned: always

Sample: false

server_type

string

Name of the server type of the server

Returned: always

Sample: "cx22"

status

string

Status of the server

Returned: always

Sample: "running"

Authors

  • Lukas Kaemmerling (@LKaemmerling)