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"
      name = "AntonK"
      type = "CLASSIC"

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

  // --- STRATEGY --------------------
 fallback_to_ondemand       = false
 spot_percentage            = 50
 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

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


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
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.Cooldown period between scaling actions. Integer

Cooldown period between scaling 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.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