SpotByFlexeraLogo
API docs by Redocly

Spot by Flexera API (1.0)

Download OpenAPI specification:Download

E-mail: support@spot.io

Welcome to the Spot by Flexera OpenAPI Specification. Here you will find REST definitions for all Spot products and platform administration tasks.

The API is hosted at https://api.spotinst.io and requires Bearer Token Authentication.

For more information on how to use the Spot platform, including user guides, developer guides, concepts, and tutorials, see the external Spot Documentation.

https://docs.spot.io/

Organizations

Create User

Create a new user and link it to the creator's organization (the organization ID from the personal token attached to the API call). If the role is a viewer, the user is also linked to the default account for the organization.

Authorizations:
auth
query Parameters
generateToken
boolean
Example: generateToken=true

If true, then the response will include personalAccessToken string

Request Body schema: application/json
email
string

Email

firstName
string

The first name of the user. Note: names cannot include these characters: + = @

lastName
string

The last name of the user. Note: names cannot include these characters: + = @

password
string

Password

role
string

User's role

Responses

Request samples

Content type
application/json
{
  • "firstName": "Test",
  • "lastName": "Test",
  • "email": "test@spot.io",
  • "password": "password1234",
  • "role": "viewer"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Users

Get all the users of the organization.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Policies

Get all the policies of the organization.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get User Details

Get all the details of a given user.

Authorizations:
auth
path Parameters
userId
required
string
Example: u-1234abcd

Identifier of a user.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete user

Delete a given user(console or programmatic) from organization.

Authorizations:
auth
path Parameters
userId
required
string
Example: u-1234abcd or pu-87654321

Identifier of a user.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

User - Update User Group Mapping

Update the mapping of a given user to user groups

Authorizations:
auth
path Parameters
userId
required
string
Example: u-1234abcd

Identifier of a user.

Request Body schema: application/json
userGroupIds
Array of strings

A list of the user groups to register the given user to (should be existing user groups only)

Responses

Request samples

Content type
application/json
{
  • "userGroupIds": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

User - Update Policy Mapping

Update the mapping of a given user directly to policies

Authorizations:
auth
path Parameters
userId
required
string
Example: u-1234abcd

Identifier of a user.

Request Body schema: application/json
Array of objects

The policies to register under the given user (should be existing policies only)

Array
accountIds
Array of strings

A list of account IDs to register with the assigned under the given user (should be existing accounts only)

policyId
string

A policy ID to register under the given user (should be existing policy only)

Responses

Request samples

Content type
application/json
{
  • "policies": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get User

Get user's account mapping

Authorizations:
auth
query Parameters
userEmail
required
string
Example: userEmail=test@spot.io

Target user email address

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Organization

Delete a Spot Organization. ID of the organization can be obtained from your Spot console via the following link: https://console.spotinst.com/#/settings/organization/general > Note: This cannot be undone. Take caution.

Authorizations:
auth
path Parameters
organizationId
required
string
Example: 606079812345

ID of the organization you would like to delete

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Programmatic User

This API creates a new programmatic user (not a human user). Use this API to provide privileges to an application that needs to interface with Spot. Spot returns a token that the programmatic user can use to perform actions with. requires accounts or policies.

Authorizations:
auth
Request Body schema: application/json
Array of objects

All the accounts the programmatic user will have access to. If used - Cannot be empty.

description
string

Brief description of the user.

name
required
string

Name of the programmatic user. Note: names cannot include these characters: + = @

Array of objects

All the policies the programmatic user will have access to. If used - Cannot be empty.

Responses

Request samples

Content type
application/json
{
  • "description": "test programmatic",
  • "name": "testProgrammaticApi",
  • "accounts": [
    ],
  • "policies": [
    ]
}

Response samples

Content type
application/json
{
  • "response": {
    }
}

Create Organization

Create a Spot Organization.

Authorizations:
auth
Request Body schema: application/json
object

Organization

name
string

Provide a name for your organization. The organization name must contain at least one character that is a-z or A-Z

Responses

Request samples

Content type
application/json
{
  • "organization": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Access Policy Actions

Get actions for access policies.

Authorizations:
auth
query Parameters
category
string
Example: category=update

The policy action category that you would like to get the information for

name
string
Example: name=ocean:updateCluster

The policy action Name that you would like to get the information for

resourcePattern
string
Example: resourcePattern=ocean:o-*

The policy action resource pattern that you would like to get the information for

scope
string
Example: scope=account

The policy action scope that you would like to get the information for

service
string
Example: service=ocean

The policy action service that you would like to get the information for

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Access Policy

Create an access policy to define the user's permissions more granularly than the role-based permissions.

Authorizations:
auth
Request Body schema: application/json
object

Set access policy settings. Example - Acme, Inc.

description
string

Short description of policy

name
string

Name of the Policy. Note: names cannot include these characters: + = @

object

Set permissions objects list

Responses

Request samples

Content type
application/json
{
  • "policy": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Access Policy

Updates an access policy settings.

Authorizations:
auth
path Parameters
policyId
required
string
Example: pol-2344nn

The access policy ID to operate on

Request Body schema: application/json
object

Set access policy settings

name
string

Set access policy name

Responses

Request samples

Content type
application/json
{
  • "policy": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Access Policy

Deletes an access policy settings.

Authorizations:
auth
path Parameters
policyId
required
string
Example: pol-2344nn

The access policy ID to operate on

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List All User Groups

List all user-groups of your Spot organization

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create a new User Group

Create a new user-group of your Spot organization

Authorizations:
auth
Request Body schema: application/json
description
string

user group description

name
string

Name of the user group. Note: names cannot include these characters: + = @

Array of objects

The policies to register under the given group (should be existing policies only)

userIds
Array of strings

The users to register under the created group (should be existing users only)

Responses

Request samples

Content type
application/json
{
  • "name": "Developers",
  • "description": "managing permissions to my group of developers",
  • "userIds": [
    ],
  • "policies": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get User Group Details

Get the details of a user Group

Authorizations:
auth
path Parameters
userGroupId
required
string
Example: ugr-1234abcd

Identifier of a user Group.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update User Group Details

Update the details of a user Group

Authorizations:
auth
path Parameters
userGroupId
required
string
Example: ugr-1234abcd

Identifier of a user Group.

Request Body schema: application/json
description
string non-empty

user group description

name
string non-empty

user group name

Responses

Request samples

Content type
application/json
{
  • "name": "Developers",
  • "description": "managing permissions to my group of developers"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete User Group

Delete a user Group

Authorizations:
auth
path Parameters
userGroupId
required
string
Example: ugr-1234abcd

Identifier of a user Group.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

User Group - Update User Mapping

Update the mapping of a given user group to users

Authorizations:
auth
path Parameters
userGroupId
required
string
Example: ugr-1234abcd

Identifier of a user Group.

Request Body schema: application/json
userIds
Array of strings

The users to register under the given user group (should be existing users only)

Responses

Request samples

Content type
application/json
{
  • "userIds": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

User Group - Update Policy Mapping

Update the mapping of a given user group to policies

Authorizations:
auth
path Parameters
userGroupId
required
string
Example: ugr-1234abcd

Identifier of a user Group.

Request Body schema: application/json
Array of objects

The policies to register under the given user group (should be existing policies only)

Array
accountIds
Array of strings

A list of accounts to register with the assigned under the given group (should be existing accounts only)

policyId
string

A policy to register under the given group (should be existing policy only)

Responses

Request samples

Content type
application/json
{
  • "policies": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get FinOps Authorization Policies

Get all available FinOps authorization policies.

Authorizations:
auth
query Parameters
paginationKey
string

key used to fetch the next page of items

paginationSize
integer

number of items to include in the response

targetOrganizationId
string

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get FinOps Authorization For User

Get the user-level FinOps authorization configuration for the specified user.

Authorizations:
auth
path Parameters
userId
required
string

The userId to retrieve.

query Parameters
includeChildOrgs
boolean
Default: false

Include the configurations for child organizations.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update FinOps Authorization For User

Update the FinOps authorization configuration for a user.

Authorizations:
auth
path Parameters
userId
required
string
Request Body schema:
object (userAuthConfigChanges)

The FinOps authorization changes for a user.

Array of objects or null (basicRequestListModification)

List of accounts to add/remove. If user or group already has an existing list of accounts, the requested actions will be applied to this existing list unless resetAccounts is true (which will clear all existing accounts first).

Array of objects or null (costTypeRequestListModification)

List of cost types to add/remove. Cost type applies to all accounts assigned to the user (regardless of how the user has access to the account). If the user already has an existing list of cost types, the requested actions are applied to this existing list unless resetCostTypes is true (which will clear all existing cost types first).

organizationId
string or null

ID of the target Spot organization where the authorization configuration should be applied. Optional: Defaults to the caller's current Spot organization. If specified, the ID must be one of these:

  • The caller's current Spot organization
  • A child Spot organization of the caller's current Spot organization
Array of objects or null (basicRequestListModification)

List of policies to add/remove. If user or group already has an existing list of policies, the requested actions will be applied to this existing list unless resetPolicies is true (which will clear all existing policies first).

resetAccounts
boolean

If true, the existing list of accounts is emptied prior to performing the changes requested.

resetCostTypes
boolean

If true, the existing list of cost types is emptied prior to performing the changes requested.

resetPolicies
boolean

If true, the existing list of policies is emptied prior to performing the changes requested.

Responses

Request samples

Content type
{
  • "authChanges": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Accounts

Update Account

Update information in an account such as the account name and slack channel. To use this command, permissions for organization admin are required. Granular permissions will require access policies with the following actions: setup:updateAccount

Authorizations:
auth
path Parameters
accountId
required
string
Example: act-123456789

The ID of the account you want to update.

Request Body schema: application/json
required
object

Used for updating items in an account.

name
string

The new name of the account. Cannot be null or empty.

slackNotificationChannels
Array of strings

List of strings containing the URLs of the slack channels to be added.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Account

Delete a Spot Account. The Spot Account ID can be obtained from your Spot console via the following link: https://console.spotinst.com/#/settings/account/general . Note This cannot be undone – take caution. Only Organization Admins can perform this action. In case you want to delete your default Spot account which is the account visible when you first log in please contact Support.

Authorizations:
auth
path Parameters
accountId
required
string
Example: act-123456789

The ID of the account you want to delete.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Users

Get all users in the organization, their details, and mapped accounts. Providing the optional account ID parameter will filter out all users not mapped to that account.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account you would like to get retrieve users from

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Assign Users to Accounts

Assign users to accounts in bulk. Only accounts under the creator's own organization are allowed. Creator's organization ID is taken from the personal token attached to the API call.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
Array of assignUsersToAccounts-example2 (object) or assignUsersToAccounts-example3 (object)

Mappings objects include user, accountID and role.

Array
Any of
accountId
string

Account for which to provide the specified user with the specified role.

role
string

Valid values "viewer", "editor". Required on permissionStrategy = ROLE_BASED

userId
string

One of userEmail / userId is required. identify user by its user ID

Responses

Request samples

Content type
application/json
Example
{
  • "mappings": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update User Permissions

Change the users' permissions for an account (only accounts under the creator's own organization are allowed). Creator's organization ID is taken from the personal token attached to the API call.

Authorizations:
auth
path Parameters
accountId
required
string
Example: act-123abc

ID of the account associated with your token

Request Body schema: application/json
One of
permissionStrategy
string
Default: "ROLE_BASED"

Set the user permissions type, by role or by access policy. Valid values "ROLE_BASED", "POLICY_BASED"

role
string

Valid values "viewer", "editor". Required on permissionStrategy = ROLE_BASED

userId
string

One of userEmail / userId is required. identify user by its user ID

Responses

Request samples

Content type
application/json
Example
{
  • "userId": "u-1234",
  • "permissionStrategy": "POLICY_BASED",
  • "role": "editor"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach User

Detach a user from an account (only accounts under the creator's own organization are allowed). Creator's organization ID is taken from the personal token attached to the API call.

Authorizations:
auth
path Parameters
accountId
required
string
Example: act-123456789

The ID of the account you want to update.

Request Body schema: application/json
userEmail
required
string

Email of the user that is going to be deleted

Responses

Request samples

Content type
application/json
{
  • "userEmail": "test@gmail.com"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Set Existing User Permissions

Add a user to the account and set its permissions on the account. Creator's organization ID is taken from the personal token attached to the API call.

Authorizations:
auth
path Parameters
accountId
required
string
Example: act-123456789

The ID of the account you want to update.

Request Body schema: application/json
One of
role
string

Valid values - "viewer", "editor". Required on permissionStrategy = ROLE_BASED

userEmail
string

One of userEmail / userId is required. identify user by its user ID

Responses

Request samples

Content type
application/json
Example
{
  • "userEmail": "test@spot.io",
  • "role": "viewer"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Account

Create a Spot account.

Authorizations:
auth
Request Body schema: application/json
object

Account

name
string

Provide a name for your account. The account name must contain at least one character that is a-z or A-Z

Responses

Request samples

Content type
application/json
{
  • "account": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Accounts

Get a list of Spot accounts in your organization. When used without any parameters, the provided token must have Organization Admin permissions and the output will contain all the Organization's accounts. Note In case you want to list all the accounts associated with Organization you can use the below request URL without the cloudAccountId parameter, https://api.spotinst.io/setup/account

Authorizations:
auth
query Parameters
cloudAccountId
string
Example: cloudAccountId=634245686616

Will list only the Spot accounts connected to the specified account ID.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Access Policies

Get access policy settings.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Set Credentials for AWS

Link a Spot account to an AWS Cloud account.
Please create external id using spot api (see /setup/credentials/aws/externalId)
and use it when creating the AWS role and then call this route with your AWS role's arn to link it to your spot account

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Credentials details

iamRole
required
string

Provide the IAM Role ARN connected to another AWS account 922761411349 and with the latest Spot Policy - https://docs.spot.io/administration/api/spot-policy-in-aws

Responses

Request samples

Content type
application/json
{
  • "credentials": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create AWS account external id

Create aws account external id
You should use the external id when creating your AWS role for your spot account
and after you create the role you need to call set-aws-credentials Set Credentials for AWS
to link your AWS account with your spot account

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Set Credentials for GCP

Link a Spot account to a GCP Cloud account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Set service account for credentials

auth_provider_x509_cert_url
auth_uri
string

Authentication uri, Default - https://accounts.google.com/o/oauth2/auth

client_email
string

Email associated with service account

client_id
string

Client ID of service account

client_x509_cert_url
string

Should be in following format - "https://www.googleapis.com/robot/v1/metadata/x509/"

private_key
string

Private key of JSON key created during prerequisites stage

private_key_id
string

Private key ID of JSON key created during prerequisites stage

project_id
string

Name of project in GCP

token_uri
string
type
string

Valid values - service_account

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Validate Credentials for GCP

Validate the credentials for connecting a Spot account to an GCP Cloud account. The validation will test the credentials without actually set it. Please notice to run the set credentials request to perform the set account credentials.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Set service account for credentials

auth_provider_x509_cert_url
auth_uri
string

Authentication uri, Default - https://accounts.google.com/o/oauth2/auth

client_email
string

Email associated with service account

client_id
string

Client ID of service account

client_x509_cert_url
string

Should be in following format - "https://www.googleapis.com/robot/v1/metadata/x509/"

private_key
string

Private key of JSON key created during prerequisites stage

private_key_id
string

Private key ID of JSON key created during prerequisites stage

project_id
string

Name of project in GCP

token_uri
string
type
string

Valid values - service_account

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Set Credentials for Azure

Link a Spot account to an Azure Cloud account. Enter the expiration date of your Azure client secret. Spot can remind you to update before the credentials expire. If your client secret expires, your Azure subscription will disconnect from Spot and prevent Spot from managing your resources.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
clientId
required
string

Set the application ID

clientSecret
required
string

Set the key secret

expirationDate
required
string <date-time>

Set the key secret expiration date

subscriptionId
required
string

Set the subscription ID

tenantId
required
string

Set the directory ID

Responses

Request samples

Content type
application/json
{
  • "clientId": 111111111,
  • "clientSecret": "32431r2431434132",
  • "tenantId": "1321e1e3123er23",
  • "subscriptionId": "234r3141131",
  • "expirationDate": "2025-12-31T23:59:00.000Z"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Credentials for Azure

Get the credentials connecting a Spot account to an Azure Cloud account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Validate Credentials for Azure

Validate the credentials for connecting a Spot account to an Azure Cloud account. The validation will test the credentials without actually set it. Please notice to run the set credentials request to perform the set Azure account credentials (https://docs.spot.io/connect-your-cloud-provider/azure-account) .

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
clientId
string

Set the application ID

clientSecret
string

Set the key secret

subscriptionId
string

Set the subscription ID

tenantId
string

Set the directory ID

Responses

Request samples

Content type
application/json
{
  • "clientId": "111111111",
  • "clientSecret": "32431r2431434132",
  • "tenantId": "1321e1e3123er23",
  • "subscriptionId": "234r3141131"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Setup Cost Intelligence

Sets up and enables Cost Intelligence functionality on a Spot account. The Spot account must already have credentials and be linked to a valid cloud provider account (e.g. AWS account, Azure subscription, etc).

Authorizations:
auth
Request Body schema: application/json
required
object (Account)
accountId
required
string

Spot account ID

Responses

Request samples

Content type
application/json
{
  • "account": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cost Intelligence Registered Accounts

Get list of Spot accounts where Cost Intelligence has been setup.

Authorizations:
auth
query Parameters
paginationKey
string

Key used to fetch a specific page of items

paginationSize
integer

Number of items to include in the response

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Perform Cost Intelligence Setup Validations

Validate that Cost Intelligence can be setup on the specified Spot Account.

Authorizations:
auth
Request Body schema: application/json
required
object (Account)
accountId
required
string

Spot account ID

Responses

Request samples

Content type
application/json
{
  • "account": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Billing Engine Registered Accounts

Get list of Spot accounts where Billing Engine has been setup.

Authorizations:
auth
query Parameters
paginationKey
string

Key used to fetch a specific page of items

paginationSize
integer

Number of items to include in the response

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Setup Billing Engine

Sets up and enables Billing Engine functionality on a Spot account. The Spot account must already have credentials and be linked to a valid cloud provider account (e.g. AWS account, Azure billing account, etc).

Authorizations:
auth
Request Body schema: application/json
accountId
required
string

Spot Account ID.

(object or null) or (BERegisteredSetupAccountAwsConfig (object or null)) or (BERegisteredSetupAccountAzureConfig (object or null)) or (BERegisteredSetupAccountGcpConfig (object or null))

Configuration for the Billing Engine (e.g. location of the billing data)

Responses

Request samples

Content type
application/json
{
  • "accountId": "act-23432",
  • "config": { }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Perform Billing Engine Setup Validations

Validate that Billing Engine can be setup on the specified Spot Account.

Authorizations:
auth
Request Body schema: application/json
accountId
required
string

Spot Account ID.

(object or null) or (BERegisteredSetupAccountAwsConfig (object or null)) or (BERegisteredSetupAccountAzureConfig (object or null)) or (BERegisteredSetupAccountGcpConfig (object or null))

Configuration for the Billing Engine (e.g. location of the billing data)

Responses

Request samples

Content type
application/json
{
  • "accountId": "act-23432",
  • "config": { }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean AWS

Ocean - Serverless containers for Amazon Web Services (AWS)

Ocean Concepts and Tutorials

Create Cluster

Prerequisites

The Ocean Controller is used to monitor the cluster resources and report back to Ocean. The Ocean Controller is required for Ocean Cloud.

To install the Ocean Controller, complete and run the following script on a machine with the kubectl command line tool installed and configured:

#!/usr/bin/env bash
curl -fsSL http://spotinst-public.s3.amazonaws.com/integrations/kubernetes/cluster-controller/scripts/init.sh | \
SPOTINST_TOKEN=<ENTER YOUR TOKEN HERE> \
SPOTINST_ACCOUNT=<ENTER YOUR SPOTINST ACCOUNT ID HERE> \
SPOTINST_CLUSTER_IDENTIFIER=<ENTER YOUR CLUSTER IDENTIFIER HERE> \
bash
Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (AWS Cluster)

The object specifying the configuration of the Ocean cluster.

object (auto-scaler)

The automatic scaling mechanism used in Ocean for Kubernetes.

object (Capacity Units)

The overall capability of the Ocean cluster expressed as number of instances and specified with a minimum, a maximum, and a target number of running instances.

required
object (Ocean Compute)

Compute specifications for the Ocean cluster.

controllerClusterId
required
string

Enter the reporting identifier for the Ocean Controller.

object (Logging configuration)
name
required
string

Add a name for the Ocean cluster.

region
required
string

Select the region for the Ocean cluster to run in.

object (Elastigroup Scheduling)

An object used to define times for a task such as a shutdown to be activated.

object (Security)

Object for cluster security features.

object (Ocean Cluster Strategy)

An object defining the cluster strategy with regard to waiting periods and utilization of on-demand and reserved instances.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Clusters

List the configurations for all Ocean clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Cluster

Delete an existing Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster

Get the configuration of an existing Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Cluster

All Ocean parameters are updatable, except for region and identifier. This API supports partial updates, so specific fields can be updated separately.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoApplyTags
string
Default: "false"
Example: autoApplyTags=true

Option to update instance tags on the fly without rolling the cluster.

Request Body schema: application/json
required
object (AWS Cluster)

The object specifying the configuration of the Ocean cluster.

object (auto-scaler)

The automatic scaling mechanism used in Ocean for Kubernetes.

object (Capacity Units)

The overall capability of the Ocean cluster expressed as number of instances and specified with a minimum, a maximum, and a target number of running instances.

object (Ocean Compute)

Compute specifications for the Ocean cluster.

controllerClusterId
string

Enter the reporting identifier for the Ocean Controller.

object (Logging configuration)
name
string

Add a name for the Ocean cluster.

region
string

Select the region for the Ocean cluster to run in.

object (Elastigroup Scheduling)

An object used to define times for a task such as a shutdown to be activated.

object (Security)

Object for cluster security features.

object (Ocean Cluster Strategy)

An object defining the cluster strategy with regard to waiting periods and utilization of on-demand and reserved instances.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Heartbeat Status

Get the heartbeat status of the Ocean Controller for the cluster.
The response returns the heartbeat status and the last heartbeat timestamp.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Fetch Elastilog

Fetch the log of an Ocean cluster.

Authorizations:
auth
path Parameters
clusterIdentifier
required
string
Example: o-6e3819ae

The reporting identifier of the Ocean Controller.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string

Beginning date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

limit
integer <= 1000
Default: 500
Example: limit=200

Maximum number of lines to extract in a response.

resourceId
string
Example: resourceId=i-12345678

Filter extracted log entries for a specific resource identifier. Default: Null

severity
string
Default: "ALL"
Enum: "ALL" "INFO" "DEBUG" "ERROR" "WARN"
Example: severity=INFO

Severity of log entries to extract.

toDate
required
string

End date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import ASG To Ocean Cluster

Create an Ocean configuration according to an AWS autoscaling group (ASG) configuration.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoScalingGroupName
required
string
Example: autoScalingGroupName=myAutoScalingGroup

The ASG name.

region
required
string
Example: region=us-east-1

Region name of the ASG.

Request Body schema: application/json
object

The object specifying the configuration of the VNG.

instanceTypes
Array of strings

List of possible instance types for the cluster.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Fetch Right Sizing Recommendations

Get right-sizing recommendations for an Ocean cluster and filter them according to namespace or label.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Optional - may be null.

object

Optional - may be null.

namespaces
Array of strings

Optional - may be null. If exists - should contain at least 1 item.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Types Filters Simulation

Returns all instances types that match the given filters. These instance types will be used if the cluster is configured with these filters.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (InstanceTypesFilters)

List of filters. The Instance types that match with all filters compose the Ocean's whitelist parameter. Cannot be configured together with whitelist/blacklist.

architectures
Array of strings
Items Enum: "i386" "x86_64" "arm64"

The filtered instance types will support at least one of the architectures from this list.

categories
Array of strings
Items Enum: "Accelerated_computing" "Compute_optimized" "General_purpose" "Memory_optimized" "Storage_optimized"

The filtered instance types will belong to one of the categories types from this list.

diskTypes
Array of strings
Items Enum: "NVMe" "EBS" "SSD" "HDD"

The filtered instance types will have one of the disk type from this list.

excludeFamilies
Array of strings

Types belonging to a family from the ExcludeFamilies will not be available for scaling (asterisk wildcard is also supported). For example, C* will exclude instance types from these families: c5, c4, c4a, etc.

excludeMetal
boolean
Default: false

In case excludeMetal is set to true, metal types will not be available for scaling.

hypervisor
Array of strings
Items Enum: "nitro" "xen"

The filtered instance types will have a hypervisor type from this list.

includeFamilies
Array of strings

Types belonging to a family from the IncludeFamilies will be available for scaling (asterisk wildcard is also supported). For example, C* will include instance types from these families: c5, c4, c4a, etc.

isEnaSupported
boolean

Ena is supported or not.

maxGpu
integer >= 1

Maximum total number of GPUs.

maxMemoryGiB
number <double> >= 0

Maximum amount of Memory (GiB).

maxNetworkPerformance
integer >= 1

Maximum Bandwidth in Gib/s of network performance.

maxVcpu
integer >= 1

Maximum number of vcpus available.

minEnis
integer >= 0

Minimum number of network interfaces (ENIs).

minGpu
integer >= 0

Minimum total number of GPUs.

minMemoryGiB
number <double> >= 0

Minimum amount of Memory (GiB).

minNetworkPerformance
integer >= 0

Minimum Bandwidth in Gib/s of network performance.

minVcpu
integer >= 0

Minimum number of vcpus available.

rootDeviceTypes
Array of strings
Items Enum: "ebs" "instance-store"

The filtered instance types will have a root device types from this list.

virtualizationTypes
Array of strings
Items Enum: "hvm" "paravirtual"

The filtered instance types will support at least one of the virtualization types from this list.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Allowed Instance Types

Return the list of the allowed Ocean cluster instance types.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Attach Load Balancers

Add new load balancers to the existing load balancers on the Ocean Cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
Array of objects (ocean-lb)

Load balancers to add to the Ocean cluster.

Array
arn
string

If type is "TARGET_GROUP" then an ARN is required. Otherwise is not allowed.

name
string

If type is "CLASSIC" then a name is required. Otherwise is not allowed.

type
required
string
Enum: "CLASSIC" "TARGET_GROUP"

Type of load balancer to use.

Responses

Request samples

Content type
application/json
{
  • "loadBalancers": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Load Balancers

Remove load balancers from the existing load balancers on the Ocean Cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
Array of objects (ocean-lb)

Load balancers to remove from the Ocean cluster.

Array
arn
string

If type is "TARGET_GROUP" then an ARN is required. Otherwise is not allowed.

name
string

If type is "CLASSIC" then a name is required. Otherwise is not allowed.

type
required
string
Enum: "CLASSIC" "TARGET_GROUP"

Type of load balancer to use.

Responses

Request samples

Content type
application/json
{
  • "loadBalancers": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Upgrade Elastigroup To Ocean

Upgrade an Elastigroup with Kubernetes integration to Ocean for Kubernetes cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

groupId
required
string

Elastigroup identifier

Responses

Response samples

Content type
application/json
{
  • "kind": "spotinst:ocean:aws:k8s",
  • "items": {
    }
}

Initiate Roll

Roll an entire Ocean cluster or roll subsets of the cluster by specifying launchSpecIds or instanceIds. Performing this request will start the roll immediately and run it in defined batches. Note that the first response for a successful request will indicate the start of a roll. In order to check the status of a roll, you can use the GET Roll API.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
object
batchMinHealthyPercentage
integer
Default: 50

Indicates the threshold of minimum healthy instances in single batch. If the amount of healthy instances in single batch is under the threshold, the cluster roll will fail. If exists, the parameter value will be in range of 1-100. In case of null as value, the default value in the backend will be 50%. Value of param should represent the number in percentage (%) of the batch.

batchSizePercentage
integer

Value as a percent to set the size of a batch in a roll. Valid values are 0-100.

comment
string

Add a comment description for the roll. The comment is limited to 256 chars.

respectPdb
boolean
Default: false

During the roll, if the parameter is set to true we honor PDB during the instance replacement.

Responses

Request samples

Content type
application/json
Example
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "id": "scr-5aaf854e",
  • "scope": "Cluster",
  • "status": "IN_PROGRESS",
  • "currentBatch": 1,
  • "numOfBatches": 5,
  • "comment": "This is why I deployed my cluster.",
  • "progress": {
    },
  • "oceanId": "o-12e31234",
  • "instanceIds": [
    ],
  • "launchSpecIds": [
    ],
  • "respectPdb": true,
  • "batchMinHealthyPercentage": 100,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

List Rolls

Get status for all rolls of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-1abcd124

The identifier of the Ocean cluster

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "status": {
    },
  • "kind": "spotinst:ocean:aws:k8s:cluster:roll",
  • "items": [
    ]
}

Update Roll

Update a roll of an Ocean cluster.

Performing the request will stop the next batch in a roll.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-1abcd124

The identifier of the Ocean cluster

ROLL_ID
required
string
Example: scr-12345abc

Ocean cluster roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object

Object that specifies the parameters required to initiate a roll (also called a deployment).

status
required
string
Value: "STOPPED"

Set status of a roll. Valid values: "STOPPED"

Responses

Request samples

Content type
application/json
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "id": "scr-5aaf854e",
  • "scope": "Cluster",
  • "status": "STOPPED",
  • "currentBatch": 1,
  • "numOfBatches": 5,
  • "progress": {
    },
  • "oceanId": "o-12e31234",
  • "respectPdb": true,
  • "batchMinHealthyPercentage": 100,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

Get Roll

Get status for a roll of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-1abcd124

The identifier of the Ocean cluster

ROLL_ID
required
string
Example: scr-12345abc

Ocean Cluster Roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "id": "scr-5aaf854e",
  • "scope": "Cluster",
  • "status": "IN_PROGRESS",
  • "currentBatch": 1,
  • "numOfBatches": 5,
  • "comment": "This is why I deployed my cluster.",
  • "progress": {
    },
  • "oceanId": "o-12e31234",
  • "instanceIds": [
    ],
  • "launchSpecIds": [
    ],
  • "respectPdb": true,
  • "batchMinHealthyPercentage": 100,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

Get Cluster Nodes

Get nodes data of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

instanceId
string
Example: instanceId=i-123

Get a specific node by instance id.

launchSpecId
string
Example: launchSpecId=ols-123abc

Ocean cluster Virtual Node Group identifier.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Instances

Detach instances from your Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
instancesToDetach
required
Array of strings

Array of instance identifiers to be detached.

shouldDecrementTargetCapacity
boolean

Determines whether the Ocean cluster's target capacity should be decremented.

shouldTerminateInstances
boolean

Determines whether the detached EC2 instances should be terminated or not.

Responses

Request samples

Content type
application/json
{
  • "instancesToDetach": [
    ],
  • "shouldTerminateInstances": true,
  • "shouldDecrementTargetCapacity": false
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Aggregated Detailed Costs

Provides Kubernetes cluster resource usage and costs over a time interval which can be grouped and/or filtered by label/annotaion.
For example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory), storage (block, file, rootVolume). The response will group the cluster usage costs based on preselected default of application namespace or user selected label or annotation.
Within the group, resource costs are broken down per resource kind (Deployment, DaemonSet etc.).

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field.

groupBy
string
Default: "namespace"
Enum: "namespace" "namespace.label.${labelKey}" "resource.label.${labelKey}" "resource.annotation.${annotationKey}" "namespace.annotation.${annotationKey}"

The parameter we want to group the costs by.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": "2018-06-20T11:35:02.745Z",
  • "endTime": "2018-06-22T11:30:01.745Z",
  • "groupBy": "namespace.label.env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Aggregated Summary Costs

Provides Kubernetes cluster summary usage and costs over a time interval which can be grouped and/or filtered by label/annotaion,
for example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory), storage (block, file, rootVolume). The response will group the cluster usage costs based on preselected default of application namespace or user selected label or annotation.

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field.

groupBy
string
Default: "namespace"
Enum: "namespace" "namespace.label.${labelKey}" "resource.label.${labelKey}" "resource.annotation.${annotationKey}" "namespace.annotation.${annotationKey}"

The parameter we want to group the costs by.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": "2018-06-20T11:35:02.745Z",
  • "endTime": "2018-06-22T11:30:01.745Z",
  • "groupBy": "namespace.label.env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Initiate EKS AMI Auto Update

Update the Ocean EKS cluster's VNGs with the latest image or the image matching the control plane's version after upgrading, by specifying ‘patch' or 'minorVersion’. Performing this request will update the VNGs with new AMI if available, and run a cluster roll if set. If the response is successful, the old and new AMIs will be included in the response along with the updated VNGs. If a cluster roll is set in the request, the first response for a successful request will indicate the start of a roll. In order to check the status of the roll, you can use the GET Roll API.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
applyRoll
boolean
Default: false

This parameter is optional. When the AMI is updated according to the configuration set, a cluster roll can be triggered.

object

Cluster roll configuration.

minorVersion
boolean
Default: false

When set to 'true', the auto-update process will update the VNGs’ AMI with the AMI to match the Kubernetes control plane version. Either "patch" or "minorVersion" must be true.

patch
boolean
Default: false

When set to 'true', the auto-update process will update the VNGs’ images with the latest security patches. Either "patch" or "minorVersion" must be true.

Responses

Request samples

Content type
application/json
{
  • "amiAutoUpdate": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Virtual Node Group

Create a Virtual Node Group.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

initialNodes
integer
Default: null
Example: initialNodes=1

When set to an integer greater than 0, a corresponding number of nodes will be launched from the virtual node group created.

Request Body schema: application/json
required
object (oceanClusterLaunchSpecWithMetadata)

AWS Cluster Virtual Node Group (VNG).

associatePublicIpAddress
boolean
Default: false

Configure public IP address allocation.

object

Object specifying the automatic scaling of an Ocean VNG.

Array of objects

Block devices that are exposed to the instance. You can specify virtual devices and EBS volumes.
This parameter and rootVolumeSize cannot be in the spec at the same time.
This parameter can be null, but if not null, it must contain at least one block device.

object

Assign an Elastic IP to the instances launched by the Virtual Node Group. Can be null.

object
object (oceanGpuConfiguration)

GPU configuration

object (auto-scaler)

The instance profile iamRole object.

imageId
string

Set image identifier. Can be null.

Array of objects (Image object, containing the id of the image used to launch instances.)

An array of image objects.

  • You can configure VNG with either the imageId or images objects, but not both simultaneously.
  • For each architecture type (amd64, arm64) only one AMI is allowed.
  • Valid values: null, or an array with at least one element
object (instanceMetadataOptions)

Ocean instance metadata options object for IMDSv2.

object (instanceStorePolicy)

Determines the utilization of instance store volumes. If not defined, instance store volumes will not be used.

instanceTypes
Array of strings

A list of instance types allowed to be provisioned for pods pending for the Virtual Node Group.
The list overrides the list defined for the Ocean cluster. Can be null.

object (InstanceTypesFilters)

List of instance types filters. The instance types that match with all filters compose the Virtual Node Group's instanceTypes parameter.
The architectures that come from the Virtual Node Group's images will be taken into account when using this parameter.
Cannot be configured together with Virtual Node Group's instanceTypes and with the Cluster's whitelist/blacklist/filters.

Array of objects

An array of labels to add to the VNG nodes. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

name
string

Set Virtual Node Group name.

oceanId
required
string

The Ocean cluster identifier. Required for Virtual Node Group creation.

preferredOnDemandTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution.

preferredSpotTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution. Learn More

reservedENIs
integer
Default: 0

Specifies the count of ENIs to reserve per instance type for scaling purposes.

object
restrictScaleDown
boolean

When set to “True”, VNG nodes will be treated as if all pods running have the restrict-scale-down label. Therefore, Ocean will not scale nodes down unless empty.

rootVolumeSize
integer

Set root volume size (in GB). This field and blockDeviceMappings cannot be used in the same specification.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

securityGroupIds
Array of strings

Set security groups. Each element in the array is a security group identifier.

Array of objects

Temporary taints applied to a node during its initialization phase. For a startup taint to work, it must also be set as a regular taint in the userData for the VNG.

object

Similar to a strategy for an Ocean cluster, but applying only to a virtual node group.

subnetIds
Array of strings

Set subnets in Virtual Node Group. Each element in the array is a subnet identifier.

Array of objects

List of kay-value pairs of tags.

Array of objects

Add taints to Virtual Node Group.

userData
string

Set user data script in base 64 encoded MIME.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Virtual Node Groups

List the configurations of all virtual node groups for the cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

oceanId
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Virtual Node Group

Delete a specified Virtual Node Group in an Ocean cluster.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

deleteNodes
boolean
Default: false
Example: deleteNodes=true

When set to "true", all instances belonging to the deleted Virtual Node Group will be drained, detached, and terminated.

forceDelete
boolean
Default: null
Example: forceDelete=true

When set to "true", delete even if it is the only custom Virtual Node Group remaining, and default Virtual Node Group has useAsTemlateOnly = true.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Virtual Node Group

Update Virtual Node Group.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoApplyTags
boolean
Default: false
Example: autoApplyTags=true

Optionally update resource tags on the fly without performing a roll.

Request Body schema: application/json
required
object (oceanClusterLaunchSpec)

AWS Cluster Virtual Node Group (VNG).

associatePublicIpAddress
boolean
Default: false

Configure public IP address allocation.

object

Object specifying the automatic scaling of an Ocean VNG.

Array of objects

Block devices that are exposed to the instance. You can specify virtual devices and EBS volumes.
This parameter and rootVolumeSize cannot be in the spec at the same time.
This parameter can be null, but if not null, it must contain at least one block device.

object

Assign an Elastic IP to the instances launched by the Virtual Node Group. Can be null.

object
object (oceanGpuConfiguration)

GPU configuration

object (auto-scaler)

The instance profile iamRole object.

imageId
string

Set image identifier. Can be null.

Array of objects (Image object, containing the id of the image used to launch instances.)

An array of image objects.

  • You can configure VNG with either the imageId or images objects, but not both simultaneously.
  • For each architecture type (amd64, arm64) only one AMI is allowed.
  • Valid values: null, or an array with at least one element
object (instanceMetadataOptions)

Ocean instance metadata options object for IMDSv2.

object (instanceStorePolicy)

Determines the utilization of instance store volumes. If not defined, instance store volumes will not be used.

instanceTypes
Array of strings

A list of instance types allowed to be provisioned for pods pending for the Virtual Node Group.
The list overrides the list defined for the Ocean cluster. Can be null.

object (InstanceTypesFilters)

List of instance types filters. The instance types that match with all filters compose the Virtual Node Group's instanceTypes parameter.
The architectures that come from the Virtual Node Group's images will be taken into account when using this parameter.
Cannot be configured together with Virtual Node Group's instanceTypes and with the Cluster's whitelist/blacklist/filters.

Array of objects

An array of labels to add to the VNG nodes. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

name
string

Set Virtual Node Group name.

preferredOnDemandTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution.

preferredSpotTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution. Learn More

reservedENIs
integer
Default: 0

Specifies the count of ENIs to reserve per instance type for scaling purposes.

object
restrictScaleDown
boolean

When set to “True”, VNG nodes will be treated as if all pods running have the restrict-scale-down label. Therefore, Ocean will not scale nodes down unless empty.

rootVolumeSize
integer

Set root volume size (in GB). This field and blockDeviceMappings cannot be used in the same specification.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

securityGroupIds
Array of strings

Set security groups. Each element in the array is a security group identifier.

Array of objects

Temporary taints applied to a node during its initialization phase. For a startup taint to work, it must also be set as a regular taint in the userData for the VNG.

object

Similar to a strategy for an Ocean cluster, but applying only to a virtual node group.

subnetIds
Array of strings

Set subnets in Virtual Node Group. Each element in the array is a subnet identifier.

Array of objects

List of kay-value pairs of tags.

Array of objects

Add taints to Virtual Node Group.

userData
string

Set user data script in base 64 encoded MIME.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Virtual Node Group

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Types Filters Simulation For Virtual Node Group

Returns all instance types that match the given filters. These instance types will be used if the Virtual Node Group is configured with these filters.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (InstanceTypesFilters)

List of instance types filters. The instance types that match with all filters compose the Virtual Node Group's instanceTypes parameter.
The architectures that come from the Virtual Node Group's images will be taken into account when using this parameter.
Cannot be configured together with Virtual Node Group's instanceTypes and with the Cluster's whitelist/blacklist/filters.

categories
Array of strings
Items Enum: "Accelerated_computing" "Compute_optimized" "General_purpose" "Memory_optimized" "Storage_optimized"

The filtered instance types will belong to one of the categories types from this list.

diskTypes
Array of strings
Items Enum: "NVMe" "EBS" "SSD" "HDD"

The filtered instance types will have one of the disk type from this list.

excludeFamilies
Array of strings

Types belonging to a family from the ExcludeFamilies will not be available for scaling (asterisk wildcard is also supported). For example, C* will exclude instance types from these families: c5, c4, c4a, etc.

excludeMetal
boolean
Default: false

In case excludeMetal is set to true, metal types will not be available for scaling.

hypervisor
Array of strings
Items Enum: "nitro" "xen"

The filtered instance types will have a hypervisor type from this list.

includeFamilies
Array of strings

Types belonging to a family from the IncludeFamilies will be available for scaling (asterisk wildcard is also supported). For example, C* will include instance types from these families: c5, c4, c4a, etc.

isEnaSupported
boolean

Ena is supported or not.

maxGpu
integer >= 1

Maximum total number of GPUs.

maxMemoryGiB
number >= 0

Maximum amount of Memory (GiB).

maxNetworkPerformance
integer >= 1

Maximum Bandwidth in Gib/s of network performance.

maxVcpu
integer >= 1

Maximum number of vcpus available.

minEnis
integer >= 0

Minimum number of network interfaces (ENIs).

minGpu
integer >= 0

Minimum total number of GPUs.

minMemoryGiB
number >= 0

Minimum amount of Memory (GiB).

minNetworkPerformance
integer >= 0

Minimum Bandwidth in Gib/s of network performance.

minVcpu
integer >= 0

Minimum number of vcpus available.

rootDeviceTypes
Array of strings
Items Enum: "ebs" "instance-store"

The filtered instance types will have a root device types from this list.

virtualizationTypes
Array of strings
Items Enum: "hvm" "paravirtual"

The filtered instance types will support at least one of the virtualization types from this list.

Responses

Request samples

Content type
application/json
{
  • "instanceTypesFilters": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Allowed Instance Types By Filters For Virtual Node Group

Returns the Virtual Node Group's instance types when instance types filters is set.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import ASG To Ocean Virtual Node Group

Returns an Ocean Virtual Node Group (VNG) configuration in a given AWS autoscaling group (ASG). The returned value ("Imported VNG") can then be used as input to the Create Virtual Node Group API in order to create an actual VNG in your Ocean cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoScalingGroupName
required
string
Example: autoScalingGroupName=myAutoScalingGroup

The ASG name.

oceanId
required
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Request Body schema: application/json
object

The object specifying the configuration of the VNG.

Array of objects

An array of labels to add to the VNG nodes. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

name
string

Set Virtual Node Group name.

Array of objects

Add taints to Virtual Node Group.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import EKS Cluster Node Group To Ocean Virtual Node Group

  • Returns an Ocean Virtual Node Group (VNG) configuration based on a given AWS EKS Cluster Node Group. The returned value ("Imported VNG") can then be used as input to the Create Virtual Node Group API in order to create an actual VNG in your Ocean cluster.
  • Notes:
    • Make sure to have the necessary permissions in your Spot policy: eks:ListNodegroups, eks:DescribeNodegroup. Click here for the full Spot policy.
    • Exactly one of region or oceanId must be supplied as query parameters.
Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

eksClusterName
required
string
Example: eksClusterName=MyEksCluster

Cluster name of the EKS cluster.

eksNodeGroupName
required
string
Example: eksNodeGroupName=MyEksClusterNodeGroup

Node group name to import.

oceanId
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

region
string
Example: region=us-east-1

Region name of the EKS cluster's node group.

Request Body schema: application/json
object

The object specifying the configuration of the VNG.

Array of objects

An array of labels to add to the VNG nodes. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

name
string

Set Virtual Node Group name.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Launch Nodes in VNG

Launch nodes in Virtual Node Group.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean AWS Virtual Node Group Launch Request)

Object specifying the details for the launch request.

amount
required
integer

The number of nodes to launch.

Responses

Request samples

Content type
application/json
{
  • "launchRequest": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Extended Resource Definition

Creates an Ocean extended resource definition entity.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean Extended Resource Definition)

The Ocean extended resource definition.

mapping
required
object (AWS mapping)

A mapping between AWS instanceType or * as default and its value for the given extended resource.

name
required
string

The extended resource name as should be requested by your pods and registered to the nodes. Cannot be updated.
The name should be a valid Kubernetes extended resource name.

Responses

Request samples

Content type
application/json
{
  • "extendedResourceDefinition": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Extended Resource Definitions

List the configurations for all Ocean extended resource definitions in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Extended Resource Definition

Get the configurations for a specified Ocean extended resource definition.

Authorizations:
auth
path Parameters
oceanExtendedResourceDefinitionId
required
string
Example: erd-12345abc

Identifier of the Ocean extended resource definition.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Extended Resource Definition

Only the mapping parameter is updatable for extended resource definition.

Authorizations:
auth
path Parameters
oceanExtendedResourceDefinitionId
required
string
Example: erd-12345abc

Identifier of the Ocean extended resource definition.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean Extended Resource Definition)

The Ocean extended resource definition.

mapping
required
object (AWS mapping)

A mapping between AWS instanceType or * as default and its value for the given extended resource.

name
required
string

The extended resource name as should be requested by your pods and registered to the nodes. Cannot be updated.
The name should be a valid Kubernetes extended resource name.

Responses

Request samples

Content type
application/json
{
  • "extendedResourceDefinition": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Extended Resource Definition

Delete a specified Ocean extended resource definition.

Authorizations:
auth
path Parameters
oceanExtendedResourceDefinitionId
required
string
Example: erd-12345abc

Identifier of the Ocean extended resource definition.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Migration Discovery

Get information about nodes which can be migrated into Ocean.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

shouldFetchPods
boolean
Example: shouldFetchPods=true

Should fetch data about running pods for each node.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Migration

Create a migration for a given existing instances.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object

Migration update configuration.

batchSizePercentage
required
integer [ 1 .. 50 ]

Indicates (in percentage) the batch size of the migration (meaning, how many nodes to migrate in each batch).
Cannot be null.

forcePodEvictionOnPdbFailure
required
boolean

Ocean will force the Pod eviction from the instance, even if the distributed budget is not satisfied.

instanceIds
required
Array of strings

A list of instance ids that should be migrated to the Ocean cluster.

shouldEvictStandAlonePods
required
boolean

Ocean will terminate pods that do not belong to a Kubernetes deployment. This means that you would need to launch the pod manually (after the migration) due to the fact that there is no object that would do it automatically.

shouldTerminateDrainedNodes
required
boolean

Ocean will terminate the old instances once the pods that reside on them are migrated, and the old instances are fully drained.

Responses

Request samples

Content type
application/json
{
  • "migration": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Migrations summary

Get summary of migrations history for an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Migration Status

Get Migration full info and status for an Ocean cluster.

Authorizations:
auth
path Parameters
migrationId
required
string
Example: owm-6e3819ae

The migration identifier of a specific migration.

oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Stop Migration

Stop an ongoing Workload Migration.

Authorizations:
auth
path Parameters
migrationId
required
string
Example: owm-6e3819ae

The migration identifier of a specific migration.

oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object

Migration update configuration.

shouldTerminateDrainedNodes
boolean
Default: false

Ocean will terminate the old instances once the pods that reside on them are migrated, and the old instances are fully drained.

state
required
string

The only allowed state to update is to "STOPPED". This state will stop a running migration.

Responses

Request samples

Content type
application/json
{
  • "migration": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean ECS

Ocean - Serverless containers for Amazon Elastic Container Service (ECS)

Ocean Concepts and Tutorials

List Clusters

Get the configurations for all Ocean clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Cluster

Create a new Ocean ECS cluster in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (ECS Ocean)
object (Ocean Autoscaler)

The Ocean ECS Autoscaler.

object (Capacity Units)

Capacity specifications for the Ocean cluster.

clusterName
required
string

ECS cluster name.

object (Ocean Compute)
object (Logging configuration)
name
required
string

Add a name for the Ocean cluster.

region
required
string

Select the region for the Ocean cluster to run in.

object (Ocean Scheduling)

An object used to define times for a task such as a shutdown to be activated.

object (Ocean Strategy)

Strategy Configuration of the Ocean cluster.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster

Get the configurations for a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Cluster

All Ocean parameters are updatable, excluding Region and ID. This API supports partial updates, so specific fields can be updated separately.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoApplyTags
boolean
Default: false
Example: autoApplyTags=true

Optionally update resource tags on the fly without performing a roll.

Request Body schema: application/json
required
object (ECS Ocean)
object (Ocean Autoscaler)

The Ocean ECS Autoscaler.

object (Capacity Units)

Capacity specifications for the Ocean cluster.

clusterName
string

ECS cluster name.

object (Ocean Compute)
object (Logging configuration)
name
string

Add a name for the Ocean cluster.

object (Ocean Scheduling)

An object used to define times for a task such as a shutdown to be activated.

object (Ocean Strategy)

Strategy Configuration of the Ocean cluster.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Cluster

Delete a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Cluster

Create Ocean cluster object from an existing ECS cluster with at least one container instance to be used as input for create cluster.
Import the configuration from the latest instance id launched with in the cluster (out of the first batch of 100 instances ECS returns).
This route will not register the ECS cluster to Ocean.

Authorizations:
auth
path Parameters
EcsClusterName
required
string
Example: ecsName

ECS Cluster name

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
instanceId
string

Indicate the container instance id that the configuration will be taken from. This is an optional field

name
string

The name for the new Ocean cluster object.
If the name is not provided, the default will be Ocean_{EcsClusterName}

region
required
string

The region that the ECS cluster is running at.

Responses

Request samples

Content type
application/json
{
  • "region": "us-east-1",
  • "name": "oceanName",
  • "instanceId": "i-123456789abcdefgh"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Fetch Elastilog

Get the log of an Ocean Cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string

Beginning date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

limit
integer <= 1000
Default: 500
Example: limit=200

Maximum number of lines to extract in a response.

resourceId
string
Example: resourceId=i-12345678

Filter extracted log entries for a specific resource identifier. Default: Null

severity
string
Default: "ALL"
Enum: "ALL" "INFO" "DEBUG" "ERROR" "WARN"
Example: severity=INFO

Severity of log entries to extract.

toDate
required
string

End date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Right Sizing Recommendations

Get right-sizing recommendations for an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Types Filters Simulation

Returns all instances types that match the given filters. These instance types will be used if the cluster is configured with these filters.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (InstanceTypesFilters)

List of filters. The Instance types that match with all filters compose the Ocean's whitelist parameter. Cannot be configured together with whitelist/blacklist.

architectures
Array of strings
Items Enum: "i386" "x86_64" "arm64"

The filtered instance types will support at least one of the architectures from this list.

categories
Array of strings
Items Enum: "Accelerated_computing" "Compute_optimized" "General_purpose" "Memory_optimized" "Storage_optimized"

The filtered instance types will belong to one of the categories types from this list.

diskTypes
Array of strings
Items Enum: "NVMe" "EBS" "SSD" "HDD"

The filtered instance types will have one of the disk type from this list.

excludeFamilies
Array of strings

Types belonging to a family from the ExcludeFamilies will not be available for scaling (asterisk wildcard is also supported). For example, C* will exclude instance types from these families: c5, c4, c4a, etc.

excludeMetal
boolean
Default: false

In case excludeMetal is set to true, metal types will not be available for scaling.

hypervisor
Array of strings
Items Enum: "nitro" "xen"

The filtered instance types will have a hypervisor type from this list.

includeFamilies
Array of strings

Types belonging to a family from the IncludeFamilies will be available for scaling (asterisk wildcard is also supported). For example, C* will include instance types from these families: c5, c4, c4a, etc.

isEnaSupported
boolean

Ena is supported or not.

maxGpu
integer >= 1

Maximum total number of GPUs.

maxMemoryGiB
number <double> >= 0

Maximum amount of Memory (GiB).

maxNetworkPerformance
integer >= 1

Maximum Bandwidth in Gib/s of network performance.

maxVcpu
integer >= 1

Maximum number of vCPUs available.

minEnis
integer >= 0

Minimum number of network interfaces (ENIs).

minGpu
integer >= 0

Minimum total number of GPUs.

minMemoryGiB
number <double> >= 0

Minimum amount of Memory (GiB).

minNetworkPerformance
integer >= 0

Minimum Bandwidth in Gib/s of network performance.

minVcpu
integer >= 0

Minimum number of vCPUs available.

rootDeviceTypes
Array of strings
Items Enum: "ebs" "instance-store"

The filtered instance types will have a root device types from this list.

virtualizationTypes
Array of strings
Items Enum: "hvm" "paravirtual"

The filtered instance types will support at least one of the virtualization types from this list.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Allowed Instance Types

Return the list of the allowed Ocean cluster instance types.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Upgrade Elastigroup to Ocean

Upgrade an Elastigroup with ECS integration into Ocean for ECS cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

groupId
required
string
Example: groupId=sig-1234abcd

The identifier of the Elastigroup to upgrade.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Initiate Roll

Roll an entire Ocean cluster or roll subsets of the cluster by specifying launchSpecIds or instanceIds. Performing this request will start the roll immediately according to defined batches. Note that the first response for a successful request will indicate the start of a roll. In order to check the status of a roll, you can use the GET Roll API using the roll identifier.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
object
batchMinHealthyPercentage
integer
Default: 50

Indicates the threshold of minimum healthy instances in single batch. If the amount of healthy instances in single batch is under the threshold, the cluster roll will fail. If exists, the parameter value will be in range of 1-100. In case of null as value, the default value in the backend will be 50%. Value of param should represent the number in percentage (%) of the batch.

batchSizePercentage
integer

Value (in percent) to set size of batch in roll. Valid values are 0-100.

comment
string

Add a brief description for the roll. The comment is limited to 256 chars.

Responses

Request samples

Content type
application/json
Example
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Rolls

List rolls of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Roll

Update a roll of an Ocean cluster. Performing the request will stop the next batch in a roll.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

ROLL_ID
required
string
Example: scr-12345abc

Ocean Cluster Roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Sets the status of the roll.

status
required
string
Value: "STOPPED"

Set status of a roll. Valid values: "STOPPED"

Responses

Request samples

Content type
application/json
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Roll

Get status for roll of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

ROLL_ID
required
string
Example: scr-12345abc

Ocean Cluster Roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Container Instances

Get container instances data of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

instanceId
string
Example: instanceId=i-123

Get a specific container instance ec2 instance id.

launchSpecId
string
Example: launchSpecId=ols-123abc

Ocean cluster Virtual Node Group identifier.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Instances

Detach instances from your Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
instancesToDetach
required
Array of strings

Array of instance identifiers to be detached.

shouldDecrementTargetCapacity
boolean

Determines whether the Ocean cluster's target capacity should be decremented.

shouldTerminateInstances
boolean

Determines whether the detached EC2 instances should be terminated or not.

Responses

Request samples

Content type
application/json
{
  • "instancesToDetach": [
    ],
  • "shouldTerminateInstances": true,
  • "shouldDecrementTargetCapacity": false
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create VNG

Create a new Ocean ECS virtual node group in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (oceanClusterLaunchSpec-create)

AWS Cluster Virtual Node Group (VNG).

Array of objects

Add attributes to the cluster.

object
Array of objects (launchSpec-blockDeviceMappings)

Block devices that are exposed to the instance. You can specify virtual devices and EBS volumes. This parameter and rootVolumeSize cannot be in the configuration at the same time. This parameter can be null, but if not null, it must contain at least one block device.

Array of arn (string) or name (string)

The instance profile iamRole object.

imageId
string

Set image identifier. Can be null.

Array of objects (Image object, containing the id of the image used to launch instances.)

An array of image objects.

  • You can configure VNG with either the imageId or images objects, but not both simultaneously.
  • For each architecture type (amd64, arm64) only one AMI is allowed.
  • Valid values: null, or an array with at least one element
object (instanceMetadataOptions)

Ocean instance metadata options object for IMDSv2.

instanceTypes
Array of strings

An array of supported instance types for the VNG.

name
required
string

User given name of the virtual node group.

oceanId
required
string

The Ocean cluster identifier. Required for to create a virtual node group.

preferredSpotTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution. Learn More

restrictScaleDown
boolean

When set to True, the VNG container instances will be treated as if all tasks running have the restrict-scale-down label. Therefore, Ocean will not scale down container instances unless they are empty.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

securityGroupIds
Array of strings

Set security groups. Each element in array should be a security group identifier.

object

Similar to a strategy for an Ocean cluster, but applying only to a virtual node group.

subnetIds
Array of strings

Set the subnets in the VNG. Each element in the array should be a subnet identifier.

Array of objects

List of kay-value pairs of tags.

userData
string <byte>

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

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List VNGs

Get all the custom VNGs for all Ocean clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

oceanId
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get VNG

Get a specific custom launch configuration for an Ocean cluster in the specified account.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete VNG

Delete a specified virtual node group in an Ocean cluster.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

deleteContainerInstances
boolean
Default: false
Example: deleteContainerInstances=true

When set to "true", all instances belonging to the deleted VNG will be drained, detached, and terminated.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update VNG

Update a specified virtual node group in an Ocean cluster.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoApplyTags
boolean
Default: false
Example: autoApplyTags=true

Optionally update resource tags on the fly without performing a roll.

Request Body schema: application/json
required
object (oceanClusterLaunchSpec-update)

AWS Cluster Virtual Node Group (VNG).

Array of objects

Add attributes to the cluster.

object
Array of objects (launchSpec-blockDeviceMappings)

Block devices that are exposed to the instance. You can specify virtual devices and EBS volumes. This parameter and rootVolumeSize cannot be in the configuration at the same time. This parameter can be null, but if not null, it must contain at least one block device.

Array of arn (string) or name (string)

The instance profile iamRole object.

imageId
string

Set image identifier. Can be null.

Array of objects (Image object, containing the id of the image used to launch instances.)

An array of image objects.

  • You can configure VNG with either the imageId or images objects, but not both simultaneously.
  • For each architecture type (amd64, arm64) only one AMI is allowed.
  • Valid values: null, or an array with at least one element
object (instanceMetadataOptions)

Ocean instance metadata options object for IMDSv2.

instanceTypes
Array of strings

An array of supported instance types for the VNG.

name
string

User given name of the virtual node group.

preferredSpotTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution. Learn More

restrictScaleDown
boolean

When set to True, the VNG container instances will be treated as if all tasks running have the restrict-scale-down label. Therefore, Ocean will not scale down container instances unless they are empty.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

securityGroupIds
Array of strings

Set security groups. Each element in array should be a security group identifier.

object

Similar to a strategy for an Ocean cluster, but applying only to a virtual node group.

subnetIds
Array of strings

Set the subnets in the VNG. Each element in the array should be a subnet identifier.

Array of objects

List of kay-value pairs of tags.

userData
string <byte>

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

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Fargate To Existing Ocean Cluster

Import a Fargate service into an existing Ocean ECS cluster. Upon Fargate service import, Spot clones the selected Fargate services and runs them with the same VPC & Subnet settings on EC2 spot Instances. Ocean will automatically and seamlessly predict and replace spot instances before they are interrupted, ensuring the uptime of the cluster and providing cost-savings of up to 90% over Fargate-enabled ECS clusters.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
services
Array of strings

List of Fargate services by their names. Must contain at least one service.

simpleNewServiceNames
boolean
Default: false

Flag to align imported service names in the following format: sfm_

Responses

Request samples

Content type
application/json
{
  • "services": [
    ],
  • "simpleNewServiceNames": false
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Fargate Services Discovery

Get existing Fargate services in the ECS cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Fargate Migration Status

Get the status of a Fargate service import.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Fargate To New Ocean Cluster

This API copies the configuration from a Fargate service into the corresponding fields of an Ocean object. (This process is commonly referred to as importing.) The API returns an Ocean object that is suitable for use in the Create API to create a new Ocean cluster based on your Fargate configuration. If you are migrating a Fargate service that has tags, you must run the Opt In procedure on your Amazon account or IAM role. This is required in order to obtain the necessary Amazon Resource Name (ARN) and resource identifier format for your ECS tasks, container instances, and services. For more information about the required ARN and the Opt In procedure, see the following pages:

The API requires one of the following permissions to be defined in Spot -

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
ecsClusterName
required
string

Name of the cluster in ECS.

keyPair
string

Specify a key pair to attach to the services.

oceanClusterName
required
string

Name of the cluster in new Ocean object.

region
required
string

Name of the AWS region the ECS cluster is in.

services
required
Array of strings[ items ]

Name of the ECS Fargate service to be imported.

Array of objects

Set tags for the service. Items should be unique.

Responses

Request samples

Content type
application/json
{
  • "oceanClusterName": "fargate-import-ocean",
  • "ecsClusterName": "fargateTestCluster",
  • "region": "us-west-1",
  • "services": [
    ],
  • "keyPair": "spot-prod",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ecs Cluster Aggregated Detailed Costs

Provides Ecs cluster resource usage and costs over a time interval which can be grouped and/or filtered by AWS tags,
for example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory), storage (block, file, rootVolume). The response will group the cluster usage costs based on the preselected default of Ecs Group Type which is composed of Service, Headroom, Custom Object, Idle and Standalone, or user selected AWS tags.
Within the default grouping, costs are broken down for the Service group, and for tag grouping the costs will be broken up by tag value.

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field. Can only be used if grouping by tags.

groupBy
string

The parameter we want to group the costs by, default is grouping by ECS group types. Only a tag key can be passed in.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": 1675209600000,
  • "endTime": 1675216800000,
  • "groupBy": "env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Costs

Describes ECS cluster costs in a time range.
The response will provide the distribution of the costs per cluster.

Deprecated API: This API is no longer supported. As an alternative you may use the "Get Ecs Cluster Aggregated Detailed Costs" API.

Authorizations:
auth
path Parameters
clusterName
required
string
Example: ocean.ecs

The name of the ECS cluster, as set in the Ocean cluster configuration under the "clusterName" field.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string

Beginning date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

region
required
string
Example: region=us-east-1

Region name.

toDate
required
string

End date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Launch Container Instances In VNG

Launch container instances in virtual node group.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean ECS VNG Launch Request)
amount
required
integer

The number of container instances to launch.

Responses

Request samples

Content type
application/json
{
  • "launchRequest": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean GKE

Ocean - Serverless containers for Google Kubernetes Engine

Ocean Concepts and Tutorials

Get Heartbeat Status

Get the heartbeat status of the Ocean Controller for the cluster.
The response returns the heartbeat status and the last heartbeat timestamp.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Cluster

Prerequisites:

The Ocean Controller is used to monitor the cluster resources and report back to Ocean.| To install the Ocean Controller, complete and run the following script on a machine with the kubectl command line tool installed and configured:

  #!/usr/bin/env bash
  curl -fsSL http://spotinst-public.s3.amazonaws.com/integrations/kubernetes/cluster-controller/scripts/init.sh | \
  SPOTINST_TOKEN=<ENTER YOUR TOKEN HERE> \
  SPOTINST_ACCOUNT=<ENTER YOUR SPOTINST ACCOUNT ID HERE> \
  SPOTINST_CLUSTER_IDENTIFIER=<ENTER YOUR CLUSTER IDENTIFIER HERE> \
  bash

You may need Kubernetes admin privileges for this script to work. To grant yourself admin privileges, run the following command:

  kubectl create clusterrolebinding <clusterName> --clusterrole=cluster-admin --user=<userEmail>

For more information, refer to our controller installation guides. You can install with Helm, Kubectl or Terraform. For more about Ocean and the Ocean Controller, see the documentation here.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object

The specification of the Ocean cluster.

object (auto-scaler)

The Ocean Kubernetes Autoscaler object.

object (auto-update)

The Ocean Kubernetes AutoUpdate object. If set to 'true', Ocean will ensure that your clusters have an up-to-date configuration according to the respective GKE cluster.

object (Capacity Units)

Capacity specifications for the Ocean cluster.

required
object (Ocean Compute)
controllerClusterId
required
string

Enter the Ocean cluster identifier.

object

Use existing GKE cluster.

name
required
string

Add a name for the Ocean cluster.

object (Ocean GKE Scheduling)

Schedule an action such as a planned shutdown or a cluster roll.

object (Security)
object (Ocean Strategy)

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Clusters

List the configurations for all Ocean clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Cluster

Delete a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster

Get the configuration for a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Cluster

All Ocean parameters are updatable, excluding the Name and controllerClusterId.
This API supports partial updates, so specific fields can be updated separately.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object

The specification of the Ocean cluster.

object (auto-scaler)

The Ocean Kubernetes Autoscaler object.

object (auto-update)

The Ocean Kubernetes AutoUpdate object. If set to 'true', Ocean will ensure that your clusters have an up-to-date configuration according to the respective GKE cluster.

object (Capacity Units)

Capacity specifications for the Ocean cluster.

object (Ocean Compute)
name
string

Add a name for the Ocean cluster.

object (Ocean GKE Scheduling)

Schedule an action such as a planned shutdown or a cluster roll.

object (Security)
object (Ocean Strategy)

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Reimport Cluster

Reimport the cluster's configuration from GKE.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Instances

Detach instances from your Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
drainingTimeout
integer

(Applies only if shouldTerminateInstances is on) The draining timeout (in seconds) before terminating the instance.

instancesToDetach
required
Array of strings

Array of instance identifiers to be detached.

shouldDecrementTargetCapacity
boolean

Determines whether the Ocean cluster's target capacity should be decremented. (Default false)

shouldTerminateInstances
boolean

Determines whether the detached instances should be terminated or not. (Default true)

Responses

Request samples

Content type
application/json
{
  • "instancesToDetach": [
    ],
  • "shouldTerminateInstances": true,
  • "shouldDecrementTargetCapacity": false,
  • "drainingTimeout": 0
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Elastilog

Get group’s Elastilog by

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string

Beginning date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

limit
integer <= 1000
Default: 500
Example: limit=200

Maximum number of lines to extract in a response.

resourceId
string
Example: resourceId=i-12345678

Filter extracted log entries for a specific resource identifier. Default: Null

severity
string
Default: "ALL"
Enum: "ALL" "INFO" "DEBUG" "ERROR" "WARN"
Example: severity=INFO

Severity of log entries to extract.

toDate
required
string

End date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Right Sizing Recommendations

Get right-sizing recommendations for an Ocean cluster and filter them according to namespace or label.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Optional - may be null.

object

Optional - may be null.

namespaces
Array of strings

Optional - may be null. If exists - should contain at least 1 item.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "response": {
    }
}

Get Cluster Aggregated Detailed Costs

Provides Kubernetes cluster resource usage and costs over a time interval which can be grouped and/or filtered by label/annotaion.
For example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory) and storage. The response will group the cluster usage costs based on preselected default of application namespace or user selected label or annotation.
Within the group, resource costs are broken down per resource kind (Deployment, DaemonSet etc.).

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field.

groupBy
string
Default: "namespace"
Enum: "namespace" "namespace.label.${labelKey}" "resource.label.${labelKey}" "resource.annotation.${annotationKey}" "namespace.annotation.${annotationKey}"

The parameter we want to group the costs by.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": "2018-06-20T11:35:02.745Z",
  • "endTime": "2018-06-22T11:30:01.745Z",
  • "groupBy": "namespace.label.env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Aggregated Summary Costs

Provides Kubernetes cluster summary usage and costs over a time interval which can be grouped and/or filtered by label/annotaion,
for example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory), storage (block, file, rootVolume). The response will group the cluster usage costs based on preselected default of application namespace or user selected label or annotation.

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field.

groupBy
string
Default: "namespace"
Enum: "namespace" "namespace.label.${labelKey}" "resource.label.${labelKey}" "resource.annotation.${annotationKey}" "namespace.annotation.${annotationKey}"

The parameter we want to group the costs by.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": "2023-07-20T11:35:01.745Z",
  • "endTime": "2023-07-22T11:30:01.745Z",
  • "groupBy": "namespace.label.env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Types Filters Simulation

Returns all instances types that match the given filters. These instance types will be used if the cluster is configured with these filters.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (InstanceTypesFilters)

List of filters. The Instance types that match with all filters compose the Ocean's whitelist parameter. Cannot be configured together with whitelist/blacklist.

excludeFamilies
Array of strings

Types belonging to a family from the ExcludeFamilies will not be available for scaling (asterisk wildcard is also supported).

includeFamilies
Array of strings

Types belonging to a family from the IncludeFamilies will be available for scaling (asterisk wildcard is also supported).

maxMemoryGiB
number <double> >= 0

Maximum amount of Memory (GiB).

maxVcpu
integer >= 1

Maximum number of vcpus available.

minMemoryGiB
number <double> >= 0

Minimum amount of Memory (GiB).

minVcpu
integer >= 0

Minimum number of vcpus available.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create VNG

Create a Virtual Node Group.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

initialNodes
integer
Default: null
Example: initialNodes=1

When set to an integer greater than 0, a corresponding number of nodes will be launched from the virtual node group created.

Request Body schema: application/json
required
object (oceanClusterLaunchSpecCreate)

Ocean Cluster Virtual Node Group (VNG).

object

Object specifying the automatic scaling of an Ocean VNG.

availabilityZones
Array of strings

An array holding availability zones, this configures the availability zones the Ocean may launch instances in per VNG. Can be null.

object (InstanceTypesFilters)

List of filters. The Instance types that match with all filters compose the Ocean's whitelist parameter. Cannot be configured together with whitelist/blacklist.

instanceTypes
Array of strings

An array of supported machine types for the virtual node group. Can be null.

Array of objects

An array of labels to add to the virtual node group. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

required
Array of objects

Add metadata to the cluster.

name
string

Set the name for the virtual node group.

Array of objects

Settings for network interfaces

oceanId
required
string

The Ocean cluster identifier. Required to create the virtual node group.

preferredTypes
Array of strings (preferredTypes)

When Ocean scales up VMs, it prioritizes the preferred instance types for launching new nodes. If launching nodes from this preferred list is not feasible, Ocean will then proceed to utilize the configured instance types available within the cluster. Note that the preferred types must be a subset of the instance types configured for the cluster/vng.

object
restrictScaleDown
boolean

When set to True, VNG nodes will be treated as if all pods running have the restrict-scale-down label. Therefore, Ocean will not scale nodes down unless they are empty.

rootVolumeSizeInGb
integer

Set root volume size (in GB).

rootVolumeType
string
Enum: "pd-standard" "pd-ssd" "pd-balanced"

Set the root volume disk type.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

serviceAccount
string

The account used by applications running on the VM to call GCP APIs.

object (shielded-instance-config)

The Ocean shielded instance configuration object.

sourceImage
required
string

Set the image URL. Can be null.

object (storage)

The Ocean virtual node group storage object.

object (strategy)

The Ocean virtual node group strategy object.

tags
Array of strings

Every node launched from this VNG will have those tags. If the value is null, the nodes will have the tags configured at the cluster level.

Array of objects

Add taints to the virtual node group.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List VNGs

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

oceanId
required
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import GKE Node Pool To VNG

Returns an Ocean Virtual Node Group (VNG) configuration based on a given GCP GKE Cluster Node Pool.
The returned value ("Imported VNG") can then be used as input to the Create VNG API in order to create an actual VNG in your Ocean cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

nodePoolName
required
string
Example: nodePoolName=test

Name of the Node Pool.

oceanId
required
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete VNG

Delete a specified virtual node group in an Ocean cluster.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

deleteNodes
boolean
Default: false
Example: deleteNodes=true

When set to "true", all instances belonging to the deleted Virtual Node Group will be drained, detached, and terminated.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update VNG

All Ocean parameters in a virtual node group are updatable.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Object specifying the automatic scaling of an Ocean VNG.

availabilityZones
Array of strings

An array holding availability zones, this configures the availability zones the Ocean may launch instances in per VNG. Can be null.

object (InstanceTypesFilters)

List of filters. The Instance types that match with all filters compose the Ocean's whitelist parameter. Cannot be configured together with whitelist/blacklist.

instanceTypes
Array of strings

An array of supported machine types for the virtual node group. Can be null.

Array of objects

An array of labels to add to the virtual node group. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

Array of objects

Add metadata to the cluster.

name
string

Set the name for the virtual node group.

oceanId
required
string

The Ocean cluster identifier. Required to create the virtual node group.

preferredTypes
Array of strings (preferredTypes)

When Ocean scales up VMs, it prioritizes the preferred instance types for launching new nodes. If launching nodes from this preferred list is not feasible, Ocean will then proceed to utilize the configured instance types available within the cluster. Note that the preferred types must be a subset of the instance types configured for the cluster/vng.

object
restrictScaleDown
boolean

When set to True, VNG nodes will be treated as if all pods running have the restrict-scale-down label. Therefore, Ocean will not scale nodes down unless they are empty.

rootVolumeSizeInGb
integer

Set root volume size (in GB).

rootVolumeType
string
Enum: "pd-standard" "pd-ssd" "pd-balanced"

Set the root volume disk type.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

serviceAccount
string

The account used by applications running on the VM to call GCP APIs.

object (shielded-instance-config)

The Ocean shielded instance configuration object.

sourceImage
required
string

Set the image URL. Can be null.

object (storage)

The Ocean virtual node group storage object.

object (strategy)

The Ocean virtual node group strategy object.

tags
Array of strings

Every node launched from this VNG will have those tags. If the value is null, the nodes will have the tags configured at the cluster level.

Array of objects

Add taints to the virtual node group.

Responses

Request samples

Content type
application/json
{
  • "oceanId": "o-1fff54ed",
  • "name": "lp_name",
  • "sourceImage": "https://www.googleapis.com/compute/v1/projects/gke-node-images/global/images/container-v1-3-v20160517",
  • "serviceAccount": "265168459660-compute@developer.gserviceaccount.com",
  • "rootVolumeSizeInGb": 8,
  • "rootVolumeType": "pd-standard",
  • "metadata": [
    ],
  • "instanceTypes": [
    ],
  • "filters": {
    },
  • "preferredTypes": [
    ],
  • "availabilityZones": [
    ],
  • "tags": [
    ],
  • "taints": [
    ],
  • "labels": [
    ],
  • "autoScale": {
    },
  • "resourceLimits": {
    },
  • "restrictScaleDown": false,
  • "shieldedInstanceConfig": {
    },
  • "strategy": {
    },
  • "storage": {
    },
  • "scheduling": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get VNG

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Initiate Roll

Roll an entire Ocean cluster or roll subsets of the cluster by specifying launchSpecIds or instanceNames. Performing this request will start the roll immediately, and the roll will take place according to defined batches.

Note that the first response for a successful request will notify about the start of a roll. In order to check the status of a roll, you can use the GET Cluster Roll API using the roll identifier.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
object
batchMinHealthyPercentage
integer
Default: 50

Indicates the threshold percentage of minimum healthy instances in a single batch. If the number is below the threshold, the cluster roll will fail. The parameter value has a range of 1-100 (default = 50%).

batchSizePercentage
integer

Value is a percentage to set the size of a batch in a roll. Valid values are 0-100.

comment
string

Add a comment description for the roll. The comment is limited to 256 chars.

respectPdb
boolean
Default: false

During the roll, if the parameter is set to 'true', PDB is honored during the instance replacement.

Responses

Request samples

Content type
application/json
Example
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "rollId": "roll-1234",
  • "oceanId": "o-12e31234",
  • "scope": "Cluster",
  • "status": "IN_PROGRESS",
  • "batchNumber": 1,
  • "numOfBatches": 5,
  • "comment": "This is why I deployed my cluster.",
  • "respectPdb": true,
  • "progress": {
    },
  • "instanceNames": [
    ],
  • "launchSpecIds": [
    ],
  • "batchMinHealthyPercentage": 100,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

List Rolls

Get status for all rolls of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "status": {
    },
  • "kind": "spotinst:ocean:aws:k8s:cluster:roll",
  • "items": [
    ]
}

Update Roll

Update a roll of an Ocean cluster.

Performing the request will stop the next batch in a roll.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

rollId
required
string
Example: scr-12345abc

Ocean Cluster Roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Object that specifies the parameters of a roll (also called a deployment).

status
required
string
Value: "STOPPED"

Set status of a roll. Valid values: "STOPPED"

Responses

Request samples

Content type
application/json
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "rollId": "roll-1234",
  • "status": "STOPPED",
  • "batchNumber": 1,
  • "numOfBatches": 5,
  • "scope": "Cluster",
  • "progress": {
    },
  • "batchMinHealthyPercentage": 100,
  • "oceanId": "o-12e31234",
  • "respectPdb": true,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

Get Roll

Get status for roll of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

rollId
required
string
Example: scr-12345abc

Ocean Cluster Roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "rollId": "roll-1234",
  • "oceanId": "o-12e31234",
  • "scope": "Cluster",
  • "status": "IN_PROGRESS",
  • "batchNumber": 1,
  • "numOfBatches": 5,
  • "comment": "This is why I deployed my cluster.",
  • "respectPdb": true,
  • "progress": {
    },
  • "instanceNames": [
    ],
  • "launchSpecIds": [
    ],
  • "batchMinHealthyPercentage": 100,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

Get Cluster Nodes

Get nodes data of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

instanceName
string
Example: instanceName=sin-123

Get a specific node by instance name.

launchSpecId
string
Example: launchSpecId=ols-123abc

Ocean cluster Virtual Node Group identifier.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Upgrade Elastigroup To Ocean

Prerequisites | Perform the following validations prior to upgrade executions: | * Group identifier cannot be null. * Group identifier exists in Elastigroup. * Group should be a GKE Elastigroup with defined scaling policy. * Group identifier is already managed by Ocean.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

groupId
required
string

Elastigroup identifier

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import GKE Cluster To Ocean

Returns an Ocean Cluster configuration, and optionally Virtual Node Group (VNG) configurations based on a given GKE Cluster and its Node Pools.
The returned values ("Imported Cluster/VNGs") can then be used as inputs to the Create Cluster/VNG APIs in order to create the respectful resources.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

clusterName
required
string
Example: clusterName=test-gke

Name of the GKE Cluster.

includeLaunchSpecs
boolean
Default: true
Example: includeLaunchSpecs=true

When set to "true", GKE cluster node pools will be imported to Ocean custom VNG ("customLaunchSpec") configurations.

location
required
string
Example: location=us-central1-a

Location GKE Cluster Master.

nodePoolName
string
Example: nodePoolName=test

Name of the Node Pool to use as a default for the Cluster configuration.

Request Body schema: application/json
required
object

The specification of the Ocean cluster.

object (auto-scaler)

The Ocean Kubernetes Autoscaler object.

availabilityZones
Array of strings

An array holding availability zones, this configures the availability zones the Ocean may launch instances in per VNG. Can be null.

Array of objects
object (Capacity Units)

Capacity specifications for the Ocean cluster.

controllerClusterId
string

Enter the Ocean cluster identifier.

object

The type of instances that may or may not be a part of the Ocean cluster.

name
string

Add a name for the Ocean cluster.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Launch Nodes In VNG

Launch nodes in virtual node group.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (Ocean GKE Virtual Node Group Launch Request)
amount
required
integer

The number of nodes to launch.

Responses

Request samples

Content type
application/json
{
  • "launchRequest": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean AKS

Ocean - Serverless containers for Azure Kubernetes Service

Ocean Concepts and Tutorials

Create Cluster

Creates an Ocean entity according to a given specification.

Notes:

It is recommended to import all necessary information from the existing AKS cluster using the Ocean AKS Cluster Import API call and use its output to create a fully configured Ocean cluster.

The Ocean Controller is used to monitor the cluster resources and report back to Ocean SaaS. A properly functioning controller is mandatory for Ocean to operate.

Installing the controller can be easily done by Helm, Terraform or a script using the guide.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (ocean-cluster-2)

The Ocean cluster.

required
object (Ocean AKS - AKS Cluster Configuration)

AKS cluster configuration. Cannot be updated.

object (Ocean AKS Autoscaler)

The Ocean Kubernetes Autoscaler object.

controllerClusterId
required
string

Enter a unique Ocean cluster identifier. Cannot be updated.

object (Ocean AKS Health)

The Ocean AKS Health object.

object (Ocean AKS Logging)

The Ocean AKS Logging object.

name
required
string

Add a name for the Ocean cluster.

object (Ocean AKS Scheduling)

An object used to specify times when the cluster will turn off. Once the shutdown time will be over, the cluster will return to its previous state.

required
object (Ocean AKS Virtual Node Group Template)

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Clusters

List the configurations for all Ocean clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster

Get the configurations for a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Cluster

Update a specified Ocean cluster.
This API supports partial updates, so specific fields can be updated separately.

Notes:
When labels, tags and taints are updated in the VNG template, all existing nodes from VNGs that inherit these properties from the tamplate will be updated as well.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (ocean-cluster-3)

The Ocean cluster.

object (Ocean AKS Autoscaler)

The Ocean Kubernetes Autoscaler object.

object (Ocean AKS Health)

The Ocean AKS Health object.

object (Ocean AKS Logging)

The Ocean AKS Logging object.

name
string

A name for the Ocean cluster.

object (Ocean AKS Scheduling)

An object used to specify times when the cluster will turn off. Once the shutdown time will be over, the cluster will return to its previous state.

object (Ocean AKS Virtual Node Group Template)

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Cluster

Delete a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Cluster

The Import Cluster API call returns a JSON formatted Ocean cluster specification for a given AKS cluster and import identifier. The returned specification is ready to use in the Ocean AKS Cluster Create API call.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

aksClusterName
required
string
Example: aksClusterName=test-cluster

The name of the aks cluster.

resourceGroupName
required
string
Example: resourceGroupName=test-clust_group

The name of the resource group of the AKS cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Launch New Nodes

Launch new nodes for a cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
adjustment
required
integer >= 1

The number of nodes to launch.

applicableVmSizes
Array of strings >= 1
availabilityZones
Array of strings

An Array holding Availability Zones, this configures the availability zones the Ocean may launch instances in per VNG.

minCoresPerNode
integer >= 2

Minimum number of core per node.

minMemoryGiBPerNode
number <float> >= 2

Minimum memory per node.

oceanId
required
string

Ocean cluster identifier.

preferredLifecycle
string
Enum: "Spot" "Regular"

The preferred life cycle to launch the node. If not specified, the life cycle is chosen accoring to the scaled VNG.

vngIds
Array of strings >= 1

Responses

Request samples

Content type
application/json
{
  • "oceanId": "o-134abcd",
  • "vngIds": [
    ],
  • "preferredLifecycle": "Spot",
  • "availabilityZones": [
    ],
  • "adjustment": 2,
  • "minCoresPerNode": 2,
  • "minMemoryGiBPerNode": 2,
  • "applicableVmSizes": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Nodes

Detach Nodes nodes for a cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
nodeNamesToDetach
required
Array of strings >= 1

Node names to detach from the Ocean cluster.

oceanId
required
string

Ocean cluster identifier.

Responses

Request samples

Content type
application/json
{
  • "oceanId": "o-134abcd",
  • "nodeNamesToDetach": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Virtual Node Group

Create a virtual node group.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean AKS Virtual Node Group)
object (Ocean AKS Auto Scale)

Object specifying the automatic scaling of an Ocean VNG.

availabilityZones
Array of strings

An Array holding Availability Zones, this configures the availability zones the Ocean may launch nodes in per VNG.
Select zone 0 if you have a workload that requires no availability zone redundancy (AZ=null). You can select this option either alone or together with other availability zones.
In case zone 0 is selected together with other availability zones, nodes of zone 0 will be scaled only for workloads that demand it.

labels
object

key-value pairs of labels to add to the virtual node group.
Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.
The following are not allowed:

  • "kubernetes.azure.com/agentpool"
  • "kubernetes.io/arch"* "kubernetes.io/os"
  • "node.kubernetes.io/instance-type"
  • "topology.kubernetes.io/region"
  • "topology.kubernetes.io/zone"
  • "kubernetes.azure.com/cluster"
  • "kubernetes.azure.com/mode"
  • "kubernetes.azure.com/role"
  • "kubernetes.azure.com/scalesetpriority"
  • "kubernetes.io/hostname"
  • "kubernetes.azure.com/storageprofile"
  • "kubernetes.azure.com/storagetier"
  • "kubernetes.azure.com/instance-sku"
  • "kubernetes.azure.com/node-image-version"
  • "kubernetes.azure.com/subnet"
  • "kubernetes.azure.com/vnet"
  • "kubernetes.azure.com/ppg"
  • "kubernetes.azure.com/encrypted-set"
  • "kubernetes.azure.com/accelerator"
  • "kubernetes.azure.com/fips_enabled"
  • "kubernetes.azure.com/os-sku"
name
required
string

Enter a name for the virtual node group.

object (Ocean AKS Node Count Limits)

Limit the number of nodes in a VNG.

object (Ocean AKS Node Pool Properties)

The Ocean Node Pool Properties.

oceanId
required
string

Ocean cluster identifier.

object (Ocean VNG AKS Scheduling)

An object used to specify times when the virtual node group will turn off all its node pools. Once the shutdown time will be over, the virtual node group will return to its previous state.

object (Ocean AKS Strategy)

The Ocean AKS Strategy object.

tags
object

A maximum of 20 unique key-value pairs for VM tags in the virtual node group. Note: Azure has a tag limit of 50 per node pool.

Array of objects

Add taints to a virtual node group.

object (Ocean AKS VM Sizes)

The Ocean AKS VM Sizes object.

Responses

Request samples

Content type
application/json
{
  • "virtualNodeGroup": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Virtual Node Groups

List the configurations for all virtual node groups in the account or in a specified cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

oceanId
required
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Virtual Node Group

Get the configuration of a specified virtual node group.

Authorizations:
auth
path Parameters
virtualNodeGroupId
required
string
Example: vng-12345abc

Ocean Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Virtual Node Group

Update a specified virtual node group in an Ocean cluster.
This API supports partial updates, so specific fields can be updated separately.

Notes:
When labels, tags and taints are updated the existing nodes are updated as well.

Authorizations:
auth
path Parameters
virtualNodeGroupId
required
string
Example: vng-12345abc

Ocean Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean AKS Virtual Node Group)
object (Ocean AKS Auto Scale)

Object specifying the automatic scaling of an Ocean VNG.

availabilityZones
Array of strings

An Array holding Availability Zones, this configures the availability zones the Ocean may launch instances in per VNG.

labels
object

key-value pairs of labels to add to the virtual node group.
Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.
The following are not allowed:

  • "kubernetes.azure.com/agentpool"
  • "kubernetes.io/arch"* "kubernetes.io/os"
  • "node.kubernetes.io/instance-type"
  • "topology.kubernetes.io/region"
  • "topology.kubernetes.io/zone"
  • "kubernetes.azure.com/cluster"
  • "kubernetes.azure.com/mode"
  • "kubernetes.azure.com/role"
  • "kubernetes.azure.com/scalesetpriority"
  • "kubernetes.io/hostname"
  • "kubernetes.azure.com/storageprofile"
  • "kubernetes.azure.com/storagetier"
  • "kubernetes.azure.com/instance-sku"
  • "kubernetes.azure.com/node-image-version"
  • "kubernetes.azure.com/subnet"
  • "kubernetes.azure.com/vnet"
  • "kubernetes.azure.com/ppg"
  • "kubernetes.azure.com/encrypted-set"
  • "kubernetes.azure.com/accelerator"
  • "kubernetes.azure.com/fips_enabled"
  • "kubernetes.azure.com/os-sku"
name
string

Enter a name for the virtual node group.

object (Ocean AKS Node Count Limits)

Limit the number of nodes in a VNG.

object (Ocean AKS Node Pool Properties)

The Ocean Node Pool Properties.

object (Ocean VNG AKS Scheduling)

An object used to specify times when the virtual node group will turn off all its node pools. Once the shutdown time will be over, the virtual node group will return to its previous state.

object (Ocean AKS Strategy)

The Ocean AKS Strategy object.

tags
object

A maximum of 20 unique key-value pairs for VM tags in the virtual node group. Note: Azure has a tag limit of 50 per node pool.

Array of objects

Add taints to a virtual node group.

object (Ocean AKS VM Sizes)

The Ocean AKS VM Sizes object.

Responses

Request samples

Content type
application/json
{
  • "virtualNodeGroup": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Virtual Node Group

Delete a specified virtual node group in an Ocean cluster.

Authorizations:
auth
path Parameters
virtualNodeGroupId
required
string
Example: vng-12345abc

Ocean Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

deleteNodes
boolean
Default: false
Example: deleteNodes=true

When set to "true", all instances belonging to the deleted Virtual Node Group will be drained, detached, and terminated.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Virtual Node Group

The Import Ocean Virtual Node Group (VNG) returns a JSON formatted Ocean Virtual Node Group specification based on a given AKS Node Pool. The returned specification is ready to use in the Ocean AKS Virtual Node Group Create API call.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

nodePoolName
required
string
Example: nodePoolName=nodePoolNameTest

The name of the Node Pool.

oceanId
required
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Virtual Node Group Allowed VM Sizes

Get the allowed VM sizes that can be launched according to the virtual node group properties and selected VM size filters.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

virtualNodeGroupId
required
string
Example: virtualNodeGroupId=vng-12345abc

Ocean Virtual Node Group identifier.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Initiate Roll

Roll an entire Ocean cluster or roll subsets of the cluster by specifying vngIds, nodePoolNames or nodeNames. Performing this request will start the roll immediately and run it in defined batches. Note that the first response for a successful request will indicate the start of a roll. In order to check the status of a roll, you can use the GET Roll API.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
batchMinHealthyPercentage
integer
Default: 50

Indicates the threshold of minimum healthy nodes in single batch. If the amount of healthy nodes in single batch is under the threshold, the roll will fail. If exists, the parameter value will be in range of 1-100. In case of null as value, the default value in the backend will be 50%. Value of param should represent the number in percentage (%) of the batch.

batchSizePercentage
integer

Value as a percent to set the size of a batch in a roll. Valid values are 0-100. In case of null as value, the default value in the backend will be 20%.

comment
string

Add a comment description for the roll. The comment is limited to 256 chars and optional.

respectPdb
boolean
Default: true

During the roll, if the parameter is set to true we honor PDB during the nodes replacement.

respectRestrictScaleDown
boolean
Default: false

During the roll, if the parameter is set to true we honor Restrict Scale Down label during the nodes replacement.

Responses

Request samples

Content type
application/json
Example
{
  • "batchSizePercentage": 25,
  • "comment": "This is why I deployed my cluster.",
  • "respectPdb": false,
  • "respectRestrictScaleDown": true,
  • "batchMinHealthyPercentage": 100
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Rolls

Get status for all rolls of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Roll

Get status for a roll of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

rollId
required
string
Example: acr-12345abc

Ocean cluster roll identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Stop Roll

Stop a roll of an Ocean cluster.

Performing the request will stop the next batch in a roll.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

rollId
required
string
Example: acr-12345abc

Ocean cluster roll identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Migration Discovery

Get information about nodes which can be migrated into Ocean.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

shouldFetchPods
boolean
Example: shouldFetchPods=true

Should fetch data about running pods for each node.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Migration

Migrate to ocean workloads that run on unmanaged nodes by specifying nodePoolNames or nodeNames. Performing this request will start the migration immediately and run it in defined batches. Note that the first response for a successful request will indicate the start of a migration. In order to check the status of a migration, you can use the GET migration API.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
batchMinHealthyPercentage
integer [ 1 .. 100 ]
Default: 50

Indicates the threshold of minimum healthy nodes in single batch. If the amount of healthy nodes in single batch is under the threshold, the migration will fail. If exists, the parameter value will be in range of 1-100. In case of null as value, the default value in the backend will be 50%. Value of param should represent the number in percentage (%) of the batch.

batchSizePercentage
integer [ 1 .. 100 ]

Value as a percent to set the size of a batch in a migration. Valid values are 0-100. In case of null as value, the default value in the backend will be 20%.

comment
string

Add a comment description for the migration. The comment is limited to 256 chars and optional.

nodeNames
Array of strings

List of node names to be migrated. Each identifier is a string. nodeNames can be null, and cannot be used together with nodePoolNames.

respectPdb
boolean
Default: true

During the migration, if the parameter is set to true we honor PDB during the nodes replacement.

respectRestrictScaleDown
boolean
Default: false

During the migration, if the parameter is set to true we honor Restrict Scale Down label during the nodes replacement.

shouldEvictStandalonePods
boolean
Default: true

If the parameter is set to true we will evict all standalone pods during the migration.

shouldTerminateNodes
boolean
Default: true

If the parameter is set to true we will terminate the node after the migration has finished successfully. If the parameter is set to false we will leave the nodes. example: true

Responses

Request samples

Content type
application/json
Example
{
  • "batchSizePercentage": 25,
  • "comment": "This is why I deployed my cluster.",
  • "respectPdb": false,
  • "respectRestrictScaleDown": true,
  • "shouldTerminateNodes": true,
  • "shouldEvictStandalonePods": true,
  • "batchMinHealthyPercentage": 100,
  • "nodeNames": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {