region_instances

Creates, updates, deletes, gets or lists a region_instances resource.

Overview

Name	region_instances
Type	Resource
Id	ovh.cloud.region_instances

Fields

The following fields are returned by SELECT queries:

get

successful operation

Name	Datatype	Description
id	string (uuid)	Instance id
name	string	Instance name
flavor_id	string (uuid)	Flavor id (wire: flavorId)
image_id	string (uuid)	Image id (wire: imageId)
flavor_name	string	Flavor name (wire: flavorName)
actions	array	Actions that can be done on the instance
addresses	array	Instance IP addresses
attached_volumes	array	Volumes attached to the instance (wire: attachedVolumes)
availability_zone	string	Availability zone of the instance (wire: availabilityZone)
backups	array	Instance Backups
flavor	object	Instance flavor
image	object	Instance image
login	string	User and address to SSH to your instance
pending_task	boolean	A task is pending for the instance (wire: pendingTask)
pricings	array	Instance Price
region	string	Instance region
region_type	string	Type of the region (localzone, region, region-3-az) (wire: regionType)
ssh_key	string	Instance SSH key name (wire: sshKey)
status	string	Instance status (ACTIVE, BUILD, BUILDING, DELETED, DELETING, ERROR, HARD_REBOOT, MIGRATING, PASSWORD, PAUSED, REBOOT, REBUILD, RESCUE, RESCUED, RESCUING, RESIZE, RESIZED, RESUMING, REVERT_RESIZE, SHELVED, SHELVED_OFFLOADED, SHELVING, SHUTOFF, SNAPSHOTTING, SOFT_DELETED, STOPPED, SUSPENDED, UNKNOWN, UNRESCUING, UNSHELVING, VERIFY_RESIZE)
task_state	string	Instance task state (, block_device_mapping, deleting, image_backup, image_pending_upload, image_snapshot, image_snapshot_pending, image_uploading, migrating, networking, pausing, powering-off, powering-on, reboot_pending, reboot_pending_hard, reboot_started, reboot_started_hard, reboot_starting, rebooting, rebooting_hard, rebooting_pending_hard, rebooting_started_hard, rebuild_block_device_mapping, rebuild_spawning, rebuilding, rescuing, resize_confirming, resize_finish, resize_migrated, resize_migrating, resize_prep, resize_reverting, restoring, resuming, scheduling, shelving, shelving_image_pending_upload, shelving_image_uploading, shelving_offloading, soft_deleting, spawning, starting, stopping, suspending, unknown, unpausing, unrescuing, unshelving, updating_password) (wire: taskState)
volumes	array	Instance volumes

list

Instance

Name	Datatype	Description
id	string (uuid)	Instance id
name	string	Instance name
flavor_id	string (uuid)	Flavor id (wire: flavorId)
image_id	string (uuid)	Image id (wire: imageId)
flavor_name	string	Flavor name (wire: flavorName)
actions	array	Actions that can be done on the instance
addresses	array	Instance IP addresses
attached_volumes	array	Volumes attached to the instance (wire: attachedVolumes)
availability_zone	string	Availability zone of the instance (wire: availabilityZone)
backups	array	Instance Backups
flavor	object	Instance flavor
image	object	Instance image
login	string	User and address to SSH to your instance
pending_task	boolean	A task is pending for the instance (wire: pendingTask)
pricings	array	Instance Price
region	string	Instance region
region_type	string	Type of the region (localzone, region, region-3-az) (wire: regionType)
ssh_key	string	Instance SSH key name (wire: sshKey)
status	string	Instance status (ACTIVE, BUILD, BUILDING, DELETED, DELETING, ERROR, HARD_REBOOT, MIGRATING, PASSWORD, PAUSED, REBOOT, REBUILD, RESCUE, RESCUED, RESCUING, RESIZE, RESIZED, RESUMING, REVERT_RESIZE, SHELVED, SHELVED_OFFLOADED, SHELVING, SHUTOFF, SNAPSHOTTING, SOFT_DELETED, STOPPED, SUSPENDED, UNKNOWN, UNRESCUING, UNSHELVING, VERIFY_RESIZE)
task_state	string	Instance task state (, block_device_mapping, deleting, image_backup, image_pending_upload, image_snapshot, image_snapshot_pending, image_uploading, migrating, networking, pausing, powering-off, powering-on, reboot_pending, reboot_pending_hard, reboot_started, reboot_started_hard, reboot_starting, rebooting, rebooting_hard, rebooting_pending_hard, rebooting_started_hard, rebuild_block_device_mapping, rebuild_spawning, rebuilding, rescuing, resize_confirming, resize_finish, resize_migrated, resize_migrating, resize_prep, resize_reverting, restoring, resuming, scheduling, shelving, shelving_image_pending_upload, shelving_image_uploading, shelving_offloading, soft_deleting, spawning, starting, stopping, suspending, unknown, unpausing, unrescuing, unshelving, updating_password) (wire: taskState)
volumes	array	Instance volumes

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	instance_id, region_name, service_name	deleted, with_backups, with_image, with_networks, with_volumes	Get a specific instance on a specific region for a public cloud project
list	select	region_name, service_name		List all instances of a specific region for a public cloud project
create	insert	region_name, service_name, billing_period, boot_from, flavor, network		Create an instance with its associated components (ssh key, private network, floating ip)
abort_snapshot	exec	instanceId, regionName, service_name		Abort an instance snapshot creation for a specific instance on a specific region for a public cloud project
associate_floating_ip	exec	instanceId, regionName, service_name, floatingIpId, ip		Associate an existing floating IP to an instance on a specific region for a public cloud project
autobackup	exec	instanceId, regionName, service_name, cron, rotation		Create an automatic instance backup workflow
floating_ip	exec	instanceId, regionName, service_name, ip		Create a floating IP and attach it to an instance on a specific region for a public cloud project
reinstall	exec	instanceId, regionName, service_name, imageRegionName		Reinstall an instance with a new image
snapshot	exec	instanceId, regionName, service_name		Create an instance snapshot for a specific instance on a specific region for a public cloud project

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
api_host	string	The OVHcloud API host. Selected by OVH_ENDPOINT (ovh-eu, ovh-ca or ovh-us; default ovh-eu). (default: api.eu.ovhcloud.com, x-stackQL-envVarSelector: {"envVar":"OVH_ENDPOINT","default":"ovh-eu","values":{"ovh-eu":"api.eu.ovhcloud.com","ovh-ca":"api.ca.ovhcloud.com","ovh-us":"api.us.ovhcloud.com"}})
instanceId	string (uuid)	Instance ID
instance_id	string (uuid)	Instance ID (wire: instanceId)
regionName	string	Region name
region_name	string	Region name (wire: regionName)
service_name	string	The Public Cloud project ID. Resolved from OVH_CLOUD_PROJECT_SERVICE when set.
deleted	boolean	Return instance even if it is deleted
with_backups	boolean	Add backup information in response (wire: withBackups)
with_image	boolean	Add image information in response (wire: withImage)
with_networks	boolean	Add network information in response (wire: withNetworks)
with_volumes	boolean	Add volume information in response (wire: withVolumes)

SELECT examples

get

Get a specific instance on a specific region for a public cloud project

SELECT
id,
name,
flavor_id,
image_id,
flavor_name,
actions,
addresses,
attached_volumes,
availability_zone,
backups,
flavor,
image,
login,
pending_task,
pricings,
region,
region_type,
ssh_key,
status,
task_state,
volumes
FROM ovh.cloud.region_instances
WHERE instance_id = '{{ instance_id }}' -- required
AND region_name = '{{ region_name }}' -- required
AND service_name = '{{ service_name }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
AND deleted = '{{ deleted }}'
AND with_backups = '{{ with_backups }}'
AND with_image = '{{ with_image }}'
AND with_networks = '{{ with_networks }}'
AND with_volumes = '{{ with_volumes }}'
;

list

List all instances of a specific region for a public cloud project

SELECT
id,
name,
flavor_id,
image_id,
flavor_name,
actions,
addresses,
attached_volumes,
availability_zone,
backups,
flavor,
image,
login,
pending_task,
pricings,
region,
region_type,
ssh_key,
status,
task_state,
volumes
FROM ovh.cloud.region_instances
WHERE region_name = '{{ region_name }}' -- required
AND service_name = '{{ service_name }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
;

INSERT examples

create

Create an instance with its associated components (ssh key, private network, floating ip)

INSERT INTO ovh.cloud.region_instances (
autobackup,
availability_zone,
billing_period,
boot_from,
bulk,
flavor,
group,
name,
network,
ssh_key,
ssh_key_create,
user_data,
volume,
region_name,
service_name
)
SELECT 
'{{ autobackup }}',
'{{ availability_zone }}',
'{{ billing_period }}' /* required */,
'{{ boot_from }}' /* required */,
{{ bulk }},
'{{ flavor }}' /* required */,
'{{ group }}',
'{{ name }}',
'{{ network }}' /* required */,
'{{ ssh_key }}',
'{{ ssh_key_create }}',
'{{ user_data }}',
'{{ volume }}',
'{{ region_name }}',
'{{ service_name }}'
RETURNING
id,
resource_id,
action,
completed_at,
created_at,
progress,
regions,
started_at,
status,
sub_operations
;

Manifest

# Description fields are for documentation purposes
- name: region_instances
props:
  - name: region_name
    value: "{{ region_name }}"
    description: Required parameter for the region_instances resource.
  - name: service_name
    value: "{{ service_name }}"
    description: Required parameter for the region_instances resource.
  - name: autobackup
    description: |
      Create an autobackup workflow after instance start up
    value:
      cron: "{{ cron }}"
      distantImageName: "{{ distantImageName }}"
      distantRegionName: "{{ distantRegionName }}"
      imageName: "{{ imageName }}"
      name: "{{ name }}"
      rotation: {{ rotation }}
  - name: availability_zone
    value: "{{ availability_zone }}"
    description: |
      The availability zone where the instance will be created
  - name: billing_period
    value: "{{ billing_period }}"
    description: |
      Billing period
    valid_values: ['hourly', 'monthly']
  - name: boot_from
    description: |
      Boot the instance from an image or a volume
    value:
      imageId: "{{ imageId }}"
      imageRegionName: "{{ imageRegionName }}"
      volumeId: "{{ volumeId }}"
  - name: bulk
    value: {{ bulk }}
    description: |
      Create multiple instances
  - name: flavor
    description: |
      Flavor information
    value:
      id: "{{ id }}"
  - name: group
    description: |
      Start instance in group
    value:
      id: "{{ id }}"
  - name: name
    value: "{{ name }}"
    description: |
      Instance name
  - name: network
    description: |
      Networks information
    value:
      private:
        floatingIp:
          id: "{{ id }}"
        floatingIpCreate:
          description: "{{ description }}"
        gateway:
          id: "{{ id }}"
        gatewayCreate:
          model: "{{ model }}"
          name: "{{ name }}"
        ip: "{{ ip }}"
        network:
          id: "{{ id }}"
          subnetId: "{{ subnetId }}"
        networkCreate:
          name: "{{ name }}"
          subnet:
            cidr: "{{ cidr }}"
            dnsNameServers:
              - "{{ dnsNameServers }}"
            enableDhcp: {{ enableDhcp }}
            enableGatewayIP: {{ enableGatewayIP }}
            ipVersion: {{ ipVersion }}
          vlanId: {{ vlanId }}
      public: {{ public }}
  - name: ssh_key
    description: |
      Existing SSH Keypair
    value:
      name: "{{ name }}"
  - name: ssh_key_create
    description: |
      Information to create a new SSH Keypair
    value:
      name: "{{ name }}"
      publicKey: "{{ publicKey }}"
  - name: user_data
    value: "{{ user_data }}"
    description: |
      Configuration information or scripts to use upon launch
  - name: volume
    description: |
      Volume to create and/or attach to the instance
    value:
      id: "{{ id }}"
      name: "{{ name }}"
      size: {{ size }}
      type: "{{ type }}"

Lifecycle Methods

EXEC variables use wire (API) names.

abort_snapshot

Abort an instance snapshot creation for a specific instance on a specific region for a public cloud project

EXEC ovh.cloud.region_instances.abort_snapshot 
@instanceId='{{ instanceId }}' --required, 
@regionName='{{ regionName }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
;

associate_floating_ip

Associate an existing floating IP to an instance on a specific region for a public cloud project

EXEC ovh.cloud.region_instances.associate_floating_ip 
@instanceId='{{ instanceId }}' --required, 
@regionName='{{ regionName }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"floatingIpId": "{{ floatingIpId }}", 
"gateway": "{{ gateway }}", 
"ip": "{{ ip }}"
}'
;

autobackup

Create an automatic instance backup workflow

EXEC ovh.cloud.region_instances.autobackup 
@instanceId='{{ instanceId }}' --required, 
@regionName='{{ regionName }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"cron": "{{ cron }}", 
"distantImageName": "{{ distantImageName }}", 
"distantRegionName": "{{ distantRegionName }}", 
"imageName": "{{ imageName }}", 
"name": "{{ name }}", 
"rotation": {{ rotation }}
}'
;

floating_ip

Create a floating IP and attach it to an instance on a specific region for a public cloud project

EXEC ovh.cloud.region_instances.floating_ip 
@instanceId='{{ instanceId }}' --required, 
@regionName='{{ regionName }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"gateway": "{{ gateway }}", 
"ip": "{{ ip }}"
}'
;

reinstall

Reinstall an instance with a new image

EXEC ovh.cloud.region_instances.reinstall 
@instanceId='{{ instanceId }}' --required, 
@regionName='{{ regionName }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"imageId": "{{ imageId }}", 
"imageRegionName": "{{ imageRegionName }}"
}'
;

snapshot

Create an instance snapshot for a specific instance on a specific region for a public cloud project

EXEC ovh.cloud.region_instances.snapshot 
@instanceId='{{ instanceId }}' --required, 
@regionName='{{ regionName }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"distantRegionName": "{{ distantRegionName }}", 
"distantSnapshotName": "{{ distantSnapshotName }}", 
"snapshotName": "{{ snapshotName }}"
}'
;