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.
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.
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
You can retrieve existing Stages, including the new one just created, via:
$ pergola list stage -p my-new-project
┌──────────────────────────────────────────────┐
| stage | type | status |
| ──────────────────────────────────────────── |
| my-new-stage (stage1) | prod | running |
| uat | prod | running |
| integration-tests (test) | 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.
Once a Stage is finally deleted, all its runtime environment, including configuration and data, is lost irrevocably.