Skip to main content

Compute API (1.0.0)

Download OpenAPI specification:Download

Seaplane IO, Inc.: support@seaplane.io License: Apache 2.0

Seaplane Compute API

formation

Everything you can do with formations

Retrieves the list of formations you have access to

By default the CLI returns the known formations based on the local database. To include remote formations add --fetch to your request or run seaplane formation fetch-remote before running seaplane formation list

The API and SDKs always pull information from the remote deployments and do not require you to fetch anything.

Authorizations:
BasicAuth

Responses

Request samples

seaplane formation list --fetch

Response samples

Content type
application/json
[
  • {
    }
]

Get metadata about a formation

Authorizations:
BasicAuth
path Parameters
formationName
required
string^(?!.*--)[a-z0-9-]{1,30}(?<!-)$
Example: example-formation

The formation name, which must be unique within your organization

Responses

Request samples

seaplane formation status <FORMATION-NAME>

Response samples

Content type
application/json

Create a new formation

Authorizations:
BasicAuth
path Parameters
formationName
required
string^(?!.*--)[a-z0-9-]{1,30}(?<!-)$
Example: example-formation

The formation name, which must be unique within your organization

query Parameters
active
boolean
Default: false

If this formation should be immediately deployed. Note that this will only work if either the request body is a configuration or the source parameter is set.

source
string

The name of a formation this formation should be cloned from. A copy of the source formation's configurations will be made under this new formation and, if the active parameter is set, its active configuration will be copied over and immediately deployed

Request Body schema: application/json
affinity
Array of strings

A list of names of other formations this formation has an affinity for. This is a hint to the scheduler to place the containers running in each of these formations "close" to each other ("close" being defined in part by latency)

connections
Array of strings

A list of names of other formations this formation is connected to. Two formations can communicate over their formation endpoints (the endpoints configured in the formation_endpoints section) if and only if both formations opt in to that connection by listing each other in their respective connections map)

required
Array of objects (Flight)

The individual flights that make up the formation

public_endpoints
object

The keys of this map are the publicly exposed endpoints of this formation and take the form http:{endpoint}. The values of this map take the form {flight_name}:{port} and describe where the traffic that hits this endpoint should be routed. For example, "http:/foo/bar": "baz:1234" means "Route all traffic from the public internet hitting the path /foo/bar on this formation's domain to the flight named 'baz' on port 1234"

formation_endpoints
object

The keys of this map are the privately exposed endpoints of this formation (that is, the endpoints that this formation exposes to other formations that are connected to it) and take the form http:{endpoint} or tcp:{port} or udp:{port}. The values of this map take the form {flight_name}:{port} and describe where the traffic that hits this endpoint should be routed. For example, "tcp:1234": "foo:4321" means "Route all internal tcp traffic hitting this formation on port 1234 to this formation's foo flight on port 4321". If this conflicts with flight_endpoints the configuration will be rejected

flight_endpoints
object

The keys of this map are the endpoints of this formation that containers within the formation can hit to communicate with one another. Containers within a formation can always communicate directly but these endpoints are load-balanced and allow for much simpler usage in many cases. The keys take the form http:{endpoint} or tcp:{port} or udp:{port}. The values of this map take the form {flight_name}:{port} and describe where traffic on that endpoint will be routed. For example, "udp:1234": "foo:4321" would mean "Route all internal udp traffic hitting this formation on port 1234 to the formation's foo flight on port 4321". If this conflicts with formation_endpoints the configuration will be rejected

providers_allowed
Array of strings (Provider)
Items Enum: "AWS" "Azure" "DigitalOcean" "Equinix" "GCP"

A list of allowed providers. Including this argument will disallow all other providers. If not included the scheduler will use any provider it pleases to schedule this formation

providers_denied
Array of strings (Provider)
Items Enum: "AWS" "Azure" "DigitalOcean" "Equinix" "GCP"

A list of denied providers, providers the scheduler will never use for this formation. If this conflicts with providers_allowed (e.g. gcp is both allowed and denied) the configuration is invalid and will be rejected

regions_allowed
Array of strings (Region)
Items Enum: "XA" "XC" "XE" "XF" "XN" "XO" "XQ" "XS" "XU"

A list of allowed regions. Including this argument will disallow all other regions. If not included the scheduler will use any provider it pleases to schedule this formation

regions_denied
Array of strings (Region)
Items Enum: "XA" "XC" "XE" "XF" "XN" "XO" "XQ" "XS" "XU"

A list of denied regions, regions the scheduler will never use for this formation. If this conflicts with regions_allowed (e.g. XC is both allowed and denied) the configuration is invalid and will be rejected

Responses

Request samples

Content type
application/json
{
  • "affinity": [
    ],
  • "connections": [
    ],
  • "flights": [],
  • "public_endpoints": { },
  • "formation_endpoints": { },
  • "flight_endpoints": { },
  • "providers_allowed": [
    ],
  • "providers_denied": [
    ],
  • "regions_allowed": [
    ],
  • "regions_denied": [
    ]
}

Response samples

Content type
application/json
[
  • "123e4567-e89b-12d3-a456-426614174000"
]

Remove a formation and all associated resources

Authorizations:
BasicAuth
path Parameters
formationName
required
string^(?!.*--)[a-z0-9-]{1,30}(?<!-)$
Example: example-formation

The formation name, which must be unique within your organization

query Parameters
force
boolean
Default: false

Delete the formation even if it is running

Responses

Request samples

seaplane formation delete <FORMATION-NAME> --force

Response samples

Content type
application/json
[
  • "123e4567-e89b-12d3-a456-426614174000"
]