Package com.pulumi.aws.ec2

Class SpotInstanceRequest

  • public class SpotInstanceRequest
extends com.pulumi.resources.CustomResource
    Provides an EC2 Spot Instance Request resource. This allows instances to be requested on the spot market. By default this provider creates Spot Instance Requests with a `persistent` type, which means that for the duration of their lifetime, AWS will launch an instance with the configured details if and when the spot market will accept the requested price. On destruction, this provider will make an attempt to terminate the associated Spot Instance if there is one present. Spot Instances requests with a `one-time` type will close the spot request when the instance is terminated either by the request being below the current spot price availability or by a user. > **NOTE:** Because their behavior depends on the live status of the spot market, Spot Instance Requests have a unique lifecycle that makes them behave differently than other Terraform resources. Most importantly: there is **no guarantee** that a Spot Instance exists to fulfill the request at any given point in time. See the [AWS Spot Instance documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-instances.html) for more information. > **NOTE [AWS strongly discourages](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-best-practices.html#which-spot-request-method-to-use) the use of the legacy APIs called by this resource. We recommend using the EC2 Instance resource with `instanceMarketOptions` instead. ## Example Usage 
     
 package generated_program;
 
 import com.pulumi.Context;
 import com.pulumi.Pulumi;
 import com.pulumi.core.Output;
 import com.pulumi.aws.ec2.SpotInstanceRequest;
 import com.pulumi.aws.ec2.SpotInstanceRequestArgs;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Map;
 import java.io.File;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 
 public class App {
     public static void main(String[] args) {
         Pulumi.run(App::stack);
     }
 
     public static void stack(Context ctx) {
         // Request a spot instance at $0.03
         var cheapWorker = new SpotInstanceRequest("cheapWorker", SpotInstanceRequestArgs.builder()
             .ami("ami-1234")
             .spotPrice("0.03")
             .instanceType("c4.xlarge")
             .tags(Map.of("Name", "CheapWorker"))
             .build());
 
     }
 }

    • Constructor Detail

      • SpotInstanceRequest

        public SpotInstanceRequest​(java.lang.String name)
        Parameters:
        name - The _unique_ name of the resulting resource.

      • SpotInstanceRequest

        public SpotInstanceRequest​(java.lang.String name,
                           @Nullable
                           SpotInstanceRequestArgs args)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.

      • SpotInstanceRequest

        public SpotInstanceRequest​(java.lang.String name,
                           @Nullable
                           SpotInstanceRequestArgs args,
                           @Nullable
                           com.pulumi.resources.CustomResourceOptions options)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.
        options - A bag of options that control this resource's behavior.

    • Method Detail

      • ami

        public com.pulumi.core.Output<java.lang.String> ami()
        Returns:
        AMI to use for the instance. Required unless `launchTemplate` is specified and the Launch Template specifies an AMI. If an AMI is specified in the Launch Template, setting `ami` will override the AMI specified in the Launch Template.

      • arn

        public com.pulumi.core.Output<java.lang.String> arn()

      • associatePublicIpAddress

        public com.pulumi.core.Output<java.lang.Boolean> associatePublicIpAddress()
        Returns:
        Whether to associate a public IP address with an instance in a VPC.

      • availabilityZone

        public com.pulumi.core.Output<java.lang.String> availabilityZone()
        Returns:
        AZ to start the instance in.

      • capacityReservationSpecification

        public com.pulumi.core.Output<SpotInstanceRequestCapacityReservationSpecification> capacityReservationSpecification()
        Returns:
        Describes an instance's Capacity Reservation targeting option. See Capacity Reservation Specification below for more details.

      • cpuOptions

        public com.pulumi.core.Output<SpotInstanceRequestCpuOptions> cpuOptions()
        Returns:
        The CPU options for the instance. See CPU Options below for more details.

      • creditSpecification

        public com.pulumi.core.Output<java.util.Optional<SpotInstanceRequestCreditSpecification>> creditSpecification()
        Returns:
        Configuration block for customizing the credit specification of the instance. See Credit Specification below for more details. This provider will only perform drift detection of its value when present in a configuration. Removing this configuration on existing instances will only stop managing it. It will not change the configuration back to the default for the instance type.

      • disableApiStop

        public com.pulumi.core.Output<java.lang.Boolean> disableApiStop()
        Returns:
        If true, enables [EC2 Instance Stop Protection](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Stop_Start.html#Using_StopProtection).

      • disableApiTermination

        public com.pulumi.core.Output<java.lang.Boolean> disableApiTermination()
        Returns:
        If true, enables [EC2 Instance Termination Protection](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingDisableAPITermination).

      • ebsBlockDevices

        public com.pulumi.core.Output<java.util.List<SpotInstanceRequestEbsBlockDevice>> ebsBlockDevices()
        Returns:
        One or more configuration blocks with additional EBS block devices to attach to the instance. Block device configurations only apply on resource creation. See Block Devices below for details on attributes and drift detection. When accessing this as an attribute reference, it is a set of objects.

      • ebsOptimized

        public com.pulumi.core.Output<java.lang.Boolean> ebsOptimized()
        Returns:
        If true, the launched EC2 instance will be EBS-optimized. Note that if this is not set on an instance type that is optimized by default then this will show as disabled but if the instance type is optimized by default then there is no need to set this and there is no effect to disabling it. See the [EBS Optimized section](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html) of the AWS User Guide for more information.

      • enablePrimaryIpv6

        public com.pulumi.core.Output<java.lang.Boolean> enablePrimaryIpv6()
        Returns:
        Whether to assign a primary IPv6 Global Unicast Address (GUA) to the instance when launched in a dual-stack or IPv6-only subnet. A primary IPv6 address ensures a consistent IPv6 address for the instance and is automatically assigned by AWS to the ENI. Once enabled, the first IPv6 GUA becomes the primary IPv6 address and cannot be disabled. The primary IPv6 address remains until the instance is terminated or the ENI is detached. Disabling `enablePrimaryIpv6` after it has been enabled forces recreation of the instance.

      • enclaveOptions

        public com.pulumi.core.Output<SpotInstanceRequestEnclaveOptions> enclaveOptions()
        Returns:
        Enable Nitro Enclaves on launched instances. See Enclave Options below for more details.

      • ephemeralBlockDevices

        public com.pulumi.core.Output<java.util.List<SpotInstanceRequestEphemeralBlockDevice>> ephemeralBlockDevices()
        Returns:
        One or more configuration blocks to customize Ephemeral (also known as "Instance Store") volumes on the instance. See Block Devices below for details. When accessing this as an attribute reference, it is a set of objects.

      • forceDestroy

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> forceDestroy()
        Returns:
        Destroys instance even if `disableApiTermination` or `disableApiStop` is set to `true`. Defaults to `false`. Once this parameter is set to `true`, a successful `pulumi up` run before a destroy is required to update this value in the resource state. Without a successful `pulumi up` after this parameter is set, this flag will have no effect. If setting this field in the same operation that would require replacing the instance or destroying the instance, this flag will not work. Additionally when importing an instance, a successful `pulumi up` is required to set this value in state before it will take effect on a destroy operation.

      • getPasswordData

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> getPasswordData()
        Returns:
        If true, wait for password data to become available and retrieve it. Useful for getting the administrator password for instances running Microsoft Windows. The password data is exported to the `passwordData` attribute. See [GetPasswordData](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_GetPasswordData.html) for more information.

      • hibernation

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> hibernation()
        Returns:
        If true, the launched EC2 instance will support hibernation.

      • hostId

        public com.pulumi.core.Output<java.lang.String> hostId()
        Returns:
        ID of a dedicated host that the instance will be assigned to. Use when an instance is to be launched on a specific dedicated host.

      • hostResourceGroupArn

        public com.pulumi.core.Output<java.lang.String> hostResourceGroupArn()
        Returns:
        ARN of the host resource group in which to launch the instances. If you specify an ARN, omit the `tenancy` parameter or set it to `host`.

      • iamInstanceProfile

        public com.pulumi.core.Output<java.lang.String> iamInstanceProfile()
        Returns:
        IAM Instance Profile to launch the instance with. Specified as the name of the Instance Profile. Ensure your credentials have the correct permission to assign the instance profile according to the [EC2 documentation](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html#roles-usingrole-ec2instance-permissions), notably `iam:PassRole`.

      • instanceInitiatedShutdownBehavior

        public com.pulumi.core.Output<java.lang.String> instanceInitiatedShutdownBehavior()
        Returns:
        Shutdown behavior for the instance. Amazon defaults this to `stop` for EBS-backed instances and `terminate` for instance-store instances. Cannot be set on instance-store instances. See [Shutdown Behavior](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingInstanceInitiatedShutdownBehavior) for more information.

      • instanceInterruptionBehavior

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> instanceInterruptionBehavior()
        Returns:
        Indicates Spot instance behavior when it is interrupted. Valid values are `terminate`, `stop`, or `hibernate`. Default value is `terminate`.

      • instanceState

        public com.pulumi.core.Output<java.lang.String> instanceState()

      • instanceType

        public com.pulumi.core.Output<java.lang.String> instanceType()
        Returns:
        Instance type to use for the instance. Required unless `launchTemplate` is specified and the Launch Template specifies an instance type. If an instance type is specified in the Launch Template, setting `instanceType` will override the instance type specified in the Launch Template. Updates to this field will trigger a stop/start of the EC2 instance.

      • ipv6AddressCount

        public com.pulumi.core.Output<java.lang.Integer> ipv6AddressCount()
        Returns:
        Number of IPv6 addresses to associate with the primary network interface. Amazon EC2 chooses the IPv6 addresses from the range of your subnet.

      • ipv6Addresses

        public com.pulumi.core.Output<java.util.List<java.lang.String>> ipv6Addresses()
        Returns:
        Specify one or more IPv6 addresses from the range of the subnet to associate with the primary network interface

      • keyName

        public com.pulumi.core.Output<java.lang.String> keyName()
        Returns:
        Key name of the Key Pair to use for the instance; which can be managed using the `aws.ec2.KeyPair` resource.

      • launchGroup

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> launchGroup()
        Returns:
        A launch group is a group of spot instances that launch together and terminate together. If left empty instances are launched and terminated individually.

      • launchTemplate

        public com.pulumi.core.Output<java.util.Optional<SpotInstanceRequestLaunchTemplate>> launchTemplate()
        Returns:
        Specifies a Launch Template to configure the instance. Parameters configured on this resource will override the corresponding parameters in the Launch Template. See Launch Template Specification below for more details.

      • maintenanceOptions

        public com.pulumi.core.Output<SpotInstanceRequestMaintenanceOptions> maintenanceOptions()
        Returns:
        Maintenance and recovery options for the instance. See Maintenance Options below for more details.

      • metadataOptions

        public com.pulumi.core.Output<SpotInstanceRequestMetadataOptions> metadataOptions()
        Returns:
        Customize the metadata options of the instance. See Metadata Options below for more details.

      • monitoring

        public com.pulumi.core.Output<java.lang.Boolean> monitoring()
        Returns:
        If true, the launched EC2 instance will have detailed monitoring enabled. (Available since v0.6.0)

      • networkInterfaces

        public com.pulumi.core.Output<java.util.List<SpotInstanceRequestNetworkInterface>> networkInterfaces()
        Returns:
        Customize network interfaces to be attached at instance boot time. See Network Interfaces below for more details.

      • outpostArn

        public com.pulumi.core.Output<java.lang.String> outpostArn()

      • passwordData

        public com.pulumi.core.Output<java.lang.String> passwordData()

      • placementGroup

        public com.pulumi.core.Output<java.lang.String> placementGroup()
        Returns:
        Placement Group to start the instance in. Conflicts with `placementGroupId`.

      • placementGroupId

        public com.pulumi.core.Output<java.lang.String> placementGroupId()
        Returns:
        Placement Group ID to start the instance in. Conflicts with `placementGroup`.

      • placementPartitionNumber

        public com.pulumi.core.Output<java.lang.Integer> placementPartitionNumber()
        Returns:
        Number of the partition the instance is in. Valid only if the `aws.ec2.PlacementGroup` resource's `strategy` argument is set to `"partition"`.

      • primaryNetworkInterfaceId

        public com.pulumi.core.Output<java.lang.String> primaryNetworkInterfaceId()

      • primaryNetworkInterfaces

        public com.pulumi.core.Output<java.util.List<SpotInstanceRequestPrimaryNetworkInterface>> primaryNetworkInterfaces()
        Returns:
        The primary network interface. See Primary Network Interface below.

      • privateDns

        public com.pulumi.core.Output<java.lang.String> privateDns()
        Returns:
        The private DNS name assigned to the instance. Can only be used inside the Amazon EC2, and only available if you've enabled DNS hostnames for your VPC

      • privateDnsNameOptions

        public com.pulumi.core.Output<SpotInstanceRequestPrivateDnsNameOptions> privateDnsNameOptions()
        Returns:
        Options for the instance hostname. The default values are inherited from the subnet. See Private DNS Name Options below for more details.

      • privateIp

        public com.pulumi.core.Output<java.lang.String> privateIp()
        Returns:
        Private IP address to associate with the instance in a VPC.

      • publicDns

        public com.pulumi.core.Output<java.lang.String> publicDns()
        Returns:
        The public DNS name assigned to the instance. For EC2-VPC, this is only available if you've enabled DNS hostnames for your VPC

      • publicIp

        public com.pulumi.core.Output<java.lang.String> publicIp()
        Returns:
        The public IP address assigned to the instance, if applicable.

      • region

        public com.pulumi.core.Output<java.lang.String> region()
        Returns:
        Region where this resource will be [managed](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints). Defaults to the Region set in the provider configuration.

      • rootBlockDevice

        public com.pulumi.core.Output<SpotInstanceRequestRootBlockDevice> rootBlockDevice()
        Returns:
        Configuration block to customize details about the root block device of the instance. See Block Devices below for details. When accessing this as an attribute reference, it is a list containing one object.

      • secondaryNetworkInterfaces

        public com.pulumi.core.Output<java.util.List<SpotInstanceRequestSecondaryNetworkInterface>> secondaryNetworkInterfaces()
        Returns:
        One or more secondary network interfaces to attach to the instance at launch time. See Secondary Network Interface below for more details.

      • secondaryPrivateIps

        public com.pulumi.core.Output<java.util.List<java.lang.String>> secondaryPrivateIps()
        Returns:
        List of secondary private IPv4 addresses to assign to the instance's primary network interface (eth0) in a VPC. Can only be assigned to the primary network interface (eth0) attached at instance creation, not a pre-existing network interface i.e., referenced in a `networkInterface` block. Refer to the [Elastic network interfaces documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html#AvailableIpPerENI) to see the maximum number of private IP addresses allowed per instance type.

      • securityGroups

        public com.pulumi.core.Output<java.util.List<java.lang.String>> securityGroups()
        Returns:
        List of security group names to associate with. > **NOTE:** If you are creating Instances in a VPC, use `vpcSecurityGroupIds` instead.

      • sourceDestCheck

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> sourceDestCheck()
        Returns:
        Controls if traffic is routed to the instance when the destination address does not match the instance. Used for NAT or VPNs. Defaults true.

      • spotBidStatus

        public com.pulumi.core.Output<java.lang.String> spotBidStatus()
        Returns:
        The current [bid status](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-bid-status.html) of the Spot Instance Request.

      • spotInstanceId

        public com.pulumi.core.Output<java.lang.String> spotInstanceId()
        Returns:
        The Instance ID (if any) that is currently fulfilling the Spot Instance request.

      • spotPrice

        public com.pulumi.core.Output<java.lang.String> spotPrice()
        Returns:
        The maximum price to request on the spot market.

      • spotRequestState

        public com.pulumi.core.Output<java.lang.String> spotRequestState()
        Returns:
        The current [request state](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-requests.html#creating-spot-request-status) of the Spot Instance Request.

      • spotType

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> spotType()
        Returns:
        If set to `one-time`, after the instance is terminated, the spot request will be closed.

      • subnetId

        public com.pulumi.core.Output<java.lang.String> subnetId()
        Returns:
        VPC Subnet ID to launch in.

      • tags

        public com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.String>>> tags()
        Returns:
        Map of tags to assign to the resource. Note that these tags apply to the instance and not block storage devices. If configured with a provider `defaultTags` configuration block present, tags with matching keys will overwrite those defined at the provider-level.

      • tagsAll

        public com.pulumi.core.Output<java.util.Map<java.lang.String,​java.lang.String>> tagsAll()
        Returns:
        A map of tags assigned to the resource, including those inherited from the provider `defaultTags` configuration block.

      • tenancy

        public com.pulumi.core.Output<java.lang.String> tenancy()
        Returns:
        Tenancy of the instance (if the instance is running in a VPC). An instance with a tenancy of `dedicated` runs on single-tenant hardware. The `host` tenancy is not supported for the import-instance command. Valid values are `default`, `dedicated`, and `host`.

      • userData

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> userData()
        Returns:
        User data to provide when launching the instance. Do not pass gzip-compressed data via this argument; see `userDataBase64` instead. Updates to this field will trigger a stop/start of the EC2 instance by default. If the `userDataReplaceOnChange` is set then updates to this field will trigger a destroy and recreate of the EC2 instance.

      • userDataBase64

        public com.pulumi.core.Output<java.lang.String> userDataBase64()
        Returns:
        Can be used instead of `userData` to pass base64-encoded binary data directly. Use this instead of `userData` whenever the value is not a valid UTF-8 string. For example, gzip-encoded user data must be base64-encoded and passed via this argument to avoid corruption. Updates to this field will trigger a stop/start of the EC2 instance by default. If the `userDataReplaceOnChange` is set then updates to this field will trigger a destroy and recreate of the EC2 instance.

      • userDataReplaceOnChange

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> userDataReplaceOnChange()
        Returns:
        When used in combination with `userData` or `userDataBase64` will trigger a destroy and recreate of the EC2 instance when set to `true`. Defaults to `false` if not set.

      • validFrom

        public com.pulumi.core.Output<java.lang.String> validFrom()
        Returns:
        The start date and time of the request, in UTC [RFC3339](https://tools.ietf.org/html/rfc3339#section-5.8) format(for example, YYYY-MM-DDTHH:MM:SSZ). The default is to start fulfilling the request immediately.

      • validUntil

        public com.pulumi.core.Output<java.lang.String> validUntil()
        Returns:
        The end date and time of the request, in UTC [RFC3339](https://tools.ietf.org/html/rfc3339#section-5.8) format(for example, YYYY-MM-DDTHH:MM:SSZ). At this point, no new Spot instance requests are placed or enabled to fulfill the request. The default end date is 7 days from the current date.

      • volumeTags

        public com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.String>>> volumeTags()
        Returns:
        Map of tags to assign, at instance-creation time, to root and EBS volumes. > **NOTE:** Do not use `volumeTags` if you plan to manage block device tags outside the `aws.ec2.Instance` configuration, such as using `tags` in an `aws.ebs.Volume` resource attached via `aws.ec2.VolumeAttachment`. Doing so will result in resource cycling and inconsistent behavior.

      • vpcSecurityGroupIds

        public com.pulumi.core.Output<java.util.List<java.lang.String>> vpcSecurityGroupIds()
        Returns:
        List of security group IDs to associate with.

      • waitForFulfillment

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> waitForFulfillment()
        Returns:
        If set, this provider will wait for the Spot Request to be fulfilled, and will throw an error if the timeout of 10m is reached.

      • get

        public static SpotInstanceRequest get​(java.lang.String name,
                                      com.pulumi.core.Output<java.lang.String> id,
                                      @Nullable
                                      SpotInstanceRequestState state,
                                      @Nullable
                                      com.pulumi.resources.CustomResourceOptions options)
        Get an existing Host resource's state with the given name, ID, and optional extra properties used to qualify the lookup.
        Parameters:
        name - The _unique_ name of the resulting resource.
        id - The _unique_ provider ID of the resource to lookup.
        state -
        options - Optional settings to control the behavior of the CustomResource.