Skip to main content

Stages

What is a Stage?โ€‹

A Stage is a runtime environment for your application within your Pergola Project.

On a Stage, you can:

  • Deploy new Builds
  • Manage configurations (e.g. environment settings)
  • Publish and share links to your application
  • Access monitoring

You deploy your application always to a Stage. There can be max one Release of your application running on one Stage at a time. Once deployed, you can see each component deployed, their state, health, shareable links, etc.

Example of an application on Stage:

Multiple Stagesโ€‹

You can have as many Stages as needed per Project. It highly depends on your needs and the maturity of your Project. In most cases, you'll start with one (DEV) Stage first, then scale to multiple, differently configured Stages, when needed.

Examples for different scenariosโ€‹

A Project with classic dev / qa / prod Stages.

A Project which does not require a live environment yet.

Still under heavy development, but needs two separate DEV environments (maybe for A/B-Testing ๐Ÿค”).

A more complex setup, with two separate Stages to serve different markets.

Separate Stages for different test cases (e.g. integration vs. acceptance), and multiple Stages live with dedicated environment configuration per factory.

How to run a Stage on edge devices, like in a remote factory, see Outposts.

Stage typesโ€‹

While you can have as many Stages as needed, each Stage is classified by a type:

  • DEV (e.g. for proving that tech and build/deploy process works)
  • QA (e.g. for testing and verifying business requirements and quality expectations are met)
  • PROD (e.g. hosting the final, proven product, typically accessed by clients / end users)

Based on the Stage type Pergola might apply different rules when it comes to prioritizing platform resources and ensuring availability.

Future releases will also support applying dedicated policies for security and service-level objectives. These policies can then be configured by Pergola administrators on a per Stage type basis.

tip

In general, you are free to deploy any Release to any Stage at any time. Though, we recommend following the DEV -> QA -> PROD approach to maintain a stable, reproducible release process.

Suspending and resuming a Stageโ€‹

If you do not need a Stage up and running for some time, you can suspend it. This saves resources (CPU and memory) while keeping your Stage and its last state ready for future use.

Suspending a Stage will shutdown all running Components, stop incoming traffic and disable scheduled jobs. Data on persistent storage will be retained, though any temporary data will get lost. During shutdown, each Component receives a graceful shutdown (SIGTERM) first. After a grace period (usually 60secs) they are forcibly killed. Already started jobs are not affected and will run till completion.

caution

If a Component stores data outside of a persistent storage attached or an external storage service (e.g. S3), this data will be lost once its Stage is suspended. Always make sure that data is kept on persistent storage when data must not be lost.

You can resume a suspended Stage anytime. This will restore its last state (services, storage, scheduled jobs...) and start serving your application as soon as it's up and running.


How to create a Stageโ€‹

Example for Web UIโ€‹

Press the '+ NEW STAGE' button on your Project's page. This will open a popup:

  • Name is a user friendly display name for your Stage, as visible on the UI
  • Type is the Stage type for classification
  • Stage ID is a unique identifier for your Stage within your Project

The Stage ID must be unique within the scope of a Project as it will be used for links (URLs) to resources available on that Stage. Usually this is automatically derived from the display name provided, though you can override it with a more pleasing ID if you prefer. Pergola will complain if the ID is already taken.

Example for CLIโ€‹

pergola create stage my-new-stage --type dev -p my-new-project
tip

You can retrieve existing Stages, including the new one just created, via:

$ pergola list stage -p my-new-project

stages (my-new-project)
โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“
โ”ƒ stage โ”ƒ type โ”ƒ state โ”ƒ
โ”กโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ
โ”‚ my-new-stage โ”‚ dev โ”‚ running โ”‚
โ”‚ uat โ”‚ qa โ”‚ running โ”‚
โ”‚ integration-tests โ”‚ qa โ”‚ suspended โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Delete or restore a Stageโ€‹

If you do not need a Stage anymore, you can delete it. To do this, navigate to the Settings of the Stage to be deleted:

and press the "DELETE STAGE" button.

A Stage to be deleted will be archived first. You can restore it without loosing any configuration or persistent storage until the actual deletion is due. An overview of archived Stages is available at the bottom of the Stages list on its Project page:

from where you can restore a Stage.

The deletion due date depends on the type of Stage. Usually, the retention periods are:

  • DEV: 1 day
  • QA: 7 days
  • PROD: 30 days

These retention periods can be adjusted by your Pergola administrator.

danger

Once a Stage is finally deleted, all its runtime environment, including configuration and data, is lost irrevocably.