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
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 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 storage attached or an external storage service (e.g. S3), this data will be lost once its Stage is suspended. Always make sure to keep data on storage if you require reliable persistence.
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
stages (my-new-project)
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━┓
┃ stage ┃ type ┃ state ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━┩
│ my-new-stage │ dev │ running │
│ uat │ qa │ running │
│ integration-tests │ qa │ suspended │
└────────────────────────┴──────┴───────────┘