Skip to main content

instances

Creates, updates, deletes, gets or lists an instances resource.

Overview​

Nameinstances
TypeResource
Idaws.lightsail.instances

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
namestringThe name the user gave the instance (Amazon_Linux_2023-1). (pattern: <code>\w[\w-]*\w</code>)
add_onsarrayAn array of objects representing the add-ons enabled on the instance.
arnstringThe Amazon Resource Name (ARN) of the instance (arn:aws:lightsail:us-east-2:123456789101:Instance/244ad76f-8aad-4741-809f-12345EXAMPLE). (pattern: <code>.\S.</code>)
blueprint_idstringThe blueprint ID (amazon_linux_2023). (pattern: <code>.\S.</code>)
blueprint_namestringThe friendly name of the blueprint (Amazon Linux 2023). (pattern: <code>.\S.</code>)
bundle_idstringThe bundle for the instance (micro_x_x). (pattern: <code>.\S.</code>)
created_atstring (date-time)The timestamp when the instance was created (1479734909.17) in Unix time format.
hardwareobjectThe size of the vCPU and the amount of RAM for the instance.
ip_address_typestringThe IP address type of the instance. The possible values are ipv4 for IPv4 only, ipv6 for IPv6 only, and dualstack for IPv4 and IPv6. (dualstack, ipv4, ipv6)
ipv_6_addressesarrayThe IPv6 addresses of the instance.
is_static_ipbooleanA Boolean value indicating whether this instance has a static IP assigned to it.
locationobjectThe region name and Availability Zone where the instance is located.
metadata_optionsobjectThe metadata options for the Amazon Lightsail instance.
networkingobjectInformation about the public ports and monthly data transfer rates for the instance.
private_ip_addressstringThe private IP address of the instance. (pattern: <code>([0-9]{1,3}.){3}[0-9]{1,3}</code>)
public_ip_addressstringThe public IP address of the instance. (pattern: <code>([0-9]{1,3}.){3}[0-9]{1,3}</code>)
resource_typestringThe type of resource (usually Instance). (ContainerService, Instance, StaticIp, KeyPair, InstanceSnapshot, Domain, PeeredVpc, LoadBalancer, LoadBalancerTlsCertificate, Disk, DiskSnapshot, RelationalDatabase, RelationalDatabaseSnapshot, ExportSnapshotRecord, CloudFormationStackRecord, Alarm, ContactMethod, Distribution, Certificate, Bucket)
ssh_key_namestringThe name of the SSH key being used to connect to the instance (LightsailDefaultKeyPair). (pattern: <code>\w[\w-]*\w</code>)
stateobjectThe status code and the state (running) for the instance.
support_codestringThe support code. Include this code in your email to support when you have questions about an instance or another resource in Lightsail. This code enables our support team to look up your Lightsail information more easily.
tagsarrayThe tag keys and optional values for the resource. For more information about tags in Lightsail, see the Amazon Lightsail Developer Guide.
usernamestringThe user name for connecting to the instance (ec2-user). (pattern: <code>.\S.</code>)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
get_instanceselectregionReturns information about a specific Amazon Lightsail instance, which is a virtual private server.
get_instancesselectregionReturns information about all Amazon Lightsail virtual private servers, or instances.
create_instancesinsertregion, instanceNames, availabilityZone, blueprintId, bundleIdCreates one or more Amazon Lightsail instances. The create instances operation supports tag-based access control via request tags. For more information, see the Lightsail Developer Guide.
create_instances_from_snapshotinsertregion, instanceNames, availabilityZone, bundleIdCreates one or more new instances from a manual or automatic snapshot of an instance. The create instances from snapshot operation supports tag-based access control via request tags and resource tags applied to the resource identified by instance snapshot name. For more information, see the Amazon Lightsail Developer Guide.
setup_instance_httpsupdateregion, instanceName, emailAddress, domainNames, certificateProviderCreates an SSL/TLS certificate that secures traffic for your website. After the certificate is created, it is installed on the specified Lightsail instance. If you provide more than one domain name in the request, at least one name must be less than or equal to 63 characters in length.
update_instance_metadata_optionsupdateregion, instanceNameModifies the Amazon Lightsail instance metadata parameters on a running or stopped instance. When you modify the parameters on a running instance, the GetInstance or GetInstances API operation initially responds with a state of pending. After the parameter modifications are successfully applied, the state changes to applied in subsequent GetInstance or GetInstances API calls. For more information, see Use IMDSv2 with an Amazon Lightsail instance in the Amazon Lightsail Developer Guide.
put_instance_public_portsreplaceregion, portInfos, instanceNameOpens ports for a specific Amazon Lightsail instance, and specifies the IP addresses allowed to connect to the instance through the ports, and the protocol. This action also closes all currently open ports that are not included in the request. Include all of the ports and the protocols you want to open in your PutInstancePublicPortsrequest. Or use the OpenInstancePublicPorts action to open ports without closing currently open ports. The PutInstancePublicPorts action supports tag-based access control via resource tags applied to the resource identified by instanceName. For more information, see the Amazon Lightsail Developer Guide.
delete_instancedeleteregionDeletes an Amazon Lightsail instance. The delete instance operation supports tag-based access control via resource tags applied to the resource identified by instance name. For more information, see the Amazon Lightsail Developer Guide.
close_instance_public_portsexecregion, portInfo, instanceNameCloses ports for a specific Amazon Lightsail instance. The CloseInstancePublicPorts action supports tag-based access control via resource tags applied to the resource identified by instanceName. For more information, see the Amazon Lightsail Developer Guide.
delete_known_host_keysexecregion, instanceNameDeletes the known host key or certificate used by the Amazon Lightsail browser-based SSH or RDP clients to authenticate an instance. This operation enables the Lightsail browser-based SSH or RDP clients to connect to the instance after a host key mismatch. Perform this operation only if you were expecting the host key or certificate mismatch or if you are familiar with the new host key or certificate on the instance. For more information, see Troubleshooting connection issues when using the Amazon Lightsail browser-based SSH or RDP client.
open_instance_public_portsexecregion, portInfo, instanceNameOpens ports for a specific Amazon Lightsail instance, and specifies the IP addresses allowed to connect to the instance through the ports, and the protocol. The OpenInstancePublicPorts action supports tag-based access control via resource tags applied to the resource identified by instanceName. For more information, see the Amazon Lightsail Developer Guide.
reboot_instanceexecregion, instanceNameRestarts a specific instance. The reboot instance operation supports tag-based access control via resource tags applied to the resource identified by instance name. For more information, see the Amazon Lightsail Developer Guide.
start_instanceexecregion, instanceNameStarts a specific Amazon Lightsail instance from a stopped state. To restart an instance, use the reboot instance operation. When you start a stopped instance, Lightsail assigns a new public IP address to the instance. To use the same IP address after stopping and starting an instance, create a static IP address and attach it to the instance. For more information, see the Amazon Lightsail Developer Guide. The start instance operation supports tag-based access control via resource tags applied to the resource identified by instance name. For more information, see the Amazon Lightsail Developer Guide.
stop_instanceexecregion, instanceNameStops a specific Amazon Lightsail instance that is currently running. When you start a stopped instance, Lightsail assigns a new public IP address to the instance. To use the same IP address after stopping and starting an instance, create a static IP address and attach it to the instance. For more information, see the Amazon Lightsail Developer Guide. The stop instance operation supports tag-based access control via resource tags applied to the resource identified by instance name. For more information, see the Amazon Lightsail Developer Guide.

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.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Returns information about a specific Amazon Lightsail instance, which is a virtual private server.

SELECT
name,
add_ons,
arn,
blueprint_id,
blueprint_name,
bundle_id,
created_at,
hardware,
ip_address_type,
ipv_6_addresses,
is_static_ip,
location,
metadata_options,
networking,
private_ip_address,
public_ip_address,
resource_type,
ssh_key_name,
state,
support_code,
tags,
username
FROM aws.lightsail.instances
WHERE region = '{{ region }}' -- required
;

INSERT examples​

Creates one or more Amazon Lightsail instances. The create instances operation supports tag-based access control via request tags. For more information, see the Lightsail Developer Guide.

INSERT INTO aws.lightsail.instances (
instanceNames,
availabilityZone,
customImageName,
blueprintId,
bundleId,
userData,
keyPairName,
tags,
addOns,
ipAddressType,
region
)
SELECT 
'{{ instanceNames }}' /* required */,
'{{ availabilityZone }}' /* required */,
'{{ customImageName }}',
'{{ blueprintId }}' /* required */,
'{{ bundleId }}' /* required */,
'{{ userData }}',
'{{ keyPairName }}',
'{{ tags }}',
'{{ addOns }}',
'{{ ipAddressType }}',
'{{ region }}'
RETURNING
operations
;

UPDATE examples​

Creates an SSL/TLS certificate that secures traffic for your website. After the certificate is created, it is installed on the specified Lightsail instance. If you provide more than one domain name in the request, at least one name must be less than or equal to 63 characters in length.

UPDATE aws.lightsail.instances
SET 
instanceName = '{{ instanceName }}',
emailAddress = '{{ emailAddress }}',
domainNames = '{{ domainNames }}',
certificateProvider = '{{ certificateProvider }}'
WHERE 
region = '{{ region }}' --required
AND instanceName = '{{ instanceName }}' --required
AND emailAddress = '{{ emailAddress }}' --required
AND domainNames = '{{ domainNames }}' --required
AND certificateProvider = '{{ certificateProvider }}' --required
RETURNING
operations;

REPLACE examples​

Opens ports for a specific Amazon Lightsail instance, and specifies the IP addresses allowed to connect to the instance through the ports, and the protocol. This action also closes all currently open ports that are not included in the request. Include all of the ports and the protocols you want to open in your PutInstancePublicPortsrequest. Or use the OpenInstancePublicPorts action to open ports without closing currently open ports. The PutInstancePublicPorts action supports tag-based access control via resource tags applied to the resource identified by instanceName. For more information, see the Amazon Lightsail Developer Guide.

REPLACE aws.lightsail.instances
SET 
portInfos = '{{ portInfos }}',
instanceName = '{{ instanceName }}'
WHERE 
region = '{{ region }}' --required
AND portInfos = '{{ portInfos }}' --required
AND instanceName = '{{ instanceName }}' --required
RETURNING
operation;

DELETE examples​

Deletes an Amazon Lightsail instance. The delete instance operation supports tag-based access control via resource tags applied to the resource identified by instance name. For more information, see the Amazon Lightsail Developer Guide.

DELETE FROM aws.lightsail.instances
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

Closes ports for a specific Amazon Lightsail instance. The CloseInstancePublicPorts action supports tag-based access control via resource tags applied to the resource identified by instanceName. For more information, see the Amazon Lightsail Developer Guide.

EXEC aws.lightsail.instances.close_instance_public_ports 
@region='{{ region }}' --required 
@@json=
'{
"portInfo": "{{ portInfo }}", 
"instanceName": "{{ instanceName }}"
}'
;
Last updated on