Amazon Lightsail

(1)

Amazon Lightsail

API Reference

API Version 2016-11-28

(2)

Amazon Lightsail: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Contents ... 530 See Also ... 530 AutoSnapshotAddOnRequest ... 531 Contents ... 531 See Also ... 531 AutoSnapshotDetails ... 532 Contents ... 532 See Also ... 532 AvailabilityZone ... 533 Contents ... 533 See Also ... 533 Blueprint ... 534 Contents ... 534 See Also ... 535 Bucket ... 537 Contents ... 537 See Also ... 539 BucketAccessLogConfig ... 540 Contents ... 540 See Also ... 540 BucketBundle ... 542 Contents ... 542 See Also ... 542 BucketState ... 544 Contents ... 544 See Also ... 544 Bundle ... 545 Contents ... 545 See Also ... 546 CacheBehavior ... 547 Contents ... 547 See Also ... 547 CacheBehaviorPerPath ... 548 Contents ... 548 See Also ... 549 CacheSettings ... 550 Contents ... 550 See Also ... 551 Certificate ... 552 Contents ... 552 See Also ... 555 CertificateSummary ... 556 Contents ... 556 See Also ... 556 CloudFormationStackRecord ... 557 Contents ... 557 See Also ... 558 CloudFormationStackRecordSourceInfo ... 559 Contents ... 559 See Also ... 559 ContactMethod ... 560 Contents ... 560 See Also ... 561 Container ... 562 Contents ... 562 See Also ... 562 ContainerImage ... 564

(23)

Contents ... 564 See Also ... 564 ContainerService ... 565 Contents ... 565 See Also ... 568 ContainerServiceDeployment ... 569 Contents ... 569 See Also ... 570 ContainerServiceDeploymentRequest ... 571 Contents ... 571 See Also ... 571 ContainerServiceEndpoint ... 572 Contents ... 572 See Also ... 572 ContainerServiceHealthCheckConﬁg ... 573 Contents ... 573 See Also ... 573 ContainerServiceLogEvent ... 575 Contents ... 575 See Also ... 575 ContainerServicePower ... 576 Contents ... 576 See Also ... 576 ContainerServiceRegistryLogin ... 578 Contents ... 578 See Also ... 578 ContainerServiceStateDetail ... 579 Contents ... 579 See Also ... 579 CookieObject ... 581 Contents ... 581 See Also ... 581 DestinationInfo ... 582 Contents ... 582 See Also ... 582 Disk ... 583 Contents ... 583 See Also ... 585 DiskInfo ... 586 Contents ... 586 See Also ... 586 DiskMap ... 587 Contents ... 587 See Also ... 587 DiskSnapshot ... 588 Contents ... 588 See Also ... 590 DiskSnapshotInfo ... 591 Contents ... 591 See Also ... 591 DistributionBundle ... 592 Contents ... 592 See Also ... 592 Domain ... 593 Contents ... 593 See Also ... 594 DomainEntry ... 595

(24)

Contents ... 595 See Also ... 596 DomainValidationRecord ... 597 Contents ... 597 See Also ... 597 EndpointRequest ... 598 Contents ... 598 See Also ... 598 ExportSnapshotRecord ... 599 Contents ... 599 See Also ... 600 ExportSnapshotRecordSourceInfo ... 601 Contents ... 601 See Also ... 602 HeaderObject ... 603 Contents ... 603 See Also ... 603 HostKeyAttributes ... 604 Contents ... 604 See Also ... 605 InputOrigin ... 606 Contents ... 606 See Also ... 606 Instance ... 607 Contents ... 607 See Also ... 610 InstanceAccessDetails ... 611 Contents ... 611 See Also ... 612 InstanceEntry ... 613 Contents ... 613 See Also ... 614 InstanceHardware ... 615 Contents ... 615 See Also ... 615 InstanceHealthSummary ... 616 Contents ... 616 See Also ... 617 InstanceNetworking ... 618 Contents ... 618 See Also ... 618 InstancePortInfo ... 619 Contents ... 619 See Also ... 621 InstancePortState ... 622 Contents ... 622 See Also ... 624 InstanceSnapshot ... 625 Contents ... 625 See Also ... 627 InstanceSnapshotInfo ... 628 Contents ... 628 See Also ... 628 InstanceState ... 629 Contents ... 629 See Also ... 629 KeyPair ... 630

(25)

Contents ... 630 See Also ... 631 LightsailDistribution ... 632 Contents ... 632 See Also ... 635 LoadBalancer ... 636 Contents ... 636 See Also ... 638 LoadBalancerTlsCertificate ... 639 Contents ... 639 See Also ... 643 LoadBalancerTlsCertificateDomainValidationOption ... 644 Contents ... 644 See Also ... 644 LoadBalancerTlsCertificateDomainValidationRecord ... 645 Contents ... 645 See Also ... 645 LoadBalancerTlsCertificateRenewalSummary ... 647 Contents ... 647 See Also ... 648 LoadBalancerTlsCertificateSummary ... 649 Contents ... 649 See Also ... 649 LogEvent ... 650 Contents ... 650 See Also ... 650 MetricDatapoint ... 651 Contents ... 651 See Also ... 652 MonitoredResourceInfo ... 653 Contents ... 653 See Also ... 653 MonthlyTransfer ... 654 Contents ... 654 See Also ... 654 Operation ... 655 Contents ... 655 See Also ... 657 Origin ... 658 Contents ... 658 See Also ... 658 PasswordData ... 660 Contents ... 660 See Also ... 660 PendingMaintenanceAction ... 661 Contents ... 661 See Also ... 661 PendingModifiedRelationalDatabaseValues ... 662 Contents ... 662 See Also ... 662 PortInfo ... 663 Contents ... 663 See Also ... 664 QueryStringObject ... 666 Contents ... 666 See Also ... 666 Region ... 667

(26)

Contents ... 667 See Also ... 667 RelationalDatabase ... 669 Contents ... 669 See Also ... 672 RelationalDatabaseBlueprint ... 673 Contents ... 673 See Also ... 673 RelationalDatabaseBundle ... 675 Contents ... 675 See Also ... 676 RelationalDatabaseEndpoint ... 677 Contents ... 677 See Also ... 677 RelationalDatabaseEvent ... 678 Contents ... 678 See Also ... 678 RelationalDatabaseHardware ... 679 Contents ... 679 See Also ... 679 RelationalDatabaseParameter ... 680 Contents ... 680 See Also ... 681 RelationalDatabaseSnapshot ... 682 Contents ... 682 See Also ... 684 RenewalSummary ... 685 Contents ... 685 See Also ... 685 ResourceLocation ... 687 Contents ... 687 See Also ... 687 ResourceReceivingAccess ... 688 Contents ... 688 See Also ... 688 ResourceRecord ... 689 Contents ... 689 See Also ... 689 StaticIp ... 690 Contents ... 690 See Also ... 691 Tag ... 692 Contents ... 692 See Also ... 692 Actions for object storage ... 693 Common Parameters ... 695 Common Errors ... 697

(27)

Welcome

Amazon Lightsail is the easiest way to get started with Amazon Web Services (AWS) for developers who need to build websites or web applications. It includes everything you need to launch your project quickly - instances (virtual private servers), container services, storage buckets, managed databases, SSD- based block storage, static IP addresses, load balancers, content delivery network (CDN) distributions, DNS management of registered domains, and resource snapshots (backups) - for a low, predictable monthly price.

You can manage your Lightsail resources using the Lightsail console, Lightsail API, AWS Command Line Interface (AWS CLI), or SDKs. For more information about Lightsail concepts and tasks, see the Amazon Lightsail Developer Guide.

This API Reference provides detailed information about the actions, data types, parameters, and errors of the Lightsail service. For more information about the supported AWS Regions, endpoints, and service quotas of the Lightsail service, see Amazon Lightsail Endpoints and Quotas in the AWS General Reference.

This document was last published on March 6, 2022.

(28)

Actions

The following actions are supported:

• AllocateStaticIp (p. 6)

• AttachCertiﬁcateToDistribution (p. 9)

• AttachDisk (p. 12)

• AttachInstancesToLoadBalancer (p. 15)

• AttachLoadBalancerTlsCertiﬁcate (p. 18)

• AttachStaticIp (p. 21)

• CloseInstancePublicPorts (p. 24)

• CopySnapshot (p. 27)

• CreateBucket (p. 33)

• CreateBucketAccessKey (p. 37)

• CreateCertiﬁcate (p. 40)

• CreateCloudFormationStack (p. 44)

• CreateContactMethod (p. 47)

• CreateContainerService (p. 50)

• CreateContainerServiceDeployment (p. 57)

• CreateContainerServiceRegistryLogin (p. 61)

• CreateDisk (p. 63)

• CreateDiskFromSnapshot (p. 67)

• CreateDiskSnapshot (p. 72)

• CreateDistribution (p. 76)

• CreateDomain (p. 81)

• CreateDomainEntry (p. 84)

• CreateInstances (p. 87)

• CreateInstancesFromSnapshot (p. 92)

• CreateInstanceSnapshot (p. 98)

• CreateKeyPair (p. 101)

• CreateLoadBalancer (p. 105)

• CreateLoadBalancerTlsCertiﬁcate (p. 109)

• CreateRelationalDatabase (p. 113)

• CreateRelationalDatabaseFromSnapshot (p. 119)

• CreateRelationalDatabaseSnapshot (p. 124)

• DeleteAlarm (p. 127)

• DeleteAutoSnapshot (p. 130)

• DeleteBucket (p. 133)

• DeleteBucketAccessKey (p. 136)

• DeleteCertiﬁcate (p. 139)

• DeleteContactMethod (p. 142)

• DeleteContainerImage (p. 145)

• DeleteContainerService (p. 147)

• DeleteDisk (p. 149)

(29)

• DeleteDiskSnapshot (p. 152)

• DeleteDistribution (p. 155)

• DeleteDomain (p. 158)

• DeleteDomainEntry (p. 161)

• DeleteInstance (p. 164)

• DeleteInstanceSnapshot (p. 167)

• DeleteKeyPair (p. 170)

• DeleteKnownHostKeys (p. 173)

• DeleteLoadBalancer (p. 176)

• DeleteLoadBalancerTlsCertiﬁcate (p. 179)

• DeleteRelationalDatabase (p. 182)

• DeleteRelationalDatabaseSnapshot (p. 185)

• DetachCertiﬁcateFromDistribution (p. 188)

• DetachDisk (p. 191)

• DetachInstancesFromLoadBalancer (p. 194)

• DetachStaticIp (p. 197)

• DisableAddOn (p. 200)

• DownloadDefaultKeyPair (p. 203)

• EnableAddOn (p. 205)

• ExportSnapshot (p. 208)

• GetActiveNames (p. 211)

• GetAlarms (p. 214)

• GetAutoSnapshots (p. 218)

• GetBlueprints (p. 221)

• GetBucketAccessKeys (p. 224)

• GetBucketBundles (p. 227)

• GetBucketMetricData (p. 229)

• GetBuckets (p. 233)

• GetBundles (p. 237)

• GetCertiﬁcates (p. 240)

• GetCloudFormationStackRecords (p. 244)

• GetContactMethods (p. 247)

• GetContainerAPIMetadata (p. 250)

• GetContainerImages (p. 252)

• GetContainerLog (p. 254)

• GetContainerServiceDeployments (p. 258)

• GetContainerServiceMetricData (p. 261)

• GetContainerServicePowers (p. 265)

• GetContainerServices (p. 267)

• GetDisk (p. 271)

• GetDisks (p. 274)

• GetDiskSnapshot (p. 277)

• GetDiskSnapshots (p. 280)

• GetDistributionBundles (p. 283)

• GetDistributionLatestCacheReset (p. 285)

• GetDistributionMetricData (p. 288)

(30)

• GetDistributions (p. 293)

• GetDomain (p. 297)

• GetDomains (p. 300)

• GetExportSnapshotRecords (p. 303)

• GetInstance (p. 306)

• GetInstanceAccessDetails (p. 310)

• GetInstanceMetricData (p. 313)

• GetInstancePortStates (p. 318)

• GetInstances (p. 321)

• GetInstanceSnapshot (p. 328)

• GetInstanceSnapshots (p. 331)

• GetInstanceState (p. 335)

• GetKeyPair (p. 338)

• GetKeyPairs (p. 341)

• GetLoadBalancer (p. 344)

• GetLoadBalancerMetricData (p. 347)

• GetLoadBalancers (p. 353)

• GetLoadBalancerTlsCertiﬁcates (p. 356)

• GetOperation (p. 359)

• GetOperations (p. 362)

• GetOperationsForResource (p. 365)

• GetRegions (p. 368)

• GetRelationalDatabase (p. 371)

• GetRelationalDatabaseBlueprints (p. 374)

• GetRelationalDatabaseBundles (p. 377)

• GetRelationalDatabaseEvents (p. 380)

• GetRelationalDatabaseLogEvents (p. 383)

• GetRelationalDatabaseLogStreams (p. 387)

• GetRelationalDatabaseMasterUserPassword (p. 389)

• GetRelationalDatabaseMetricData (p. 392)

• GetRelationalDatabaseParameters (p. 397)

• GetRelationalDatabases (p. 400)

• GetRelationalDatabaseSnapshot (p. 404)

• GetRelationalDatabaseSnapshots (p. 407)

• GetStaticIp (p. 410)

• GetStaticIps (p. 413)

• ImportKeyPair (p. 416)

• IsVpcPeered (p. 419)

• OpenInstancePublicPorts (p. 421)

• PeerVpc (p. 424)

• PutAlarm (p. 426)

• PutInstancePublicPorts (p. 432)

• RebootInstance (p. 435)

• RebootRelationalDatabase (p. 438)

• RegisterContainerImage (p. 441)

• ReleaseStaticIp (p. 444)

(31)

• ResetDistributionCache (p. 447)

• SendContactMethodVeriﬁcation (p. 450)

• SetIpAddressType (p. 453)

• SetResourceAccessForBucket (p. 456)

• StartInstance (p. 459)

• StartRelationalDatabase (p. 462)

• StopInstance (p. 465)

• StopRelationalDatabase (p. 468)

• TagResource (p. 471)

• TestAlarm (p. 474)

• UnpeerVpc (p. 477)

• UntagResource (p. 479)

• UpdateBucket (p. 482)

• UpdateBucketBundle (p. 486)

• UpdateContainerService (p. 489)

• UpdateDistribution (p. 495)

• UpdateDistributionBundle (p. 499)

• UpdateDomainEntry (p. 502)

• UpdateLoadBalancerAttribute (p. 505)

• UpdateRelationalDatabase (p. 508)

• UpdateRelationalDatabaseParameters (p. 513)

(32)

AllocateStaticIp

Allocates a static IP address.

Request Syntax

{

"staticIpName": "string"

}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 695).

The request accepts the following data in JSON format.

staticIpName (p. 6)

The name of the static IP address.

Type: String

Pattern: \w[\w\-]*\w Required: Yes

Response Syntax

{ "operations": [ {

"createdAt": number, "errorCode": "string", "errorDetails": "string", "id": "string",

"isTerminal": boolean, "location": {

"availabilityZone": "string", "regionName": "string"

},

"operationDetails": "string", "operationType": "string", "resourceName": "string", "resourceType": "string", "status": "string", "statusChangedAt": number }

] }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

(33)

Errors

operations (p. 6)

An array of objects that describe the result of the action, such as the status of the request, the timestamp of the request, and the resources aﬀected by the request.

Type: Array of Operation (p. 655) objects

Errors

For information about the errors that are common to all actions, see Common Errors (p. 697).

AccessDeniedException

Lightsail throws this exception when the user cannot be authenticated or uses invalid credentials to access a resource.

HTTP Status Code: 400

AccountSetupInProgressException

Lightsail throws this exception when an account is still in the setup in progress state.

HTTP Status Code: 400 InvalidInputException

Lightsail throws this exception when user input does not conform to the validation rules of an input ﬁeld.

Note

Domain and distribution APIs are only available in the N. Virginia (us-east-1) AWS Region.

Please set your AWS Region conﬁguration to us-east-1 to create, view, or edit these resources.

HTTP Status Code: 400 NotFoundException

Lightsail throws this exception when it cannot ﬁnd a resource.

HTTP Status Code: 400 OperationFailureException

Lightsail throws this exception when an operation fails to execute.

HTTP Status Code: 400 ServiceException

A general service exception.

HTTP Status Code: 500 UnauthenticatedException

Lightsail throws this exception when the user has not been authenticated.

AttachCertiﬁcateToDistribution

Attaches an SSL/TLS certiﬁcate to your Amazon Lightsail content delivery network (CDN) distribution.

After the certificate is attached, your distribution accepts HTTPS traffic for all of the domains that are associated with the certificate.

Use the CreateCertificate action to create a certiﬁcate that you can attach to your distribution.

Important

Only certiﬁcates created in the us-east-1 AWS Region can be attached to Lightsail

distributions. Lightsail distributions are global resources that can reference an origin in any AWS Region, and distribute its content globally. However, all distributions are located in the us- east-1 Region.

Request Syntax

{

"certificateName": "string", "distributionName": "string"

}

Request Parameters

certiﬁcateName (p. 9)

The name of the certiﬁcate to attach to a distribution.

Only certiﬁcates with a status of ISSUED can be attached to a distribution.

Use the GetCertificates action to get a list of certiﬁcate names that you can specify.

Note

This is the name of the certificate resource type and is used only to reference the certificate in other API actions. It can be different than the domain name of the certificate. For

example, your certiﬁcate name might be WordPress-Blog-Certificate and the domain name of the certiﬁcate might be example.com.

Type: String

distributionName (p. 9)

The name of the distribution that the certiﬁcate will be attached to.

Use the GetDistributions action to get a list of distribution names that you can specify.

Type: String

Pattern: \w[\w\-]*\w

(36)

Response Syntax

Required: Yes

Response Syntax

{ "operation": {

},

}

Response Elements

operation (p. 10)

An object that describes the result of the action, such as the status of the request, the timestamp of the request, and the resources aﬀected by the request.

Type: Operation (p. 655) object

Errors

NoteDomain and distribution APIs are only available in the N. Virginia (us-east-1) AWS Region.

(37)

See Also

AttachDisk

Attaches a block storage disk to a running or stopped Lightsail instance and exposes it to the instance with the speciﬁed disk name.

The attach disk operation supports tag-based access control via resource tags applied to the resource identiﬁed by disk name. For more information, see the Amazon Lightsail Developer Guide.

Request Syntax

{ "diskName": "string", "diskPath": "string", "instanceName": "string"

}

Request Parameters

diskName (p. 12)

The unique Lightsail disk name (e.g., my-disk).

Type: String

diskPath (p. 12)

The disk path to expose to the instance (e.g., /dev/xvdf).

Type: String Pattern: .*\S.*

Required: Yes instanceName (p. 12)

The name of the Lightsail instance where you want to utilize the storage disk.

Type: String

Response Syntax

{ "operations": [

(39)

Response Elements

{

},

]}

Response Elements

Errors

(40)

See Also

NotFoundException

AttachInstancesToLoadBalancer

Attaches one or more Lightsail instances to a load balancer.

After some time, the instances are attached to the load balancer and the health check status is available.

The attach instances to load balancer operation supports tag-based access control via resource tags applied to the resource identiﬁed by load balancer name. For more information, see the Lightsail Developer Guide.

Request Syntax

{

"instanceNames": [ "string" ], "loadBalancerName": "string"

}

Request Parameters

instanceNames (p. 15)

An array of strings representing the instance name(s) you want to attach to your load balancer.

An instance must be running before you can attach it to your load balancer.

There are no additional limits on the number of instances you can attach to your load balancer, aside from the limit of Lightsail instances you can create in your account (20).

Type: Array of strings Pattern: \w[\w\-]*\w Required: Yes

loadBalancerName (p. 15)

The name of the load balancer.

Type: String

Response Syntax

{ "operations": [ {

"createdAt": number, "errorCode": "string",

(42)

Response Elements

"errorDetails": "string", "id": "string",

},

]}

Response Elements

Errors

Note

(43)

See Also

AttachLoadBalancerTlsCertiﬁcate

Attaches a Transport Layer Security (TLS) certiﬁcate to your load balancer. TLS is just an updated, more secure version of Secure Socket Layer (SSL).

Once you create and validate your certificate, you can attach it to your load balancer. You can also use this API to rotate the certificates on your account. Use the AttachLoadBalancerTlsCertificate action with the non-attached certificate, and it will replace the existing one and become the attached certificate.

The AttachLoadBalancerTlsCertificate operation supports tag-based access control via resource tags applied to the resource identiﬁed by load balancer name. For more information, see the Amazon Lightsail Developer Guide.

Request Syntax

{ "certificateName": "string", "loadBalancerName": "string"

}

Request Parameters

certiﬁcateName (p. 18)

The name of your SSL/TLS certiﬁcate.

Type: String

loadBalancerName (p. 18)

The name of the load balancer to which you want to associate the SSL/TLS certiﬁcate.

Type: String

Response Syntax

{

"operations": [ {

"createdAt": number, "errorCode": "string", "errorDetails": "string",

(45)

Response Elements

"id": "string",

},

] }

Response Elements

These SSL/TLS certiﬁcates are only usable by Lightsail load balancers. You can't get the certiﬁcate and use it for another purpose.

Errors

(46)

See Also

NotFoundException

AttachStaticIp

Attaches a static IP address to a speciﬁc Amazon Lightsail instance.

Request Syntax

{ "instanceName": "string", "staticIpName": "string"

}

Request Parameters

instanceName (p. 21)

The instance name to which you want to attach the static IP address.

Type: String

staticIpName (p. 21)

The name of the static IP.

Type: String

Response Syntax

{ "operations": [ {

},

"operationDetails": "string", "operationType": "string", "resourceName": "string", "resourceType": "string", "status": "string",

(48)

Response Elements

"statusChangedAt": number }

]}

Response Elements

Errors

Note

(49)

See Also

CloseInstancePublicPorts

Closes ports for a speciﬁc Amazon Lightsail instance.

The CloseInstancePublicPorts action supports tag-based access control via resource tags applied to the resource identiﬁed by instanceName. For more information, see the Amazon Lightsail Developer Guide.

Request Syntax

{

"instanceName": "string", "portInfo": {

"cidrListAliases": [ "string" ], "cidrs": [ "string" ],

"fromPort": number, "ipv6Cidrs": [ "string" ], "protocol": "string", "toPort": number }}

Request Parameters

instanceName (p. 24)

The name of the instance for which to close ports.

Type: String

portInfo (p. 24)

An object to describe the ports to close for the speciﬁed instance.

Type: PortInfo (p. 663) object Required: Yes

Response Syntax

{

"operation": {

Amazon Lightsail

Amazon Lightsail

API Reference

API Version 2016-11-28

Amazon Lightsail: API Reference

Table of Contents

Welcome

Actions

AllocateStaticIp

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

AttachCertiﬁcateToDistribution

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

AttachDisk

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

AttachInstancesToLoadBalancer

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

AttachLoadBalancerTlsCertiﬁcate

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

AttachStaticIp

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CloseInstancePublicPorts

Request Syntax

Request Parameters

Response Syntax