hetzner.hcloud.primary_ip module – Create and manage cloud Primary IPs on the Hetzner Cloud.

Note

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

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

New in hetzner.hcloud 1.8.0

Synopsis
Requirements
Parameters
See Also
Examples
Return Values

Synopsis

Create, update and manage cloud Primary IPs on the Hetzner Cloud.
To manage the DNS pointer of a Primary IP, use the hetzner.hcloud.rdns module.

Aliases: hcloud_primary_ip

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 endpoint for the Hetzner Cloud API. You can also set this option by using the `HCLOUD_ENDPOINT` environment variable. Default: `"https://api.hetzner.cloud/v1"`
api_endpoint_hetzner string	The endpoint for the Hetzner API. You can also set this option by using the `HETZNER_ENDPOINT` environment variable. Default: `"https://api.hetzner.com/v1"`
api_token string / required	The token for the Hetzner Cloud API. You can also set this option by using the `HCLOUD_TOKEN` environment variable.
auto_delete boolean	Delete the Primary IP when the resource it is assigned to is deleted. Choices: `false` ← (default) `true`
datacenter string	Deprecated: The `datacenter` argument is deprecated and will be removed after 1 July 2026. Please use the `location` argument instead. See https://docs.hetzner.cloud/changelog#2025-12-16-phasing-out-datacenters. Home Location of the Hetzner Cloud Primary IP. Required if no `server` or `location` is given and Primary IP does not exist.
delete_protection boolean	Protect the Primary IP for deletion. Choices: `false` `true`
id integer	The ID of the Hetzner Cloud Primary IPs to manage. Only required if no Primary IP `name` is given.
labels dictionary	User-defined labels (key-value pairs).
location string	ID or name of the Location the Hetzner Cloud Primary IP will be bound to. Required if no `server` or `datacenter` is given and Primary IP does not exist.
name string	The Name of the Hetzner Cloud Primary IPs to manage. Only required if no Primary IP `id` is given or a Primary IP does not exist.
server string	Name or ID of the Hetzner Cloud Server the Primary IP should be assigned to. The Primary IP cannot be assigned to a running server. Required if no `datacenter` is given and the Primary IP does not exist. Use `null` to unassign the Primary IP from the server.
state string	State of the Primary IP. Choices: `"absent"` `"present"` ← (default)
type string	Type of the Primary IP. Required if Primary IP does not exist Choices: `"ipv4"` `"ipv6"`

Examples

- name: Create a IPv4 Primary IP
  hetzner.hcloud.primary_ip:
    name: my-primary-ip
    location: fsn1
    type: ipv4
    state: present

- name: Create a IPv6 Primary IP
  hetzner.hcloud.primary_ip:
    name: my-primary-ip
    location: fsn1
    type: ipv6
    state: present

- name: Delete a Primary IP
  hetzner.hcloud.primary_ip:
    name: my-primary-ip
    state: absent

- name: Ensure the server is stopped
  hetzner.hcloud.server:
    name: my-server
    state: stopped
- name: Create a Primary IP attached to a Server
  hetzner.hcloud.primary_ip:
    name: my-primary-ip
    server: my-server
    type: ipv4
    state: present
- name: Ensure the server is started
  hetzner.hcloud.server:
    name: my-server
    state: started

- name: Unassign a Primary IP from a Server
  hetzner.hcloud.primary_ip:
    name: my-primary-ip
    type: ipv4
    server: null
    state: present

Return Values

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

Key	Description
hcloud_primary_ip dictionary	The Primary IP instance Returned: Always
assignee_id integer	ID of the resource where the Primary IP is assigned to, none if unassigned. Returned: always Sample: `19584637`
assignee_type string	Type of the resource where the Primary IP is assigned to. Returned: always Sample: `"server"`
auto_delete boolean	Delete the Primary IP when the resource it is assigned to is deleted. Returned: always Sample: `false`
datacenter string	Name of the datacenter of the Primary IP Deprecated: The `hcloud_primary_ip.datacenter` value is deprecated and will be removed after 1 July 2026. Please use the `hcloud_primary_ip.location` value instead. See https://docs.hetzner.cloud/changelog#2025-12-16-phasing-out-datacenters. Returned: Always Sample: `"fsn1-dc14"`
delete_protection boolean	True if Primary IP is protected for deletion Returned: always Sample: `false`
id integer	ID of the Primary IP Returned: Always Sample: `12345`
ip string	IP Address of the Primary IP Returned: Always Sample: `"116.203.104.109"`
labels dictionary	User-defined labels (key-value pairs) Returned: Always Sample: `{"key": "value", "mylabel": 123}`
location string	Name of the Location of the Primary IP Returned: Always Sample: `"fsn1"`
name string	Name of the Primary IP Returned: Always Sample: `"my-primary-ip"`
type string	Type of the Primary IP Returned: Always Sample: `"ipv4"`

Authors

Lukas Kaemmerling (@lkaemmerling)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/hetzner/hcloud/primary_ip_module.html