Skip to main content

Compute Terminology

This document describes the various terms and phrases used throughout Seaplane and the associated CLI/SDK.

The best way to introduce these terms is in reverse, from the outermost components that you'll interact with regularly, to the physical components running underneath the hood. We do this because we want you to think about your applications and services in the same way — you shouldn't need to worry about the low level building blocks!

All that said, let's dive in.

Formation​

At the heart of Seaplane is your formation(s). Formations can be thought of as your high level
application or service load balancer and entry point. This is the entry point for all public and private traffic.

When using the seaplane CLI tool, you'll create local formation Definitions. These definitions can be used to create remote Instances running on our Seaplane Cloud. But what is a
formation? A formation is made up of two items, configuration and flight definitions.
We'll discuss flights in a moment.

NOTE on Terms: Throughout this document if we say "Formation" without qualifying whether it's a
Definition (which resides locally on your hard drive), or an Instance (which is running in our Cloud based on your definition); that means it applies equally to both concepts. Where there are differences we will specifically say Definition or Instance as appropriate!

Formation Configurations​

Each formation has one (or more!) configurations. A configuration tells us how to schedule your formation along with other details like what type of traffic should be allowed.

As noted above, one thing that makes formations a little different, and quite powerful, is that they can actually have multiple configurations. They can even have multiple active configurations (we refer to those as In Air) and multiple inactive (Grounded) configurations!

A configuration whose status is In Air is one where Seaplane is actively sending traffic. Having multiple configurations from a single formation listed as In Air means Seaplane is load balancing between them based on the defined traffic weight setting of each configuration.

A configuration whose status is Grounded is one that has been deployed (uploaded to Seaplane), but is not yet In Air (being utilized).

Deployed Configurations​

When you create a new formation configuration using the seaplane CLI, that configuration only resides locally on your computer. You can edit or view this configuration freely without impacting any of the systems running in the Seaplane Cloud. Once you're satisfied, you can launch the formation and any associated configurations to our Seaplane Cloud.

Once a configuration has been launched successfully, it now resides in our Seaplane Cloud and traffic will be sent to any of the flights that it describes. Do note that there are command line options for launching a formation and setting it as Grounded or immediately In Air depending on your use case.

Which brings us to the heart of formations, and what these configurations are actually describing.

That's the flight definition!

Flight​

A flight is logically a single container. However, under the hood we spin up many actual
container instances and spread them around the globe or within regions you specify.

When your users send traffic to Seaplane, it gets routed to the appropriate formation who's configuration describes the actual flights it is made up of, and who ultimately receive and process the user traffic.

To take a step back and describe a scenario in industry terms, imagine you are setting up a website to sell your state of the art Airplane Landing Gear (sticking within our motif). Like many modern web applications, your website will be made up of a few different components; a front facing webserver, a backend database, and perhaps a backend metrics platform. You've already created the container images for each of these components, and if you were to draw out a diagram of how they interconnect, it would look something like this:

The important point is your webserver is the only component receiving public traffic, but the backend components all may need to network with one another to form the entire service.

If we translate this into Seaplane terms we still get the exact same diagram, but we would describe it like this:

  • A "Landing Gear Website" formation
  • The formations configuration would specify
    • That it is made up of three flights
      • A "webserver" flight
      • A "database" flight
      • A "metrics" flight
    • How public traffic arrives, and which flight to send it to
    • How the flights are allowed to communicate/network with each-other

Now what's really neat to us, is that each of these flights is not just a single physical container, but it's own CDN-like cluster! This makes your service (the Landing Gear Website in our example) much more robust, and can drastically increase your performance as you sell landing gear to customers around the world.

Additionally, let's say you had a version 2.0 of this Landing Gear Website you wanted to roll out. Perhaps it swaps out one metrics server for another, or maybe it consists of entirely different flights in total.

You can add a new configuration to the existing formation. Once activated, Seaplane will balance between your two version. Since these two "versions" could be referencing the same flight definitions, you can easily swap out only the parts you want to balance between. Or if you want to do full on A/B testing, all the flights could be different, the sky is the limit!

To visualize the example, image we kept it simple and the only difference between these two configurations is the metrics platform. After launching the formation with the second configuration added, your diagram would look like this:

In the more complex scenario, where all flights are different, it would look like this:

Container Instance​

The lowest level components we should address, which we've already mentioned a few times, are the actual Container Instances themselves. We don't bring this initially because if everything is working as it should these are invisible to you and your users. Logically, the flight is your container instance.

That being said, there are rare occurrences where you will need to think about how Seaplane is distributing your traffic, and in those instances it's important to know that there are actual container instances running under the hood.

These container instances are controlled by your flight and formation configuration. For the most part, you can let Seaplane handle the details of how they are distributed. However, it is possible to network between physical container instances individually when coordination is necessary. Doing so is outside the scope of this guide, and is normally handled out-of-band.

Container Image​

Just like the container images you know and love from all your standard OCI compliant tools. There is nothing fancy here. We instantiate your container instances, which make up your flights and form your formations from good ol' standard OCI images.