Ocean: AWS

This page demonstrates how to create an Ocean cluster using AWS using the Spotinst Terraform plugin.

This post assumes that you already have a Spotinst account and went through Spotinst Terraform Installation & Configuration

Example Usage – Ocean Cluster
 resource "spotinst_ocean_aws" "demo_cluster" {
  name          = "demo"
  controller_id = "myClusterID"
  region        = "us-west-2"

  max_size         = 3
  min_size         = 1
  desired_capacity = 2

  subnet_ids = ["subnet-123456789"]
  whitelist  = ["t1.micro", "m1.small"]

   // --- LAUNCH CONFIGURATION --------------
  image_id             = "ami-123456"
  security_groups      = ["sg-123456"]
  key_name             = "my key"
  user_data            = "echo hello world"
  iam_instance_profile = "iam-profile"
  root_volume_size     = 20

  associate_public_ip_address = true
  load_balancers {
    arn  = "arn:aws:elasticloadbalancing:us-west-2:fake-arn"
    type = "TARGET_GROUP"

  load_balancers {
    name = "AntonK"
    type = "CLASSIC"

  tags {
    key   = "fakeKey"
    value = "fakeValue"
 // ---------------------------------------

  // --- STRATEGY --------------------
 fallback_to_ondemand       = false
 spot_percentage            = 50
 draining_timeout           = 120
 utilize_reserved_instances = true
 // ---------------------------------

  // --- AUTOSCALER -----------------
 autoscaler {
    autoscale_is_enabled     = true
    autoscale_is_auto_config = false
    autoscale_cooldown       = 300

    autoscale_headroom {
      cpu_per_unit    = 1024
      gpu_per_unit    = 1
      memory_per_unit = 512
      num_of_units    = 3

    autoscale_down {
      max_scale_down_percentage = 10

    resource_limits {
      max_vcpu       = 1024
      max_memory_gib = 30
 // --------------------------------
    update_policy {
      should_roll = true
      roll_config {
        batch_size_percentage = 100

output "ocean_id" {
  value = spotinst_ocean_aws.demo_cluster.id



Argument Reference

Parameter Type Description
name * String

The cluster name.

Example: demo
controller_id * String

The ocean cluster identifier.

Example: ocean.k8s
region * String

The region the cluster will run in.

Example: us-east-2
max_size Integer

The upper limit of instances the cluster can scale up to.

Example: 1000
Default: 1000
min_size Integer

The lower limit of instances the cluster can scale down to.

Example: 100
desired_capacity Integer

The number of instances to launch and maintain in the cluster.

Example: 500
subnet_ids * Array<String>

A comma-separated list of subnet identifiers for the Ocean cluster. Subnet IDs should be configured with auto assign public ip.

Example: ["subnet-09d9755d9bdeca3c5"]
whitelist Array<String>

Instance types allowed in the Ocean cluster. Cannot be configured if `blacklist` is configured.

Example: ["t1.micro", "m1.small"]
blacklist Array<String>

Instance types not allowed in the Ocean cluster. Cannot be configured if `whitelist` is configured.

Example: ["t1.micro", "m1.small"]
user_data String

Base64-encoded MIME user data to make available to the instances.

Example: echo hello world
image_id * String

ID of the image used to launch the instances.

Example: ami-12345
security_groups * Array<String>

One or more security group ids.

Example: ["sig-123456", "sig-98765"]
key_name String

The key pair to attach the instances.

Example: myKey
iam_instance_profile String

The instance profile iam role.

Example: myRoleName
root_volume_size Integer

(Optional) The size (in Gb) to allocate for the root volume. Minimum `20`.

Example: 120
load_balancers Array<Object>

Array of load balancer objects to add to ocean cluster

load_balancers.arn String

Required if type is set to TARGET_GROUP

load_balancers.name String

Required if type is set to CLASSIC

load_balancers.type * String


fallback_to_ondemand Boolean

If not Spot instance markets are available, enable Ocean to launch On-Demand instances instead.

Example: true
spot_percentage Integer

The percentage of Spot instances the cluster should maintain. Min 0, max 100.

Example: 100
Default: 100
draining_timeout String

The time in seconds, the instance is allowed to run while detached from the ELB. This is to allow the instance time to be drained from incoming TCP connections before terminating it, during a scale down operation.

Example: 120
utilize_reserved_instances Boolean

If Reserved instances exist, OCean will utilize them before launching Spot instances.

Example: true
Default: false
autoscaler Object

Describes the Ocean Kubernetes autoscaler.

autoscaler.autoscale_is_enabled Boolean

Enable the Ocean Kubernetes autoscaler.

Example: true
autoscaler.autoscale_is_auto_config Boolean

Automatically configure and optimize headroom resources.

Example: true
autoscaler.autoscale_cooldown Integer

Cooldown period (in seconds) between scaling down actions.

Example: 300
autoscaler.autoscale_headroom Object

Spare resource capacity management enabling fast assignment of Pods without waiting for new resources to launch.

autoscaler.autoscale_headroom.cpu_per_unit Integer

Optionally configure the number of CPUs to allocate the headroom. CPUs are denoted in millicores, where 1000 millicores = 1 vCPU.

Example: 1024
autoscaler.autoscale_headroom.gpu_per_unit Integer

Optionally configure the number of GPUS to allocate the headroom.

autoscaler.autoscale_headroom.memory_per_unit Integer

Optionally configure the amount of memory (MB) to allocate the headroom.

Example: 512
autoscaler.autoscale_headroom.num_of_units Integer

The number of units to retain as headroom, where each unit has the defined headroom CPU and memory.

Example: 10
autoscaler.autoscale_down Object

Auto Scaling scale down operations.

autoscaler.autoscale_down.max_scale_down_percentage Integer

Would represent the maximum % to scale-down. Number between 1-100.

Example: 10
autoscaler.resource_periods Object

Optionally set upper and lower bounds on the resource usage of the cluster.

autoscaler.resource_periods.max_vcpu Integer

The maximum cpu in vCPU units that can be allocated to the cluster.

Example: 1024
autoscaler.resource_periods.max_memory_gib Integer

The maximum memory in GiB units that can be allocated to the cluster.

Example: 20
tags Object

Optionally adds tags to instances launched in an Ocean cluster.

Example: myTag
tags.key String

The tag key.

Example: fakeKey
tags.value String

The tag value.

Example: fakeValue
update_policy Object

While used, you can control whether the group should perform a deployment after an update to the configuration.

update_policy.should_roll * Boolean

Enables roll on update.

Example: true
update_policy.roll_config * Object

Roll parameters.

update_policy.roll_config.batch_size_percentage * Integer

Sets the percentage of the cluster capacity to deploy in each batch.

Example: 33