Documentation

vultr_server - Manages virtual servers on Vultr.

New in version 2.5.

Synopsis

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

Aliases: vr_server

Requirements

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

  • python >= 2.6

Parameters

Parameter Choices/Defaults Comments
api_account 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
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
API key of the Vultr API.
The ENV variable VULTR_API_KEY is used as default, when defined.
api_retries
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_timeout
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
bool
    Choices:
  • no
  • yes
Whether to enable automatic backups or not.
firewall_group
The firewall group to assign this server to.
force
bool
    Choices:
  • no
  • yes
Force stop/start the server if required to apply changes
Otherwise a running server will not be changed.
hostname
Hostname to assign to this server.
ipv6_enabled
bool
    Choices:
  • no
  • yes
Whether to enable IPv6 or not.
name
required
Name of the server.

aliases: label
notify_activate
bool
    Choices:
  • no
  • yes
Whether to send an activation email when the server is ready or not.
Only considered on creation.
os
The operating system.
Required if the server does not yet exist.
plan
Plan to use for the server.
Required if the server does not yet exist.
private_network_enabled
bool
    Choices:
  • no
  • yes
Whether to enable private networking or not.
region
Region the server is deployed into.
Required if the server does not yet exist.
reserved_ip_v4
IP address of the floating IP to use as the main IP of this server.
Only considered on creation.
ssh_keys
List of SSH keys passed to the server on creation.

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

Notes

Note

Examples

- name: create server
  local_action:
    module: vultr_server
    name: "{{ vultr_server_name }}"
    os: CentOS 7 x64
    plan: 1024 MB RAM,25 GB SSD,1.00 TB BW
    region: Amsterdam
    state: present

- name: ensure a server is present and started
  local_action:
    module: vultr_server
    name: "{{ vultr_server_name }}"
    os: CentOS 7 x64
    plan: 1024 MB RAM,25 GB SSD,1.00 TB BW
    region: Amsterdam
    state: started

- name: ensure a server is present and stopped
  local_action:
    module: vultr_server
    name: "{{ vultr_server_name }}"
    os: CentOS 7 x64
    plan: 1024 MB RAM,25 GB SSD,1.00 TB BW
    region: Amsterdam
    state: stopped

- name: ensure an existing server is stopped
  local_action:
    module: vultr_server
    name: "{{ vultr_server_name }}"
    state: stopped

- name: ensure an existing server is started
  local_action:
    module: vultr_server
    name: "{{ vultr_server_name }}"
    state: started

- name: ensure a server is absent
  local_action:
    module: 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_endpoint
string
success
Endpoint used for the API requests

Sample:
https://api.vultr.com
  api_timeout
int
success
Timeout used for the API requests

Sample:
60
  api_retries
int
success
Amount of max retries for the API requests

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

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

  status
string
success
Status about the deployment of the server

Sample:
active
  v6_network_size
string
success
Network size IPv6

  server_state
string
success
State about the server

Sample:
ok
  ram
string
success
Information about the RAM size

Sample:
1024 MB
  tag
string
success
TBD

  allowed_bandwidth_gb
int
success
Allowed bandwidth to use in GB

Sample:
1000
  default_password
string
success
Password to login as root into the server

Sample:
!p3EWYJm$qDWYaFr
  internal_ip
string
success
Internal IP

  auto_backup_enabled
bool
success
Whether automatic backups are enabled

  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
  v6_network
string
success
Network IPv6

  disk
string
success
Information about the disk

Sample:
Virtual 25 GB
  v4_netmask
string
success
Netmask IPv4

Sample:
255.255.254.0
  id
string
success
ID of the server

Sample:
10194376
  v6_networks
list
success
Networks IPv6

  vcpu_count
int
success
Virtual CPU count

Sample:
1
  name
string
success
Name (label) of the server

Sample:
ansible-test-vm
  kvm_url
string
success
URL to the VNC

Sample:
https://my.vultr.com/subs/vps/novnc/api.php?data=xyz
  os
string
success
Operating system used for the server

Sample:
CentOS 6 x64
  v6_main_ip
string
success
Main IPv6

  v4_gateway
string
success
IPv4 gateway

Sample:
45.32.232.1
  firewall_group
string
success and available
Firewall group the server is assinged to

Sample:
CentOS 6 x64
  current_bandwidth_gb
int
success
Current bandwidth used for the server

  power_status
string
success
Power status of the server

Sample:
running
  date_created
string
success
Date when the server was created

Sample:
2017-08-26 12:47:48
  v4_main_ip
string
success
Main IPv4

Sample:
45.32.233.154
  region
string
success
Region the server was deployed into

Sample:
Amsterdam
  cost_per_month
float
success
Cost per month for the server

Sample:
5.0


Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author

  • René Moser (@resmo)

Hint

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