Terminology

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

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

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 will 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, configurations and flights 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 briefly 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 that Seaplane is actively sending traffic to. 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 tool, that configuration only resides locally on your computer. You can edit or view this configuration freely without affecting 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 across the globe or within the regions you specify.

When your users send traffic to Seaplane, it gets routed to the appropriate formation whose 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're setting up a website to sell your state of the art Airplane Landing Gear (sticking within our motif, of course). 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 may all 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 so:

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 its 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 these landing gear to customers around the globe!

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 versions. Since these two "versions" could be referencing the same flight definitions, you easily can 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 component we should address, and we've already mentioned it a few times, is the actual container instances themselves. We haven't mentioned these until now because, if everything is working as intended, container instances 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 get 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.