Give Feedback

reserved_ip_assign

Generated on 16 Dec 2025 from digitalocean.cloud version v1.2.1

Synopsis

Create a reserved IP without assigning it. Create a reserved IP and assign it to a Droplet. Assign an existing reserved IP to a Droplet. Unassign and delete a reserved IP. View the API documentation at https://docs.digitalocean.com/reference/api/api-reference/#operation/assign_reserved_ip.

Requirements

pydo >= 0.1.3
azure-core >= 1.26.1

Parameters

Parameter	Choices / Default	Description
`client_override_options` dict		Client override options (developer use). For example, can be used to override the DigitalOcean API endpoint for an internal test suite. If provided, these options will knock out existing options.
`droplet_id` int		A unique identifier for a Droplet instance. The Droplet that the reserved IP will be assigned to. If provided, `name` and `region` are ignored. Required when `reserved_ip` is provided and `state=present`. Not used when `state=absent`.
`module_override_options` dict		Module override options (developer use). Can be used to override module options to support experimental or future options. If provided, these options will knock out existing options.
`name` str		The name of the Droplet to assign the reserved IP to. If provided, must be unique and given with `region`. Required when `reserved_ip` is provided and `state=present`. Not used when `state=absent`.
`region` str		The region slug where the Droplet is located or where the reserved IP should be created. Required with `name`. Required when creating an unassigned reserved IP. Not used when `state=absent`.
`reserved_ip` str		The reserved IP address to assign or delete. If not provided, a new reserved IP will be created (only when `state=present`). Required when `state=absent`. Aliases `floating_ip`.
`state` str	Choices: `present` (default) `absent`	Whether the reserved IP should be assigned or deleted. When `present`, the reserved IP will be created and/or assigned. When `absent`, the reserved IP will be unassigned (if assigned) and then deleted.
`timeout` int	Default: `300`	Polling timeout in seconds.
`token` str		DigitalOcean API token. There are several environment variables which can be used to provide this value. `DIGITALOCEAN_ACCESS_TOKEN`, `DIGITALOCEAN_TOKEN`, `DO_API_TOKEN`, `DO_API_KEY`, `DO_OAUTH_TOKEN` and `OAUTH_TOKEN`

Examples

- name: Create a reserved IP without assigning it
  digitalocean.cloud.reserved_ip_assign:
    token: "{{ token }}"
    region: nyc3

- name: Create a reserved IP and assign it to a Droplet by ID
  digitalocean.cloud.reserved_ip_assign:
    token: "{{ token }}"
    droplet_id: 3164444

- name: Create a reserved IP and assign it to a Droplet by name and region
  digitalocean.cloud.reserved_ip_assign:
    token: "{{ token }}"
    name: example.com
    region: nyc3

- name: Assign an existing reserved IP to a Droplet by ID
  digitalocean.cloud.reserved_ip_assign:
    token: "{{ token }}"
    reserved_ip: "45.55.96.47"
    droplet_id: 3164444

- name: Assign an existing reserved IP to a Droplet by name and region
  digitalocean.cloud.reserved_ip_assign:
    token: "{{ token }}"
    reserved_ip: "45.55.96.47"
    name: example.com
    region: nyc3

- name: Unassign and delete a reserved IP
  digitalocean.cloud.reserved_ip_assign:
    token: "{{ token }}"
    reserved_ip: "45.55.96.47"
    state: absent

Return Values

Key	Returned	Description
`action` dict	when assigning or unassigning an existing reserved IP	DigitalOcean action information. Sample: `{ "completed_at": null, "id": 1882339039, "region": { "available": true, "features": [ "backups", "ipv6", "metadata", "install_agent", "storage", "image_transfer" ], "name": "New York 3", "sizes": [ "s-1vcpu-1gb", "s-1vcpu-1gb-amd", "s-1vcpu-1gb-intel", "and many more" ], "slug": "nyc3" }, "region_slug": "nyc3", "resource_id": "45.55.96.47", "resource_type": "reserved_ip", "started_at": "2023-09-03T12:59:10Z", "status": "in-progress", "type": "assign" }`
`error` dict	failure	DigitalOcean API error. Sample: `{ "Message": "Informational error message.", "Reason": "Unauthorized", "Status Code": 401 }`
`msg` str	always	Reserved IP operation result information. Sample: `[ "Created reserved IP 45.55.96.47", "Created reserved IP 45.55.96.47 and assigned to Droplet 3164444", "Reserved IP 45.55.96.47 assigned to Droplet 3164444", "Reserved IP 45.55.96.47 assigned to Droplet 3164444 and it has not completed, status is 'in-progress'", "Reserved IP 45.55.96.47 already assigned to Droplet 3164444", "Reserved IP 45.55.96.47 unassigned from Droplet 3164444", "Reserved IP 45.55.96.47 deleted", "Reserved IP 45.55.96.47 not found", "Droplet 3164444 not found" ]`
`reserved_ip` dict	always	Reserved IP information. Sample: { "droplet": { "id": 3164444, "name": "example.com" }, "ip": "45.55.96.47", "locked": false, "project_id": "746c6152-2fa2-11ed-92d3-27aaa54e4988", "region": { "available": true, "features": [ "private_networking", "backups", "ipv6", "metadata", "install_agent", "storage", "image_transfer" ], "name": "New York 3", "sizes": [ "s-1vcpu-1gb", "s-1vcpu-2gb", "s-1vcpu-3gb", "s-2vcpu-2gb", "s-3vcpu-1gb", "s-2vcpu-4gb", "s-4vcpu-8gb", "s-6vcpu-16gb", "s-8vcpu-32gb", "s-12vcpu-48gb", "s-16vcpu-64gb", "s-20vcpu-96gb", "s-24vcpu-128gb", "s-32vcpu-192g" ], "slug": "nyc3" } }