Docs4dev
Docs
ansible / latest / collections / ngine_io / vultr / vultr_server_module.html

ngine_io.vultr.vultr_server – Manages virtual servers on Vultr.

Note

This plugin is part of the ngine_io.vultr collection (version 1.1.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 ngine_io.vultr.

To use it in a playbook, specify: ngine_io.vultr.vultr_server.

New in version 0.1.0: of ngine_io.vultr

Synopsis

  • Deploy, start, stop, update, restart, reinstall servers.

Requirements

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

  • python >= 2.6

Parameters

Parameter Choices/Defaults Comments
api_account
string
Default:
"default"
Name of the ini section in the vultr.ini file.
The ENV variable VULTR_API_ACCOUNT is used as default, when defined.
api_endpoint
string
URL to API endpint (without trailing slash).
The ENV variable VULTR_API_ENDPOINT is used as default, when defined.
Fallback value is https://api.vultr.com if not specified.
api_key
string
API key of the Vultr API.
The ENV variable VULTR_API_KEY is used as default, when defined.
api_retries
integer
Amount of retries in case of the Vultr API retuns an HTTP 503 code.
The ENV variable VULTR_API_RETRIES is used as default, when defined.
Fallback value is 5 retries if not specified.
api_retry_max_delay
integer
Retry backoff delay in seconds is exponential up to this max. value, in seconds.
The ENV variable VULTR_API_RETRY_MAX_DELAY is used as default, when defined.
Fallback value is 12 seconds.
api_timeout
integer
HTTP timeout to Vultr API.
The ENV variable VULTR_API_TIMEOUT is used as default, when defined.
Fallback value is 60 seconds if not specified.
auto_backup_enabled
boolean
    Choices:
  • no
  • yes
Whether to enable automatic backups or not.
firewall_group
string
The firewall group description or ID to assign this server to.
force
boolean
    Choices:
  • no ←
  • yes
Force stop/start the server if required to apply changes
Otherwise a running server will not be changed.
hostname
string
The hostname to assign to this server.
ipv6_enabled
boolean
    Choices:
  • no
  • yes
Whether to enable IPv6 or not.
name
string / required
Name of the server.

aliases: label
notify_activate
boolean
    Choices:
  • no ←
  • yes
Whether to send an activation email when the server is ready or not.
Only considered on creation.
os
string
The operating system name or ID.
Required if the server does not yet exist and is not restoring from a snapshot.
plan
string
Plan name or ID to use for the server.
Required if the server does not yet exist.
private_network_enabled
boolean
    Choices:
  • no
  • yes
Whether to enable private networking or not.
region
string
Region name or ID the server is deployed into.
Required if the server does not yet exist.
reserved_ip_v4
string
IP address of the floating IP to use as the main IP of this server.
Only considered on creation.
snapshot
string
Name or ID of the snapshot to restore the server from.
ssh_keys
list / elements=string
List of SSH key names or IDs passed to the server on creation.

aliases: ssh_key
startup_script
string
Name or ID of the startup script to execute on boot.
Only considered while creating the server.
state
string
    Choices:
  • present ←
  • absent
  • restarted
  • reinstalled
  • started
  • stopped
State of the server.
tag
string
Tag for the server.
user_data
string
User data to be passed to the server.
validate_certs
boolean
    Choices:
  • no
  • yes ←
Validate SSL certs of the Vultr API.

Notes

Note

Examples

- name: create server
  ngine_io.vultr.vultr_server:
    name: "{{ vultr_server_name }}"
    os: CentOS 7 x64
    plan: 1024 MB RAM,25 GB SSD,1.00 TB BW
    ssh_keys:
      - my_key
      - your_key
    region: Amsterdam
    state: present

- name: ensure a server is present and started
  ngine_io.vultr.vultr_server:
    name: "{{ vultr_server_name }}"
    os: CentOS 7 x64
    plan: 1024 MB RAM,25 GB SSD,1.00 TB BW
    firewall_group: my_group
    ssh_key: my_key
    region: Amsterdam
    state: started

- name: ensure a server is present and stopped provisioned using IDs
  ngine_io.vultr.vultr_server:
    name: "{{ vultr_server_name }}"
    os: "167"
    plan: "201"
    region: "7"
    state: stopped

- name: ensure an existing server is stopped
  ngine_io.vultr.vultr_server:
    name: "{{ vultr_server_name }}"
    state: stopped

- name: ensure an existing server is started
  ngine_io.vultr.vultr_server:
    name: "{{ vultr_server_name }}"
    state: started

- name: ensure a server is absent
  ngine_io.vultr.vultr_server:
    name: "{{ vultr_server_name }}"
    state: absent

Return Values

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

Key Returned Description
vultr_api
complex
success
Response from Vultr API with a few additions/modification

api_account
string
success
Account used in the ini file to select the key

Sample:
default
api_endpoint
string
success
Endpoint used for the API requests

Sample:
https://api.vultr.com
api_retries
integer
success
Amount of max retries for the API requests

Sample:
5
api_retry_max_delay
integer
success
Exponential backoff delay in seconds between retries up to this max delay value.

Sample:
12
api_timeout
integer
success
Timeout used for the API requests

Sample:
60
vultr_server
complex
success
Response from Vultr API with a few additions/modification

allowed_bandwidth_gb
integer
success
Allowed bandwidth to use in GB

Sample:
1000
auto_backup_enabled
boolean
success
Whether automatic backups are enabled

cost_per_month
float
success
Cost per month for the server

Sample:
5.0
current_bandwidth_gb
integer
success
Current bandwidth used for the server

date_created
string
success
Date when the server was created

Sample:
2017-08-26 12:47:48
default_password
string
success
Password to login as root into the server

Sample:
!p3EWYJm$qDWYaFr
disk
string
success
Information about the disk

Sample:
Virtual 25 GB
firewall_group
string
success and available
Firewall group the server is assigned to

Sample:
CentOS 6 x64
id
string
success
ID of the server

Sample:
10194376
internal_ip
string
success
Internal IP

kvm_url
string
success
URL to the VNC

Sample:
https://my.vultr.com/subs/vps/novnc/api.php?data=xyz
name
string
success
Name (label) of the server

Sample:
ansible-test-vm
os
string
success
Operating system used for the server

Sample:
CentOS 6 x64
pending_charges
float
success
Pending charges

Sample:
0.01
plan
string
success
Plan used for the server

Sample:
1024 MB RAM,25 GB SSD,1.00 TB BW
power_status
string
success
Power status of the server

Sample:
running
ram
string
success
Information about the RAM size

Sample:
1024 MB
region
string
success
Region the server was deployed into

Sample:
Amsterdam
server_state
string
success
State about the server

Sample:
ok
status
string
success
Status about the deployment of the server

Sample:
active
tag
string
success
TBD

v4_gateway
string
success
IPv4 gateway

Sample:
45.32.232.1
v4_main_ip
string
success
Main IPv4

Sample:
45.32.233.154
v4_netmask
string
success
Netmask IPv4

Sample:
255.255.254.0
v6_main_ip
string
success
Main IPv6

v6_network
string
success
Network IPv6

v6_network_size
string
success
Network size IPv6

v6_networks
list / elements=string
success
Networks IPv6

vcpu_count
integer
success
Virtual CPU count

Sample:
1


Authors

  • René Moser (@resmo)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ngine_io/vultr/vultr_server_module.html