# hcloud_server – Create and manage cloud servers on the Hetzner Cloud

New in version 2.8.

- Synopsis
- Requirements
- Parameters
- See Also
- Examples
- Return Values
- Status

## Synopsis

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

## Requirements

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

- hcloud-python >= 1.0.0

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
api_token string / required |  | This is the API Token for the Hetzner Cloud.

backups
boolean

Choices:
- no ←
- yes

Enable or disable Backups for the given Server.

datacenter string |  | Datacenter of Server. Required of no location is given and server does not exists.
endpoint string | Default: "https://api.hetzner.cloud/v1" | This is the API Endpoint for the Hetzner Cloud.

force_upgrade
boolean

Choices:
- no ←
- yes

Force the upgrade of the server.
Power off the server if it is running on upgrade.

id integer |  | The ID of the Hetzner Cloud server to manage. Only required if no server name is given
image string |  | Image the server should be created from. Required if server does not exists.
labels dictionary |  | User-defined labels (key-value pairs).
location string |  | Location of Server. Required if no datacenter is given and server does not exists.
name string |  | The Name of the Hetzner Cloud server to manage. Only required if no server id is given or a server does not exists.
rescue_mode string added in 2.9 |  | Add the Hetzner rescue system type you want the server to be booted into.
server_type string |  | The Server Type of the Hetzner Cloud server to manage. Required if server does not exists.
ssh_keys list |  | List of SSH key names The key names correspond to the SSH keys configured for your Hetzner Cloud account access.

state
string

Choices:
- absent
- present ←
- restarted
- started
- stopped
- rebuild

State of the server.

upgrade_disk
boolean

Choices:
- no ←
- yes

Resize the disk size, when resizing a server.
If you want to downgrade the server later, this value should be False.

user_data string |  | User Data to be passed to the server on creation. Only used if server does not exists.
volumes list |  | List of Volumes IDs that should be attached to the server on server creation.

## See Also

See also

Documentation for Hetzner Cloud API
  Complete reference for the Hetzner Cloud API.

## Examples

    - name: Create a basic server
      hcloud_server:
        name: my-server
        server_type: cx11
        image: ubuntu-18.04
        state: present

    - name: Create a basic server with ssh key
      hcloud_server:
        name: my-server
        server_type: cx11
        image: ubuntu-18.04
        location: fsn1
        ssh_keys:
          - me@myorganisation
        state: present

    - name: Resize an existing server
      hcloud_server:
        name: my-server
        server_type: cx21
        upgrade_disk: yes
        state: present

    - name: Ensure the server is absent (remove if needed)
      hcloud_server:
        name: my-server
        state: absent

    - name: Ensure the server is started
      hcloud_server:
        name: my-server
        state: started

    - name: Ensure the server is stopped
      hcloud_server:
        name: my-server
        state: stopped

    - name: Ensure the server is restarted
      hcloud_server:
        name: my-server
        state: restarted

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

    - name: Ensure the server is rebuild
      hcloud_server:
        name: my-server
        image: ubuntu-18.04
        state: rebuild

## Return Values

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

Key | Returned | Description
--- | --- | ---
hcloud_server complex | Always | The server instance
| backup_window boolean | always | Time window (UTC) in which the backup will run, or null if the backups are not enabled Sample: 22-02
| datacenter string | always | Name of the datacenter of the server Sample: fsn1-dc14
| id integer | always | Numeric identifier of the server Sample: 1937415
| ipv4_address string | always | Public IPv4 address of the server Sample: 116.203.104.109
| ipv6 string | always | IPv6 network of the server Sample: 2a01:4f8:1c1c:c140::/64
| labels dictionary | always | User-defined labels (key-value pairs)
| location string | always | Name of the location of the server Sample: fsn1
| name string | always | Name of the server Sample: my-server
| rescue_enabled boolean | always | True if rescue mode is enabled, Server will then boot into rescue system on next reboot
| server_type string | always | Name of the server type of the server Sample: cx11
| status string | always | Status of the server Sample: running

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Lukas Kaemmerling (@LKaemmerling)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.