Releases
What is a Release?
A Release is a Build bundled with an optional Configuration and is ready for immediate execution on a Stage. Once a Release got published, it cannot be mutated, so for any change, a new Release must be deployed. Pergola stores the history of all Releases, and as a result, Releases can be traced back to the exact state they were in when they were deployed.
A Release always requires a successful Build. A Configuration is required only if your Project Manifest has references to Configuration entries, or if you need customization per Stage (e.g. Identities).
How to deploy a Release?
Example for Web UI
Navigate to your Project on the start page or under the 'Projects' navigation and click on the Stage you want to deploy the Release on. On the right side, click on the '+ NEW RELEASE':
Choose the Build you want to Release and the Config, then hit 'DEPLOY':
Example for CLI
pergola push release -s my-new-stage -p my-new-project -b master_b2
So the Release got pushed and is in the process of deploying. This should take only a few seconds, depending on the size of your application and the number of Components to be deployed.
You can retrieve all Releases for a specific Stage, including the Release just pushed, via:
$ pergola list releases -p my-new-project -s my-new-stage
┌──────────────────────────────────────────────────────────────────┐
| build | config | released | status |
| ──────────────────────────────────────────────────────────────── |
| master_b2 | - | 29 seconds ago by Silas Dahmen | deployed |
└──────────────────────────────────────────────────────────────────┘
For further options see CLI reference.
Behaviour of Components during a Release
Principle: Least possible service interruption
When releasing to a Stage, Pergola tries to not interrupt the running services. To achieve this goal, each type of Components is treated gracefully as described below.
Permanently running Components
Permanently running Components are updated by starting a new instance of the Component with a new Release. Pergola waits until the new instance is up and running before it stops the old running instance of the Component.
This happens regardless of the number of Components running. In this case Pergola might start multiple new instances with the new Release in parallel.
In the following screenshot, you can see the Component todo-app just starting (pending):
A Component is restarted only, if it has changed in the new Release. Means for example, it has a new image, or new command/args, or changed env variables, etc. Otherwise, the Component is kept running without any interruption.
Scheduled Components
A scheduled Component is usually not affected during a Release. On its next scheduled run, it will simply be started with the new Release.
If it is currently running, Pergola will not interfere with the current instance nor start a new one. The old instance will continue till completion. Only the next scheduled run will use the new Release.
You can always stop, kill and restart a running scheduled Component with the 'Also run job immediately' - checkbox to force a re-run with the new Release.
If the scheduled Component is declared with the @release trigger, an instance will be started immediately.
Configuration-only Releases
If a Release contains the same Build but a changed Configuration, Pergola keeps all running Component instances alive, unless the env variables have changed. Otherwise, it updates their state at runtime by replacing any configuration files and mapped identities only.
For the new Configuration to be applied directly by permanently running Components, it is recommended that your application actively monitors required configuration files and re-initializes if needed.
You can always restart a permanently running Component to force your application to re-initialize with the new Configuration.
Release on a new Stage
A Release on a new Stage instantiates all Components for the first time. It also acquires permanent resources like storage.
Release on a suspended Stage
A Release on a suspended Stage will not take effect immediately. It gets active as soon as you resume the Stage.
@release scheduled Components will not run at all, even after resuming the Stage. You will need to manually start them.
Automatically Release after a successful Build
Pergola can automatically push a Release to a Stage after a successful Build. This feature is called Auto-Release.
To configure Auto-Releases, navigate to your Project on the start page or under the 'Projects' navigation and click on the Stage you want to enable Auto-Release for:
There, you can enable an Auto-Release by typing in the Git branch name the successful Build will belong to and by selecting a Config to be bundled with the Build to a Release. You can also keep the dynamic Config option 'use current one', which will keep the Config currently in use on the Stage. Finish the Auto-Release setting by first clicking 'ADD', followed by 'SAVE'.
You can add multiple Auto-Releases easily. The following example shows two Auto-Releases configured:
Please see CLI reference for Auto-Release as well.
For a fully automated continuous integration and delivery - cycle, see the Automated CI/CD tutorial. This combines Auto-Release with the Auto-Build feature.